Package {PhysMove}

Type:	Package
Title:	Quantifying Animal Movement and Space-Use Patterns with Statistical Physics
Version:	1.2.4
Date:	2026-07-25
Description:	Provides tools to analyse animal movement and space-use patterns from telemetry data using methods derived from statistical physics. Methods span displacement-based approaches, distribution fitting, space-use metrics (including the influence of correlations on space-use), network-based community detection, and measures of entropy and predictability. The package enables characterisation of these patterns across spatial and temporal scales, including variation within and among individuals (inter- and intraspecific analyses). Outputs include interpretable metrics and visualisations to support ecological analysis and the investigation of fundamental movement processes. For applications of these methods in ecological studies see Rodríguez et al. (2017) <doi:10.1038/s41598-017-00165-0> and Sequeira et al. (2018) <doi:10.1073/pnas.1716137115>.
License:	GPL (≥ 3)
URL:	https://github.com/HannahCalich/PhysMove
BugReports:	https://github.com/HannahCalich/PhysMove/issues
Depends:	R (≥ 4.4)
Imports:	broom (≥ 1.0.5), ggplot2 (≥ 3.4.2), graphics, grDevices, grid, methods, poweRlaw (≥ 1.0.0), RColorBrewer (≥ 1.1-3), rlang (≥ 1.1.1), rootSolve (≥ 1.8.2.3), scales (≥ 1.2.1), sf (≥ 1.0-16), stats, utils
Suggests:	emln (≥ 1.0), infomapecology (≥ 2.0.0), kableExtra (≥ 1.3.4), knitr (≥ 1.43), maps (≥ 3.4.2), officedown (≥ 0.3.0), rmarkdown (≥ 2.22), spelling (≥ 2.2.1), testthat (≥ 3.1.9)
VignetteBuilder:	knitr
Additional_repositories:	https://HannahCalich.github.io/drat
Config/Needs/check:	rcmdcheck
Config/testthat/edition:	3
Encoding:	UTF-8
Language:	en-US
LazyData:	true
LazyDataCompression:	xz
RoxygenNote:	7.3.3
NeedsCompilation:	no
Packaged:	2026-07-25 02:15:43 UTC; u1133331
Author:	Hannah J. Calich [aut, cre, cph], Jorge Rodríguez [aut], Víctor Eguíluz [aut], Ana M. M. Sequeira [aut]
Maintainer:	Hannah J. Calich <hannah.calich@gmail.com>
Repository:	CRAN
Date/Publication:	2026-08-04 14:10:24 UTC

Example output from turningAngles()

Description

Example output from the turningAngles function. Angles calculated using the tracks dataset and turningAngles() with max_hr=24. Note that the turningAngles() default is normally max_hr=240; however, this creates an unnecessarily large file for an example dataset so max_hr=24 was used instead.

Usage

angleList

Format

list

Example output from turningAngles()

Description

Example output from the turningAngles function. Angles calculated using the tracks dataset and turningAngles() default parameters.

Usage

angleListAll

Format

list

Calculate displacements

Description

This function allows you to calculate the displacement distances travelled by individuals over set time windows.

Usage

calcDisp(
  species_df,
  min_hr = 24,
  max_hr = 240,
  interval_hr = 24,
  range_hr = 6,
  verbose = FALSE
)

Arguments

Value

A list containing the displacements in km recorded for each time window. Each list element corresponds with the time windows set (i.e., the first list element is the first time window).

Examples

calcDisp(tracks, min_hr=24, max_hr=240, interval_hr=24, range_hr=6, verbose=TRUE)

Check data format This function checks the format of telemetry data prior to running PhysMove metrics.

Description

Check data format This function checks the format of telemetry data prior to running PhysMove metrics.

Usage

checkTracks(species_df, verbose = TRUE)

Arguments

Details

The columns must be formatted as follows: ref: numeric ID for each individual. lon and lat: numeric longitude and latitude in decimal degrees. day: POSIXct datetime values. Datetime format:

