feat: add compute_inactivity_bouts() for detecting inactivity periods

[mujju-212]

Description

Closes #760.

Adds compute_inactivity_bouts() to movement.kinematics, implementing the inactivity detection feature requested in #760 (reframed by @niksirbi from "freezing detection" to the more general "inactivity" concept).

---

API

from movement.kinematics import compute_inactivity_bouts

bout_ids = compute_inactivity_bouts(
    data=ds.position,
    speed_threshold=0.5,       # px/s — frames below this are "inactive"
    min_bout_duration=0.25,    # seconds — bouts shorter than this are dropped
)

Returns an xr.DataArray named "inactivity_bout_id" with the same time (and any extra individual/keypoint) dimensions as the input but without the space dimension. Each frame is labelled with an integer: 0 = active, 1, 2, 3, … = consecutive inactive bouts ordered by onset time.

---

Implementation details

• Built on compute_speed() — uses the existing kinematics pipeline (velocity → norm) rather than reimplementing differentiation.
• speed_threshold: frames where speed < speed_threshold are candidates for inactivity.
• min_bout_duration: contiguous inactive stretches shorter than this (in the units of the time coordinate) are discarded. Defaults to 0.0 (keep all bouts including single-frame ones).
• NaN contract: frames with any NaN in the space dimension are always treated as active, never as inactive. This prevents the central-differences artefact where numpy.gradient can compute speed ≈ 0 at a NaN frame by using its non-NaN neighbours.
• Per-track labelling: xr.apply_ufunc with vectorize=True labels each individual/keypoint track independently, so bout IDs restart from 1 for each track.

---

Changes

File	Change
movement/kinematics/kinematics.py	New function compute_inactivity_bouts() + import numpy as np
movement/kinematics/__init__.py	Export compute_inactivity_bouts
tests/test_unit/test_kinematics/test_inactivity_bouts.py	20 unit tests across 5 classes

---

Tests (20 new)

Class	Count	What it covers
TestComputeInactivityBoutsBasic	7	stationary→1 bout; moving→0; still-move-still→2; ordered IDs; space dim removed; int dtype; threshold=0
TestMinBoutDuration	5	suppress short bouts; keep long; single-frame at 0.0; drop at 0.5; non-default time unit
TestNaNHandling	2	NaN frame → active; all-NaN → no bouts
TestMultipleIndividuals	2	independent per-track labelling; mixed still/moving
TestInvalidInputs	4	negative threshold; negative min_dur; missing time dim; missing space dim

Type of change

• New feature (non-breaking addition)

Checklist

• I have read the contributing guidelines
• Follows existing patterns (compute_speed, validate_dims_coords, logger.error)
• Full docstring with Parameters, Returns, Raises, Notes, Examples, See Also
• 20 unit tests; all pass locally

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud