% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/edge_nn.R
\name{edge_nn}
\alias{edge_nn}
\title{Nearest neighbour based edge-lists}
\usage{
edge_nn(
  DT = NULL,
  id = NULL,
  coords = NULL,
  timegroup,
  crs = NULL,
  splitBy = NULL,
  threshold = NULL,
  geometry = "geometry",
  returnDist = FALSE
)
}
\arguments{
\item{DT}{input data.table}

\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{timegroup}{timegroup field in the DT within which the output will be
calculated}

\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{splitBy}{(optional) character string or vector of grouping column
name(s) upon which the output will be calculated}

\item{threshold}{(optional) spatial distance threshold to set maximum
distance between an individual and their neighbour.}

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

\item{returnDist}{logical indicating if the distance between individuals
should be returned. If FALSE (default), only individual columns (and
timegroup, splitBy columns if provided) are returned. If TRUE, a column
"distance" is also returned indicating the distance between individuals in
the units of the \code{crs}, or if \code{crs = NULL} no units are set.}
}
\value{
\code{edge_nn} returns a \code{data.table}  with three columns: timegroup, ID
and NN. If 'returnDist' is TRUE, a column 'distance' is returned indicating
the distance between ID and NN.  The ID and NN columns represent the edges
defined by the nearest neighbours (and temporal thresholds with
\code{group_times}).

If an individual was alone in a timegroup or splitBy, or did not have any
neighbours within the threshold distance, they are assigned NA for nearest
neighbour.

Note: unlike many other functions (eg. \code{group_pts}) in \code{spatsoc}, \code{edge_nn}
needs to be reassigned. See details in
\href{https://docs.ropensci.org/spatsoc/articles/faq.html}{FAQ}.
}
\description{
\code{edge_nn} returns edge-lists defined by the nearest neighbour. The function
expects a \code{data.table} with relocation data, individual identifiers and a
threshold argument. The threshold argument is used to specify the criteria
for distance between points which defines a group. 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{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{timegroup} (and optional \code{splitBy}) arguments expect the names of
columns in \code{DT} which correspond to the individual identifier, and timegroup
(generated by \code{group_times}) and additional grouping columns.

If a \code{threshold} is provided, it should match the units of the coordinates.
The \code{threshold} can be provided with units specified using the units package
(eg. \code{threshold = units::set_units(10, m)}) which will be checked against the
units of the coordinates using the \code{crs}. If units are not specified, the
\code{threshold} is assumed to be in the units of the coordinates.

The \code{timegroup} argument is required to define the temporal groups within
which edge nearest neighbours are calculated. The intended framework is to
group rows temporally with \code{group_times} then spatially with \code{edge_nn}. If
you have already calculated temporal groups without \code{group_times}, you can
pass this column to the \code{timegroup} argument. Note that the expectation is
that each individual will be observed only once per timegroup. Caution that
accidentally including huge numbers of rows within timegroups can overload
your machine since all pairwise distances are calculated within each
timegroup.

The \code{splitBy} argument offers further control over grouping. 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_nn} will only consider rows within each \code{splitBy} subgroup.

See below under "Interface" for details on providing coordinates and under
"Distance function" for details on underlying distance 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{Distance function}{


The underlying distance function used depends on the crs of the coordinates
or geometry provided.
\itemize{
\item If the crs is longlat degrees (as determined by
\code{\link[sf:st_is_longlat]{sf::st_is_longlat()}}), the distance function is \code{\link[sf:geos_measures]{sf::st_distance()}} which
passes to \code{\link[s2:s2_is_collection]{s2::s2_distance()}} if \code{\link[sf:s2]{sf::sf_use_s2()}} is TRUE and
\code{\link[lwgeom:geod]{lwgeom::st_geod_distance()}} if \code{\link[sf:s2]{sf::sf_use_s2()}} is FALSE. The distance
returned has units set according to the crs.
\item If the crs is not longlat degrees (eg. NULL, NA_crs_, or projected), the
distance function used is \code{\link[stats:dist]{stats::dist()}}, maintaining expected behaviour
from previous versions. The distance returned does not have units set.
}

Note: in both cases, if the coordinates are NA then the result will be NA.
}

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

# Edge-list generation
edges <- edge_nn(DT, id = 'ID', coords = c('X', 'Y'),
        timegroup = 'timegroup')

# Edge-list generation using maximum distance threshold
edges <- edge_nn(DT, id = 'ID', coords = c('X', 'Y'),
        timegroup = 'timegroup', threshold = 100)

# Edge-list generation, returning distance between nearest neighbours
edge_nn(DT, id = 'ID', coords = c('X', 'Y'),
        timegroup = 'timegroup', threshold = 100,
        returnDist = TRUE)

# Or, using the new geometry interface
get_geometry(DT, coords = c('X', 'Y'), crs = 32736)
edge_nn(DT, threshold = 100, id = 'ID', timegroup = 'timegroup', returnDist = TRUE)
}
\seealso{
Other Edge-list generation: 
\code{\link{edge_alignment}()},
\code{\link{edge_delay}()},
\code{\link{edge_direction}()},
\code{\link{edge_dist}()}

Other Distance functions: 
\code{\link{distance_to_centroid}()},
\code{\link{distance_to_leader}()},
\code{\link{edge_dist}()},
\code{\link{edge_zones}()}
}
\concept{Distance functions}
\concept{Edge-list generation}
