Eye movement example

[stellaprins]

Description

What is this PR

• Bug fix
• Addition of a new feature
• Other (adds an example)

Why is this PR needed?

What does this PR do?
Adds an example (using data Sepi provided), analysing pupil movement of a mouse that is rotated on a platform in two different conditions (black and uniform).

In the example movement is used in the following ways:

• Import movement example data (sample_data).
• Quickly plot the trajectory of the pupil using plot_trajectory from movement.plots .
• Quantify the velocity with which the pupil centroid moves using compute_velocity from the movement.kinematics module
• Quantify the pupil diameter using compute_pairwise_distances from movement.kinematics to calculate the Euclidean distances between two keypoints.
• Filtering pupil diameter data using median_filter from the movement.filtering module.

References

How has this PR been tested?

Looked over the locally generated docs.

Is this a breaking change?

No.

Does this PR require an update to the documentation?

It is itself an update to the documentation.

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.84%. Comparing base (9c98037) to head (3f12ec2).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #429   +/-   ##
=======================================
  Coverage   99.84%   99.84%           
=======================================
  Files          23       23           
  Lines        1250     1250           
=======================================
  Hits         1248     1248           
  Misses          2        2           

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

[niksirbi]

Now you could directly get it from our sample datasets (ignore me if you were already planning this).

[stellaprins]

I tried using the :func:movement.filtering.median_filter function on the pupil size to replace my moving average filter (usingnp.convolve with mode="same") with the moving median filter used in movement but it wants space as one of the array dimensions (maybe it was silly of my to try this in the first place? @niksirbi ).

[niksirbi]

I tried using the :func:movement.filtering.median_filter function on the pupil size to replace my moving average filter (usingnp.convolve with mode="same") with the moving median filter used in movement but it wants space as one of the array dimensions (maybe it was silly of my to try this in the first place? @niksirbi ).

That's not a bad idea at all, it should work. I think the problem arises because of the report_nan_values function, which in turn calls calculate_nan_stats, which contains a reference to the space dimension. If I'm right, calling the median filter with print_report=False should work. Assuming we confirm my theory, this is a bug that should be fixed.

[niksirbi]

Also @stellaprins I just had a brief look a this example, and it's shaping up nicely!
I don't think it needs any more content, just a tidying up of the existing content.

Some initial observations:

• I love how you've used velocity here, it really makes the rotation events pop out!
• I think the title could be "pupil tracking" instead of "pupillometry"

[stellaprins]

@niksirbi awesome! Will have a look tomorrow. This PR is pretty much ready for review after that I think. The example nicely demonstrates the use of kinematics.compute_velocity and kinematics.compute_pairwise_distances, but it would be very nice if the movement filter can be used as well.

Will change the title, any other comments are welcome but can wait till later too.

And thanks! This was so much fun to work on!

[stellaprins]

@niksirbi Yep, it all works when print_report=False! Also, it would be really easy to add a mean_filter to the movement.filtering module? I left the mean filtering in using np.convolve in so that it can be replaced by movement.filtering.mean_filter if it's created.

[niksirbi]

@niksirbi Yep, it all works when print_report=False! Also, it would be really easy to add a mean_filter to the movement.filtering module? I left the mean filtering in using np.convolve in so that it can be replaced by movement.filtering.mean_filter if it's created.

Yeah it would be really easy to add, we just haven't gotten around to doing it yet.
How about using the median filter (instead of the mean) in the example? It should be as good at smoothing the diameter time series, no?

[sonarqubecloud]

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

[stellaprins]

How about using the median filter (instead of the mean) in the example? It should be as good at smoothing the diameter time series, no?

@niksirbi I have a slight preference for how the moving mean filtered plot looks, but equally happy to remove this and just keep the median filtered example in there. Will leave both plots in so that you can see the difference.