fusion_id: Fission-fusion events

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

Fission-fusion events

Description

fusion_id identifies fusion events in distance based edge lists. The function accepts a distance based edge list generated by edge_dist, a threshold argument and arguments controlling how fusion events are defined.

Usage

fusion_id(
  edges = NULL,
  threshold = 50,
  n_min_length = 0,
  n_max_missing = 0,
  allow_split = FALSE
)

Arguments

edges	distance based edge list generated by edge_dist function, with dyad ID generated by dyad_ID
threshold	spatial distance threshold in the units of the projection
n_min_length	minimum length of fusion events
n_max_missing	maximum number of missing observations within a fusion event
allow_split	boolean defining if a single observation can be greater than the threshold distance without initiating fission event

Details

The edges must be a data.table returned by the edge_dist function. In addition, fusion_id requires a dyad ID set on the edge list generated by dyad_id. If your data is a data.frame, you can convert it by reference using data.table::setDT.

The threshold must be provided in the units of the coordinates. The threshold must be larger than 0. The coordinates must be planar coordinates (e.g.: UTM). In the case of UTM, a threshold = 50 would indicate a 50 m distance threshold.

The n_min_length argument defines the minimum number of successive fixes that are required to establish a fusion event. The n_max_missing argument defines the the maximum number of allowable missing observations for the dyad within a fusion event. The allow_split argument defines if a single observation can be greater than the threshold distance without initiating fission event.

Value

fusion_id returns the input edges appended with a fusionID column.

This column represents the fusion event id. As with spatsoc's grouping functions, the actual value of fusionID is arbitrary and represents the identity of a given fusion event. If the data was reordered, the fusionID may change, but the membership of each fusion event would not.

A message is returned when a column named fusionID already exists in the input edges, because it will be overwritten.

References

See examples of identifying fission-fusion events with spatiotemporal data:

• https://doi.org/10.1111/ele.12457

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

• https://doi.org/10.1890/08-0345.1

See Also

edge_dist

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

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

dyad_id(edges, 'ID1', 'ID2')

fusion_id(
  edges = edges,
  threshold = 100,
  n_min_length = 1,
  n_max_missing = 0,
  allow_split = FALSE
  )

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