diff --git a/NAMESPACE b/NAMESPACE index cb04785a..fad615cb 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -9,7 +9,9 @@ export(direction_group) export(direction_polarization) export(direction_step) export(direction_to_centroid) +export(direction_to_leader) export(distance_to_centroid) +export(distance_to_leader) export(dyad_id) export(edge_dist) export(edge_nn) diff --git a/man/direction_group.Rd b/man/direction_group.Rd index 9ee8f334..560d441b 100644 --- a/man/direction_group.Rd +++ b/man/direction_group.Rd @@ -7,8 +7,8 @@ direction_group(DT, direction = "direction", group = "group") } \arguments{ -\item{DT}{input data.table with distance column generated by -\code{distance_step} and group column generated with \code{group_pts}} +\item{DT}{input data.table with direction column generated by +\code{direction_step} and group column generated with \code{group_pts}} \item{direction}{character string of direction column name, default "direction"} @@ -87,6 +87,7 @@ See examples of using mean group direction: Other Direction functions: \code{\link{direction_polarization}()}, -\code{\link{direction_step}()} +\code{\link{direction_step}()}, +\code{\link{direction_to_leader}()} } \concept{Direction functions} diff --git a/man/direction_polarization.Rd b/man/direction_polarization.Rd index 51312ebb..4db6d66e 100644 --- a/man/direction_polarization.Rd +++ b/man/direction_polarization.Rd @@ -7,8 +7,8 @@ direction_polarization(DT, direction = "direction", group = "group") } \arguments{ -\item{DT}{input data.table with distance column generated by -\code{distance_step} and group column generated with \code{group_pts}} +\item{DT}{input data.table with direction column generated by +\code{direction_step} and group column generated with \code{group_pts}} \item{direction}{character string of direction column name, default "direction"} @@ -87,6 +87,7 @@ See examples of using polarization: Other Direction functions: \code{\link{direction_group}()}, -\code{\link{direction_step}()} +\code{\link{direction_step}()}, +\code{\link{direction_to_leader}()} } \concept{Direction functions} diff --git a/man/direction_step.Rd b/man/direction_step.Rd index 0ec38ee2..aaa64f30 100644 --- a/man/direction_step.Rd +++ b/man/direction_step.Rd @@ -100,6 +100,7 @@ direction_step( Other Direction functions: \code{\link{direction_group}()}, -\code{\link{direction_polarization}()} +\code{\link{direction_polarization}()}, +\code{\link{direction_to_leader}()} } \concept{Direction functions} diff --git a/man/direction_to_centroid.Rd b/man/direction_to_centroid.Rd index c459ea37..312d8b28 100644 --- a/man/direction_to_centroid.Rd +++ b/man/direction_to_centroid.Rd @@ -7,7 +7,8 @@ direction_to_centroid(DT = NULL, coords = NULL) } \arguments{ -\item{DT}{input data.table} +\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.} @@ -75,6 +76,7 @@ See example of using direction to group centroid: \link{centroid_group}, \link{group_pts} Other Distance functions: -\code{\link{distance_to_centroid}()} +\code{\link{distance_to_centroid}()}, +\code{\link{distance_to_leader}()} } \concept{Distance functions} diff --git a/man/direction_to_leader.Rd b/man/direction_to_leader.Rd new file mode 100644 index 00000000..48c107c4 --- /dev/null +++ b/man/direction_to_leader.Rd @@ -0,0 +1,107 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/direction_to_leader.R +\name{direction_to_leader} +\alias{direction_to_leader} +\title{Direction to group leader} +\usage{ +direction_to_leader(DT = NULL, coords = NULL, group = "group") +} +\arguments{ +\item{DT}{input data.table with 'rank_position_group_direction' column +generated by \code{leader_direction_group} and group column generated by +\code{group_pts}} + +\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'} +} +\value{ +\code{direction_to_leader} returns the input \code{DT} appended with +a \code{direction_leader} column indicating the direction to the group leader. + +A message is returned when the \code{direction_leader} column is already exist in the input \code{DT} +because it will be overwritten. +} +\description{ +\code{direction_to_leader} calculates the direction to the leader of each +spatiotemporal group. The function accepts a \code{data.table} with +relocation data appended with a \code{rank_position_group_direction} column +indicating the ranked position along the group direction generated with +\code{leader_direction_group(return_rank = TRUE)}. 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{rank_position_group_direction} column +generated with \code{leader_direction_group(return_rank = TRUE)}, +a \code{group} column generated with the +\code{group_pts} 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 = 50, id = 'ID', + coords = c('X', 'Y'), timegroup = 'timegroup') + +# Calculate direction at each step +direction_step( + DT = DT, + id = 'ID', + coords = c('X', 'Y'), + projection = 32736 +) + +# Calculate group centroid +centroid_group(DT, coords = c('X', 'Y')) + +# Calculate group direction +direction_group(DT) + +# Calculate leader in terms of position along group direction +leader_direction_group( + DT, + coords = c('X', 'Y'), + return_rank = TRUE +) + +# Calculate direction to leader +direction_to_leader(DT, coords = c('X', 'Y')) +} +\references{ +See examples of using direction to leader and position within group: +\itemize{ +\item \url{https://doi.org/10.1016/j.anbehav.2023.09.009} +\item \url{https://doi.org/10.1016/j.beproc.2013.10.007} +\item \url{https://doi.org/10.1371/journal.pone.0036567} +} +} +\seealso{ +\link{distance_to_leader}, \link{leader_direction_group}, \link{group_pts} + +Other Direction functions: +\code{\link{direction_group}()}, +\code{\link{direction_polarization}()}, +\code{\link{direction_step}()} +} +\concept{Direction functions} diff --git a/man/distance_to_centroid.Rd b/man/distance_to_centroid.Rd index f27b5862..6b0022ae 100644 --- a/man/distance_to_centroid.Rd +++ b/man/distance_to_centroid.Rd @@ -13,10 +13,8 @@ distance_to_centroid( ) } \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{DT}{input data.table with centroid columns generated by eg. +\code{centroid_group}} \item{group}{group column name, generated by \code{group_pts}, default 'group'} @@ -102,6 +100,7 @@ See examples of using distance to group centroid: \link{centroid_group}, \link{group_pts} Other Distance functions: -\code{\link{direction_to_centroid}()} +\code{\link{direction_to_centroid}()}, +\code{\link{distance_to_leader}()} } \concept{Distance functions} diff --git a/man/distance_to_leader.Rd b/man/distance_to_leader.Rd new file mode 100644 index 00000000..049e4e9d --- /dev/null +++ b/man/distance_to_leader.Rd @@ -0,0 +1,106 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/distance_to_leader.R +\name{distance_to_leader} +\alias{distance_to_leader} +\title{Distance to group leader} +\usage{ +distance_to_leader(DT = NULL, coords = NULL, group = "group") +} +\arguments{ +\item{DT}{input data.table with 'rank_position_group_direction' column +generated by \code{leader_direction_group} and group column generated by +\code{group_pts}} + +\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'} +} +\value{ +\code{distance_to_leader} returns the input \code{DT} appended with +a \code{distance_leader} column indicating the distance to the group leader. + +A message is returned when the \code{distance_leader} column is already exist in the input \code{DT} +because it will be overwritten. +} +\description{ +\code{distance_to_leader} calculates the distance to the leader of each +spatiotemporal group. The function accepts a \code{data.table} with +relocation data appended with a \code{rank_position_group_direction} column +indicating the ranked position along the group direction generated with +\code{leader_direction_group(return_rank = TRUE)}. 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{rank_position_group_direction} column +generated with \code{leader_direction_group(return_rank = TRUE)}, +a \code{group} column generated with the +\code{group_pts} 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 = 50, id = 'ID', + coords = c('X', 'Y'), timegroup = 'timegroup') + +# Calculate direction at each step +direction_step( + DT = DT, + id = 'ID', + coords = c('X', 'Y'), + projection = 32736 +) + +# Calculate group centroid +centroid_group(DT, coords = c('X', 'Y')) + +# Calculate group direction +direction_group(DT) + +# Calculate leader in terms of position along group direction +leader_direction_group( + DT, + coords = c('X', 'Y'), + return_rank = TRUE +) + +# Calculate distance to leader +distance_to_leader(DT, coords = c('X', 'Y')) +} +\references{ +See examples of using distance to leader and position within group: +\itemize{ +\item \url{https://doi.org/10.1111/jfb.15315} +\item \url{https://doi.org/10.1098/rspb.2017.2629} +\item \url{https://doi.org/10.1016/j.anbehav.2023.09.009} +} +} +\seealso{ +\link{direction_to_leader}, \link{leader_direction_group}, \link{group_pts} + +Other Distance functions: +\code{\link{direction_to_centroid}()}, +\code{\link{distance_to_centroid}()} +} +\concept{Distance functions} diff --git a/man/leader_direction_group.Rd b/man/leader_direction_group.Rd index b3835cbf..34e8708d 100644 --- a/man/leader_direction_group.Rd +++ b/man/leader_direction_group.Rd @@ -8,14 +8,15 @@ leader_direction_group( DT = NULL, group_direction = "group_direction", coords = NULL, - group = NULL, + group = "group", return_rank = FALSE, ties.method = "average" ) } \arguments{ -\item{DT}{input data.table with distance column generated by -\code{distance_step} and group column generated with \code{group_pts}} +\item{DT}{input data.table with group direction columns generated by +\code{direction_group} and centroid columns generated by +\code{centroid_group}} \item{group_direction}{group_direction column name generated using \code{direction_group}, default 'group_direction'} @@ -23,7 +24,8 @@ leader_direction_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}{character string of group column name, default "group"} +\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} @@ -33,10 +35,9 @@ FALSE} \value{ \code{leader_direction_group} returns the input \code{DT} appended with a \code{position_group_direction} column indicating the position along -the group direction in the units of the projection and, optionally, a -\code{rank_position_group_direction} column indicating the -within group rank position along the group dirtection \code{return_rank = - TRUE}). +the group direction in the units of the projection and, optionally when +\code{return_rank = TRUE}, a \code{rank_position_group_direction} column +indicating the the ranked position along the group direction. A message is returned when \code{position_group_direction} or \code{rank_position_group_direction} columns already exist in the input