From 28c2389ae9e02607cbac11050a07634934b226d3 Mon Sep 17 00:00:00 2001
From: "Alec L. Robitaille" <robit.alec@gmail.com>
Date: Fri, 19 Jul 2024 12:10:14 -0300
Subject: [PATCH 01/24] fst bearing polarization

---
 R/bearing_polarization.R | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)
 create mode 100644 R/bearing_polarization.R

diff --git a/R/bearing_polarization.R b/R/bearing_polarization.R
new file mode 100644
index 00000000..8c5018a0
--- /dev/null
+++ b/R/bearing_polarization.R
@@ -0,0 +1,18 @@
+#' Calculate group polarization
+#'
+#' Polarization of group bearings from 0-1
+#'
+#' @param DT with bearing column generated by eg. bearing_sequential
+#' @param bearing bearing column name, default 'bearing'
+#' @param group group column name generated by eg. group_pts, default 'group'
+#' @param degree boolean, if bearing is measured in degrees. See ?CircStats::r.test
+bearing_polarization <- function(DT,  bearing = 'bearing', group = 'group', degree = FALSE) {
+  stopifnot(bearing %in% colnames(DT))
+  stopifnot(group %in% colnames(DT))
+
+  DT[, polarization := CircStats::r.test(.SD[[1]], degree = degree)$r.bar,
+     by = c(group),
+     .SDcols = c(bearing)]
+
+  return(DT)
+}

From ba8ac02716e8f602dab601108d01138a71edb438 Mon Sep 17 00:00:00 2001
From: "Alec L. Robitaille" <robit.alec@gmail.com>
Date: Tue, 8 Oct 2024 10:59:54 -0300
Subject: [PATCH 02/24] rename to direction_polarization

---
 R/bearing_polarization.R   |  18 -----
 R/direction_polarization.R | 148 +++++++++++++++++++++++++++++++++++++
 2 files changed, 148 insertions(+), 18 deletions(-)
 delete mode 100644 R/bearing_polarization.R
 create mode 100644 R/direction_polarization.R

diff --git a/R/bearing_polarization.R b/R/bearing_polarization.R
deleted file mode 100644
index 8c5018a0..00000000
--- a/R/bearing_polarization.R
+++ /dev/null
@@ -1,18 +0,0 @@
-#' Calculate group polarization
-#'
-#' Polarization of group bearings from 0-1
-#'
-#' @param DT with bearing column generated by eg. bearing_sequential
-#' @param bearing bearing column name, default 'bearing'
-#' @param group group column name generated by eg. group_pts, default 'group'
-#' @param degree boolean, if bearing is measured in degrees. See ?CircStats::r.test
-bearing_polarization <- function(DT,  bearing = 'bearing', group = 'group', degree = FALSE) {
-  stopifnot(bearing %in% colnames(DT))
-  stopifnot(group %in% colnames(DT))
-
-  DT[, polarization := CircStats::r.test(.SD[[1]], degree = degree)$r.bar,
-     by = c(group),
-     .SDcols = c(bearing)]
-
-  return(DT)
-}
diff --git a/R/direction_polarization.R b/R/direction_polarization.R
new file mode 100644
index 00000000..5da0da53
--- /dev/null
+++ b/R/direction_polarization.R
@@ -0,0 +1,148 @@
+#' Calculate group polarization
+#'
+#' Polarization of group bearings from 0-1
+#'
+#' @param DT with bearing column generated by eg. bearing_sequential
+#' @param bearing bearing column name, default 'bearing'
+#' @param group group column name generated by eg. group_pts, default 'group'
+#' @param degree boolean, if bearing is measured in degrees. See ?CircStats::r.test
+direction_polarization <- function(DT,  bearing = 'bearing', group = 'group', degree = FALSE) {
+  stopifnot(bearing %in% colnames(DT))
+  stopifnot(group %in% colnames(DT))
+
+  DT[, polarization := CircStats::r.test(.SD[[1]], degree = degree)$r.bar,
+     by = c(group),
+     .SDcols = c(bearing)]
+
+  return(DT)
+}
+
+
+#' Group mean direction
+#'
+#' \code{direction_group} calculates the mean direction of all individuals in
+#' each spatiotemporal group identified by \code{group_pts}. The function
+#' accepts a \code{data.table} with relocation data appended with a
+#' \code{direction} column from \code{direction_step} and a \code{group} column
+#' from \code{group_pts}.
+#'
+#' 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
+#' [CircStats::circ.mean()].
+#'
+#' @param DT input data.table with distance column generated by
+#'   \code{distance_step} and group column generated with \code{group_pts}
+#' @param direction character string of direction column name, default
+#'   "direction"
+#' @param group character string of group column name, default "group"
+#'
+#' @return \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 [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.
+#'
+#' @export
+#' @seealso \code{\link{direction_step}}, \code{\link{group_pts}},
+#'   [CircStats::circ.mean()]
+#' @family Direction functions
+#'
+#' @references
+#' See example of using mean group direction:
+#'  * <https://doi.org/10.1098/rsos.170148>
+#'  * <https://doi.org/10.1098/rsos.201128>
+#'  * <https://doi.org/10.1016/j.beproc.2018.01.013>
+#'
+#' @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 direction
+#' direction_group(DT)
+direction_group <- function(
+    DT,
+    direction = 'direction',
+    group = 'group') {
+
+  if (is.null(DT)) {
+    stop('input DT required')
+  }
+
+  if (is.null(direction)) {
+    stop('direction column name required')
+  }
+
+  if (is.null(group)) {
+    stop('group column name required')
+  }
+
+  if (any(!(
+    c(direction, group) %in% colnames(DT)
+  ))) {
+    stop(paste0(
+      as.character(paste(setdiff(
+        c(direction, group),
+        colnames(DT)
+      ), collapse = ', ')),
+      ' field(s) provided are not present in input DT'
+    ))
+  }
+
+  if (any(!(DT[, vapply(.SD, is.numeric, TRUE), .SDcols = c(direction)]))) {
+    stop('direction must be numeric')
+  }
+
+  out_mean <- 'group_direction'
+
+  if (out_mean %in% colnames(DT)) {
+    message(paste(out_mean, 'column will be overwritten by this function'))
+    data.table::set(DT, j = out_mean, value = NULL)
+  }
+
+  if (DT[, !inherits(.SD[[1]], 'units'), .SDcols = c(direction)] ||
+      DT[, units(.SD[[1]])$numerator != 'rad', .SDcols = c(direction)]) {
+    stop('units(DT$direction) is not radians, did you use direction_step?')
+  }
+
+  DT[, c(out_mean) := units::as_units(
+    CircStats::circ.mean(units::drop_units(.SD)),
+    'rad'),
+    by = c(group),
+    .SDcols = c(direction)]
+
+  return(DT[])
+}
+
+

