Plotting wrappers: Body-vector orientation

[stellaprins]

Description

What is this PR

• Bug fix
• Addition of a new feature
• Other

Why is this PR needed?
To conveniently plot the vector between or midpoints between two keypoints (e.g. left_ear and right_ear for head trajectory, see third plot in computes polar coordinates example) with a single line of code.

What does this PR do?

References

#389

How has this PR been tested?

Checked the updated documentation locally.
Added tests that check whether the extracted vector ("quiver") U and V coordinates match the expected U V coordinates.

Is this a breaking change?

No.

Does this PR require an update to the documentation?

computes polar coordinates example) has been updated.

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

All modified and coverable lines are covered by tests ✅

Project coverage is 99.82%. Comparing base (84b245c) to head (3c1c0a7).
Report is 13 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #402      +/-   ##
==========================================
+ Coverage   99.80%   99.82%   +0.01%     
==========================================
  Files          15       21       +6     
  Lines        1048     1162     +114     
==========================================
+ Hits         1046     1160     +114     
  Misses          2        2              

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

[stellaprins]

The plot_vector function should simply plot an arrow from one centroid to another centroid (the keypoint itself if a single keypoint is passed), right? @niksirbi and @willGraham01

[willGraham01]

The plot_vector function should simply plot an arrow from one centroid to another centroid (the keypoint itself if a single keypoint is passed), right?

I believe so, but for each time-point. I'm also not the expert on this 😅 But I believe you'll have one arrow per timepoint (the vector between the two keypoints that are given) that needs to be ploteed.

[niksirbi]

@stellaprins I think this function in its current form is not very broadly useful, because it follows the existing example too closely. What Sofía has done in that example is valuable for didactic reasons, but I don't think it's such a common use-case.
And anyway that example needs updating, to include the compute_forward_vector function, see #317.

I could see something like plot_vector working if we could make it more general, but I thinks we'd have to think a bit about what kind of inputs we'd expect in such a function.

I suggest pausing this for now and coming back to it later, after we've updated the "polar" example (I could take that on, we've neglected it for long enough).

As far as plotting wrappers are concerned, I'd say the following have higher priority:

• occupancy histogram
• a polar histogram of angles (for inspiration, see https://github.com/neuroinformatics-unit/In2Research-2024/blob/f164215fb1dd34fea333f7b07a5ac5886208eb55/plotting.py#L117). This would take a DataArray of angles, like that output by compute_forwards_vector_angle.

Sorry for not looking at this PR earlier!

[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 SonarQube Cloud

[stellaprins]

Sorry, I could have let you know I was working on this.

I think this function in its current form is not very broadly useful

@niksirbi Yes, I did not totally realise (the displacement plots look quite similar at first sight), but I noticed it while revisiting this today and updating the examples that I could only use it in one specific case.

I just finished updating plot_vector when I read your message on Zulip and saw your response here, in it's current form closely follows the current plot_trajectory function and is tested in a similar way as we did for plot_trajectory too. But I agree, if it is not likely to be useful, it does not make sense to merge it in unless it's made more applicable.

[niksirbi]

I don't think your effort here is wasted.

It could be very useful to re-purpose this function to specifically plot the "forward vector", i.e. the output of this function.

This way users would be able to quickly visualise the head/body vector (depending on the chosen left+right keypoints).

But I think we need to brainstorm on this, because there are several ways we could approach this. Could be something for this Thursday.

[niksirbi]

We decided to close this for now, until we re-think how we want vector plot to look like. May re-visit this later.