getRecursionsInPolygon.Move {recurse}

Calculates recursion information from the trajectory inside a polygon

Description

The number of revisits to a polygon is calculated as the number of segments of the trajectory passing through the polygon.

Usage

## S3 method for class 'Move'
getRecursionsInPolygon(
  trajectory,
  polygon,
  threshold = 0,
  timeunits = c("hours", "secs", "mins", "days"),
  verbose = TRUE
)

getRecursionsInPolygon(
  trajectory,
  polygon,
  threshold = 0,
  timeunits = c("hours", "secs", "mins", "days"),
  verbose = TRUE
)

## S3 method for class 'data.frame'
getRecursionsInPolygon(
  trajectory,
  polygon,
  threshold = 0,
  timeunits = c("hours", "secs", "mins", "days"),
  verbose = TRUE
)

## S3 method for class 'move2'
getRecursionsInPolygon(
  trajectory,
  polygon,
  threshold = 0,
  timeunits = c("hours", "secs", "mins", "days"),
  verbose = TRUE
)

## S3 method for class 'MoveStack'
getRecursionsInPolygon(
  trajectory,
  polygon,
  threshold = 0,
  timeunits = c("hours", "secs", "mins", "days"),
  verbose = TRUE
)

Arguments

trajectory

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)

polygon

A st_polygon object with a single convex polygon.

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

The number of segments of the trajectory passing through the polygon is counted as the number of revisits. For each revisit, the time spent inside the polygon 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 polygon is calculated by assuming linear movement at a constant speed between the points inside and outside the polygon. Note the polygon must be convex as described in further detail below.

Projection. Consider the projection used. Since segments are counted passing through the polygon, an equal area projection would ensure similar size comparisons. A geographic projection is not appropriate. The projection for the polygon and the trajectory must be the same.

Polygon. The polygon must be specified as a st_polygon object. It should consist of a single polygon (i.e. st_geometry_type = POLYGON). It should further be convex, though this requirement is not enforced, calculations for non-convex polygons will not necessarily be accurate. It may be advantageous to simplify complex geometry in order to shorten the time to run. If it is necessary to use a non-convex polygon, one approach would be to split it into convex pieces that can be run one-by-one. However, some visits would then be double-counted and would need to be combined back together based on the entrance/exit times and sequence of trajectory locations. Multiple polygons would need to be handled with multiple calls with the output then concatenated together.

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). Multiple individuals are handled via the id column of the data.frame.

Value

A list with several components. revisits is the number of revisits to the polygon. residenceTime is the total time spent withing the polygon. radius is NA in the case of polygons. timeunits is the specified time units used to specify timespans.

When verbose = TRUE, additional information is also returned in 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 (NA and 1 in the case of polygons), 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)

• getRecursionsInPolygon(Move): Get recursions in polygon for a Move-class trajectory

• getRecursionsInPolygon(data.frame): Get recursions inside a polygon for a trajectory data.frame object consisting of columns x, y, datetime, and id

• getRecursionsInPolygon(move2): Get recursions in polygon for a move2 object (for details see vignette("programming_move2_object", package = "move2"))

• getRecursionsInPolygon(MoveStack): Get recursions in polygon for a MoveStack trajectory

Author(s)

Chloe Bracis <[e-mail]>

See Also

getRecursions

Examples

if (requireNamespace("sf")) 
{
    data(track)
    poly = sf::st_polygon(list(cbind(c(4,6,6,3,4), c(1,2,4,3,1))))
    poly = sf::st_sfc(poly, crs = "EPSG:3410")
    revisits = getRecursionsInPolygon(track, poly)
}