getRecursionsAtLocations: Calculates recursion information from the trajectory for...

In cbracis/recurse: Computes Revisitation Metrics for Trajectory Data

Calculates recursion information from the trajectory for specific locations

Description

A circle of radius R is drawn around each specified location. The number of revisits is calculated as the number of segments of the trajectory passing through that circle.

Usage

getRecursionsAtLocations(
  x,
  locations,
  radius,
  threshold = 0,
  timeunits = c("hours", "secs", "mins", "days"),
  verbose = TRUE
)

## S3 method for class 'data.frame'
getRecursionsAtLocations(
  x,
  locations,
  radius,
  threshold = 0,
  timeunits = c("hours", "secs", "mins", "days"),
  verbose = TRUE
)

## S3 method for class 'Move'
getRecursionsAtLocations(
  x,
  locations,
  radius,
  threshold = 0,
  timeunits = c("hours", "secs", "mins", "days"),
  verbose = TRUE
)

## S3 method for class 'move2'
getRecursionsAtLocations(
  x,
  locations,
  radius,
  threshold = 0,
  timeunits = c("hours", "secs", "mins", "days"),
  verbose = TRUE
)

## S3 method for class 'MoveStack'
getRecursionsAtLocations(
  x,
  locations,
  radius,
  threshold = 0,
  timeunits = c("hours", "secs", "mins", "days"),
  verbose = TRUE
)

Arguments

x	Either a data frame, move2, Move-class, or MoveStack object. For a data frame, the trajectory data with four columns (the x-coordinate, the y-coordinate, the datetime, and the animal id).
locations	A data frame with x and y locations at which to calculate the recursions.
radius	numeric radius to use in units of the (x,y) location data to detect recursions.
threshold	a time difference (in units timeunits) to ignore excursions outside the radius. Defaults to 0.
timeunits	character string specifying units to calculate time differences in for the time spans inside the radius and since the visit in revisitStats. Defaults to hours.
verbose	TRUE to output complete information (can be large for large input data frames) or FALSE to output basic information.

Details

For specified location, a circle of radius R is drawn around that point. This method differs from getRecursions in that only specified locations are used, rather than all points in the trajectory. Then the number of segments of the trajectory passing through that circle is counted. This is the number of revisits to that location. For each revisit, the time spent inside the circle is calculated, as well as the time since the last visit (NA for the first visit). In order to calculate the time values, the crossing time of the radius is calculated by assuming linear movement at a constant speed between the points inside and outside the circle.

Projection. Consider the projection used. Since segments are counted passing through circles drawn around points, an equal area projection would ensure similar size comparisons (e.g., spTransform).

Either single or multiple individuals are supported, but be aware that this function will be slow with large amounts of data (e.g. millions of points), so consider pre-specifying the locations (getRecursionsAtLocations) or use clustering. Multiple individuals are handled via the id column of the data.frame or using a move2 or MoveStack object.

Value

A list with several components, revisits and residenceTime are vectors of the same length as the x dataframe. revisits is the number of revisits for each location, where 1 means that there were no revisits, only the initial visit. residenceTime is the total time spent withing the radius. radius is the specified radius used for all the calculations. timeunits is the specified time units used to specify timespans.

When verbose = TRUE, additional information is also returned, dists and revisitStats. Next, dists gives the distance matrix between all locations. Finally, revisitStats gives further statistics on each visit. These are calculated per location (i.e., no aggregation of nearby points is performed), and give the index and location of the point of the track at the center of the radius, the radius entrance and exit time of the track for that visit, how much time was spent inside the radius, and how long since the last visit (NA for the first visit).

Methods (by class)

• getRecursionsAtLocations(data.frame): Get recursions at specified locations for a data.frame object

• getRecursionsAtLocations(Move): Get recursions at specified locations for a Move-class object

• getRecursionsAtLocations(move2): Get recursions at specified locations for a move2 object (for details see vignette("programming_move2_object", package = "move2"))

• getRecursionsAtLocations(MoveStack): Get recursions at specified locations for a MoveStack object

Author(s)

Chloe Bracis <[e-mail]>

See Also

getRecursions

Examples

data(martin)
locations = data.frame(x = c(-10, 0, 20), y = c(5, 0, 0))
revisits = getRecursionsAtLocations(martin, locations, radius = 1)
plot(revisits, locations, legendPos = c(10, -15), 
     alpha = 1, pch = 17, xlim = range(martin$x), ylim = range(martin$y))
points(martin$x, martin$y, pch = ".", col = "gray50")
drawCircle(10, -10, 1)

cbracis/recurse documentation built on July 23, 2024, 5:18 a.m.