leader_direction_group.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/leader_direction_group.R
\name{leader_direction_group}
\alias{leader_direction_group}
\title{Leadership along group direction}
\usage{
leader_direction_group(
  DT = NULL,
  group_direction = "group_direction",
  coords = NULL,
  group = "group",
  crs = NULL,
  geometry = "geometry",
  return_rank = TRUE,
  ties.method = NULL
)
}
\arguments{
\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'}

\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{geometry}{simple feature geometry list column name, generated by
\code{\link[=get_geometry]{get_geometry()}}. Default 'geometry', 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()}}}
}
\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 crs and, optionally when \code{return_rank = TRUE}, a \code{rank_position_group_direction} column indicating 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 \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{
Given the mean direction of a group of individuals, \code{leader_direction_group}
shifts the coordinate system to a new origin at the group centroid and
rotates the coordinate system by the mean direction to return each
individual's position along the mean direction, representing leadership in
terms of the front-back position in each group's mean direction. 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 function expects a \code{data.table} with relocation data appended with a
\code{group_direction} column from \code{\link[=direction_group]{direction_group()}} and group centroid columns
from \code{\link[=centroid_group]{centroid_group()}}.

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()}}.

The \code{group_direction} argument expects the names of columns in \code{DT} which
correspond to the mean group direction generated by \code{\link[=direction_group]{direction_group()}}. The
mean group direction column is expected in units of radians. The
\code{return_rank} argument controls if the rank of each individual's distance to
the group centroid is also returned. If \code{return_rank} is TRUE, the \code{group}
argument is required to specify the group column generated by \code{\link[=group_pts]{group_pts()}}.
The \code{ties.method} argument is passed to \code{\link[data.table:frank]{data.table::frank()}}, see details at
\code{\link[data.table:frank]{?data.table::frank()}}.

See below under "Interface" for details on providing coordinates.
}
\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.
}
}

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

# Or, using the new geometry interface
get_geometry(DT, coords = c('X', 'Y'), crs = 32736)
direction_step(DT = DT, id = 'ID')
centroid_group(DT)
direction_group(DT)
leader_direction_group(DT)
}
\references{
See examples of measuring leadership along group direction (also called
forefront index):
\itemize{
\item \doi{doi:10.1371/journal.pone.0036567}
\item \doi{doi:10.1111/jfb.15315}
\item \doi{doi:10.1098/rspb.2021.0839}
}
}
\seealso{
\code{direction_group}, \code{centroid_group}

Other Leadership functions: 
\code{\link{direction_to_leader}()},
\code{\link{leader_edge_delay}()}

Other Direction functions: 
\code{\link{direction_group}()},
\code{\link{direction_polarization}()},
\code{\link{direction_step}()},
\code{\link{direction_to_centroid}()},
\code{\link{direction_to_leader}()},
\code{\link{edge_alignment}()},
\code{\link{edge_delay}()},
\code{\link{edge_direction}()},
\code{\link{edge_zones}()},
\code{\link{leader_edge_delay}()}
}
\concept{Direction functions}
\concept{Leadership functions}