| Title: | Processing Collective Movement Data |
|---|---|
| Description: | Function library for processing collective movement data (e.g. fish schools, ungulate herds, baboon troops) collected from GPS trackers or computer vision tracking software. |
| Authors: | Simon Garnier [aut, cre] |
| Maintainer: | Simon Garnier <[email protected]> |
| License: | GPL-3 |
| Version: | 0.6.0 |
| Built: | 2025-01-16 04:08:20 UTC |
| Source: | https://github.com/swarm-lab/swarm |
This package contains functions to facilitate and automate the analysis of collective animal movement data.
Simon Garnier, [email protected]
Useful links:
Report bugs at https://github.com/swarm-lab/swaRm/issues
Given a set of Cartesian coordinates representing a polygon, this function computes the perimeter of the polygon.
.cartesian_perimeter(x, y).cartesian_perimeter(x, y)
x |
A vector of x coordinates. |
y |
A vector of y coordinates. |
Simon Garnier, [email protected]
Given a set of headings and locations, this function returns the rotational order of the set
.cartesianPerimeter(x, y) rot_order(x, y, h) rotOrder(h, x, y).cartesianPerimeter(x, y) rot_order(x, y, h) rotOrder(h, x, y)
x |
A vector of x (or longitude) coordinates. |
y |
A vector of y (or latitude) coordinates. |
h |
A vector of headings (in radians). |
A single value between 0 and 1 corresponding to the rotational order parameter of the group.
Simon Garnier, [email protected]
x <- rnorm(25) y <- rnorm(25, sd = 3) h <- runif(25, 0, 2 * pi) rot_order(x, y, h)x <- rnorm(25) y <- rnorm(25, sd = 3) h <- runif(25, 0, 2 * pi) rot_order(x, y, h)
This function computes the confidence ellipse of a set of bivariate coordinates.
.ellipse(x, y, level = 0.95).ellipse(x, y, level = 0.95)
x |
A vector of x coordinates. |
y |
A vector of y coordinates. |
level |
The confidence level of the ellipse. |
Simon Garnier, [email protected]
Given a set of locations defining a trajectory, this function approximates their instantaneous angular accelerations computed as the difference between successive angular speeds.
ang_acc(x, y, t, geo = FALSE) angAcc(x, y, t, geo = FALSE)ang_acc(x, y, t, geo = FALSE) angAcc(x, y, t, geo = FALSE)
x |
A vector of x (or longitude) coordinates corresponding to a single trajectory. |
y |
A vector of y (or latitude) coordinates corresponding to a single trajectory. |
t |
A vector of timestamps corresponding to a single trajectory. |
geo |
A logical value indicating whether the locations are defined by geographic coordinates (pairs of longitude/latitude values). Default: FALSE. |
A vector of the same length as x, y and t corresponding to the approximated instantaneous angular accelerations along the trajectory.
Simon Garnier, [email protected]
x <- rnorm(25) y <- rnorm(25, sd = 3) t <- as.POSIXct(1:25, origin = Sys.time()) ang_acc(x, y, t)x <- rnorm(25) y <- rnorm(25, sd = 3) t <- as.POSIXct(1:25, origin = Sys.time()) ang_acc(x, y, t)
Given a set of locations defining a trajectory, this function approximates their instantaneous instantaneous angular speeds computed as the difference between successive headings divided by the time between these successive headings.
ang_speed(x, y, t, geo = FALSE) angSpeed(x, y, t, geo = FALSE)ang_speed(x, y, t, geo = FALSE) angSpeed(x, y, t, geo = FALSE)
x |
A vector of x (or longitude) coordinates corresponding to a single trajectory. |
y |
A vector of y (or latitude) coordinates corresponding to a single trajectory. |
t |
A vector of timestamps corresponding to a single trajectory. |
geo |
A logical value indicating whether the locations are defined by geographic coordinates (pairs of longitude/latitude values). Default: FALSE. |
A vector of the same length as x, y and t corresponding to the approximated instantaneous angular speeds along the trajectory.
Simon Garnier, [email protected]
x <- rnorm(25) y <- rnorm(25, sd = 3) t <- as.POSIXct(1:25, origin = Sys.time()) ang_speed(x, y, t)x <- rnorm(25) y <- rnorm(25, sd = 3) t <- as.POSIXct(1:25, origin = Sys.time()) ang_speed(x, y, t)
This function computes the centroid (or center of mass) of a set of x-y (or longitude-latitude) coordinates.
centroid(x, y, robust = FALSE, geo = FALSE)centroid(x, y, robust = FALSE, geo = FALSE)
x |
A vector of x (or longitude) coordinates. |
y |
A vector of y (or latitude) coordinates. |
robust |
A logical value indicating whether to compute the centroid as a simple average of the coordinates (FALSE, the default), or as the average of the coordinates weighted by the inverse of their mean pairwise distance to all other coordinates in the set (TRUE). |
geo |
A logical value indicating whether the locations are defined by geographic coordinates (pairs of longitude/latitude values). Default: FALSE. |
A two-element list corresponding to the location of the centroid.
Simon Garnier, [email protected]
x <- rnorm(25) y <- rnorm(25, sd = 3) centroid(x, y)x <- rnorm(25) y <- rnorm(25, sd = 3) centroid(x, y)
Given a set of locations, this function determines the surface area of the convex hull (or envelope) of the set.
chull_area(x, y, geo = FALSE) chullArea(x, y, geo = FALSE)chull_area(x, y, geo = FALSE) chullArea(x, y, geo = FALSE)
x |
A vector of x (or longitude) coordinates. |
y |
A vector of y (or latitude) coordinates. |
geo |
A logical value indicating whether the locations are defined by
geographic coordinates (pairs of longitude/latitude values). If |
A single numeric value corresponding to the surface area of the
convex hull (in square meters if geo is TRUE).
Simon Garnier, [email protected]
x <- rnorm(25) y <- rnorm(25, sd = 3) chull_area(x, y)x <- rnorm(25) y <- rnorm(25, sd = 3) chull_area(x, y)
Given a set of locations, this function determines the perimeter of the convex hull (or envelope) of the set.
chull_perimeter(x, y, geo = FALSE) chullPerimeter(x, y, geo = FALSE)chull_perimeter(x, y, geo = FALSE) chullPerimeter(x, y, geo = FALSE)
x |
A vector of x (or longitude) coordinates. |
y |
A vector of y (or latitude) coordinates. |
geo |
A logical value indicating whether the locations are defined by
geographic coordinates (pairs of longitude/latitude values). If |
A single numeric value corresponding to the perimeter of the convex
hull (in meters if geo is TRUE).
Simon Garnier, [email protected]
x <- rnorm(25) y <- rnorm(25, sd = 3) chull_perimeter(x, y)x <- rnorm(25) y <- rnorm(25, sd = 3) chull_perimeter(x, y)
Given a set of x-y (or longitude-latitude) coordinates, this function computes their respective distance to the centroid (or center of mass) of the set.
dist2centroid(x, y, robust = FALSE, geo = FALSE)dist2centroid(x, y, robust = FALSE, geo = FALSE)
x |
A vector of x (or longitude) coordinates. |
y |
A vector of y (or latitude) coordinates. |
robust |
A logical value indicating whether to compute the centroid as a simple average of the coordinates (FALSE, the default), or as the average of the coordinates weighted by the inverse of their mean pairwise distance to all other coordinates in the set (TRUE). |
geo |
A logical value indicating whether the locations are defined by geographic coordinates (pairs of longitude/latitude values). Default: FALSE. |
A vector of the same length as x and y corresponding to the individual distance of each point to the centroid of the set.
Simon Garnier, [email protected]
x <- rnorm(25) y <- rnorm(25, sd = 3) dist2centroid(x, y)x <- rnorm(25) y <- rnorm(25, sd = 3) dist2centroid(x, y)
Given a set of locations defining a trajectory, this function approximates their instantaneous headings computed as the direction of the vectors between successive locations along the trajectory.
heading(x, y, geo = FALSE)heading(x, y, geo = FALSE)
x |
A vector of x (or longitude) coordinates corresponding to a single trajectory. |
y |
A vector of y (or latitude) coordinates corresponding to a single trajectory. |
geo |
A logical value indicating whether the locations are defined by geographic coordinates (pairs of longitude/latitude values). Default: FALSE. |
A vector of the same length as x and y corresponding to the approximated headings along the trajectory.
Simon Garnier, [email protected]
x <- rnorm(25) y <- rnorm(25, sd = 3) heading(x, y)x <- rnorm(25) y <- rnorm(25, sd = 3) heading(x, y)
Given a set of locations, this function determines which locations belongs to the convex hull (or envelope) of the set.
is_chull(x, y) isChull(x, y)is_chull(x, y) isChull(x, y)
x |
A vector of x (or longitude) coordinates. |
y |
A vector of y (or latitude) coordinates. |
A numerical vector of the same length as x and y.
0 indicates that the corresponding location is not part of the convex
hull of the set. Values >0 indicates that the corresponding location
is part of the convex hull, and each value corresponds to the order of the
locations along the convex hull polygon.
Simon Garnier, [email protected]
x <- rnorm(25) y <- rnorm(25, sd = 3) is_chull(x, y)x <- rnorm(25) y <- rnorm(25, sd = 3) is_chull(x, y)
Given a set of locations defining a trajectory, this function computes the linear accelerations between each pair of successive locations along the trajectory.
linear_acc(x, y, t, geo = FALSE) linAcc(x, y, t, geo = FALSE)linear_acc(x, y, t, geo = FALSE) linAcc(x, y, t, geo = FALSE)
x |
A vector of x (or longitude) coordinates corresponding to a single trajectory. |
y |
A vector of y (or latitude) coordinates corresponding to a single trajectory. |
t |
A vector of timestamps corresponding to a single trajectory. |
geo |
A logical value indicating whether the locations are defined by geographic coordinates (pairs of longitude/latitude values). Default: FALSE. |
A vector of the same length as x and y corresponding to the linear accelerations between each pair of successive locations along the trajectory.
Simon Garnier, [email protected]
x <- rnorm(25) y <- rnorm(25, sd = 3) t <- as.POSIXct(1:25, origin = Sys.time()) linear_acc(x, y, t)x <- rnorm(25) y <- rnorm(25, sd = 3) t <- as.POSIXct(1:25, origin = Sys.time()) linear_acc(x, y, t)
Given a set of locations defining a trajectory, this function computes the linear distances between each pair of successive locations along the trajectory.
linear_dist(x, y, geo = FALSE) linDist(x, y, geo = FALSE)linear_dist(x, y, geo = FALSE) linDist(x, y, geo = FALSE)
x |
A vector of x (or longitude) coordinates corresponding to a single trajectory. |
y |
A vector of y (or latitude) coordinates corresponding to a single trajectory. |
geo |
A logical value indicating whether the locations are defined by geographic coordinates (pairs of longitude/latitude values). Default: FALSE. |
A vector of the same length as x and y corresponding to the linear distances between each pair of successive locations along the trajectory.
Simon Garnier, [email protected]
x <- rnorm(25) y <- rnorm(25, sd = 3) linear_dist(x, y)x <- rnorm(25) y <- rnorm(25, sd = 3) linear_dist(x, y)
Given a set of locations defining a trajectory, this function computes the linear speeds between each pair of successive locations along the trajectory.
linear_speed(x, y, t, geo = FALSE) linSpeed(x, y, t, geo = FALSE)linear_speed(x, y, t, geo = FALSE) linSpeed(x, y, t, geo = FALSE)
x |
A vector of x (or longitude) coordinates corresponding to a single trajectory. |
y |
A vector of y (or latitude) coordinates corresponding to a single trajectory. |
t |
A vector of timestamps corresponding to a single trajectory. |
geo |
A logical value indicating whether the locations are defined by geographic coordinates (pairs of longitude/latitude values). Default: FALSE. |
A vector of the same length as x and y corresponding to the linear speeds between each pair of successive locations along the trajectory.
Simon Garnier, [email protected]
x <- rnorm(25) y <- rnorm(25, sd = 3) t <- as.POSIXct(1:25, origin = Sys.time()) linear_speed(x, y, t)x <- rnorm(25) y <- rnorm(25, sd = 3) t <- as.POSIXct(1:25, origin = Sys.time()) linear_speed(x, y, t)
Given the locations of different objects, this function determines the identity of the nearest neighboring object to each object.
nn(x, y, id, geo = FALSE)nn(x, y, id, geo = FALSE)
x |
A vector of x (or longitude) coordinates. |
y |
A vector of y (or latitude) coordinates. |
id |
A vector corresponding to the unique identities of each track. |
geo |
A logical value indicating whether the locations are defined by geographic coordinates (pairs of longitude/latitude values). Default: FALSE. |
A vector of the same length as x and y representing the identity of the nearest neighboring object to each object.
Simon Garnier, [email protected]
x <- rnorm(25) y <- rnorm(25, sd = 3) id <- 1:25 nn(x, y, id)x <- rnorm(25) y <- rnorm(25, sd = 3) id <- 1:25 nn(x, y, id)
Given the locations of different objects, this function determines the distance of the nearest neighboring object to each object.
nnd(x, y, geo = FALSE)nnd(x, y, geo = FALSE)
x |
A vector of x (or longitude) coordinates. |
y |
A vector of y (or latitude) coordinates. |
geo |
A logical value indicating whether the locations are defined by geographic coordinates (pairs of longitude/latitude values). Default: FALSE. |
A vector of the same length as x and y representing the distance to the nearest neighboring object for each object.
Simon Garnier, [email protected]
x <- rnorm(25) y <- rnorm(25, sd = 3) id <- 1:25 nnd(x, y)x <- rnorm(25) y <- rnorm(25, sd = 3) id <- 1:25 nnd(x, y)
Given a set of locations defining a trajectory, this function computes the net squared displacement of the trajectory, that is the squared distances between each location and the first location of the trajectory
nsd(x, y, geo = FALSE)nsd(x, y, geo = FALSE)
x |
A vector of x (or longitude) coordinates corresponding to a single trajectory. |
y |
A vector of y (or latitude) coordinates corresponding to a single trajectory. |
geo |
A logical value indicating whether the locations are defined by geographic coordinates (pairs of longitude/latitude values). Default: FALSE. |
A vector of the same length as x and y corresponding to the net squared distances between each location and the first location of the trajectory.
Simon Garnier, [email protected]
x <- rnorm(25) y <- rnorm(25, sd = 3) nsd(x, y)x <- rnorm(25) y <- rnorm(25, sd = 3) nsd(x, y)
Given a set of locations, this function computes the distances between each possible pair of locations.
pdist(x, y, geo = FALSE)pdist(x, y, geo = FALSE)
x |
A vector of x (or longitude) coordinates. |
y |
A vector of y (or latitude) coordinates. |
geo |
A logical value indicating whether the locations are defined by geographic coordinates (pairs of longitude/latitude values). Default: FALSE. |
A square matrix representing pairwise distances between each possible pair of locations.
Simon Garnier, [email protected]
x <- rnorm(25) y <- rnorm(25, sd = 3) pdist(x, y)x <- rnorm(25) y <- rnorm(25, sd = 3) pdist(x, y)
Given a set of headings, this function returns the polarization order of the set.
pol_order(h) polOrder(h)pol_order(h) polOrder(h)
h |
A vector of headings (in radians). |
A single value between 0 and 1 corresponding to the polarization order parameter of the group.
Simon Garnier, [email protected]
h <- runif(25, 0, 2 * pi) pol_order(h)h <- runif(25, 0, 2 * pi) pol_order(h)
Given a set of successive step lengths and turning angles, this function computes he sinuosity of a trajectory as defined by Benhamou (2004), equation 8. This is a corrected version of the sinuosity index defined in Bovet & Benhamou (1988), which is suitable for a wider range of turning angle distributions, and does not require a constant step length.
sinuosity(step_lengths, turning_angles)sinuosity(step_lengths, turning_angles)
step_lengths |
A vector of step lengths as calculated by
|
turning_angles |
A vector of turning angles as calculated by
|
A single numeric value corresponding to the sinuosity of the trajectory.
Simon Garnier, [email protected]
Benhamou, S. (2004). How to reliably estimate the tortuosity of an animal’s path: straightness, sinuosity, or fractal dimension? Journal of Theoretical Biology, 229(2), 209–220. https://doi.org/10.1016/j.jtbi.2004.03.016
Bovet, P., & Benhamou, S. (1988). Spatial analysis of animals’ movements using a correlated random walk model. Journal of Theoretical Biology, 131(4), 419–433. https://doi.org/10.1016/S0022-5193(88)80038-9
x <- rnorm(25) y <- rnorm(25, sd = 3) t <- as.POSIXct(1:25, origin = Sys.time()) step_lengths <- linear_dist(x, y) turning_angles <- ang_speed(x, y, t) sinuosity(step_lengths, turning_angles)x <- rnorm(25) y <- rnorm(25, sd = 3) t <- as.POSIXct(1:25, origin = Sys.time()) step_lengths <- linear_dist(x, y) turning_angles <- ang_speed(x, y, t) sinuosity(step_lengths, turning_angles)
Given a set of locations, this function approximates the sphericity of the set by calculating the bivariate 95 the set.
sphericity(x, y)sphericity(x, y)
x |
A vector of x coordinates. |
y |
A vector of y coordinates. |
A single numeric value corresponding to the ratio between the minor and major axis of the bivariate 95 close to 1 indicates that the set is approximately circular; a value close to 0 indicates that the set is strongly elongated.
Simon Garnier, [email protected]
x <- rnorm(25) y <- rnorm(25, sd = 3) sphericity(x, y)x <- rnorm(25) y <- rnorm(25, sd = 3) sphericity(x, y)
Given a set of locations, this function approximates the stretching direction of the set by calculating the angle of the main axis of the bivariate 95
stretch(x, y)stretch(x, y)
x |
A vector of x coordinates. |
y |
A vector of y coordinates. |
A single numeric value corresponding to the angle (in radians) of the main axis of the bivariate 95
Simon Garnier, [email protected]
x <- rnorm(25) y <- rnorm(25, sd = 3) stretch(x, y)x <- rnorm(25) y <- rnorm(25, sd = 3) stretch(x, y)