edge_delay: Directional correlation delay based edge lists
In ropensci/spatsoc: Group Animal Relocation Data by Spatial and Temporal Relationship

edge_delay

R Documentation

Directional correlation delay based edge lists

Description

edge_delay returns edge lists defined by the directional correlation delay between individuals. The function expects a distance based edge list generated by edge_dist or edge_nn, a data.table with relocation data, individual identifiers and a window argument. The window argument is used to specify the temporal window within which to measure the directional correlation delay. Relocation data should be in two columns representing the X and Y coordinates.

Usage

edge_delay(edges, DT, window = NULL, id = NULL, direction = "direction")

Arguments

`edges`	edge list generated generated by `edge_dist` or `edge_nn`, with fusionID column generated by `fusion_id`
`DT`	input data.table with timegroup column generated with `group_times` matching the input data.table used to generate the edge list with `edge_nn` or `edge_dist`
`window`	temporal window in unit of timegroup column generated with `group_times`, eg. `window = 4` corresponds to the 4 timegroups before and after the focal observation
`id`	character string of ID column name
`direction`	character string of direction column name, default "direction"

Details

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

The edges argument expects a distance based edge list generated with edge_nn or edge_dist. The DT argument expects relocation data with a timegroup column generated with group_times.

The rows in edges and DT are internally matched in edge_delay using the columns timegroup (from group_times) and ID1 and ID2 (in edges, from dyad_id) with id (in DT). This function expects a fusionID present, generated with the fusion_id function, and a dyadID present, generated with the dyad_id function. The id, and direction arguments expect the names of a column in DT which correspond to the id, and direction columns.

Value

edge_delay returns the input edges appended with a 'dir_corr_delay' column indicating the temporal delay (in units of timegroups) at which ID1's direction of movement is most similar to ID2's direction of movement, within the temporal window defined. For example, if focal individual 'A' moves in a 45 degree direction at time 2 and individual 'B' moves in a most similar direction within the window at time 5, the directional correlation delay between A and B is 3. Positive values of directional correlation delay indicate a directed leadership edge from ID1 to ID2.

References

The directional correlation delay is defined in Nagy et al. 2010 (https://doi.org/10.1038/nature08891).

See examples of measuring the directional correlation delay:

Examples

# Load data.table
library(data.table)


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

# Select only individuals A, B, C for this example
DT <- DT[ID %in% c('A', 'B', 'C')]

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

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

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

# Distance based edge list generation
edges <- edge_dist(
  DT,
  threshold = 100,
  id = 'ID',
  coords = c('X', 'Y'),
  timegroup = 'timegroup',
  returnDist = TRUE,
  fillNA = FALSE
)

# Generate dyad id
dyad_id(edges, id1 = 'ID1', id2 = 'ID2')

# Generate fusion id
fusion_id(edges, threshold = 100)

# Directional correlation delay
delay <- edge_delay(
  edges = edges,
  DT = DT,
  window = 3,
  id = 'ID'
)

delay[, mean(dir_corr_delay, na.rm = TRUE), by = .(ID1, ID2)][V1 > 0]

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