% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/edge_delay.R
\name{edge_delay}
\alias{edge_delay}
\title{Directional correlation delay based edge-lists}
\usage{
edge_delay(edges, DT, window = NULL, id = NULL, direction = "direction")
}
\arguments{
\item{edges}{edge-list generated generated by \code{\link[=edge_dist]{edge_dist()}} or
\code{\link[=edge_nn]{edge_nn()}}, with fusionID column generated by \code{\link[=fusion_id]{fusion_id()}}}

\item{DT}{input data.table with timegroup column generated with
\code{\link[=group_times]{group_times()}} matching the input data.table used to generate the edge
list with \code{\link[=edge_nn]{edge_nn()}} or \code{\link[=edge_dist]{edge_dist()}}}

\item{window}{temporal window in unit of timegroup column generated with
\code{group_times}, eg. \code{window = 4} corresponds to the 4 timegroups
before and after the focal observation}

\item{id}{character string of ID column name}

\item{direction}{character string of direction column name, default
"direction", expects that the unit of the direction column is radians.}
}
\value{
\code{edge_delay} returns the input \code{edges} appended with a
'direction_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, and a
'direction_diff' column indicating the absolute difference in direction.
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.

Note: due to the merge required within this function, the output needs to be
reassigned unlike some other \code{spatsoc} functions like \code{dyad_id}.
See details in \href{https://docs.ropensci.org/spatsoc/articles/faq.html}{FAQ}.
}
\description{
\code{edge_delay} returns edge-lists defined by the directional correlation
delay between individuals. The function expects a distance based edge-list
generated by \code{edge_dist} or \code{edge_nn}, a \code{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.
}
\details{
The \code{edges} and \code{DT} must be \code{data.table}s. If your data is a
\code{data.frame}, you can convert it by reference using
\code{\link[data.table:setDT]{data.table::setDT()}}.

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

The rows in \code{edges} and \code{DT} are internally matched in
\code{edge_delay} using the columns \code{timegroup} (from
\code{group_times}) and \code{ID1} and \code{ID2} (in \code{edges}, from
\code{dyad_id}) with \code{id} (in \code{DT}). This function expects a
\code{fusionID} present, generated with the \code{fusion_id} function, and a
\code{dyadID} present, generated with the \code{dyad_id} function. The
\code{id}, and \code{direction} arguments expect the names of a column in
\code{DT} which correspond to the id, and direction columns.
}
\examples{
# Load data.table
library(data.table)
\dontshow{data.table::setDTthreads(1)}

# 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'),
  crs = 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(direction_delay, na.rm = TRUE), by = .(ID1, ID2)][V1 > 0]

# Or, using the new geometry interface
get_geometry(DT, coords = c('X', 'Y'), crs = 32736)
direction_step(DT, id = 'ID')
edges <- edge_dist(DT, threshold = 100, id = 'ID', timegroup = 'timegroup', returnDist = TRUE)
dyad_id(edges, id = 'ID1', id2 = 'ID2')
fusion_id(edges, threshold = 100)
delay <- edge_delay(
  edges = edges,
  DT = DT,
  window = 3,
  id = 'ID'
)
}
\references{
The directional correlation delay is defined in Nagy et al. 2010
(\doi{doi:10.1038/nature08891}).

See examples of measuring the directional correlation delay:
\itemize{
\item \doi{doi:10.1016/j.anbehav.2013.07.005}
\item \doi{doi:10.1073/pnas.1305552110}
\item \doi{doi:10.1111/jfb.15315}
\item \doi{doi:10.1371/journal.pcbi.1003446}
}
}
\seealso{
Other Edge-list generation: 
\code{\link{edge_alignment}()},
\code{\link{edge_direction}()},
\code{\link{edge_dist}()},
\code{\link{edge_nn}()}

Other Direction functions: 
\code{\link{direction_group}()},
\code{\link{direction_polarization}()},
\code{\link{direction_step}()},
\code{\link{direction_to_centroid}()},
\code{\link{direction_to_leader}()},
\code{\link{edge_alignment}()},
\code{\link{edge_direction}()},
\code{\link{edge_zones}()},
\code{\link{leader_direction_group}()},
\code{\link{leader_edge_delay}()}
}
\concept{Direction functions}
\concept{Edge-list generation}
