feat: add compute_polarization() to collective behavior metrics

[khan-u]

Description

What is this PR

• Bug fix
• Addition of a new feature
• Other

Why is this PR needed?

Movement currently lacks collective behavior metrics for analyzing multi-individual tracking data. Polarization is a fundamental metric for measuring group alignment, widely used in collective behavior studies of fish schools, bird flocks, and other animal groups.

What does this PR do?

Adds compute_polarization() function that measures how aligned the heading directions of multiple individuals are. Returns values from 0 (random orientations) to 1 (perfectly aligned).

References

Partial implementation of #873 (adds compute_polarization)

How has this PR been tested?

• Added 9 unit tests in tests/test_unit/test_kinematics/test_collective.py
• Tests cover: aligned individuals, opposite directions, keypoint-based heading, NaN handling, value range validation, and input validation errors
• All 1136 existing tests pass
• collective.py has 97% test coverage

Is this a breaking change?

No. This adds a new function without modifying existing functionality.

Does this PR require an update to the documentation?

API documentation will be auto-generated from docstrings. No manual documentation update required for this PR.

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