direction_polarization: Polarization

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

Polarization

Description

direction_polarization calculates the polarization of individual directions in each spatiotemporal group identified by group_pts. The function expects a data.table with relocation data appended with a direction column from direction_step and a group column from group_pts.

Usage

direction_polarization(DT, direction = "direction", group = "group")

Arguments

DT	input data.table with direction column generated by direction_step and group column generated with group_pts
direction	character string of direction column name, default "direction"
group	character string of group column name, 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.

The direction and group arguments expect the names of columns in DT which correspond to the direction and group columns. The direction column is expected in units of radians and the polarization is calculated with CircStats::r.test().

Value

direction_polarization returns the input DT appended with a polarization column representing the direction polarization of all individuals in each spatiotemporal group.

The direction polarization is calculated using CircStats::r.test() which expects units of radians.

A message is returned when the polarization columns already exists in the input DT, because it will be overwritten.

References

See examples of using polarization:

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

• https://doi.org/10.1371/journal.pcbi.1009437

• https://doi.org/10.7554/eLife.19505

See Also

direction_step, group_pts, CircStats::r.test()

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

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 = 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 polarization
direction_polarization(DT)

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