centroid_dyad: Dyad centroid

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

Dyad centroid

Description

centroid_dyad calculates the centroid (mean location) of a dyad in each observation identified by edge_nn or edge_dist. The function accepts an edge list generated by edge_nn or edge_dist and a data.table with relocation data appended with a timegroup column from group_times. It is recommended to use the argument fillNA = FALSE for edge_dist when using centroid_dyad to avoid unnecessarily merging additional rows. Relocation data should be in two columns representing the X and Y coordinates.

Usage

centroid_dyad(
  edges = NULL,
  DT = NULL,
  id = NULL,
  coords = NULL,
  timegroup = "timegroup",
  na.rm = FALSE
)

Arguments

edges	edge list generated generated by edge_dist or edge_nn, with dyad ID column generated by dyad_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
id	character string of ID column name
coords	character vector of X coordinate and Y coordinate column names. Note: the order is assumed X followed by Y column names.
timegroup	timegroup field in the DT within which the grouping will be calculated
na.rm	if NAs should be removed in calculating mean location, see rowMeans

Details

The edges and DT must be 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 edges and DT are internally merged in this function using the columns id, dyadID and timegroup. This function expects a dyadID present, generated with the dyad_id function. The dyadID and timegroup arguments expect the names of a column in edges which correspond to the dyadID and timegroup columns. The id and timegroup arguments expect the names of a column in DT which correspond to the X and Y coordinates and group columns. The na.rm argument is passed to the rowMeans function to control if NA values are removed before calculation.

Value

centroid_dyad returns the input edges appended with centroid columns for the X and Y coordinate columns.

These columns represents the centroid coordinate columns for the dyad. The naming of these columns will correspond to the provided coordinate column names prefixed with "centroid_".

Note: due to the merge required within this function, the output needs to be reassigned unlike some other spatsoc functions like dyad_id and group_pts.

A message is returned when centroid columns are already exists in the input edges, because they will be overwritten.

See Also

dyad_id edge_dist edge_nn group_pts

Other Centroid functions: centroid_fusion(), centroid_group()

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 = FALSE
  )

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

# Calculate dyad centroid
centroids <- centroid_dyad(
  edges,
  DT,
  id = 'ID',
  coords = c('X', 'Y'),
  timegroup = 'timegroup', na.rm = TRUE
)

print(centroids)

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