From 68b397571bee731fbe4c5b8e826162db0277a3a9 Mon Sep 17 00:00:00 2001
From: "Alec L. Robitaille" <robit.alec@gmail.com>
Date: Tue, 8 Oct 2024 11:01:51 -0300
Subject: [PATCH 03/24] fix expects not accepts

---
 R/build_lines.R        |  2 +-
 R/build_polys.R        |  2 +-
 R/edge_dist.R          |  2 +-
 R/edge_nn.R            |  2 +-
 R/get_gbi.R            |  2 +-
 R/group_lines.R        |  2 +-
 R/group_polys.R        |  2 +-
 R/group_pts.R          |  2 +-
 R/group_times.R        |  2 +-
 R/randomizations.R     |  2 +-
 man/build_lines.Rd     |  2 +-
 man/build_polys.Rd     |  2 +-
 man/direction_group.Rd | 86 ++++++++++++++++++++++++++++++++++++++++++
 man/edge_dist.Rd       |  2 +-
 man/edge_nn.Rd         |  2 +-
 man/get_gbi.Rd         |  2 +-
 man/group_lines.Rd     |  2 +-
 man/group_polys.Rd     |  2 +-
 man/group_pts.Rd       |  2 +-
 man/group_times.Rd     |  2 +-
 man/randomizations.Rd  |  2 +-
 man/spatsoc.Rd         |  1 -
 22 files changed, 106 insertions(+), 21 deletions(-)
 create mode 100644 man/direction_group.Rd

diff --git a/R/build_lines.R b/R/build_lines.R
index 7f7dfbc4..f3a3843c 100644
--- a/R/build_lines.R
+++ b/R/build_lines.R
@@ -2,7 +2,7 @@
 #'
 #'
 #' `build_lines` generates a simple feature collection with LINESTRINGs from a
-#' `data.table`. The function accepts a `data.table` with relocation data,
+#' `data.table`. The function expects a `data.table` with relocation data,
 #' individual identifiers, a sorting column and a `projection`. The relocation
 #' data is transformed into LINESTRINGs for each individual and, optionally,
 #' combination of columns listed in `splitBy`. Relocation data should be in two
diff --git a/R/build_polys.R b/R/build_polys.R
index d68fd458..3a0de2cd 100644
--- a/R/build_polys.R
+++ b/R/build_polys.R
@@ -1,7 +1,7 @@
 #' Build Polygons
 #'
 #' `build_polys` generates a simple feature collection with POLYGONs from a
-#' `data.table`. The function accepts a `data.table` with
+#' `data.table`. The function expects a `data.table` with
 #' relocation data, individual identifiers, a projection,
 #' home range type and parameters. The relocation
 #' data is transformed into POLYGONs using either [adehabitatHR::mcp] or
diff --git a/R/edge_dist.R b/R/edge_dist.R
index 7201ab12..127041f2 100644
--- a/R/edge_dist.R
+++ b/R/edge_dist.R
@@ -2,7 +2,7 @@
 #'
 #'
 #' \code{edge_dist} returns edge lists defined by a spatial distance within the
-#' user defined threshold. The function accepts a \code{data.table} with
+#' user defined threshold. The function expects a \code{data.table} with
 #' relocation data, individual identifiers and a threshold argument. The
 #' threshold argument is used to specify the criteria for distance between
 #' points which defines a group. Relocation data should be in two columns
diff --git a/R/edge_nn.R b/R/edge_nn.R
index a96f2818..c89bcd7e 100644
--- a/R/edge_nn.R
+++ b/R/edge_nn.R
@@ -2,7 +2,7 @@
 #'
 #'
 #' \code{edge_nn} returns edge lists defined by the nearest neighbour. The
-#' function accepts a \code{data.table} with relocation data, individual
+#' function expects a \code{data.table} with relocation data, individual
 #' identifiers and a threshold argument. The threshold argument is used to
 #' specify the criteria for distance between points which defines a group.
 #' Relocation data should be in two columns representing the X and Y
diff --git a/R/get_gbi.R b/R/get_gbi.R
index 792d35ad..05d02dbe 100644
--- a/R/get_gbi.R
+++ b/R/get_gbi.R
@@ -1,7 +1,7 @@
 #' Generate group by individual matrix
 #'
 #'
-#' \code{get_gbi} generates a group by individual matrix. The function accepts a
+#' \code{get_gbi} generates a group by individual matrix. The function expects a
 #' \code{data.table} with individual identifiers and a group column. The group
 #' by individual matrix can then be used to build a network using
 #' \code{\link[asnipe:get_network]{asnipe::get_network}}.
diff --git a/R/group_lines.R b/R/group_lines.R
index ece668d9..9336e43c 100644
--- a/R/group_lines.R
+++ b/R/group_lines.R
@@ -1,7 +1,7 @@
 #' Group Lines
 #'
 #' `group_lines` groups rows into spatial groups by generating LINESTRINGs and
-#' grouping based on spatial intersection. The function accepts a `data.table`
+#' grouping based on spatial intersection. The function expects a `data.table`
 #' with relocation data, individual identifiers and a distance threshold. The
 #' relocation data is transformed into sf LINESTRINGs using [build_lines] and
 #' intersecting LINESTRINGs are grouped. The threshold argument is used to
diff --git a/R/group_polys.R b/R/group_polys.R
index d82cbd6f..17db4582 100644
--- a/R/group_polys.R
+++ b/R/group_polys.R
@@ -1,7 +1,7 @@
 #' Group Polygons
 #'
 #' `group_polys` groups rows into spatial groups by overlapping polygons (home
-#' ranges). The function accepts a `data.table` with relocation data, individual
+#' ranges). The function expects a `data.table` with relocation data, individual
 #' identifiers and an `area` argument.  The relocation data is transformed into
 #' home range POLYGONs using [build_polys()] with [adehabitatHR::mcp] or
 #' [adehabitatHR::kernelUD]. If the `area` argument is `FALSE`, `group_polys`
