% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/edge_alignment.R
\name{edge_alignment}
\alias{edge_alignment}
\title{Directional alignment based edge-lists}
\usage{
edge_alignment(
  DT = NULL,
  id = NULL,
  direction = "direction",
  timegroup = "timegroup",
  group = NULL,
  splitBy = NULL,
  signed = FALSE
)
}
\arguments{
\item{DT}{input data.table}

\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.}

\item{timegroup}{character string of timegroup column name, default "timegroup"}

\item{group}{(optional) character string of group column name, used to restrict
the calculation of directional alignment to within spatiotemporal groups}

\item{splitBy}{(optional) vector of column names indicating subgroups within
which the direction alignment will be calculated}

\item{signed}{logical if signed difference should be returned, default FALSE}
}
\value{
\code{edge_alignment} returns a \code{data.table} with columns ID1, ID2,
timegroup, and a 'direction_diff' column indicating the difference in direction
between ID1 and ID2 in radians, along with any columns provided in splitBy.

Note: unlike many other functions (eg. \code{group_pts}) in \code{spatsoc},
\code{edge_alignment} needs to be reassigned. See details in
\href{https://docs.ropensci.org/spatsoc/articles/faq.html}{FAQ}.
}
\description{
\code{edge_alignment} returns edge-lists defined by directional alignment
(difference in movement direction) between individuals. The function expects
a \code{data.table} with relocation data and individual identifiers, a
direction column (generated by \code{direction_step}) and timegroup column
(generated by \code{group_times}).
}
\details{
The \code{DT} 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()}}.

The \code{id}, \code{direction}, \code{timegroup}, and optional \code{group}
and \code{splitBy} arguments expect the names of a column in \code{DT} which
correspond to the individual identifier, direction (generated by
\code{direction_step}), timegroup (generated by \code{group_times}), group
(generated by \code{group_pts}) and additional grouping columns.

There are two approaches to spatially restricting the calculation of
directional alignment. The \code{group} argument can be used to pass the
output group column from \code{group_pts} to calculate direction alignment
within spatiotemporal groups. Alternatively, the output of
\code{edge_alignment} can be merged with the output of \code{edge_dist} to
compare the difference in direction to the distance between individuals.

The \code{splitBy} argument offers further control over the calculation of
directional alignment.  If within your \code{DT}, you have multiple
populations, subgroups or other distinct parts, you can provide the name of
the column which identifies them to \code{splitBy}. \code{edge_alignment}
will only consider rows within each \code{splitBy} subgroup.
}
\examples{
# Load data.table
library(data.table)
\dontshow{
data.table::setDTthreads(1)
}

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

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

# Calculate directional alignment edge-list
align <- edge_alignment(
  DT,
  id = 'ID',
  signed = FALSE
)

# Or, calculate directional alignment within spatiotemporal groups
group_pts(DT, threshold = 5, id = 'ID',
          coords = c('X', 'Y'), timegroup = 'timegroup')

align_group <- edge_alignment(
  DT,
  id = 'ID',
  group = 'group',
  signed = FALSE
)

# Or, using the new geometry interface
get_geometry(DT, coords = c('X', 'Y'), crs = 32736)
group_pts(DT, threshold = 5, id = 'ID', timegroup = 'timegroup')
direction_step(DT, id = 'ID')
align_group <- edge_alignment(
  DT,
  id = 'ID',
  group = 'group',
  signed = FALSE
)
}
\references{
See examples of using directional alignment:
\itemize{
\item \doi{doi:10.1098/rsif.2013.0529}
\item \doi{doi:10.1016/j.beproc.2021.104473}
\item \doi{doi:10.1126/science.aaa5099}
}
}
\seealso{
Other Edge-list generation: 
\code{\link{edge_delay}()},
\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_delay}()},
\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}
