direction_to_centroid: Direction to group centroid

In ropensci/spatsoc: Group Animal Relocation Data by Spatial and Temporal Relationship

Direction to group centroid

Description

direction_to_centroid calculates the direction of each relocation to the centroid of the spatiotemporal group identified by group_pts. The function accepts a data.table with relocation data appended with a group column from group_pts and centroid columns from centroid_group. Relocation data should be in planar coordinates provided in two columns representing the X and Y coordinates.

Usage

direction_to_centroid(DT = NULL, coords = NULL)

Arguments

DT	input data.table with centroid columns generated by eg. centroid_group
coords	character vector of X coordinate and Y coordinate column names. Note: the order is assumed X followed by Y column names.

Details

The DT must be a data.table. If your data is a data.frame, you can convert it by reference using data.table::setDT or by reassigning using data.table::data.table.

This function expects a group column present generated with the group_pts function and centroid coordinate columns generated with the centroid_group function. The coords and group arguments expect the names of columns in DT which correspond to the X and Y coordinates and group columns.

Value

direction_to_centroid returns the input DT appended with a direction_centroid column indicating the direction to group centroid in radians. The direction is measured in radians in the range of 0 to 2 * pi from the positive x-axis.

A message is returned when direction_centroid column already exist in the input DT, because they will be overwritten.

References

See example of using direction to group centroid:

• https://doi.org/10.1016/j.cub.2017.08.004

See Also

centroid_group, group_pts

Other Distance functions: distance_to_centroid(), distance_to_leader()

Examples

# Load data.table
library(data.table)


# Read example data
DT <- fread(system.file("extdata", "DT.csv", package = "spatsoc"))

# Cast the character column to POSIXct
DT[, datetime := as.POSIXct(datetime, tz = 'UTC')]

# Temporal grouping
group_times(DT, datetime = 'datetime', threshold = '20 minutes')

# Spatial grouping with timegroup
group_pts(DT, threshold = 5, id = 'ID',
          coords = c('X', 'Y'), timegroup = 'timegroup')

# Calculate group centroid
centroid_group(DT, coords = c('X', 'Y'), group = 'group', na.rm = TRUE)

# Calculate direction to group centroid
direction_to_centroid(DT, coords = c('X', 'Y'))

ropensci/spatsoc documentation built on Feb. 12, 2025, 7:16 a.m.