Merge pull request #76 from ropensci/feat/polarization

Feat/polarization

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)

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

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

R/direction_polarization.R

@@ -0,0 +1,122 @@
+#' Polarization
+#'
+#' \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}.
+#'
+#' 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 [CircStats::r.test()].
+#'
+#' @inheritParams direction_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 direction polarization is calculated using [CircStats::r.test()]
+#'   which expects units of radians.
+#'
+#'   A message is returned when the \code{polarization} columns already
+#'   exists in the input \code{DT}, because it will be overwritten.
+#'
+#' @export
+#' @seealso \code{\link{direction_step}}, \code{\link{group_pts}},
+#'   [CircStats::r.test()]
+#' @family Direction functions
+#'
+#' @references
+#' 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
+#' 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)
+direction_polarization <- 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 <- 'polarization'
+
+  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)] ||
+      DT[, units(.SD[[1]])$numerator != 'rad', .SDcols = c(direction)]) {
+    stop('units(DT$direction) is not radians, did you use direction_step?')
+  }
+
+  DT[, c(out) := CircStats::r.test(units::drop_units(.SD[[1]]), degree = FALSE)$r.bar,
+    by = c(group),
+    .SDcols = c(direction)]
+
+  return(DT[])
+}
+
+

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

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

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

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

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`

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

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.
 #'

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