direction_to_leader: Direction to group leader

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

Direction to group leader

Description

direction_to_leader calculates the direction to the leader of each spatiotemporal group. The function accepts a data.table with relocation data appended with a rank_position_group_direction column indicating the ranked position along the group direction generated with leader_direction_group(return_rank = TRUE). Relocation data should be in planar coordinates provided in two columns representing the X and Y coordinates.

Usage

direction_to_leader(DT = NULL, coords = NULL, group = "group")

Arguments

DT	input data.table with 'rank_position_group_direction' column generated by leader_direction_group and group column generated by group_pts
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'

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 rank_position_group_direction column generated with leader_direction_group(return_rank = TRUE), a group column generated with the group_pts 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_leader returns the input DT appended with a direction_leader column indicating the direction to the group leader.

A message is returned when the direction_leader column is already exist in the input DT because it will be overwritten.

References

See examples of using direction to leader and position within group:

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

• https://doi.org/10.1016/j.beproc.2013.10.007

• https://doi.org/10.1371/journal.pone.0036567

See Also

distance_to_leader, leader_direction_group, group_pts

Other Direction functions: direction_group(), direction_polarization(), direction_step(), edge_delay()

Examples

# Load data.table
library(data.table)


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

# (Subset example data to reduce example run time)
DT <- DT[year(datetime) == 2016]

# 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 = 50, id = 'ID',
          coords = c('X', 'Y'), timegroup = 'timegroup')

# Calculate direction at each step
direction_step(
  DT = DT,
  id = 'ID',
  coords = c('X', 'Y'),
  projection = 32736
)

# Calculate group centroid
centroid_group(DT, coords = c('X', 'Y'))

# Calculate group direction
direction_group(DT)

# Calculate leader in terms of position along group direction
leader_direction_group(
  DT,
  coords = c('X', 'Y'),
  return_rank = TRUE
)

# Calculate direction to leader
direction_to_leader(DT, coords = c('X', 'Y'))

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