Classify Movement States Based on Stability Analysis

This function analyzes movement tracking data to identify periods of high and low activity by detecting stable periods in the movement data. It returns a binary classification where 1 indicates high activity and 0 indicates low activity.

Usage

classify_by_stability(
  speed,
  window_size = 30,
  min_stable_period = 30,
  tolerance = 0.1,
  refine_transitions = TRUE,
  min_low_state_duration = 0,
  min_high_state_duration = 0,
  search_window = 90,
  stability_window = 10,
  stability_threshold = 0.5,
  return_type = c("numeric", "factor")
)

Arguments

speed

Numeric vector of speed or velocity measurements. If velocity is provided, absolute values will be used automatically

window_size

Number of measurements to consider when calculating variance (default: 30)

min_stable_period

Minimum length required for a stable period (default: 30)

tolerance

Tolerance for variance in stable periods (default: 0.1, must be between 0 and 1)

refine_transitions

Whether to refine state transitions using stability detection (default: TRUE)

min_low_state_duration

Minimum duration for low activity states; shorter periods are merged using majority context (default: 0, no merging)

min_high_state_duration

Minimum duration for high activity states; shorter periods are merged using majority context (default: 0, no merging)

search_window

How far to look for movement transitions when refining (default: 90)

stability_window

Window size for checking if movement has stabilized (default: 10)

stability_threshold

Maximum variance allowed in stable state (default: 0.5)

return_type

Should the function return "factor" ("high"/"low") or "numeric" (1/0) (default: "numeric")

Value

Numeric vector of the same length as input:

• 1: High activity state

• 0: Low activity state

• NA: Unable to classify (usually due to missing data)

Details

The classification process follows these key steps:

1. Stability Detection:

   • Identifies stable periods in the movement data

   • Uses the longest stable period to establish a baseline for low activity

2. State Classification:

   • Sets an activity threshold based on the baseline period

   • Classifies periods that deviate from baseline stability as high activity

3. Optional Refinement:

   • If refine_transitions = TRUE, examines transitions between states to find precise start/end points using stability detection

   • Short duration states can be filtered based on min_low_state_duration and min_high_state_duration parameters using a majority context approach