Value

Invisibly returns an integer error count (0 if no issues found), in addition to printing diagnostic messages/warnings.

Examples

checkTracks(tracks)

Map Infomap communities

Description

This function allows you to create a map of the level 1 Infomap communities calculated using the infomapCommunities function. To map only a selection of the communities use the subset_communities parameter.

Usage

communityMap(infomap_output, subset_communities, colours = "Dark2")

Arguments

Value

A map illustrating level 1 Infomap communities.

Examples

communityMap(infomapResult)

Identify the best-fit distribution for data

Description

This function allows you to determine if a power law, exponential, or log-normal distribution best-fit a probability density function of the input data using weighted Akaike Information Criterion (AIC). These fits use input data in conjunction with dmin and parameter values that were previously calculated with the fitDist function. By default, this function will calculate AICc scores (AIC scores corrected for small sample sizes) if n/K is <= 40 for the largest value of K, where n = sample size (nTail) and K = number of parameters in the model (see Burnham and Anderson (2004) for further details, <doi:10.1177/0049124104268644>). However, if force_AICc = TRUE AICc scores will be calculated regardless of n/K.

Usage

compDist(input, distResults, force_AICc = FALSE)

Arguments

Value

A data frame with that contains the summary statistics for each distribution fit (from the fitDist function) as well as the AICc/AIC scores and weighted AICc/AIC scores (wAICc/wAIC) for each distribution fit.

Examples

compDist(disp, distResultsAll, force_AICc=FALSE)

Example output from calcDisp()

Description

Example output from the calcDisp function. Displacements calculated using the tracks dataset and calcDisp() with max_hr=24. Note that the calcDisp() default is normally max_hr=240; however, this creates an unnecessarily large file for an example dataset so max_hr=24 was used instead.

Usage

disp

Format

list

Example output from calcDisp()

Description

Example output from the calcDisp function. Displacements calculated using the tracks dataset and calcDisp() with default parameters.

Usage

dispAll

Format

list

Example output from fitDist()

Description

Example output from the fitDist function. Full distribution fits calculated using the tracks dataset and fitDist() with full=TRUE. The first list element contains a data frame of distribution results (dmin, parameters, etc) and the second list element is a record of if the data were normalized or not, which is needed for compDist and plotDist.

Usage

distResultsAll

Format

list

Example output from fitDist() using the best-fit dmin for an exponential distribution

Description

Example output from the fitDist function. Distribution fits calculated using the tracks dataset and fitDist() with set_dmin=1.649160, which is the best-fit dmin for an exponential distribution for the tracks dataset. The first list element contains a data frame of distribution results (dmin, parameters, etc) and the second list element is a record of if the data were normalized or not, which is needed for compDist and plotDist.

Usage

distResultsExp

Format

list

Example output from fitDist()

Description

Example output from the fitDist function. Full distribution fits calculated using the tracks dataset and fitDist() with full=FALSE. The first list element contains a data frame of distribution results (dmin, parameters, etc) and the second list element is a record of if the data were normalized or not, which is needed for compDist and plotDist.

Usage

distResultsTrunc

Format

list

Entropy of trajectories

Description

This function calculates the normalised entropy of individual trajectories based on the probability distribution of location observations across grid cells. Normalised entropy scores are calculated by dividing individual entropy scores by the log number of cells each trajectory visited, providing insight to how ordered or disordered the trajectories were. Values close to 1 indicate high entropy (disordered trajectories), while values closer to 0 indicate low entropy (ordered trajectories). A pdf plot of the normalized entropy values can be created with the plotPDF function.

Usage

entropy(species_df, gridCell = 0.25, histPlot = TRUE)

Arguments

Value

Data frame of the normalised entropy values for each trajectory as well as the individual entropy values (not normalised) and the number of cells each trajectory visited. If histPlot=TRUE a histogram of the normalised entropy scores is created.

Examples