diff --git a/R/group_pts.R b/R/group_pts.R
index 94287afb..f75a189f 100644
--- a/R/group_pts.R
+++ b/R/group_pts.R
@@ -1,6 +1,6 @@
 #' Group Points
 #'
-#' \code{group_pts} groups rows into spatial groups. The function accepts a
+#' \code{group_pts} groups rows into spatial groups. The function expects a
 #' \code{data.table} with relocation data, individual identifiers and a
 #' threshold argument. The threshold argument is used to specify the criteria
 #' for distance between points which defines a group. Relocation data should be
diff --git a/R/group_times.R b/R/group_times.R
index 4fb19e96..7db4fe5b 100644
--- a/R/group_times.R
+++ b/R/group_times.R
@@ -1,6 +1,6 @@
 #' Group Times
 #'
-#' \code{group_times} groups rows into time groups. The function accepts date
+#' \code{group_times} groups rows into time groups. The function expects date
 #' time formatted data and a threshold argument. The threshold argument is used
 #' to specify a time window within which rows are grouped.
 #'
diff --git a/R/randomizations.R b/R/randomizations.R
index e1033402..353a477d 100644
--- a/R/randomizations.R
+++ b/R/randomizations.R
@@ -1,7 +1,7 @@
 #' Data-stream randomizations
 #'
 #' \code{randomizations} performs data-stream social network randomization. The
-#' function accepts a \code{data.table} with relocation data, individual
+#' function expects a \code{data.table} with relocation data, individual
 #' identifiers and a randomization \code{type}. The \code{data.table} is
 #' randomized either using \code{step} or \code{daily} between-individual
 #' methods, or within-individual daily \code{trajectory} method described by
diff --git a/man/build_lines.Rd b/man/build_lines.Rd
index f4cbfc58..dbd65708 100644
--- a/man/build_lines.Rd
+++ b/man/build_lines.Rd
@@ -40,7 +40,7 @@ build a line.
 }
 \description{
 \code{build_lines} generates a simple feature collection with LINESTRINGs from a
-\code{data.table}. The function accepts a \code{data.table} with relocation data,
+\code{data.table}. The function expects a \code{data.table} with relocation data,
 individual identifiers, a sorting column and a \code{projection}. The relocation
 data is transformed into LINESTRINGs for each individual and, optionally,
 combination of columns listed in \code{splitBy}. Relocation data should be in two
diff --git a/man/build_polys.Rd b/man/build_polys.Rd
index 33e58183..0443e61a 100644
--- a/man/build_polys.Rd
+++ b/man/build_polys.Rd
@@ -46,7 +46,7 @@ of the respective \code{hrType} \code{adehabitatHR} function.
 }
 \description{
 \code{build_polys} generates a simple feature collection with POLYGONs from a
-\code{data.table}. The function accepts a \code{data.table} with
+\code{data.table}. The function expects a \code{data.table} with
 relocation data, individual identifiers, a projection,
 home range type and parameters. The relocation
 data is transformed into POLYGONs using either \link[adehabitatHR:mcp]{adehabitatHR::mcp} or
diff --git a/man/direction_group.Rd b/man/direction_group.Rd
new file mode 100644
index 00000000..56102f79
--- /dev/null
+++ b/man/direction_group.Rd
@@ -0,0 +1,86 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/direction_polarization.R
+\name{direction_group}
+\alias{direction_group}
+\title{\code{direction_polarization} calculates the direction polarization of
+all individuals in each spatiotemporal group identified by \code{group_pts}. The function
+expects a \code{data.table} with relocation data appended with a
+\code{direction} column from \code{direction_step} and a \code{group} column
+from \code{group_pts}.}
+\usage{
+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{direction}{character string of direction column name, default
+"direction"}
+
+\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.
+}
+\description{
+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}}.
+}
+\details{
+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'),
+  projection = 32736
+)
+
+# Calculate group direction
+direction_group(DT)
+}
+\references{
+See example of using mean group direction:
+\itemize{
+\item \url{https://doi.org/10.1098/rsos.170148}
+\item \url{https://doi.org/10.1098/rsos.201128}
+\item \url{https://doi.org/10.1016/j.beproc.2018.01.013}
+}
+}
+\seealso{
+\code{\link{direction_step}}, \code{\link{group_pts}},
+\code{\link[CircStats:circ.mean]{CircStats::circ.mean()}}
+}
+\concept{Direction functions}
diff --git a/man/edge_dist.Rd b/man/edge_dist.Rd
index c885d370..08066865 100644
--- a/man/edge_dist.Rd
+++ b/man/edge_dist.Rd
@@ -52,7 +52,7 @@ temporal with \code{group_times}) thresholds.
 }
 \description{
 \code{edge_dist} returns edge lists defined by a spatial distance within the
-user defined threshold. The function accepts a \code{data.table} with
+user defined threshold. The function expects a \code{data.table} with
 relocation data, individual identifiers and a threshold argument. The
 threshold argument is used to specify the criteria for distance between
 points which defines a group. Relocation data should be in two columns
diff --git a/man/edge_nn.Rd b/man/edge_nn.Rd
index d92a1b7c..561f8be7 100644
--- a/man/edge_nn.Rd
+++ b/man/edge_nn.Rd
@@ -49,7 +49,7 @@ neighbour.
 }
 \description{
 \code{edge_nn} returns edge lists defined by the nearest neighbour. The
-function accepts a \code{data.table} with relocation data, individual
+function expects a \code{data.table} with relocation data, individual
 identifiers and a threshold argument. The threshold argument is used to
 specify the criteria for distance between points which defines a group.
 Relocation data should be in two columns representing the X and Y
diff --git a/man/get_gbi.Rd b/man/get_gbi.Rd
index d9bbb6ce..cef044f5 100644
--- a/man/get_gbi.Rd
+++ b/man/get_gbi.Rd
@@ -25,7 +25,7 @@ but is more efficient thanks to
 \code{\link[data.table:dcast.data.table]{data.table::dcast}}.
 }
 \description{
-\code{get_gbi} generates a group by individual matrix. The function accepts a
+\code{get_gbi} generates a group by individual matrix. The function expects a
 \code{data.table} with individual identifiers and a group column. The group
 by individual matrix can then be used to build a network using
 \code{\link[asnipe:get_network]{asnipe::get_network}}.
diff --git a/man/group_lines.Rd b/man/group_lines.Rd
index 94fa5bf2..5dc32c74 100644
--- a/man/group_lines.Rd
+++ b/man/group_lines.Rd
@@ -61,7 +61,7 @@ input \code{DT}, because it will be overwritten.
 }
 \description{
 \code{group_lines} groups rows into spatial groups by generating LINESTRINGs and
-grouping based on spatial intersection. The function accepts a \code{data.table}
+grouping based on spatial intersection. The function expects a \code{data.table}
 with relocation data, individual identifiers and a distance threshold. The
 relocation data is transformed into sf LINESTRINGs using \link{build_lines} and
 intersecting LINESTRINGs are grouped. The threshold argument is used to
diff --git a/man/group_polys.Rd b/man/group_polys.Rd
index bdd5c2d9..7df2b888 100644
--- a/man/group_polys.Rd
+++ b/man/group_polys.Rd
@@ -60,7 +60,7 @@ through the \code{units} package.
 }
 \description{
 \code{group_polys} groups rows into spatial groups by overlapping polygons (home
-ranges). The function accepts a \code{data.table} with relocation data, individual
+ranges). The function expects a \code{data.table} with relocation data, individual
 identifiers and an \code{area} argument.  The relocation data is transformed into
 home range POLYGONs using \code{\link[=build_polys]{build_polys()}} with \link[adehabitatHR:mcp]{adehabitatHR::mcp} or
 \link[adehabitatHR:kernelUD]{adehabitatHR::kernelUD}. If the \code{area} argument is \code{FALSE}, \code{group_polys}
diff --git a/man/group_pts.Rd b/man/group_pts.Rd
index 6e706805..dd6c1de0 100644
--- a/man/group_pts.Rd
+++ b/man/group_pts.Rd
@@ -43,7 +43,7 @@ A message is returned when a column named \code{group} already exists in
 the input \code{DT}, because it will be overwritten.
 }
 \description{
-\code{group_pts} groups rows into spatial groups. The function accepts a
+\code{group_pts} groups rows into spatial groups. The function expects a
 \code{data.table} with relocation data, individual identifiers and a
 threshold argument. The threshold argument is used to specify the criteria
 for distance between points which defines a group. Relocation data should be
diff --git a/man/group_times.Rd b/man/group_times.Rd
index 9cfcd4aa..c84e5dff 100644
--- a/man/group_times.Rd
+++ b/man/group_times.Rd
@@ -39,7 +39,7 @@ A message is returned when any of these columns already exist in the input
 \code{DT}, because they will be overwritten.
 }
 \description{
-\code{group_times} groups rows into time groups. The function accepts date
+\code{group_times} groups rows into time groups. The function expects date
 time formatted data and a threshold argument. The threshold argument is used
 to specify a time window within which rows are grouped.
 }
