Adding function: compute_group_spread

[X-Deng]

Description

What is this PR

• Bug fix
• Addition of a new feature
• Other

Why is this PR needed?

Collective behavior analysis requires quantitative measures of group-level spatial organisation.
Currently, movement does not provide a built-in way to quantify group dispersion, which is a fundamental metric in many behavioral studies.

What does this PR do?

This PR introduces a new function compute_group_spread to compute the per-frame group spread using the radius of gyration.

Key features:

• Computes group spread from position data
• Supports datasets with or without keypoints
• Automatically selects the centroid keypoint when available
• Handles NaN values safely
• Fully compatible with xarray-based movement datasets

---

References

Related to #873

---

How has this PR been tested?

• Added unit tests in tests/test_unit/test_kinematics/test_collective.py
• Covered:
  • Known-value validation
  • Keypoint selection logic
  • NaN handling
  • Error cases (missing dimensions, ambiguous keypoints)
• Verified locally with:
  • pytest tests/test_unit/test_kinematics/test_collective.py -q
  • pre-commit run --all-files

---

Is this a breaking change?

No. This PR only adds new functionality and does not modify existing APIs.

---

Does this PR require an update to the documentation?

Not yet. This PR focuses on introducing the core functionality.
Documentation and usage examples can be added in a follow-up PR if needed.

---

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