entropy(tracks, gridCell=0.25, histPlot=TRUE)

Example output from entropy()

Description

Example output from the entropy function. Results calculated using the tracks dataset with entropy() default parameters

Usage

entropyResults

Format

data.frame

Fit distributions to data

Description

This function allows you to fit power law, exponential, or lognormal distributions to a list of values (e.g., displacement data).

Usage

fitDist(
  input,
  dist = c("pl", "exp", "lnorm"),
  set_dmin = NULL,
  full = FALSE,
  normalise = TRUE
)

Arguments

Value

A list including a data frame of summary statistics for each distribution fit (first list element). Results data frame includes the distribution name, dmin (minimum value used to fit each distribution), parameter 1 (alpha, lambda, mu) and parameter 2 (NA, NA, sigma) for pl, exp, and lnorm distributions respectively, and nTail (the number of data points greater than or equal to dmin). A logical argument indicating if data were normalised is exported as the second list element because this information is needed for the compDist and plotDist functions.

Examples

fitDist(disp, dist=c("pl","exp","lnorm"), full=TRUE)

Gyration Radius

Description

This function calculates the gyration radius of individual trajectories. A pdf plot of the gyration radius values can be created with the plotPDF function.

Usage

gyrationRad(species_df, map = TRUE, mapCol = c("Black", "Red"), verbose = TRUE)

Arguments

Details

Data frame must also be sorted by ref and then day within each ref, see checkTracks for details

Value

A data frame containing the unique trajectory identifier (ref), the mean location (longitude and latitude), and the gyration radius (rG, in km) for each trajectory. If map = TRUE, a map of the gyration radius results is also produced

Examples

gyrationRad(tracks, map = TRUE, mapCol = c("Black","Red"))

Identify Infomap communities and create a transition probability matrix

Description

This function uses the network community detection Infomap to identify Infomap communities based on a transition probability matrix (tpm), which summarizes the probability of individuals moving from one grid cell to another over a set time window. This function assumes directed movement, allows for self-links (where an individual stays in the same cell over time), and uses a tpm in link list format to create an Infomap 'monolayer_object'. Note that if warnings appear about columns or rows summing to 0 this simply means an individual moved into a cell and did not leave, which is a valid movement and not cause for alarm.

Usage

infomapCommunities(
  species_df,
  gridCell = 0.25,
  hours = 24,
  range_hr = 6,
  tpm = FALSE
)

Arguments

Details

Please note: to run this function you must first download the infomapecology and emln R packages from GitHub and install the stand-alone Infomap file. For details please see: https://ecological-complexity-lab.github.io/infomap_ecology_package/installation To learn more about Infomap please visit: https://www.mapequation.org/

Example: library (infomapecology) infomapCommunities(tracks, gridCell=0.25, hours=24, range_hr=6, tpm=FALSE)

Value

A list where element 1 ('infomap_object') contains the Infomap results summarising the hierarchical structure of communities. If tpm = TRUE, element 2 ('tpm') contains the transition probability matrix used to construct the network. The transition probability matrix is returned in link list format (origin node, destination node, and transition probability).

Example output from infomapCommunities()

Description

Example output from the infomapCommunities function. Results calculated using the tracks dataset and infomapCommunities() default parameters. The first list element contains the Infomap results (i.e., an Infomap monolayer object) and the second list element (if tpm = TRUE) includes the transition probability matrix (tpm).

Usage

infomapResult

Format

list

Occupancy

Description

This function allows you to calculate the spatial occupancy patterns of location estimates and create a map. A pdf plot of the occupancy values can be created with the plotPDF function.

Usage

occupancy(
  species_df,
  gridCell = 0.25,
  map = TRUE,
  colGrad = c("blue", "lightblue", "red")
)

Arguments

Value

A data frame including occupancy values and corresponding locations (provided as the centre values of each grid cell). If map = TRUE, a map is created.

Examples

occupancy(tracks, gridCell=0.25, map=TRUE, colGrad=c("blue", "lightblue", "red"))

