% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/edge_direction.R
\name{edge_direction}
\alias{edge_direction}
\title{Direction based edge-lists}
\usage{
edge_direction(
  edges = NULL,
  DT = NULL,
  id = NULL,
  coords = NULL,
  crs = NULL,
  timegroup = "timegroup",
  geometry = "geometry",
  projection = NULL
)
}
\arguments{
\item{edges}{edge-list generated generated by \code{edge_dist} or
\code{edge_nn}, with dyad ID column generated by \code{dyad_id}}

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

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

\item{coords}{character vector of X coordinate and Y coordinate column names.
Note: the order is assumed X followed by Y column names}

\item{crs}{numeric or character defining the coordinate reference
system to be passed to \link[sf:st_crs]{sf::st_crs}. For example, either
\code{crs = "EPSG:32736"} or \code{crs = 32736}. Used only if coords are provided,
see details under Interface}

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

\item{geometry}{simple feature geometry list column name, generated by
\code{\link[=get_geometry]{get_geometry()}}. Default 'geometry', see details under Interface}

\item{projection}{(deprecated) use crs argument instead}
}
\value{
\code{\link[=edge_direction]{edge_direction()}} returns the input \code{edges} appended with a
"direction_dyad" column representing the direction between ID1 and ID2 in
radians. A value of NaN is returned when the coordinates of ID1 equal the
coordinates of ID2.

If the "direction" column is found in input DT, it will be retained for ID1
in the output for use in downstream functions (eg. \code{\link[=edge_zones]{edge_zones()}}).

Missing values in coordinates / geometry are ignored and NA is returned.

Note: due to the merge required within this function, the output needs to
be reassigned unlike some other \code{spatsoc} functions like \code{\link[=dyad_id]{dyad_id()}} and
\code{\link[=group_pts]{group_pts()}}. See details in
\href{https://docs.ropensci.org/spatsoc/articles/faq.html}{FAQ}.
}
\description{
\code{\link[=edge_direction]{edge_direction()}} returns edge lists defined by the direction between
individuals. The function expects a distance based edge-list generated by
\code{edge_nn} or \code{\link[=edge_dist]{edge_dist()}} and a \code{data.table} with relocation data appended
with a \code{timegroup} column from \code{\link[=group_times]{group_times()}}. It is required to use the
argument \code{fillNA = FALSE} for \code{\link[=edge_dist]{edge_dist()}} to ensure there are no NAs in the
coordinate columns. Relocation data should be in two columns representing the
X and Y coordinates, or in a geometry column prepared by the helper function
\code{\link[=get_geometry]{get_geometry()}}.
}
\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()}} or by reassigning
using \code{\link[data.table:data.table]{data.table::data.table()}}.

The \code{edges} and \code{DT} are internally merged in this function using the columns
\code{id} / \code{ID1} and \code{ID2}, \code{timegroup}. The \code{id}, and \code{timegroup} arguments
expect the names of columns which correspond to the ID, and timegroup
columns in \code{DT}.

See below under "Interface" for details on providing coordinates and under
"Direction function" for details on the underlying direction function used.
}
\section{Interface}{

Two interfaces are available for providing coordinates:
\enumerate{
\item Provide \code{coords} and \code{crs}. The \code{coords} argument expects the names of
the X and Y coordinate columns. The \code{crs} argument expects a character
string or numeric defining the coordinate reference system to be passed to
\link[sf:st_crs]{sf::st_crs}. For example, for UTM zone 36S (EPSG 32736), the crs argument
is \code{crs = "EPSG:32736"} or \code{crs = 32736}. See \url{https://spatialreference.org}
for a list of EPSG codes.
\item (New!) Provide \code{geometry}. The \code{geometry} argument allows the user to
supply a \code{geometry} column that represents the coordinates as a simple
feature geometry list column. This interface expects the user to prepare
their input DT with \code{\link[=get_geometry]{get_geometry()}}. To use this interface, leave the
\code{coords} and \code{crs} arguments \code{NULL}, and the default argument for \code{geometry}
('geometry') will be used directly.
}
}

\section{Direction function}{


The underlying distance function used depends on the crs of the coordinates
or geometry provided.
\itemize{
\item If the crs is provided and longlat degrees (as determined by
\code{\link[sf:st_is_longlat]{sf::st_is_longlat()}}), the distance function is
\code{\link[lwgeom:st_geod_azimuth]{lwgeom::st_geod_azimuth()}}.
\item If the crs is provided and not longlat degrees (eg. a projected UTM),
the coordinates or geometry are transformed to \code{sf::st_crs(4326)} before the
distance is measured using \code{\link[lwgeom:st_geod_azimuth]{lwgeom::st_geod_azimuth()}}.
\item If the crs is NULL or NA_crs_, the distance function cannot be used
and an error is returned.
}
}

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

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

# Direction based edge-lists
dyad_directions <- edge_direction(
  edges,
  DT,
  id = 'ID',
  coords = c('X', 'Y'),
  crs = 32736,
  timegroup = 'timegroup'
)

print(dyad_directions)

# Or, using the new geometry interface
get_geometry(DT, coords = c('X', 'Y'), crs = 32736)
dyad_directions <- edge_direction(
  edges,
  DT,
  id = 'ID',
  timegroup = 'timegroup'
)
}
\references{
See examples of measuring the direction between individuals:
\itemize{
\item \doi{doi:10.1098/rsif.2013.0529}
\item \doi{doi:10.1098/rstb.2019.0380}
\item \doi{doi:10.1111/jfb.15315}
}
}
\seealso{
\link{dyad_id}, \link{edge_dist}, \link{edge_nn}, \link{group_times},
\code{\link[lwgeom:st_geod_azimuth]{lwgeom::st_geod_azimuth()}}

Other Edge-list generation: 
\code{\link{edge_alignment}()},
\code{\link{edge_delay}()},
\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_delay}()},
\code{\link{edge_zones}()},
\code{\link{leader_direction_group}()},
\code{\link{leader_edge_delay}()}
}
\concept{Direction functions}
\concept{Edge-list generation}
