diff --git a/NAMESPACE b/NAMESPACE index cc3f44e7..ba4c7247 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -6,6 +6,8 @@ export(centroid_dyad) export(centroid_fusion) export(centroid_group) export(direction_step) +export(direction_to_centroid) +export(distance_to_centroid) export(dyad_id) export(edge_dist) export(edge_nn) diff --git a/man/direction_to_centroid.Rd b/man/direction_to_centroid.Rd new file mode 100644 index 00000000..d28dca68 --- /dev/null +++ b/man/direction_to_centroid.Rd @@ -0,0 +1,79 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/direction_to_centroid.R +\name{direction_to_centroid} +\alias{direction_to_centroid} +\title{Direction to group centroid} +\usage{ +direction_to_centroid(DT = NULL, coords = NULL) +} +\arguments{ +\item{DT}{input data.table} + +\item{coords}{Character vector of X coordinate and Y coordinate column names. +Note: the order is assumed X followed by Y column names.} +} +\value{ +\code{direction_to_centroid} returns the input \code{DT} appended +with a \code{direction_centroid} column indicating the direction to group +centroid in radians. + +A message is returned when \code{direction_centroid} column already exist +in the input \code{DT}, because they will be overwritten. +} +\description{ +\code{direction_to_centroid} calculates the direction 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 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. +} +\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 direction to group centroid +direction_to_centroid(DT, coords = c('X', 'Y')) +} +\references{ +See example of using direction to group centroid: +\itemize{ +\item \url{https://doi.org/10.1016/j.cub.2017.08.004} +} +} +\seealso{ +\link{centroid_group}, \link{group_pts} + +Other Distance functions: +\code{\link{distance_to_centroid}()} +} +\concept{Distance functions} diff --git a/man/distance_to_centroid.Rd b/man/distance_to_centroid.Rd new file mode 100644 index 00000000..fa7a43fe --- /dev/null +++ b/man/distance_to_centroid.Rd @@ -0,0 +1,102 @@ +% 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} + +\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 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}()} +} +\concept{Distance functions}