% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/direction_group.R
\name{direction_group}
\alias{direction_group}
\title{Group mean direction}
\usage{
direction_group(DT, direction = "direction", group = "group")
}
\arguments{
\item{DT}{input data.table with direction column generated by
\code{\link[=direction_step]{direction_step()}} and group column generated with \code{\link[=group_pts]{group_pts()}}}

\item{direction}{character string of direction column name, default
"direction", expects that the unit of the direction column is radians.}

\item{group}{character string of group column name, default "group"}
}
\value{
\code{direction_group} returns the input \code{DT} appended with a
\code{group_direction} column representing the mean direction of all individuals
in each spatiotemporal group.

The mean direction is calculated using \code{\link[CircStats:circ.mean]{CircStats::circ.mean()}} which
expects units of radians.

A message is returned when the \code{group_direction} columns already exists in
the input \code{DT}, because it 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{direction_group} calculates the mean direction of all individuals in each
spatiotemporal group identified by \code{\link[=group_pts]{group_pts()}}. The function expects a
\code{data.table} with relocation data appended with a \code{direction} column from
\code{\link[=direction_step]{direction_step()}} and a \code{group} column from \code{\link[=group_pts]{group_pts()}}.
}
\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()}}.

The \code{direction} and \code{group} arguments expect the names of columns in \code{DT}
which correspond to the direction and group columns. The direction column is
expected in units of radians and the mean calculated with
\code{\link[CircStats:circ.mean]{CircStats::circ.mean()}}.
}
\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'),
  crs = 32736
)

# Calculate group direction
direction_group(DT)

# Or, using the new geometry interface
get_geometry(DT, coords = c('X', 'Y'), crs = 32736)
group_pts(DT, threshold = 5, id = 'ID', timegroup = 'timegroup')
direction_step(DT, id = 'ID')
direction_group(DT)
}
\references{
See examples of using mean group direction:
\itemize{
\item \doi{doi:10.1098/rsos.170148}
\item \doi{doi:10.1098/rsos.201128}
\item \doi{doi:10.1016/j.beproc.2018.01.013}
}
}
\seealso{
\code{\link[=direction_step]{direction_step()}}, \code{\link[=group_pts]{group_pts()}},
\code{\link[CircStats:circ.mean]{CircStats::circ.mean()}}

Other Direction functions: 
\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_direction_group}()},
\code{\link{leader_edge_delay}()}
}
\concept{Direction functions}
