Reframe polar coordinates example around head direction #426

niksirbi · 2025-02-20T20:26:08Z

Description

What is this PR

Bug fix
Addition of a new feature
Other: docs

Why is this PR needed?

Closes #317

What does this PR do?

The updating of this example was was long overdue, as it was written before we had forward vectors and their angles and all the jazz. In the updated example, the primary focus is on head direction, and polar coordinate systems are mentioned in passing as a useful representation (instead of the other way around).

I basically provide two methods for computing head direction vector

the "old" way: as the difference between two keypoints (the angle is then derived from polar coordinates)
the "new" way: as the forward vector and its angle (this also serves as documentation for these functions)

At the end I compare the angles derived from both methods using polar histograms. Note that the "old" way is still valuable, in case there are no handy bilaterally symmetric keypoints, but only a posterior and anterior one.

While I was at it, I added several "notes" about coordinate systems and linear algebra concepts. Let me know if they are too much, we could omit them or "collapse" them.

To not have this example balloon out of all proportion (it's already very long) I removed some of the old example's content. I also deliberately chose no to demonstrate forward angle relative to moving reference vectors (e.g. another animal). That usage is better suited for a "social interactions" example.

I also added an exception to the ruff rules, to not enforce import statements being at the top of the file. This exception applies to all examples, where it's often advantageous to have the imports close to where you need them (for teaching purposes).

The best way to review this is by building the example locally, looking at the diff won't help much.

How has this PR been tested?

Local docs build completes without errors.

Is this a breaking change?

No.

Checklist:

The code has been tested locally
[n/a] 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 · 2025-02-20T20:29:07Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 99.87%. Comparing base (470cf6a) to head (3f1cbf7).
Report is 16 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #426      +/-   ##
==========================================
+ Coverage   99.84%   99.87%   +0.03%     
==========================================
  Files          23       27       +4     
  Lines        1250     1605     +355     
==========================================
+ Hits         1248     1603     +355     
  Misses          2        2

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

sfmig

Looks nice ✨ - a bit more compact than before.

I added some comments, a couple are a bit more substantial but I leave it up to you to assess their importance.

sfmig · 2025-03-03T11:07:58Z

docs/source/_static/Cartesian-vs-Polar.png

Some comments about the cartesian coordinates diagram:

can we translate the red and green axes so that their origin is exactly on top of the origin marker? As it is now it can be confusing.

Similarly, I think it would be clearer if the dotted lines go directly from the axes.

I think we can also do away with the purple pixel, as the position is not necessarily constrained to be a pixel centre.

I think I would do away with the "positive angle" inset in the cartesian coordinates and have it in the polar coordinates diagram instead. I realise it mixes a bit both things, but I think it would make the explanation clearer if we put it in the polar coordinates context.

maybe we can add a small text to the diagram to clarify it exemplifies cartesian coordinates specifically in the image coordinate system.

Re the polar coordinates diagram:

since we define the positive phi relative to the positive x-axis, I think it would be helpful to plot the image coordinate x and y positive axes in this diagram too. Then you can indicate the sign of the angle by changing the phi text to phi > 0 (the rotation arrow already implies a sign) .

Thanks for this very helpful feedback @sfmig.
Have I succeeded in implemented your comments graphically?

Note that I removed the greek spelling for rho and phi (to declutter the polar plot a bit). Besides, I wasn't even using the greek spelling for pi.

Looks great!!

I like the "in the image coordinate system" subtitle - what do you think if we can add it to the polar coordinates too? (not sure tho)

why not, I will add it.

sfmig · 2025-03-03T11:09:53Z

docs/source/_static/Forward-Vector.png

"Top-Down" ---> "Top-down"
(for consistency with "Bottom-up")

I would place the coordinate system origin at the top left corner of the frame (rather than slightly offset and outside of the frame). Or if you want, at the centre of the top-left pixel, but I think simplifying to just the top left corner in the diagrams after the first one should be enough.

Would it be helpful to sketch a mouse's dorsal / ventral view for extra clarity? (and possibly extra cuteness)

yup adding the dorsal/ventral views would be very helpful.

sfmig · 2025-03-03T11:12:54Z

docs/source/_static/Vector-Subtraction.png

As before I would place the axes with its origin matching the "origin" marker.

I comment on this below, but I think we can use the diagram on the left to introduce the point U vs vector u concept (rather than repeating the other image coordinate system diagram). So maybe instead of a random "position" vector, we plot the U point and the u vector.

Also: I wonder if we can remove the text with "Image/Video frame" - I think that should be clear... Or maybe we can keep it only in the first diagram?

So sth like this?

yes, looks great! thanks Niko

examples/compute_head_direction.py

sfmig · 2025-03-03T13:26:46Z

examples/compute_head_direction.py

+head_to_snout_angles = head_to_snout_polar.sel(space_pol="phi")
+forward_vector_angles = forward_vector_angle


Suggested change

head_to_snout_angles = head_to_snout_polar.sel(space_pol="phi")

forward_vector_angles = forward_vector_angle

head_to_snout_angle = head_to_snout_polar.sel(space_pol="phi")

Is forward_vector_angles = forward_vector_angle worth renaming?

Not really, you are right.

examples/compute_head_direction.py

sfmig · 2025-03-03T13:50:08Z

examples/compute_head_direction.py

+# dimension with two coordinates: ``x`` and ``y``.
+
+head_to_snout_cart = pol2cart(head_to_snout_polar)
+print(head_to_snout_cart)


Maybe instead of printing (which potentially doesn't add much) we can assert that the output is the same as head_to_snout.

Or if we want to keep the print statement, we can add a line in text to notice that the space coordinates are back to 'x' and 'y'.

Co-authored-by: sfmig <[email protected]>

for more information, see https://pre-commit.ci

sonarqubecloud · 2025-03-03T17:32:15Z

Quality Gate passed

Issues
1 New issue
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

rename example to "compute_head_direction"

4b17d60

Update polar example to be about head direction

b7539cc

niksirbi force-pushed the make-polar-example-about-head-direction branch from d973c46 to b7539cc Compare February 21, 2025 17:19

niksirbi marked this pull request as ready for review February 21, 2025 17:41

niksirbi requested a review from sfmig February 21, 2025 17:41

sfmig approved these changes Mar 3, 2025

View reviewed changes

niksirbi and others added 5 commits March 3, 2025 15:31

Apply suggestions from code review

d8785b9

Co-authored-by: sfmig <[email protected]>

[pre-commit.ci] auto fixes from pre-commit.com hooks

16f2a42

for more information, see https://pre-commit.ci

moved all import statements to the top, across all examples

7e9d2a0

remove introductory paragraph from head direction example

b772445

updates schematics and accompanying notes

3f1cbf7

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Reframe polar coordinates example around head direction #426

Reframe polar coordinates example around head direction #426

niksirbi commented Feb 20, 2025 •

edited

Loading

codecov bot commented Feb 20, 2025 •

edited

Loading

sfmig left a comment

sfmig Mar 3, 2025

niksirbi Mar 3, 2025 •

edited

Loading

sfmig Mar 3, 2025

niksirbi Mar 3, 2025

sfmig Mar 3, 2025

niksirbi Mar 3, 2025

sfmig Mar 3, 2025

niksirbi Mar 3, 2025 •

edited

Loading

sfmig Mar 3, 2025

sfmig Mar 3, 2025

niksirbi Mar 3, 2025

sfmig Mar 3, 2025

sonarqubecloud bot commented Mar 3, 2025

		head_to_snout_angles = head_to_snout_polar.sel(space_pol="phi")
		forward_vector_angles = forward_vector_angle

	head_to_snout_angles = head_to_snout_polar.sel(space_pol="phi")
	forward_vector_angles = forward_vector_angle
	head_to_snout_angle = head_to_snout_polar.sel(space_pol="phi")

Reframe polar coordinates example around head direction #426

Are you sure you want to change the base?

Reframe polar coordinates example around head direction #426

Conversation

niksirbi commented Feb 20, 2025 • edited Loading

Description

How has this PR been tested?

Is this a breaking change?

Checklist:

codecov bot commented Feb 20, 2025 • edited Loading

Codecov Report

sfmig left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

niksirbi Mar 3, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

niksirbi Mar 3, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sonarqubecloud bot commented Mar 3, 2025

Quality Gate passed

niksirbi commented Feb 20, 2025 •

edited

Loading

codecov bot commented Feb 20, 2025 •

edited

Loading

niksirbi Mar 3, 2025 •

edited

Loading

niksirbi Mar 3, 2025 •

edited

Loading