distance_to_centroid: Distance to group centroid

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

Distance to group centroid

Description

distance_to_centroid calculates the distance 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

distance_to_centroid(
  DT = NULL,
  coords = NULL,
  group = "group",
  return_rank = FALSE,
  ties.method = 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.
group	group column name, generated by group_pts, default 'group'
return_rank	boolean if rank distance should also be returned, default FALSE
ties.method	see ?data.table::frank

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. The return_rank argument controls if the rank of each individual's distance to the group centroid is also returned. The ties.method argument is passed to data.table::frank, see details at ?data.table::frank.

Value

distance_to_centroid returns the input DT appended with a distance_centroid column indicating the distance to group centroid and, optionally, a rank_distance_centroid column indicating the within group rank distance to group centroid (if return_rank = TRUE).

A message is returned when distance_centroid and optional rank_distance_centroid columns already exist in the input DT, because they will be overwritten.

References

See examples of using distance to group centroid:

• https://doi.org/10.1016/j.anbehav.2021.08.004

• https://doi.org/10.1111/eth.12336

• https://doi.org/10.1007/s13364-018-0400-2

See Also

centroid_group, group_pts

Other Distance functions: direction_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 distance to group centroid
distance_to_centroid(
  DT,
  coords = c('X', 'Y'),
  group = 'group',
  return_rank = TRUE
)

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