Just docs and patches to ensure successful building

DESCRIPTION

@@ -32,6 +32,7 @@ Imports:
     rhdf5,
     rlang,
     roll,
+    scales,
     signal,
     stinepack,
     stringi,

NAMESPACE

@@ -1,6 +1,8 @@
 # Generated by roxygen2: do not edit by hand
 
+export(add_centroid)
 export(calculate_kinematics)
+export(calculate_speed)
 export(calculate_statistics)
 export(calculate_straightness)
 export(check_confidence)
@@ -15,12 +17,13 @@ export(filter_by_confidence)
 export(filter_by_speed)
 export(get_metadata)
 export(ggplot_na_gapsize)
-export(ggplot_na_timing)
 export(group_every)
 export(init_metadata)
 export(map_to_cartesian)
 export(map_to_polar)
 export(na_interpolation)
+export(plot_position_timeseries)
+export(plot_speed_timeseries)
 export(read_animalta)
 export(read_bonsai)
 export(read_deeplabcut)
@@ -56,11 +59,14 @@ importFrom(cli,cli_inform)
 importFrom(collapse,fmean)
 importFrom(collapse,fmedian)
 importFrom(collapse,fsd)
+importFrom(dplyr,arrange)
+importFrom(dplyr,bind_rows)
 importFrom(dplyr,filter)
 importFrom(dplyr,group_by)
 importFrom(dplyr,if_else)
 importFrom(dplyr,mutate)
 importFrom(dplyr,select)
+importFrom(dplyr,summarise)
 importFrom(dplyr,ungroup)
 importFrom(ggplot2,aes)
 importFrom(ggplot2,after_stat)
@@ -69,6 +75,7 @@ importFrom(ggplot2,coord_flip)
 importFrom(ggplot2,element_blank)
 importFrom(ggplot2,element_text)
 importFrom(ggplot2,geom_bar)
+importFrom(ggplot2,geom_line)
 importFrom(ggplot2,ggplot)
 importFrom(ggplot2,ggtitle)
 importFrom(ggplot2,labs)
@@ -87,7 +94,6 @@ importFrom(ggtext,element_markdown)
 importFrom(grDevices,nclass.Sturges)
 importFrom(janitor,clean_names)
 importFrom(lifecycle,deprecated)
-importFrom(magrittr,"%>%")
 importFrom(methods,hasArg)
 importFrom(patchwork,plot_annotation)
 importFrom(patchwork,plot_layout)
@@ -96,9 +102,10 @@ importFrom(rlang,":=")
 importFrom(rlang,.data)
 importFrom(roll,roll_mean)
 importFrom(roll,roll_median)
+importFrom(scales,rescale)
+importFrom(signal,sgolayfilt)
 importFrom(stats,approx)
 importFrom(stats,spline)
-importFrom(stats,ts)
 importFrom(stinepack,stinterp)
 importFrom(stringi,stri_rand_strings)
 importFrom(vroom,vroom)

R/calculate_kinematics.R

@@ -100,11 +100,61 @@ adjust_direction <- function(direction) {
   circular::circular(direction, modulo = "2pi")
 }
 
-#' Calculate the centroid
+#' Add Centroid to Movement Data
 #'
