---
title: "PhysMove: Intraspecific Movements"
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: Intraspecific Movements}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

<style>
      img {
      border: 0;
      height: auto;
      display: block; 
      margin: 1em auto
    }
</style>

```{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 = "#>") 
```

<img src="../vignettes/PhysMoveHexNew.png" align="right" width="130" />

## 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)

## *Intraspecific movements*

*PhysMove* includes three metrics for quantifying intraspecific movement patterns that are based on four functions, including:

  * [Track dispersion](pt4_intraspecific_movements.html#track-dispersion): `gyrationRad()` and `plotPDF()`
  * [Track entropy](pt4_intraspecific_movements.html#track-entropy): `entropy()` and `plotPDF()`
  * [Track predictability](pt4_intraspecific_movements.html#track-predictability): `predictability()` and `plotPDF()`

```{r load physmove intraspecific vignette, echo=FALSE}
# Load PhysMove
library(PhysMove)
```

## Track dispersion 

The `gyrationRad()` function calculates the dispersion (i.e., the gyration radius) of each track in a dataset (Figure V16).  

`gyrationRad()` requires a data frame with telemetry data (see [data formatting](pt1_introduction.html#data-formatting)) and includes two optional parameters:

* `map`: create a map (`map=TRUE`, by default), and
* `mapCol`: change the colour of the points, which indicate average track location,
and circles, which indicate how far each animal dispersed (`mapCol=c("Black", "Red")`, by default).

`gyrationRad()` outputs a data frame of the results that were used to create the map, including: 

* *ref*: the reference ID for each track,
* *avg long* and *avg lat*: the average longitude and latitude coordinates in degrees for each track, and 
* *rG* *(km)*: the gyration radius in kilometres for each track 

```{r gyrad, message=FALSE}
# Calculate the dispersion of each track in the 'tracks' dataset
GR <- gyrationRad(tracks)
```
**Figure V16** Map illustrating dispersion patterns for `'tracks'` dataset using `gyrationRad()` default parameters. Black points represent the mean location of each track and red circles represent how far each track dispersed (i.e., each track's gyration radius).

```{r preview gyrad}
# Summarize gyration radius results
summary(GR)
```

### Probability density function of gyration radius results

A pdf of the results from `gyrationRad()` can be plotted with the `plotPDF()` function when the `desc` parameter is set to "gyrationRad" (Figure V17).

```{r gyrad pdf}
# Create a pdf plot of gyration radius values
pdf.gr <- plotPDF((GR$`rG_(km)`), desc="gyrationRad")
```
**Figure V17** Probability density function (pdf) plot of gyration radius values for the `'tracks'` dataset determined with `gyrationRad()` default parameters. Plot created using `plotPDF()` with `desc="gyrationRad"`.

[Back to top](pt4_intraspecific_movements.html)

## Track entropy

The `entropy()` function calculates track randomness based on the fraction of data points from each track within each grid cell (Figure V18). The resulting entropy scores are then normalised so results can be compared between individuals. Note that if a track only visits a single grid cell, normalised entropy cannot be calculated and will return NaN; these values are excluded from visualisations. 

`entropy()` requires a data frame with telemetry data (see [data formatting](pt1_introduction.html#data-formatting)) and includes two optional parameters:

* `gridCell`: change grid cell size in degrees (`gridCell=0.25`, by default), and
* `histPlot`: output a histogram (`histPlot=TRUE`, by default).

`entropy()` outputs a data frame with four columns, including: 

* *ref*: reference ID for each track,
* *normalisedEntropy*: normalised entropy scores,
* *indivEntropy*: individual entropy scores (before normalisation), and 
* *cellsVisited*: number of cells visited by each track. 

```{r ent}
# Calculate track entropy using default parameters
Ent <- entropy(tracks)
```
**Figure V18** Histogram of normalised entropy scores for `'tracks'` dataset created using `entropy()` default parameters.

```{r ent head}
# Summarise entropy results
summary(Ent)
```

### Probability density function of entropy results

A pdf of the results from `entropy()` can be plotted with the `plotPDF()` function when the `desc` parameter is set to "entropy" (Figure V19).

```{r ent pdf}
# Create a pdf plot of the entropy scores
pdf.ent <- plotPDF(Ent$normalisedEntropy, desc="entropy")
```
**Figure V19** Probability density function (pdf) plot of normalised entropy scores for `'tracks'` dataset determined with `entropy()` default parameters. Plot created using `plotPDF()` with `desc="entropy"`.

[Back to top](pt4_intraspecific_movements.html)

## Track predictability 

The `predictability()` function calculates the limit of predictability for each track based on their individual entropy scores (Figure V20).  

`predictability()` requires a data frame with telemetry data (see [data formatting](pt1_introduction.html#data-formatting)) and a data frame of results output from `entropy()`, and includes two optional parameters:

* `startVal`: Optional starting value used to find a root value for the limit of predictability equation. If NULL (default), the starting value is automatically determined from the normalised entropy for each individual. The function will iteratively decrease the starting value by 0.01 until an acceptable root within (0,1) is found.
* `histPlot`: output a histogram (`histPlot=TRUE`, by default).

`predictability()` outputs a data frame of results with two columns, including: 

* *ref*: reference ID for each track, and 
* *predictability*:  predictability scores for each track. 

```{r predict}
# Track predictability using predictability() default parameters and the output from entropy()
Pred <- predictability(tracks, Ent)
```
**Figure V20** Histogram of predictability scores for `'tracks'` dataset determined using `predictability()` default parameters and entropy scores from `entropy()`.

```{r predict head}
# Summarize predictability scores
summary(Pred)
```

### Probability density function of predictability results

A pdf of the results from `predictability()` can be plotted with the `plotPDF()` function when the `desc` parameter is set to "predictability" (Figure V21).

```{r predict pdf}
# Create a pdf plot of the predictability scores
pdf.pred <- plotPDF(Pred$predictability, desc="predictability")
```
**Figure V21** Probability density function (pdf) plot of predictability scores for `'tracks'` dataset determined with `predictability()` default parameters and results from `entropy()`. Plot created using `plotPDF()` with `desc="predictability"`.

[Back to top](pt4_intraspecific_movements.html)

## References & Recommended resources

<div style="text-indent: -40px; padding-left: 40px;">

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.

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.

</div>