% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/distance_to_centroid.R
\name{distance_to_centroid}
\alias{distance_to_centroid}
\title{Distance to group centroid}
\usage{
distance_to_centroid(
  DT = NULL,
  coords = NULL,
  group = "group",
  crs = NULL,
  return_rank = TRUE,
  ties.method = NULL,
  geometry = "geometry"
)
}
\arguments{
\item{DT}{input data.table with centroid columns generated by eg.
\code{centroid_group}}

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

\item{group}{group column name, generated by \code{group_pts}, default
'group'}

\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{return_rank}{logical if rank distance should also be returned, default
TRUE}

\item{ties.method}{see \code{\link[data.table:frank]{?data.table::frank()}}}

\item{geometry}{simple feature geometry list column name, generated by
\code{\link[=get_geometry]{get_geometry()}}. Default 'geometry', see details under Interface}
}
\value{
\code{distance_to_centroid} returns the input \code{DT} appended with a
\code{distance_centroid} column indicating the distance to the group centroid
and, optionally, a \code{rank_distance_centroid} column indicating the within
group rank distance to the group centroid (if \code{return_rank = TRUE}).

A message is returned when \code{distance_centroid} and optional
\code{rank_distance_centroid} columns already exist in the input \code{DT}, because
they will be overwritten.

See details for appending outputs using modify-by-reference in the
\href{https://docs.ropensci.org/spatsoc/articles/faq.html}{FAQ}.
}
\description{
\code{distance_to_centroid} calculates the distance of each relocation to the
centroid of the spatiotemporal group identified by \code{group_pts}. The function
expects a \code{data.table} with relocation data appended with a \code{group} column
from \code{group_pts} and centroid columns from \code{centroid_group}. Relocation data
should be provided 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()}} or by reassigning using
\code{\link[data.table:data.table]{data.table::data.table()}}.

This function expects a \code{group} column present generated with the \code{group_pts}
function and centroid coordinate column(s) generated with the
\code{centroid_group} function. The \code{group} arguments expect the names of columns
in \code{DT} which correspond to the group column. The \code{return_rank} argument
controls if the rank of each individual's distance to the group centroid is
also returned. The \code{ties.method} argument is passed to \code{data.table::frank},
see details at \code{\link[data.table:frank]{?data.table::frank()}}.

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"))
\dontshow{
# (Subset example data to reduce runtime on CRAN)
if (isFALSE(rlang::is_interactive())) {
  DT <- DT[as.Date(datetime) == '2017-01-17']
}
}
# Cast the character column to POSIXct
DT[, datetime := as.POSIXct(datetime, tz = 'UTC')]

# Temporal grouping
group_times(DT, datetime = 'datetime', threshold = '20 minutes')

# Spatial grouping with timegroup
group_pts(DT, threshold = 5, id = 'ID',
          coords = c('X', 'Y'), timegroup = 'timegroup')

# Calculate group centroid
centroid_group(DT, coords = c('X', 'Y'), group = 'group')

# Calculate distance to group centroid
distance_to_centroid(
  DT,
  coords = c('X', 'Y'),
  group = 'group',
)

# Or, using the new geometry interface
get_geometry(DT, coords = c('X', 'Y'), crs = 32736)
group_pts(DT, threshold = 5, id = 'ID', timegroup = 'timegroup')
centroid_group(DT)
direction_to_centroid(DT)
}
\references{
See examples of using distance to group centroid:
\itemize{
\item \doi{doi:10.1016/j.anbehav.2021.08.004}
\item \doi{doi:10.1111/eth.12336}
\item \doi{doi:10.1007/s13364-018-0400-2}
}
}
\seealso{
\link{centroid_group}, \link{group_pts}, \code{\link[sf:geos_measures]{sf::st_distance()}}

Other Distance functions: 
\code{\link{distance_to_leader}()},
\code{\link{edge_dist}()},
\code{\link{edge_nn}()},
\code{\link{edge_zones}()}

Other Centroid functions: 
\code{\link{centroid_dyad}()},
\code{\link{centroid_fusion}()},
\code{\link{centroid_group}()},
\code{\link{direction_to_centroid}()}
}
\concept{Centroid functions}
\concept{Distance functions}
