Implemented head angle velocity

[Edu92337]

Description

What is this PR

• Addition of a new feature

Why is this PR needed?
There was no built-in way to compute the angular velocity of the head direction over time. The naive approach — computing the polar angle of the head direction vector and differentiating — produces noisy results with large spikes at the ±π boundary due to angle wrapping.

What does this PR do?
Adds compute_head_angle_velocity to the kinematics module. The function:

• Computes the head direction angle from a user-defined pair of keypoints via compute_forward_vector_angle
• Applies a circular rolling mean (scipy.stats.circmean) over a configurable window to reduce noise while correctly handling the ±π boundary
• Unwraps the smoothed angle to remove 2π discontinuities before differentiation
• Returns the time derivative as a DataArray. Units are rad/s if the dataset was loaded with fps (time coordinate in seconds), or rad/frame otherwise — because compute_time_derivative uses .differentiate("time"), which divides by the actual time coordinate values.
  Also adds the private helper _rolling_circmean, which applies scipy.stats.circmean in a centred sliding window along a 1D array.

References

Closes #367

How has this PR been tested?

Two new test classes in tests/test_unit/test_kinematics/test_kinematics.py:

• TestRollingCircmean — tests the private helper in isolation: identity for window=1, constant signal, shape preservation, and correct circular averaging near the ±π boundary
• TestComputeHeadAngleVelocity — tests the public function: output name and dimensions, constant angular velocity for a known spinning fixture (π/4 rad/frame), smoke test for larger smoothing windows, and all three validation error paths (TypeError for bad data, TypeError/ValueError for bad smoothing_window)

Existing tests were run locally to confirm no regressions.

Is this a breaking change?

No.

Does this PR require an update to the documentation?

Yes. compute_head_angle_velocity should be added to the API reference page for the kinematics module.

Checklist:

• The code has been tested locally
• Tests have been added to cover all new functionality
• The documentation has been updated to reflect any changes
• The code has been formatted with pre-commit

[sonarqubecloud]

Quality Gate passed

Issues
0 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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (dc95ddd) to head (fedb904).

Additional details and impacted files

@@            Coverage Diff            @@
##              main      #855   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           36        36           
  Lines         2220      2245   +25     
=========================================
+ Hits          2220      2245   +25     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.