Adding function: compute_directional_change

[X-Deng]

Description

What is this PR

• Bug fix
• Addition of a new feature
• Other

Why is this PR needed?

Directional change (DC) is a trajectory-based metric that quantifies how rapidly an individual changes direction per unit time. Unlike purely geometric measures such as sinuosity or straightness, DC incorporates temporal information and can distinguish trajectories with identical shapes but different speeds.

This metric is widely used in movement ecology and behavioural analysis (e.g. Kitamura & Imafuku, 2015), and is particularly relevant for high-temporal-resolution pose tracking data.

What does this PR do?

• Adds a new function compute_directional_change to movement.kinematics

• Computes per-time-step directional change:

  DC_i = |θ_i| / (t[i+1] - t[i-1])

• Uses signed turning angles between consecutive displacement vectors

• Handles edge cases:

  • first and last timepoints return NaN
  • zero-length displacement vectors return NaN

• Supports broadcasting across individuals and optional keypoints

• Follows existing kinematics/orientation module conventions

---

References

Related to #907

---

How has this PR been tested?

Unit tests have been added to cover:

• Straight-line motion (DC = 0)
• Known 90° turn (analytical value)
• Irregular time intervals
• NaN propagation (missing data)
• Zero-length displacement vectors
• Multi-individual consistency

All tests pass locally using pytest, and all pre-commit checks pass successfully.

---

Is this a breaking change?

No.

---

Does this PR require an update to the documentation?

Not yet. This functionality can be documented 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