PhysMove: Introduction

Introduction

PhysMove contains a comprehensive collection of methods for documenting species’ movement and space-use patterns from satellite telemetry data. These vignettes demonstrate how to calculate each of the PhysMove functions and review all relevant functions and parameters. We demonstrate each function with a simulated telemetry dataset, called ‘tracks’, which is automatically loaded with PhysMove (see Explore ‘tracks’ dataset section for further details). For further details on our methods and interpreting results please see the corresponding manuscript.

The most up-to-date version of PhysMove and the accompanying vignettes can be installed by following the instructions below.

Installation

The development version of PhysMove can be installed from its GitHub repository.

# Install the devtools package from CRAN (if required)
install.packages("devtools")

# Download the development version from GitHub:
devtools::install_github("HannahCalich/PhysMove", build_vignettes = TRUE)

# Load PhysMove
library(PhysMove)

Data formatting

PhysMove was designed to be user-friendly and most functions only require you to input a data frame containing standard telemetry data (tibbles and other data.frame subclasses are not supported). The input data frame must only contain these four columns in the following order: ref, lon, lat, and day.

Columns must be formatted as follows:

ref: the unique telemetry tag ID number for each animal in numeric format (note that characters are not accepted because they can be slower to process than integers, so please convert all reference IDs to integers before proceeding)
lon and lat: the longitude (-180 to + 180) and latitude (-90 to +90) in decimal degrees of each position estimate, respectively, in numeric format, and
day: the datetime stamp for each location estimate in POSIXct format following %Y-%m-%d %H:%M:%S.

The checkTracks function can be used to confirm your input data are formatted as described above. This function checks that column names are in order and that each column is in the correct format as described above. Note that this function does not evaluate data quality or quantity.

# Check your data are formatted correctly
checkTracks(tracks) # replace 'tracks' with your data frame

Sample datasets

PhysMove includes two example telemetry datasets that are automatically loaded with the package and can be used to demonstrate functionality and analytical workflows across the vignettes.

The primary dataset, ‘tracks’, is a simulated telemetry dataset of 25 unique tracks with a defined set of movement parameters that was designed to demonstrate each of the PhysMove functions. This dataset is used throughout the PhysMove vignettes to provide a consistent and reproducible example for demonstrating analytical workflows. In detail, ‘tracks’ was created using a biased, uncorrelated random walk model with variable step lengths drawn from an exponential distribution with λ = 0.125. We defined the turning angles such that 30% indicated directed forward movement (movements with angles <30° or >330°), and 30% indicated directed return movement (angles between 150–210°), allowing the remainder (40%) to be randomly between 0–360°. These metrics were chosen because they are broadly consistent with literature describing animal movement in resource-rich habitats. The code used to make the ‘tracks’ dataset is available in the PhysMove doc folder as “createTracks.R”.
The second dataset, ‘tracksCRW’, represents movement generated from a correlated random walk (CRW) model using the aniMotum R package simulation framework (Jonsen et al. 2023). ‘tracksCRW’ consists of 25 simulated telemetry tracks, with each track containing between approximately 200 and 1000 locations to mirror the structure of the ‘tracks’ dataset. Tracks were generated using the sim() function with a CRW model, where a correlation parameter (D = 0.5) introduces temporal autocorrelation in successive displacements, resulting in directional persistence in movement trajectories. In contrast to the uncorrelated random walk used to generate ‘tracks’, this structure produces movement behaviour where step direction is partially dependent on previous steps. Simulations were iteratively repeated until 25 tracks that did not intersect land were obtained, ensuring all trajectories remain within the intended spatial domain. This dataset is included to demonstrate how PhysMove performs when applied to movement trajectories exhibiting temporal autocorrelation and short-term directional persistence, enabling comparison between correlated and uncorrelated movement regimes. The code used to make the ‘tracksCRW’ dataset is available in the PhysMove doc folder as “createTracksCRW.R”.

Together, these datasets provide reproducible examples that illustrate how methods in PhysMove can be applied across different movement regimes. Users can also compare their own data frames to the ‘tracks’ or ‘tracksCRW’ dataset to ensure appropriate formatting prior to analysis.

Explore ‘`tracks`’ dataset

# Preview the first 6 rows of the 'tracks' dataset
head(tracks)
#>   ref       lon       lat                 day
#> 1   1 0.5310173 0.5310173 2017-10-13 12:00:00
#> 2   1 0.5156939 0.5500691 2017-10-14 12:00:00
#> 3   1 0.5052581 0.5158941 2017-10-15 12:00:00
#> 4   1 0.5247597 0.4555179 2017-10-16 12:00:00
#> 5   1 0.5491573 0.2831650 2017-10-17 12:00:00
#> 6   1 0.5670918 0.2875133 2017-10-18 12:00:00

# Determine the structure of the 'tracks' dataset
str(tracks)
#> 'data.frame':    15623 obs. of  4 variables:
#>  $ ref: num  1 1 1 1 1 1 1 1 1 1 ...
#>  $ lon: num  0.531 0.516 0.505 0.525 0.549 ...
#>  $ lat: num  0.531 0.55 0.516 0.456 0.283 ...
#>  $ day: POSIXct, format: "2017-10-13 12:00:00" "2017-10-14 12:00:00" ...

Create a map of the ‘tracks’ dataset

A basic map of your telemetry data can be created using our plotTracks() function (Figure V1).

plotTracks() requires a data frame with telemetry data (see data formatting) and includes three optional parameters:

ref: plot specific tracks based on their reference IDs (ref=NULL, by default),
tracks: connect points with lines (tracks=TRUE, by default), and
colours: edit the colours used in the map (colours=rainbow, by default).

plotTracks(tracks)

Figure V1 Map of the simulated ‘tracks’ dataset created with plotTracks() default settings.

Proceed to Movement Patterns

References & Recommended resources

Burnham, K.P. & Anderson, D.R. (2004) Multimodel Inference: Understanding AIC and BIC in Model Selection. Sociological Methods & Research, 33, 261-304.

Calich, H.J. et al. (2021) Comprehensive analytical approaches reveal species-specific search strategies in sympatric apex predatory sharks. Ecography, 44, 1544-1556.

Farage, C. et al. (2021) Identifying flow modules in ecological networks using Infomap. Methods in Ecology and Evolution, 12, 778–786.

Jonsen, I. et al. (2023) aniMotum, an R package for animal movement data: Rapid quality control, behavioural estimation and simulation. Methods in Ecology and Evolution, 14(3), 806-816.

Méndez, V., et al. (2013). Stochastic Foundations in Movement Ecology: Anomalous Diffusion, Front Propagation and Random Searches. Berlin, Heidelberg, Germany, Springer Berlin / Heidelberg.

Rodríguez, J.P. et al. (2017) Big data analyses reveal patterns and drivers of the movements of southern elephant seals. Scientific Reports, 7, 1-10.

Viswanathan, G. M., et al. (2011). The Physics of Foraging: An Introduction to Biological Encounters and Random Searches. Cambridge, Cambridge University Press.

Wickham, H. (2016) ggplot2: Elegant Graphics for Data Analysis. Springer-Verlag, New York.