---
title: "PhysMove: Introduction"
author: "Hannah J. Calich, Jorge Rodríguez, Víctor Eguíluz & Ana M. M. Sequeira"
date: 'Last updated: `r Sys.Date()`'
output:
rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{PhysMove: Introduction}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r setup, include=FALSE}
knitr::opts_chunk$set(dev = "png",
dpi = 120,
fig.width = 5,
fig.height = 4,
out.width = "70%",
fig.align = "center",
echo = TRUE,
collapse = TRUE,
comment = "#>")
```
## Index
1. [Introduction and data preparation](pt1_introduction.html)
2. [Movement patterns](pt2_movement_patterns.html)
3. [Space-use patterns](pt3_space_use_patterns.html)
4. [Intraspecific movements](pt4_intraspecific_movements.html)
## 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](pt1_introduction.html#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.
```{r installation, eval=FALSE}
# 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)
```
```{r load physmove}
# 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.
``` {r check_tracks, eval=FALSE}
# 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.
1. 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”.
2. 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
```{r head tracks}
# Preview the first 6 rows of the 'tracks' dataset
head(tracks)
```
```{r structure tracks}
# Determine the structure of the 'tracks' dataset
str(tracks)
```
## 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](pt1_introduction.html#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).
```{r plot_tracks, message=FALSE}
plotTracks(tracks)
```
**Figure V1** Map of the simulated '`tracks`' dataset created with `plotTracks()` default settings.
[Proceed to Movement Patterns](pt2_movement_patterns.html)
[Back to top](pt1_introduction.html)
## 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.