% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/leader_edge_delay.R
\name{leader_edge_delay}
\alias{leader_edge_delay}
\title{Leadership in directional correlation delay}
\usage{
leader_edge_delay(edges = NULL, threshold = NULL, splitBy = NULL)
}
\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{threshold}{(optional) threshold difference in direction used to subset
rows included in calculation of mean directional delay. eg.
\code{threshold = 0.5} corresponds to only rows where direction_diff is
less than 0.5. Expects that unit is radians, see \code{edge_delay}.}

\item{splitBy}{(optional) character string or vector of grouping column
name(s) upon which the mean directional correlation delay will be
calculated}
}
\value{
\code{leader_edge_delay} returns the input \code{edges} aggregated
with a \code{mean_direction_delay_dyad} column indicating the mean
directional correlation delay between ID1 and ID2 and a
\code{mean_direction_delay} column indicating the mean directional
correlation delay for each individual in 'ID1' column.

Note: since \code{leader_edge_delay} returns an aggregation of the input
\code{edges}, 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{
Given the directional correlation delay, \code{leader_edge_delay}
calculates the mean directional correlation delay for individuals in a
group to identify leadership patterns.
}
\details{
The function expects an edge-list from \code{edge_delay} with columns
'direction_delay' indicating the directional correlation delay between
individuals and 'direction_diff' indicating the unsigned difference in
movement directions at the temporal delay, columns 'ID1' and 'ID2' indicating
individuals and column 'dyadID' indicating the dyad.

The \code{edge} must be a \code{data.table}. If your data is a
\code{data.frame}, you can convert it by reference using
\code{\link[data.table:setDT]{data.table::setDT()}} or by reassigning using
\code{\link[data.table:data.table]{data.table::data.table()}}.
}
\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'
)

# Leadership from directional correlation delay
leadership <- leader_edge_delay(
  delay,
  threshold = 0.5
)
print(leadership)

# 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'
)
leadership <- leader_edge_delay(
  delay,
  threshold = 0.5
)
print(leadership)
}
\references{
See examples of measuring leadership using 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.1126/science.aap7781}
\item \doi{doi:10.1111/jfb.15315}
\item \doi{doi:10.1371/journal.pcbi.1003446}
}
}
\seealso{
\code{edge_delay}

Other Leadership functions: 
\code{\link{direction_to_leader}()},
\code{\link{leader_direction_group}()}

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_delay}()},
\code{\link{edge_direction}()},
\code{\link{edge_zones}()},
\code{\link{leader_direction_group}()}
}
\concept{Direction functions}
\concept{Leadership functions}
