. Further details can be found in Farage *et* *al*. (2021). The following instructions assume both the `infomapecology` and `emln` R packages and the stand-alone Infomap file have been installed.
The `infomapCommunities()` function identifies community-wide movements in two steps. First, `infomapCommunities()` calculates the probability of individuals moving between specific grid cells along their track within a predetermined time window. This step creates a transition probability matrix (tpm), which can also be referred to as a "unipartite edge list". Next, `infomapCommunities()` feeds the transition probability matrix into functions from the `emln` and `infomapecology` R packages to create an *Infomap monolayer object* that identifies movement communities.
To ensure the `infomapecology` algorithm calculates movement patterns consistent with telemetry data, we assign parameters to the `infomapecology` function that allow for directed movement, self-links (i.e., individuals can remain in the same grid cell over time), and hierarchical partitioning (i.e., resulting communities can be composed of multiple levels). Because we allowed hierarchical partitioning, the resulting communities are associated with different levels. Level 1 communities are the most inclusive and have been used to identify community-wide movements (following Rodríguez *et* *al*. 2017 and Calich *et* *al*. 2021).
The `infomapCommunities()` function requires a data frame with telemetry data (see [data formatting](pt1_introduction.html#data-formatting)) and includes five optional parameters:
* `gridCell`: grid cell size in degrees (`gridCell=0.25`, by default),
* `hours`: number of hours between location estimates (`hours=24`, by default),
* `range_hr`: time range in hours (`range_hr=6`, by default). This parameter allows you to identify location estimates that are close to, but not exactly separated by the set number of `hours`, and
* `tpm`: save the transition probability matrix to the output list as a second list element (`tpm=FALSE`, by default).
`infomapCommunities()` outputs a list with up to two list objects. The first list object is an *infomap monolayer object* that summarizes the hierarchical structure of the Infomap communities (regions where individuals follow similar movement patterns and are likely to stay for longer periods of time). The second list object is the transition probability matrix, which is only output if `tpm=TRUE`.
**Important**: Before running `infomapCommunities()` you must:
1. Set your working directory to the folder that contains the stand-alone Infomap file using `setwd()`
2. Load the infomapecology R package using `library(infomapecology)`
```{r run infomap, eval=FALSE}
# Identify community-wide movements
infomapResult <- infomapCommunities(tracks)
```
```{r load example data, include=FALSE}
# Load example dataset included in the package
data("infomapResult", package = "PhysMove")
```
```{r structure of infomap}
# View the Infomap monolayer object structure
str(infomapResult[["infomap_object"]])
```
### Plot Infomap communities
`communityMap()` visualises results from `infomapCommunities()` by converting the *Infomap monolayer object* into a map (Figure V13).
The `communityMap()` function requires the full output list from `infomapCommunities()`, from which *Infomap monolayer object* is extracted internally, and includes two optional parameters:
* `subset_communities`: used to only map specific level 1 communities. For example, `subset_communities = c(1,2,3)` would plot the first three level 1 communities (all communities are included by default), and
* `colours`: change colours of the communities (`colours= "Dark2"`, by default).
```{r infomap map, message=FALSE}
# Create a map of the Infomap communities
communityMap(infomapResult)
```
**Figure V13** Map illustrating level 1 Infomap communities from the `'tracks'` dataset determined using `infomapCommunities()` default parameters. Map created with `communityMap()` default parameters.
[Back to top](pt3_space_use_patterns.html)
## Occupancy patterns
The `occupancy()` function helps describe species’ space-use patterns by calculating the total number of location estimates within each grid cell divided by the grid cell’s area, calculated using spherical coordinates (Figure V14).
`occupancy()` requires a data frame with telemetry data (see [data formatting](pt1_introduction.html#data-formatting)) and includes three optional parameters:
* `gridCell`: change the grid cell size in degrees (`gridCell=0.25`, by default),
* `map`: present results in a map (`map=TRUE`, by default) and
* `colGrad`: edit the colours used in the map to indicate low, moderate, and high occupancy, respectively, which are visualised using scale_fill_gradientn() from the ggplot2 package (Wickham 2016) (`colGrad=c("blue", "light blue", "red")`, by default).
`occupancy()` outputs a data frame of all results, including:
* *Latitude* and *Longitude*: coordinates for the centre point of each grid cell,
* *Area*: area of the grid cell,
* *Counts*: the number of location estimates recorded in the grid cell, and
* *Occupancy*: occupancy values per grid cell, defined as the number of counts/area.
```{r calc occ, message=FALSE}
# Create an occupancy map based on the tracks dataset
occ <- occupancy(tracks)
```
**Figure V14** Map of occupancy patterns from the `'tracks'` dataset. Map created with `occupancy()` default parameters.
```{r summarise occ}
# Summarize occupancy results
summary(occ)
```
### Probability density function of occupancy results
A pdf of the results from `occupancy()` can be plotted with the `plotPDF()` function when the `desc` parameter is set to "occupancy" (Figure V15).
```{r pdf occ}
# Create a pdf plot of occupancy values
pdf.occ <- plotPDF(occ$Occupancy, desc="occupancy")
```
**Figure V15** Probability density function (pdf) plot of occupancy values for the tracks dataset calculated with `occupancy()` default parameters. Plot created using `plotPDF()` with `desc="occupancy"`.
[Proceed to Intraspecific Movements](pt4_intraspecific_movements.html)
[Back to top](pt3_space_use_patterns.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.
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.
## 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)
## *Space-use patterns*
*PhysMove* includes two metrics for identifying space-use patterns that are based on four functions, including:
* [Community-wide movements](pt3_space_use_patterns.html#community-wide-movements): `infomapCommunities()` and `communityMap()`
* [Occupancy patterns](pt3_space_use_patterns.html#occupancy-patterns): `occupancy()` and `plotPDF()`
```{r load physmove space-use vignette, echo=FALSE}
# Load PhysMove
library(PhysMove)
```
## Community-wide movements
Interactions between species’ movements and space-use can be described using a network analysis algorithm called Infomap, which identifies communities where animals follow similar movement patterns and remain for extended periods. To identify Infomap communities, *PhysMove* requires the `infomapecology` [R package](https://github.com/Ecological-Complexity-Lab/infomap_ecology_package), the `emln` [R package](https://github.com/Ecological-Complexity-Lab/emln), and a stand-alone [Infomap file](https://infomapecology.ecomplab.com/installation).
**Installation instructions for both packages and the Infomap file are available here:**