Compute Heading

[b-peri]

Description

This PR introduces compute_heading(), a new function for computing "heading" to movement. Here, "heading" is defined as the signed angle between the animal's forward-facing vector and a reference vector. Following the convention established in our existing vector utility functions, the reference vector is [1, 0] (i.e. the positive x-axis) by default, but this can be changed by passing a 2D vector (as a list, tuple, or numpy.ndarray) to the reference_vector argument.

What is this PR

• Bug fix
• Addition of a new feature
• Other

References

Closes #238

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

[codecov]

Codecov Report

Attention: Patch coverage is 12.24490% with 43 lines in your changes missing coverage. Please review.

Project coverage is 95.29%. Comparing base (bfb20d2) to head (246801e).

Files with missing lines	Patch %	Lines
movement/utils/vector.py	5.55%	34 Missing ⚠️
movement/analysis/kinematics.py	30.76%	9 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #315      +/-   ##
==========================================
- Coverage   99.77%   95.29%   -4.49%     
==========================================
  Files          15       15              
  Lines         909      956      +47     
==========================================
+ Hits          907      911       +4     
- Misses          2       45      +43     

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

[sonarqubecloud]

Quality Gate passed

Issues
4 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 SonarCloud

[vigji]

related to #358 , what are your thoughts on heading in 3D? if you have any, posting here looking for people who might be interested in the option once we start having the first 3D data around

[niksirbi]

Reminder to self: rename this to compute_heading_angle()?