-#' @param data a movement data frame
-#' @param include_keypoints choose a subset of keypoints used for computing the centorid
-#' @param exclude_keypoints chosose a subset of keypoints that are excluded when conputing the centroid
+#' @description
+#' Calculates and adds a centroid point to movement tracking data. The centroid
+#' represents the mean position of selected keypoints at each time point.
+#'
+#' @param data A data frame containing movement tracking data with the following
+#'   required columns:
+#'   - `individual`: Identifier for each tracked subject
+#'   - `keypoint`: Factor specifying tracked points
+#'   - `time`: Time values
+#'   - `x`: x-coordinates
+#'   - `y`: y-coordinates
+#'   - `confidence`: Confidence values for tracked points
+#' @param include_keypoints Optional character vector specifying which keypoints
+#'   to use for centroid calculation. If NULL (default), all keypoints are used
+#'   unless `exclude_keypoints` is specified.
+#' @param exclude_keypoints Optional character vector specifying which keypoints
+#'   to exclude from centroid calculation. If NULL (default), no keypoints are
+#'   excluded unless `include_keypoints` is specified.
+#' @param centroid_name Character string specifying the name for the centroid
+#'   keypoint (default: "centroid")
+#'
+#' @return A data frame with the same structure as the input, but with an
+#'   additional keypoint representing the centroid. The centroid's confidence
+#'   values are set to NA.
+#'
+#' @details
+#' The function calculates the centroid as the mean x and y position of the
+#' selected keypoints at each time point for each individual. Keypoints can be
+#' selected either by specifying which ones to include (`include_keypoints`) or
+#' which ones to exclude (`exclude_keypoints`). The resulting centroid is added
+#' as a new keypoint to the data frame.
+#'
+#' @examples
+#' \dontrun{
+#' # Add centroid using all keypoints
+#' add_centroid(movement_data)
+#'
+#' # Calculate centroid using only specific keypoints
+#' add_centroid(movement_data,
+#'             include_keypoints = c("head", "thorax", "abdomen"))
+#'
+#' # Calculate centroid excluding certain keypoints
+#' add_centroid(movement_data,
+#'             exclude_keypoints = c("antenna_left", "antenna_right"),
+#'             centroid_name = "body_centroid")
+#' }
+#'
+#' @seealso
+#' `convert_nan_to_na()` for NaN handling in the centroid calculation
+#'
+#' @importFrom dplyr filter group_by summarise mutate arrange bind_rows
+#'
+#' @export
 add_centroid <- function(data,
                          include_keypoints=NULL,
                          exclude_keypoints=NULL,

R/calculate_speed.R

@@ -14,8 +14,8 @@
 #' @examples
 #' \dontrun{
 #' # Inside dplyr pipeline
-#' data %>%
-#'   group_by(keypoint) %>%
+#' data |>
+#'   group_by(keypoint) |>
 #'   mutate(speed = calculate_speed(x, y, time))
 #' }
 #'

R/check_confidence.R

@@ -22,7 +22,7 @@
 #' @examples
 #' library(dplyr)
 #' library(patchwork)
-#' data <- tibble::tibble(
+#' data <- dplyr::tibble(
 #'   keypoint = rep(c("head", "arm", "leg", "torso"), each = 10),
 #'   confidence = runif(40, min = 0, max = 1)
 #' )

R/check_na_gapsize.R

@@ -30,7 +30,7 @@
 #' library(dplyr)
 #' library(ggplot2)
 #' library(patchwork)
-#' data <- tibble::tibble(
+#' data <- dplyr::tibble(
 #'   x = c(NA, NA, 3, NA, 5, 6, NA, NA, NA, 10),
 #'   keypoint = factor(rep(c("head", "arm"), each = 5))
 #' )

R/check_na_timing.R

@@ -27,7 +27,7 @@
 #' library(dplyr)
 #' library(ggplot2)
 #' library(patchwork)
-#' data <- tibble::tibble(
+#' data <- dplyr::tibble(
 #'   x = c(1, 2, NA, 4, NA, 6),
 #'   individual = rep("A", 6),
 #'   keypoint = factor(rep(c("head", "arm"), each = 3))

R/check_pose.R

@@ -7,17 +7,17 @@
 #' @param data A data frame containing at least the columns `keypoint`, `x`, and `y`.
 #' @param reference_keypoint The keypoint used as a reference to calculate the distance.
 #' @param type Character string specifying the type of plot to create. Options are:
-#' - `"histogram"`: Histograms of the distance distributions (default).
-#' - `"confidence"`: Plots showing confidence intervals for the distances.
+#'   - `"histogram"`: Histograms of the distance distributions (default)
+#'   - `"confidence"`: Plots showing confidence intervals for the distances
 #'
 #' @return A `patchwork` object combining plots for each keypoint, visualizing
 #' the distances to the centroid.
 #'
 #' @details
-#' - The centroid is computed using the `add_centroid` function and distances are
+#' The centroid is computed using the `add_centroid` function and distances are
 #' calculated with the `calculate_distance_to_centroid` function.
-#' - The function automatically excludes the centroid itself from the visualizations.
-#' - Histograms provide an overview of distance distributions, while confidence plots
+#' The function automatically excludes the centroid itself from the visualizations.
+#' Histograms provide an overview of distance distributions, while confidence plots
 #' summarize variability with intervals.
 #'
 #' @importFrom dplyr filter mutate
@@ -26,14 +26,20 @@
 #' @importFrom cli cli_abort
 #'
 #' @examples
-#' library(dplyr)
-#' library(patchwork)
-#' data <- tibble::tibble(
+#' \dontrun{
+#' # Create sample data
+#' data <- dplyr::tibble(
 #'   keypoint = rep(c("head", "arm", "leg", "torso"), each = 10),
 #'   x = rnorm(40, mean = 0, sd = 1),
 #'   y = rnorm(40, mean = 0, sd = 1)
 #' )
-#' check_pose(data, type = "histogram")
+#'
+#' # Plot histogram of distances
+#' check_pose(data, reference_keypoint = "head", type = "histogram")
+#'
+#' # Plot confidence intervals
+#' check_pose(data, reference_keypoint = "head", type = "confidence")
+#' }
 #'
 #' @export
 check_pose <- function(data, reference_keypoint, type = "histogram"){
@@ -45,7 +51,7 @@ check_pose <- function(data, reference_keypoint, type = "histogram"){
   color_border = "black"
   na_plots <- list()
   d_ref <- data |>
-    dplyr::filter(keypoint == reference_keypoint) |>
+    dplyr::filter(.data$keypoint == reference_keypoint) |>
     dplyr::mutate(keypoint = "reference_keypoint")
   data <- dplyr::bind_rows(data, d_ref)
 

R/filter_by_confidence.R

@@ -15,12 +15,12 @@
 #'
 #' @examples
 #' library(dplyr)
-#' data <- tibble::tibble(
+#' data <- dplyr::tibble(
 #'   x = 1:5,
 #'   y = 6:10,
 #'   confidence = c(0.5, 0.7, 0.4, 0.8, 0.9)
 #' )
-#' filter_confidence(data, threshold = 0.6)
+#' filter_by_confidence(data, threshold = 0.6)
 #'
 #' @export
 filter_by_confidence <- function(data, threshold=0.6){

R/filter_by_speed.R

@@ -1,54 +1,103 @@
 #' Filter values by speed threshold
 #'
+#' @description
 #' This function filters out values in a dataset where the calculated speed exceeds
 #' a specified threshold. Values for `x`, `y`, and `confidence` are replaced with
 #' `NA` if their corresponding speed exceeds the threshold. Speed is calculated
 #' using the `calculate_kinematics` function.
 #'
-#' @param data A data frame containing at least the columns `x` and `y`.
-#' @param threshold A numeric value specifying the speed threshold. Observations
-#' with speeds greater than this value will have their `x`, `y`, and `confidence`
-#' values replaced with `NA`. If set to `"auto"`, the function will set the threshold at the mean speed + 3 standard deviations (SD).
+#' @param data A data frame containing the following required columns:
+#'   - `x`: x-coordinates
+#'   - `y`: y-coordinates
+#'   - `time`: time values
+#' Optional column:
+#'   - `confidence`: confidence values for each observation
+#' @param threshold A numeric value specifying the speed threshold, or "auto".
+#'   - If numeric: Observations with speeds greater than this value will have their
+#'     `x`, `y`, and `confidence` values replaced with `NA`
+#'   - If "auto": Sets threshold at mean speed + 3 standard deviations
 #'
 #' @return A data frame with the same columns as the input `data`, but with
 #' values replaced by `NA` where the speed exceeds the threshold.
 #'
 #' @details
-#' - The speed is calculated using the `calculate_kinematics` function, which
+#' The speed is calculated using the `calculate_kinematics` function, which
 #' computes translational velocity (`v_translation`) and other kinematic parameters.
-#' - The `"auto"` threshold option is currently not implemented and will result
-#' in an error.
-#' - The output data frame retains the original columns and structure of the input
-#' data.
+#' When using `threshold = "auto"`, the function calculates the threshold as the
+#' mean speed plus three standard deviations, which assumes normally distributed speeds.
 #'
 #' @importFrom dplyr mutate if_else select
 #' @importFrom cli cli_abort
 #'
 #' @examples
-#' library(dplyr)
-#' data <- tibble::tibble(
+#' \dontrun{
+#' data <- dplyr::tibble(
+#'   time = 1:5,
 #'   x = c(1, 2, 4, 7, 11),
 #'   y = c(1, 1, 2, 3, 5),
 #'   confidence = c(0.8, 0.9, 0.7, 0.85, 0.6)
 #' )
-
+#'
 #' # Filter data by a speed threshold of 3
 #' filter_by_speed(data, threshold = 3)
 #'
+#' # Use automatic threshold
+#' filter_by_speed(data, threshold = "auto")
+#' }
+#'
 #' @export
-filter_by_speed <- function(data, threshold = "auto"){
+filter_by_speed <- function(data, threshold = "auto") {
+  # Check required columns
+  required_cols <- c("x", "y", "time")
+  missing_cols <- setdiff(required_cols, names(data))
+
+  if (length(missing_cols) > 0) {
+    cli::cli_abort(c(
+      "Missing required columns in data:",
+      "x" = paste(missing_cols, collapse = ", ")
+    ))
+  }
+
+  # Check that x, y, time are numeric
+  non_numeric_cols <- sapply(data[required_cols], function(col) !is.numeric(col))
+  if (any(non_numeric_cols)) {
+    bad_cols <- names(non_numeric_cols)[non_numeric_cols]
+    cli::cli_abort(c(
+      "The following columns must be numeric:",
+      "x" = paste(bad_cols, collapse = ", ")
+    ))
+  }
+
+  # Check threshold input
+  if (!identical(threshold, "auto") && !is.numeric(threshold)) {
+    cli::cli_abort("threshold must be either 'auto' or a numeric value")
+  }
+
   n_cols <- ncol(data)
   d <- data |>
     calculate_kinematics()
-  if (threshold == "auto"){
-    threshold <- mean(d$v_translation) + 3*sd(d$v_translation)
-  } else {
+
+  if (identical(threshold, "auto")) {
+    threshold <- mean(d$v_translation, na.rm = TRUE) +
+      3 * sd(d$v_translation, na.rm = TRUE)
+  }
+
   d <- d |>
-    dplyr::mutate(x = dplyr::if_else(abs(.data$v_translation) < threshold, NA, .data$x),
-                  y = dplyr::if_else(abs(.data$v_translation) < threshold, NA, .data$y),
-                  confidence = dplyr::if_else(abs(.data$v_translation) < threshold, NA, .data$confidence)) |>
-    dplyr::select(1:n_cols)
+    dplyr::mutate(
+      x = dplyr::if_else(abs(.data$v_translation) < threshold, NA, .data$x),
+      y = dplyr::if_else(abs(.data$v_translation) < threshold, NA, .data$y)
+    )
+
+  # Only modify confidence if it exists
+  if ("confidence" %in% names(d)) {
+    d <- d |>
+      dplyr::mutate(
+        confidence = dplyr::if_else(abs(.data$v_translation) < threshold,
+                                    NA, .data$confidence)
+      )
   }
 
+  d <- d |> dplyr::select(1:n_cols)
+
   return(d)
 }