leader_direction_group: Leadership along group direction

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

Leadership along group direction

Description

Given the mean direction of a group of animals, leader_direction_group shifts the coordinate system to a new origin at the group centroid and rotates the coordinate system by the mean direction to return each individual's position along the mean direction, representing leadership in terms of the front-back position in each group's mean direction.

Usage

leader_direction_group(
  DT = NULL,
  group_direction = "group_direction",
  coords = NULL,
  group = "group",
  return_rank = FALSE,
  ties.method = "average"
)

Arguments

DT	input data.table with group direction columns generated by direction_group and centroid columns generated by centroid_group
group_direction	group_direction column name generated using direction_group, default 'group_direction'
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 function accepts a data.table with relocation data appended with a group_direction column from direction_group and group centroid columns from centroid_group. Relocation data should be in two columns representing the X and Y coordinates.

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.

The group_direction argument expects the names of columns in DT which correspond to the mean group direction generated by direction_group. The mean group direction column is expected in units of radians. The coords arguments expects the names of columns in DT which correspond to the X and Y coordinate columns. The return_rank argument controls if the rank of each individual's distance to the group centroid is also returned. If return_rank is TRUE, the group argument is required to specify the group column generated by group_pts. The ties.method argument is passed to data.table::frank, see details at ?data.table::frank.

Value

leader_direction_group returns the input DT appended with a position_group_direction column indicating the position along the group direction in the units of the projection and, optionally when return_rank = TRUE, a rank_position_group_direction column indicating the the ranked position along the group direction.

A message is returned when position_group_direction or rank_position_group_direction columns already exist in the input DT, because they will be overwritten.

References

See examples of measuring leadership along group direction (also called forefront index):

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

• https://doi.org/10.1111/jfb.15315

• https://doi.org/10.1098/rspb.2021.0839

See Also

direction_group, centroid_group

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'))

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