Example output from occupancy()

Description

Example output from the occupancy function. Results calculated using the tracks dataset and occupancy() default parameters.

Usage

occupancyResults

Format

data.frame

Plot turning angles with a circle plot

Description

This function allows you to create a circle plot illustrating the frequency of turning angles from the turningAngles function.

Usage

plotAngles(angleList, timePlot = "all", colours = rainbow, legend = TRUE)

Arguments

Value

Produces a circle plot of the angles calculated with the turningAngles function. Invisibly returns a data frame containing the values used to generate the plot, including time windows, frequencies, and angles. Assign the output to an object to access these data.

Examples

plotAngles(angleList, timePlot="all", colours=rainbow, legend=TRUE)

Create probability density function (PDF) plots of displacements

Description

This function allows you to plot probability density functions (pdfs) of displacements. Displacements must be in list format where each list element corresponds to displacements calculated over a specific time window, which is the default output format from the calcDisp function.

Usage

plotDispPDF(displacements, normalised = TRUE, colours = rainbow, legend = TRUE)

Arguments

Value

Produces probability density function (pdf) plots of displacements. Invisibly returns a data frame containing the calculated pdf values, corresponding displacements, and time window identifiers used to generate the plot. Assign the output to an object to access these data.

Examples

plotDispPDF(disp)

Plot best-fit distributions to complementary cumulative distribution function (ccdf) of data

Description

This function allows you to plot a complementary cumulative distribution function (ccdf) of values with fit lines based on distribution fits calculated with the fitDist function.

Usage

plotDist(
  input,
  distResults,
  fitLines = TRUE,
  setDist = NULL,
  colours = c("red", "gold2", "blue"),
  legend = TRUE,
  label = NULL
)

Arguments

Value

Produces a complementary cumulative distribution function (ccdf) plot of the input data with optional fit lines. Invisibly returns a data frame containing the sorted input values and corresponding ccdf values used to generate the plot. Assign the output to an object to access these data.

Examples

plotDist(disp, distResultsExp)

Plot a probability density function

Description

This function allows you to plot a probability density function (pdf).

Usage

plotPDF(result, desc = NULL, nBins)

Arguments

Value

Produces a probability density function (pdf) plot of the input data. Invisibly returns a data frame containing the values used to generate the plot. Assign the output to an object to access these data.

Examples

plotPDF(occupancyResults$Occupancy, desc="occupancy")

Plot Randomised Tracks

Description

Plot locations from original and reshuffled tracks using RandomisedLat and RandomisedLong outputs from the randomise function

Usage

plotRandomTracks(
  species_df,
  ref = NULL,
  randomResults,
  numPlot = 1:5,
  colours = c("black", "grey70"),
  tracks = TRUE,
  startCol = "red",
  endCol = "blue",
  legend = TRUE
)

Arguments

Value

Produces a plot showing the original and randomised track locations. Invisibly returns a data frame containing the randomised track data used to create the plot. Assign the output to an object to access these data.

Examples

plotRandomTracks(tracks, ref=1, randomResults=randomResults, numPlot=1)

Plot Tracks

Description

Plot species' location estimates and tracks.

Usage

plotTracks(species_df, ref = NULL, tracks = TRUE, colours = rainbow)

Arguments

Value

Map of location estimates and tracks (if tracks=TRUE).

Examples

plotTracks(tracks, ref=NULL, tracks=TRUE, colours=rainbow)

Predictability of trajectories

Description

This function allows you to calculate the limit of predictability for each trajectory based on each individual's entropy. This function requires 'indivEntropy', 'cellsVisited', and 'normalisedEntropy' from the entropy function. A pdf plot of the predictability values can be created with the plotPDF function.

Usage

predictability(species_df, entropyResults, startVal = NULL, histPlot = TRUE)

Arguments

Value

Limit of predictability values for each trajectory. If histPlot=TRUE a histogram of the limit of predictability scores is created.

