Add Benhamou's sinuosity.

CRAN-SUBMISSION

@@ -0,0 +1,3 @@
+Version: 0.6.0
+Date: 2023-01-10 21:18:49 UTC
+SHA: 7182964fda4ecdbb720171163eca50e420d93a71

NAMESPACE

@@ -28,5 +28,6 @@ export(polOrder)
 export(pol_order)
 export(rotOrder)
 export(rot_order)
+export(sinuosity)
 export(sphericity)
 export(stretch)

R/shape.R

@@ -72,3 +72,53 @@ stretch <- function(x, y) {
     ell$alpha}, 
     error = function(e) as.numeric(NA))
 }
+
+
+#' @title Sinuosity
+#' 
+#' @description Given a set of successive step lengths and turning angles, this
+#'  function computes he sinuosity of a trajectory as defined by Benhamou (2004), 
+#'  equation 8.  This is a corrected version of the sinuosity index defined in 
+#'  Bovet & Benhamou (1988), which is suitable for a wider range of turning 
+#'  angle distributions, and does not require a constant step length.
+#'
+#' @param step_lengths A vector of step lengths as calculated by 
+#'  \code{\link{linear_dist}}. 
+#' 
+#' @param turning_angles A vector of turning angles as calculated by 
+#'  \code{\link{ang_speed}}. 
+#'
+#' @return A single numeric value corresponding to the sinuosity of the 
+#'  trajectory. 
+#' 
+#' @references Benhamou, S. (2004). How to reliably estimate the tortuosity of 
+#'  an animal’s path: straightness, sinuosity, or fractal dimension? Journal of 
+#'  Theoretical Biology, 229(2), 209–220. https://doi.org/10.1016/j.jtbi.2004.03.016
+#'  
+#'  Bovet, P., & Benhamou, S. (1988). Spatial analysis of animals’ movements 
+#'  using a correlated random walk model. Journal of Theoretical Biology, 131(4), 
+#'  419–433. https://doi.org/10.1016/S0022-5193(88)80038-9
+#' 
+#' @author Simon Garnier, \email{garnier@@njit.edu}
+#' 
+#' @seealso \code{\link{linear_dist}}, \code{\link{ang_speed}}
+#' 
+#' @examples
+#' x <- rnorm(25)
+#' y <- rnorm(25, sd = 3)
+#' t <- as.POSIXct(1:25, origin = Sys.time())
+#' step_lengths <- linear_dist(x, y)
+#' turning_angles <- ang_speed(x, y, t)
+#' sinuosity(step_lengths, turning_angles)
+#' 
+#' @export
+sinuosity <- function(step_lengths, turning_angles) {
+  if (length(step_lengths) != length(turning_angles)) 
+    stop("step_lengths and turning_angles should have the same length.")
+
+  nas <- is.na(step_lengths) | is.na(turning_angles)
+  mean_sl <- mean(step_lengths[!nas])
+  coefvar_sl <- stats::sd(step_lengths[!nas]) / mean_sl
+  meancos_ta <- mean(cos(turning_angles[!nas]))
+  2 / sqrt(mean_sl * (((1 + meancos_ta) / (1 - meancos_ta)) + coefvar_sl ^ 2))
+}

docs/pkgdown.yml

@@ -1,9 +1,9 @@
-pandoc: 2.19.2
+pandoc: 3.1.9
 pkgdown: 2.0.7
 pkgdown_sha: ~
 articles:
   z1_install: z1_install.html
-last_built: 2023-01-10T17:25Z
+last_built: 2023-11-23T09:14Z
 urls:
   reference: https://swarm-lab.github.io/swaRm/reference
   article: https://swarm-lab.github.io/swaRm/articles