diff --git a/man/randomizations.Rd b/man/randomizations.Rd
index a2af5123..0651e7d6 100644
--- a/man/randomizations.Rd
+++ b/man/randomizations.Rd
@@ -55,7 +55,7 @@ day relocations are swapped to. }
 }
 \description{
 \code{randomizations} performs data-stream social network randomization. The
-function accepts a \code{data.table} with relocation data, individual
+function expects a \code{data.table} with relocation data, individual
 identifiers and a randomization \code{type}. The \code{data.table} is
 randomized either using \code{step} or \code{daily} between-individual
 methods, or within-individual daily \code{trajectory} method described by
diff --git a/man/spatsoc.Rd b/man/spatsoc.Rd
index 84fd40e8..31afc909 100644
--- a/man/spatsoc.Rd
+++ b/man/spatsoc.Rd
@@ -3,7 +3,6 @@
 \docType{package}
 \name{spatsoc}
 \alias{spatsoc}
-\alias{_PACKAGE}
 \alias{spatsoc-package}
 \title{spatsoc}
 \description{

From 983e4e5ecd08e503443f836c2616660e838b6cc5 Mon Sep 17 00:00:00 2001
From: "Alec L. Robitaille" <robit.alec@gmail.com>
Date: Tue, 8 Oct 2024 11:11:02 -0300
Subject: [PATCH 04/24] title

---
 R/direction_polarization.R | 20 +-------------------
 1 file changed, 1 insertion(+), 19 deletions(-)

diff --git a/R/direction_polarization.R b/R/direction_polarization.R
index 5da0da53..60d62bbf 100644
--- a/R/direction_polarization.R
+++ b/R/direction_polarization.R
@@ -1,23 +1,5 @@
-#' Calculate group polarization
+#' Polarization
 #'
-#' Polarization of group bearings from 0-1
-#'
-#' @param DT with bearing column generated by eg. bearing_sequential
-#' @param bearing bearing column name, default 'bearing'
-#' @param group group column name generated by eg. group_pts, default 'group'
-#' @param degree boolean, if bearing is measured in degrees. See ?CircStats::r.test
-direction_polarization <- function(DT,  bearing = 'bearing', group = 'group', degree = FALSE) {
-  stopifnot(bearing %in% colnames(DT))
-  stopifnot(group %in% colnames(DT))
-
-  DT[, polarization := CircStats::r.test(.SD[[1]], degree = degree)$r.bar,
-     by = c(group),
-     .SDcols = c(bearing)]
-
-  return(DT)
-}
-
-
 #' Group mean direction
 #'
 #' \code{direction_group} calculates the mean direction of all individuals in

From a717b903a4e456ecc659b347a0f6379d863df467 Mon Sep 17 00:00:00 2001
From: "Alec L. Robitaille" <robit.alec@gmail.com>
Date: Tue, 8 Oct 2024 11:11:09 -0300
Subject: [PATCH 05/24] description

---
 R/direction_polarization.R | 12 +++++-------
 1 file changed, 5 insertions(+), 7 deletions(-)

diff --git a/R/direction_polarization.R b/R/direction_polarization.R
index 60d62bbf..1cc0781d 100644
--- a/R/direction_polarization.R
+++ b/R/direction_polarization.R
@@ -1,10 +1,8 @@
 #' Polarization
 #'
-#' Group mean direction
-#'
-#' \code{direction_group} calculates the mean direction of all individuals in
-#' each spatiotemporal group identified by \code{group_pts}. The function
-#' accepts a \code{data.table} with relocation data appended with a
+#' \code{direction_polarization} calculates the polarization of individual
+#' directions in each spatiotemporal group identified by \code{group_pts}. The
+#' function expects a \code{data.table} with relocation data appended with a
 #' \code{direction} column from \code{direction_step} and a \code{group} column
 #' from \code{group_pts}.
 #'
@@ -15,8 +13,8 @@
 #'
 #' 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
-#' [CircStats::circ.mean()].
+#' direction column is expected in units of radians and the polarization is
+#' calculated with [CircStats::r.test()].
 #'
 #' @param DT input data.table with distance column generated by
 #'   \code{distance_step} and group column generated with \code{group_pts}

From 3ff99c66c43a8396ce1a9f900a4ea9e52658eccb Mon Sep 17 00:00:00 2001
From: "Alec L. Robitaille" <robit.alec@gmail.com>
Date: Tue, 8 Oct 2024 11:11:12 -0300
Subject: [PATCH 06/24] params

---
 R/direction_polarization.R | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

diff --git a/R/direction_polarization.R b/R/direction_polarization.R
index 1cc0781d..28cd93b1 100644
--- a/R/direction_polarization.R
+++ b/R/direction_polarization.R
@@ -16,11 +16,7 @@
 #' direction column is expected in units of radians and the polarization is
 #' calculated with [CircStats::r.test()].
 #'
-#' @param DT input data.table with distance column generated by
-#'   \code{distance_step} and group column generated with \code{group_pts}
-#' @param direction character string of direction column name, default
-#'   "direction"
-#' @param group character string of group column name, default "group"
+#' @inheritParams direction_group
 #'
 #' @return \code{direction_group} returns the input \code{DT} appended with a
 #'   \code{group_direction} column representing the mean direction of

From 37fce07adca01835497e85821da8df076899a0a7 Mon Sep 17 00:00:00 2001
From: "Alec L. Robitaille" <robit.alec@gmail.com>
Date: Tue, 8 Oct 2024 11:11:15 -0300
Subject: [PATCH 07/24] return

---
 R/direction_polarization.R | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/R/direction_polarization.R b/R/direction_polarization.R
index 28cd93b1..524e62bd 100644
--- a/R/direction_polarization.R
+++ b/R/direction_polarization.R
@@ -18,14 +18,14 @@
 #'
 #' @inheritParams direction_group
 #'
-#' @return \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.
+#' @return \code{direction_polarization} returns the input \code{DT} appended
+#'   with a \code{polarization} column representing the direction polarization
+#'   of all individuals in each spatiotemporal group.
 #'
-#'   The mean direction is calculated using [CircStats::circ.mean()]
+#'   The direction polarization is calculated using [CircStats::r.test()]
 #'   which expects units of radians.
 #'
-#'   A message is returned when the \code{group_direction} columns already
+#'   A message is returned when the \code{polarization} columns already
 #'   exists in the input \code{DT}, because it will be overwritten.
 #'
 #' @export

From caf1cb5fc37251e71d5d08358930efcd3b3c2f57 Mon Sep 17 00:00:00 2001
From: "Alec L. Robitaille" <robit.alec@gmail.com>
Date: Tue, 8 Oct 2024 11:11:25 -0300
Subject: [PATCH 08/24] seealso, references

---
 R/direction_polarization.R | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/R/direction_polarization.R b/R/direction_polarization.R
index 524e62bd..2bcafcfc 100644
--- a/R/direction_polarization.R
+++ b/R/direction_polarization.R
@@ -30,14 +30,14 @@
 #'
 #' @export
 #' @seealso \code{\link{direction_step}}, \code{\link{group_pts}},
-#'   [CircStats::circ.mean()]
+#'   [CircStats::r.test()]
 #' @family Direction functions
 #'
 #' @references
-#' See example of using mean group direction:
-#'  * <https://doi.org/10.1098/rsos.170148>
-#'  * <https://doi.org/10.1098/rsos.201128>
-#'  * <https://doi.org/10.1016/j.beproc.2018.01.013>
+#' See example of using polarization:
+#'  * <https://doi.org/10.1016/j.cub.2017.08.004>
+#'  * <10.1371/journal.pcbi.1009437>
+#'  * <https://doi.org/10.7554/eLife.19505>
 #'
 #' @examples
 #' # Load data.table

From f5a957a1abd4cf78114c52130412761bd83ca429 Mon Sep 17 00:00:00 2001
From: "Alec L. Robitaille" <robit.alec@gmail.com>
Date: Tue, 8 Oct 2024 11:11:31 -0300
Subject: [PATCH 09/24] examples

---
 R/direction_polarization.R | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/R/direction_polarization.R b/R/direction_polarization.R
index 2bcafcfc..4460064f 100644
--- a/R/direction_polarization.R
+++ b/R/direction_polarization.R
@@ -65,8 +65,8 @@
 #'   projection = 32736
 #' )
 #'
-#' # Calculate group direction
-#' direction_group(DT)
+#' # Calculate polarization
+#' direction_polarization(DT)
 direction_group <- function(
     DT,
     direction = 'direction',

From dd162e11add9cb96141598bc07dc874879edb9da Mon Sep 17 00:00:00 2001
From: "Alec L. Robitaille" <robit.alec@gmail.com>
Date: Tue, 8 Oct 2024 11:11:38 -0300
Subject: [PATCH 10/24] calc polarization

---
 R/direction_polarization.R | 12 +++++-------
 1 file changed, 5 insertions(+), 7 deletions(-)

diff --git a/R/direction_polarization.R b/R/direction_polarization.R
index 4460064f..789216b2 100644
--- a/R/direction_polarization.R
+++ b/R/direction_polarization.R
@@ -100,11 +100,11 @@ direction_group <- function(
     stop('direction must be numeric')
   }
 
-  out_mean <- 'group_direction'
+  out <- 'polarization'
 
-  if (out_mean %in% colnames(DT)) {
-    message(paste(out_mean, 'column will be overwritten by this function'))
-    data.table::set(DT, j = out_mean, value = NULL)
+  if (out %in% colnames(DT)) {
+    message(paste(out, 'column will be overwritten by this function'))
+    data.table::set(DT, j = out, value = NULL)
   }
 
   if (DT[, !inherits(.SD[[1]], 'units'), .SDcols = c(direction)] ||
@@ -112,9 +112,7 @@ direction_group <- function(
     stop('units(DT$direction) is not radians, did you use direction_step?')
   }
 
-  DT[, c(out_mean) := units::as_units(
-    CircStats::circ.mean(units::drop_units(.SD)),
-    'rad'),
+  DT[, c(out) := CircStats::r.test(units::drop_units(.SD))$r.bar,
     by = c(group),
     .SDcols = c(direction)]
 

From 6d39a950e2c6781d8c0afc5aee55f465c09f6935 Mon Sep 17 00:00:00 2001
From: "Alec L. Robitaille" <robit.alec@gmail.com>
Date: Tue, 8 Oct 2024 11:11:45 -0300
Subject: [PATCH 11/24] fst test-direction-polarization

---
 tests/testthat/test-direction-polarization.R | 2 ++
 1 file changed, 2 insertions(+)
 create mode 100644 tests/testthat/test-direction-polarization.R

diff --git a/tests/testthat/test-direction-polarization.R b/tests/testthat/test-direction-polarization.R
new file mode 100644
index 00000000..e8341e48
--- /dev/null
+++ b/tests/testthat/test-direction-polarization.R
@@ -0,0 +1,2 @@
+# Test direction_polarization
+context('test direction_polarization')

From 114160c979d75f4fa996a2e3c56e7beaae1671c7 Mon Sep 17 00:00:00 2001
From: "Alec L. Robitaille" <robit.alec@gmail.com>
Date: Tue, 8 Oct 2024 11:11:49 -0300
Subject: [PATCH 12/24] setup

---
 tests/testthat/test-direction-polarization.R | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/tests/testthat/test-direction-polarization.R b/tests/testthat/test-direction-polarization.R
index e8341e48..c9949412 100644
--- a/tests/testthat/test-direction-polarization.R
+++ b/tests/testthat/test-direction-polarization.R
@@ -1,2 +1,21 @@
 # Test direction_polarization
 context('test direction_polarization')
+
+library(spatsoc)
+
+DT <- fread('../testdata/DT.csv')
+id <- 'ID'
+datetime <- 'datetime'
+timethreshold <- '20 minutes'
+threshold <- 50
+coords <- c('X', 'Y')
+timegroup <- 'timegroup'
+group <- 'group'
+projection <- 32736
+
+DT[, datetime := as.POSIXct(datetime, tz = 'UTC')]
+group_times(DT, datetime = datetime, threshold = timethreshold)
+group_pts(DT, threshold = threshold, id = id, coords = coords, timegroup = timegroup)
+direction_step(DT, id = id, coords = coords, projection = projection)
+
+clean_DT <- copy(DT)

From 07bba3ba569c94843455a6b8501a672736468656 Mon Sep 17 00:00:00 2001
From: "Alec L. Robitaille" <robit.alec@gmail.com>
Date: Tue, 8 Oct 2024 11:11:57 -0300
Subject: [PATCH 13/24] test DT required

---
 tests/testthat/test-direction-polarization.R | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/tests/testthat/test-direction-polarization.R b/tests/testthat/test-direction-polarization.R
index c9949412..f4544047 100644
--- a/tests/testthat/test-direction-polarization.R
+++ b/tests/testthat/test-direction-polarization.R
@@ -19,3 +19,7 @@ group_pts(DT, threshold = threshold, id = id, coords = coords, timegroup = timeg
 direction_step(DT, id = id, coords = coords, projection = projection)
 
 clean_DT <- copy(DT)
+
+test_that('DT is required', {
+  expect_error(direction_polarization(DT = NULL))
+})

From 488c5fa02cf290de05f71756f0b1370e924df8fe Mon Sep 17 00:00:00 2001
From: "Alec L. Robitaille" <robit.alec@gmail.com>
Date: Tue, 8 Oct 2024 11:11:59 -0300
Subject: [PATCH 14/24] test args

---
 tests/testthat/test-direction-polarization.R | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/tests/testthat/test-direction-polarization.R b/tests/testthat/test-direction-polarization.R
index f4544047..44559877 100644
--- a/tests/testthat/test-direction-polarization.R
+++ b/tests/testthat/test-direction-polarization.R
@@ -23,3 +23,10 @@ clean_DT <- copy(DT)
 test_that('DT is required', {
   expect_error(direction_polarization(DT = NULL))
 })
+
+test_that('arguments required, otherwise error detected', {
+  expect_error(direction_polarization(DT, group = NULL),
+               'group column name required')
+  expect_error(direction_polarization(DT, direction = NULL),
+               'direction column name required')
+})

From db9486171a1eccdf65612f76e63e3406c43ad2a8 Mon Sep 17 00:00:00 2001
From: "Alec L. Robitaille" <robit.alec@gmail.com>
Date: Tue, 8 Oct 2024 11:12:02 -0300
Subject: [PATCH 15/24] test colnames

---
 tests/testthat/test-direction-polarization.R | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/tests/testthat/test-direction-polarization.R b/tests/testthat/test-direction-polarization.R
index 44559877..3ff0d7f8 100644
--- a/tests/testthat/test-direction-polarization.R
+++ b/tests/testthat/test-direction-polarization.R
@@ -30,3 +30,10 @@ test_that('arguments required, otherwise error detected', {
   expect_error(direction_polarization(DT, direction = NULL),
                'direction column name required')
 })
+
+test_that('column names must exist in DT', {
+  expect_error(direction_polarization(DT, direction = 'potato'),
+               'potato field')
+  expect_error(direction_polarization(DT, group = 'potato'),
+               'potato field')
+})

From ea5103e3d31b0f1a19f37cbeea9ee1911d593845 Mon Sep 17 00:00:00 2001
From: "Alec L. Robitaille" <robit.alec@gmail.com>
Date: Tue, 8 Oct 2024 11:12:05 -0300
Subject: [PATCH 16/24] test radians

---
 tests/testthat/test-direction-polarization.R | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/tests/testthat/test-direction-polarization.R b/tests/testthat/test-direction-polarization.R
index 3ff0d7f8..a31b52fc 100644
--- a/tests/testthat/test-direction-polarization.R
+++ b/tests/testthat/test-direction-polarization.R
@@ -37,3 +37,8 @@ test_that('column names must exist in DT', {
   expect_error(direction_polarization(DT, group = 'potato'),
                'potato field')
 })
+
+test_that('radians expected else error', {
+  expect_error(direction_polarization(DT, direction = 'X'),
+               'direction_step')
+})

From 1c7de46be87cb2906557651f7a2635d92a338c5c Mon Sep 17 00:00:00 2001
From: "Alec L. Robitaille" <robit.alec@gmail.com>
Date: Tue, 8 Oct 2024 11:12:10 -0300
Subject: [PATCH 17/24] test numeric

---
 tests/testthat/test-direction-polarization.R | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/tests/testthat/test-direction-polarization.R b/tests/testthat/test-direction-polarization.R
index a31b52fc..40da64ad 100644
--- a/tests/testthat/test-direction-polarization.R
+++ b/tests/testthat/test-direction-polarization.R
@@ -42,3 +42,8 @@ test_that('radians expected else error', {
   expect_error(direction_polarization(DT, direction = 'X'),
                'direction_step')
 })
+
+test_that('direction expected numeric', {
+  expect_error(direction_polarization(DT, direction = 'ID'),
+               'direction must be numeric')
+})

From 246521789a474686fd82d5551f2cbc2f9bf85a1d Mon Sep 17 00:00:00 2001
From: "Alec L. Robitaille" <robit.alec@gmail.com>
Date: Tue, 8 Oct 2024 11:12:18 -0300
Subject: [PATCH 18/24] test msg if overwrite

---
 tests/testthat/test-direction-polarization.R | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/tests/testthat/test-direction-polarization.R b/tests/testthat/test-direction-polarization.R
index 40da64ad..d1928a57 100644
--- a/tests/testthat/test-direction-polarization.R
+++ b/tests/testthat/test-direction-polarization.R
@@ -47,3 +47,12 @@ test_that('direction expected numeric', {
   expect_error(direction_polarization(DT, direction = 'ID'),
                'direction must be numeric')
 })
+
+
+test_that('group_direction column succesfully detected', {
+  copyDT <- copy(clean_DT)[, group_direction := 1]
+  expect_message(
+    direction_polarization(copyDT),
+    'group_direction column will be overwritten'
+  )
+})

From 38d721ac5f6a084ae0b8fac13e71a0e39864ac78 Mon Sep 17 00:00:00 2001
From: "Alec L. Robitaille" <robit.alec@gmail.com>
Date: Tue, 8 Oct 2024 11:13:06 -0300
Subject: [PATCH 19/24] fix colname output

---
 tests/testthat/test-direction-polarization.R | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/tests/testthat/test-direction-polarization.R b/tests/testthat/test-direction-polarization.R
index d1928a57..efdc1bad 100644
--- a/tests/testthat/test-direction-polarization.R
+++ b/tests/testthat/test-direction-polarization.R
@@ -49,10 +49,11 @@ test_that('direction expected numeric', {
 })
 
 
-test_that('group_direction column succesfully detected', {
-  copyDT <- copy(clean_DT)[, group_direction := 1]
+test_that('polarization column succesfully detected', {
+  copyDT <- copy(clean_DT)[, polarization := 1]
   expect_message(
     direction_polarization(copyDT),
-    'group_direction column will be overwritten'
+    'polarization column will be overwritten'
   )
 })
+

From 9a21367cf79fa99ea29c6bc6cb59184b419e2597 Mon Sep 17 00:00:00 2001
From: "Alec L. Robitaille" <robit.alec@gmail.com>
Date: Tue, 8 Oct 2024 11:13:17 -0300
Subject: [PATCH 20/24] test output

---
 tests/testthat/test-direction-polarization.R | 21 ++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/tests/testthat/test-direction-polarization.R b/tests/testthat/test-direction-polarization.R
index efdc1bad..e99cc296 100644
--- a/tests/testthat/test-direction-polarization.R
+++ b/tests/testthat/test-direction-polarization.R
@@ -57,3 +57,24 @@ test_that('polarization column succesfully detected', {
   )
 })
 
+test_that('no rows are added to the result DT', {
+  copyDT <- copy(clean_DT)
+
+  expect_equal(nrow(copyDT),
+               nrow(direction_polarization(copyDT)))
+})
+
+test_that('one column added to the result DT', {
+  copyDT <- copy(clean_DT)
+
+  expect_equal(ncol(copyDT) + 1,
+               ncol(direction_polarization(DT)))
+})
+
+test_that('column added to the result DT is numeric', {
+  expect_type(direction_polarization(DT)$polarization, 'double')
+})
+
+test_that('returns a data.table', {
+  expect_s3_class(direction_polarization(DT), 'data.table')
+})

From fbc21644e1a6cc187e8d7942e2cbdbca8735de82 Mon Sep 17 00:00:00 2001
From: "Alec L. Robitaille" <robit.alec@gmail.com>
Date: Tue, 8 Oct 2024 11:16:07 -0300
Subject: [PATCH 21/24] rename to direction_polarization

---
 R/direction_polarization.R | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/R/direction_polarization.R b/R/direction_polarization.R
index 789216b2..37dba845 100644
--- a/R/direction_polarization.R
+++ b/R/direction_polarization.R
@@ -67,7 +67,7 @@
 #'
 #' # Calculate polarization
 #' direction_polarization(DT)
-direction_group <- function(
+direction_polarization <- function(
     DT,
     direction = 'direction',
     group = 'group') {

From c434b3a83b76ce8ac5e98971cb1be574fe2ce1f4 Mon Sep 17 00:00:00 2001
From: "Alec L. Robitaille" <robit.alec@gmail.com>
Date: Tue, 8 Oct 2024 11:16:53 -0300
Subject: [PATCH 22/24] man

---
 NAMESPACE                     |  1 +
 man/direction_group.Rd        | 22 ++++++---
 man/direction_polarization.Rd | 91 ++++++++++++++++++++++++++++++-----
 man/direction_step.Rd         |  3 +-
 4 files changed, 96 insertions(+), 21 deletions(-)

diff --git a/NAMESPACE b/NAMESPACE
index 50f26890..fe75b39e 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -6,6 +6,7 @@ export(centroid_dyad)
 export(centroid_fusion)
 export(centroid_group)
 export(direction_group)
+export(direction_polarization)
 export(direction_step)
 export(direction_to_centroid)
 export(distance_to_centroid)
diff --git a/man/direction_group.Rd b/man/direction_group.Rd
index 56102f79..839fc7b5 100644
--- a/man/direction_group.Rd
+++ b/man/direction_group.Rd
@@ -1,12 +1,8 @@
 % Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/direction_polarization.R
+% Please edit documentation in R/direction_group.R
 \name{direction_group}
 \alias{direction_group}
-\title{\code{direction_polarization} calculates the direction polarization of
-all individuals in each spatiotemporal group identified by \code{group_pts}. The function
-expects a \code{data.table} with relocation data appended with a
-\code{direction} column from \code{direction_step} and a \code{group} column
-from \code{group_pts}.}
+\title{Group mean direction}
 \usage{
 direction_group(DT, direction = "direction", group = "group")
 }
@@ -31,12 +27,18 @@ A message is returned when the \code{group_direction} columns already
 exists in the input \code{DT}, because it will be overwritten.
 }
 \description{
+\code{direction_group} calculates the mean direction of all individuals in
+each spatiotemporal group identified by \code{group_pts}. The function
+accepts a \code{data.table} with relocation data appended with a
+\code{direction} column from \code{direction_step} and a \code{group} column
+from \code{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}}.
-}
-\details{
+
 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
@@ -82,5 +84,9 @@ See example of using mean group direction:
 \seealso{
 \code{\link{direction_step}}, \code{\link{group_pts}},
 \code{\link[CircStats:circ.mean]{CircStats::circ.mean()}}
+
+Other Direction functions: 
+\code{\link{direction_polarization}()},
+\code{\link{direction_step}()}
 }
 \concept{Direction functions}
diff --git a/man/direction_polarization.Rd b/man/direction_polarization.Rd
index 69d7f90e..b4832f6a 100644
--- a/man/direction_polarization.Rd
+++ b/man/direction_polarization.Rd
@@ -2,24 +2,91 @@
 % Please edit documentation in R/direction_polarization.R
 \name{direction_polarization}
 \alias{direction_polarization}
-\title{Calculate group polarization}
+\title{Polarization}
 \usage{
-direction_polarization(
-  DT,
-  bearing = "bearing",
-  group = "group",
-  degree = FALSE
-)
+direction_polarization(DT, direction = "direction", group = "group")
 }
 \arguments{
-\item{DT}{with bearing column generated by eg. bearing_sequential}
+\item{DT}{input data.table with distance column generated by
+\code{distance_step} and group column generated with \code{group_pts}}
+
+\item{direction}{character string of direction column name, default
+"direction"}
 
-\item{bearing}{bearing column name, default 'bearing'}
+\item{group}{character string of group column name, default "group"}
+}
+\value{
+\code{direction_polarization} returns the input \code{DT} appended
+with a \code{polarization} column representing the direction polarization
+of all individuals in each spatiotemporal group.
 
-\item{group}{group column name generated by eg. group_pts, default 'group'}
+The direction polarization is calculated using \code{\link[CircStats:r.test]{CircStats::r.test()}}
+which expects units of radians.
 
-\item{degree}{boolean, if bearing is measured in degrees. See ?CircStats::r.test}
+A message is returned when the \code{polarization} columns already
+exists in the input \code{DT}, because it will be overwritten.
 }
 \description{
-Polarization of group bearings from 0-1
+\code{direction_polarization} calculates the polarization of individual
+directions in each spatiotemporal group identified by \code{group_pts}. The
+function expects a \code{data.table} with relocation data appended with a
+\code{direction} column from \code{direction_step} and a \code{group} column
+from \code{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 polarization is
+calculated with \code{\link[CircStats:r.test]{CircStats::r.test()}}.
+}
+\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 polarization
+direction_polarization(DT)
+}
+\references{
+See example of using polarization:
+\itemize{
+\item \url{https://doi.org/10.1016/j.cub.2017.08.004}
+\item <10.1371/journal.pcbi.1009437>
+\item \url{https://doi.org/10.7554/eLife.19505}
+}
+}
+\seealso{
+\code{\link{direction_step}}, \code{\link{group_pts}},
+\code{\link[CircStats:r.test]{CircStats::r.test()}}
+
+Other Direction functions: 
+\code{\link{direction_group}()},
+\code{\link{direction_step}()}
 }
+\concept{Direction functions}
diff --git a/man/direction_step.Rd b/man/direction_step.Rd
index 0b6df87c..07a56fba 100644
--- a/man/direction_step.Rd
+++ b/man/direction_step.Rd
@@ -99,6 +99,7 @@ direction_step(
 \code{\link[amt:steps]{amt::direction_abs()}}, \code{\link[geosphere:bearing]{geosphere::bearing()}}
 
 Other Direction functions: 
-\code{\link{direction_group}()}
+\code{\link{direction_group}()},
+\code{\link{direction_polarization}()}
 }
 \concept{Direction functions}

From 512ab612ad58b86055196a318fa930ca4f48fb38 Mon Sep 17 00:00:00 2001
From: "Alec L. Robitaille" <robit.alec@gmail.com>
Date: Tue, 8 Oct 2024 11:25:43 -0300
Subject: [PATCH 23/24] fix .SD

---
 R/direction_polarization.R | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/R/direction_polarization.R b/R/direction_polarization.R
index 37dba845..1b03210c 100644
--- a/R/direction_polarization.R
+++ b/R/direction_polarization.R
@@ -112,7 +112,7 @@ direction_polarization <- function(
     stop('units(DT$direction) is not radians, did you use direction_step?')
   }
 
-  DT[, c(out) := CircStats::r.test(units::drop_units(.SD))$r.bar,
+  DT[, c(out) := CircStats::r.test(units::drop_units(.SD[[1]]), degree = FALSE)$r.bar,
     by = c(group),
     .SDcols = c(direction)]
 

From 6190ff0c38d727c0017a86f5a5fce6ecc193c35b Mon Sep 17 00:00:00 2001
From: "Alec L. Robitaille" <robit.alec@gmail.com>
Date: Tue, 8 Oct 2024 11:25:51 -0300
Subject: [PATCH 24/24] test range polarization

---
 tests/testthat/test-direction-polarization.R | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/tests/testthat/test-direction-polarization.R b/tests/testthat/test-direction-polarization.R
index e99cc296..fd74de23 100644
--- a/tests/testthat/test-direction-polarization.R
+++ b/tests/testthat/test-direction-polarization.R
@@ -71,8 +71,10 @@ test_that('one column added to the result DT', {
                ncol(direction_polarization(DT)))
 })
 
-test_that('column added to the result DT is numeric', {
+test_that('column added to the result DT is numeric, between 0-1', {
   expect_type(direction_polarization(DT)$polarization, 'double')
+  expect_gte(min(direction_polarization(DT)$polarization, na.rm = TRUE), 0)
+  expect_lte(max(direction_polarization(DT)$polarization, na.rm = TRUE), 1)
 })
 
 test_that('returns a data.table', {