distance_to_centroid.Rd

% 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",
  return_rank = FALSE,
  ties.method = NULL
)
}
\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{return_rank}{boolean if rank distance should also be returned, default
FALSE}

\item{ties.method}{see \code{\link[data.table:frank]{?data.table::frank}}}
}
\value{
\code{distance_to_centroid} returns the input \code{DT} appended with
a \code{distance_centroid} column indicating the distance to group centroid
and, optionally, a \code{rank_distance_centroid} column indicating the
within group rank distance to 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.
}
\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 accepts 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 in planar coordinates
provided in two columns representing the X and Y coordinates.
}
\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 columns generated with the
\code{centroid_group} function. The \code{coords} and \code{group} arguments
expect the names of columns in \code{DT} which correspond to the X and Y
coordinates and group columns. 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}}.
}
\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')

# 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', na.rm = TRUE)

# Calculate distance to group centroid
distance_to_centroid(
  DT,
  coords = c('X', 'Y'),
  group = 'group',
  return_rank = TRUE
)
}
\references{
See examples of using distance to group centroid:
\itemize{
\item \url{https://doi.org/10.1016/j.anbehav.2021.08.004}
\item \url{https://doi.org/10.1111/eth.12336}
\item \url{https://doi.org/10.1007/s13364-018-0400-2}
}
}
\seealso{
\link{centroid_group}, \link{group_pts}

Other Distance functions: 
\code{\link{direction_to_centroid}()},
\code{\link{distance_to_leader}()}
}
\concept{Distance functions}