Add Centroid to Movement Data

Calculates and adds a centroid point to movement tracking data. The centroid represents the mean position of selected keypoints at each time point.

Usage

add_centroid(
  data,
  include_keypoints = NULL,
  exclude_keypoints = NULL,
  centroid_name = "centroid"
)

Arguments

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

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.

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.

centroid_name

Character string specifying the name for the centroid keypoint (default: "centroid")

Value

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.

See also

convert_nan_to_na() for NaN handling in the centroid calculation

Examples

if (FALSE) { # \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")
} # }