Examples

predictability(tracks, entropyResults, startVal = NULL, histPlot=TRUE)

Example output from randomise()

Description

Example output from the randomise function. Results calculated using the tracks dataset and randomise() with randTrack=1. Note that the randomise() default is normally randTrack=100; however, this creates an unnecessarily large file for an example dataset so randTrack=1 was used instead.

Usage

randomResults

Format

list

Randomise tracks

Description

This function allows you to investigate the influence spatial and/or temporal correlations may have on an individuals' space use patterns. This is done by maintaining the origin and end location of each track, randomizing the order displacements occurred in between these points, and calculating how many grid cells the original and randomised tracks visited, which summarizes their space use.

Usage

randomise(species_df, randTrack = 100, gridCell = 0.25, plot = TRUE, lm = TRUE)

Arguments

Value

List containing a dataframe of results (list element 1), the randomised longitude and latitude values (list elements 2 and 3, respectively), which are needed for the plotRandomTracks function, and if lm = TRUE, the results of the linear model are output (list element 4). The dataframe of results includes columns for the number of cells visited by each original track and the average number of cells visited by the Randomised tracks for each ref. Lastly, if plot = TRUE, a plot illustrating the number of cells visited by the original and randomised tracks is created, and if lm = TRUE, a fit line and reference line are added to the plot.

Examples

randomise(tracks, randTrack=100, gridCell=0.25, plot=TRUE, lm=TRUE)

Root-Mean-Square of Displacements

Description

This function allows you to calculate root-mean-square displacements and plot them as a function of time

Usage

rms(
  species_df,
  timeUnit = "days",
  wBins = 1.1,
  plot = TRUE,
  lm = TRUE,
  strict = TRUE,
  verbose = TRUE
)

Arguments

Value

List containing a dataframe of results (list element 1) and the results of the linear model (if lm = TRUE, list element 2). The results dataframe includes the 'timeWindows' in log-sized bins along with their corresponding 'meanDisplacements' and 'rmsDisplacements' (root-mean-square displacements). If plot = TRUE, a plot of the mean displacement values and the root-mean-square displacement values against their corresponding time period is created, and if lm=TRUE, a fit line and reference line are added to the plot.#'

Examples

rms(tracks, timeUnit="days", wBins=1.1, plot=TRUE, lm=TRUE, verbose=TRUE)

Sample location data to demonstrate PhysMove functions

Description

A data frame containing location data from 25 sample trajectories.

Usage

tracks

Format

A data frame with 15623 rows and 4 variables:

ref

trajectory ID number as an integer

lon

longitude of each position estimate in decimal degrees

lat

latitude of each position estimate in decimal degrees

day

datetime stamp for each location estimate in POSIXct format

Sample location data to demonstrate PhysMove functions

Description

A data frame containing location data from 25 sample trajectories that were developed to follow a correlated random walk model using the aniMotum R package.

Usage

tracksCRW

Format

A data frame with 15623 rows and 4 variables:

ref

trajectory ID number as an integer

lon

longitude of each position estimate in decimal degrees

lat

latitude of each position estimate in decimal degrees

day

datetime stamp for each location estimate in POSIXct format

Details

Reference: https://ianjonsen.r-universe.dev/aniMotum

Calculate turning angles from trajectories

Description

This function allows you to calculate turning angles between sets of three consecutive location estimates separated by set time window(s).

Usage

turningAngles(
  species_df,
  min_hr = 24,
  max_hr = 240,
  interval_hr = 24,
  range_hr = 6,
  histPlot = c(TRUE, "all"),
  verbose = TRUE
)

Arguments

Value

List of turning angles for each time window, the name of each list element corresponds with a time window in days. If histPlot = TRUE, a histogram of results is created.

Examples

turningAngles(tracks, min_hr=24, max_hr=240, interval_hr=24, 
              range_hr=6, histPlot=c(FALSE, "all"), verbose=TRUE)