ENH: eyetracking plot_heatmap function

[scott-huberty]

Closes #11782.

What does this implement/fix?

Added a mne.viz.eyetracking namespace and added a function plot_gaze to plot a heatmap of the gaze position data.

Minimally Working Example from our test file:

import mne
from mne.datasets.testing import data_path

eyelink = data_path() / "eyetrack" / "test_eyelink.asc"
raw = mne.io.read_raw_eyelink(eyelink)
mne.preprocessing.eyetracking.interpolate_blinks(raw, interpolate_gaze=True)
epochs = mne.make_fixed_length_epochs(raw, duration=5, preload=True)
mne.viz.eyetracking.plot_gaze(epochs, width=1920, height=1080, sigma=2)

Documentation Quick links

• Updated tutorial
• New tutorial
• API Doc

TODOS:

• add a new tutorial "visualizing eye-tracking data", and a new dataset that would produce a more informative heatmap.

[larsoner]

Looks like a good start, let me know when I should really look @scott-huberty !

[scott-huberty]

Looks like a good start, let me know when I should really look @scott-huberty !

Alright! It's not ready yet and I'm a bit stuck on a few points, can I meet with you @britta-wstnr or one of the other devs tomorrow or next week?

[scott-huberty]

Looks like a good start, let me know when I should really look @scott-huberty !

Alright! It's not ready yet and I'm a bit stuck on a few points, can I meet with you @britta-wstnr or one of the other devs tomorrow or next week?

[larsoner]

I can't meet tomorrow morning my time, which would be my only reasonable overlap with @britta-wstnr . So feel free to meet with her in my morning if you can and if not ping me on Discord and we can meet afternoon EDT

[britta-wstnr]

@scott-huberty we can meet during dev meeting today?

[scott-huberty]

@scott-huberty we can meet during dev meeting today?

Sure!

[scott-huberty]

Sorry for the delay on this! I think this is finally ready for review. @larsoner / @drammock I assume I'll mainly be corresponding with you next week for the code sprint. Could we carve out some time next week to look at this?

Also CC @britta-wstnr as my GSOC mentor and @mscheltienne .

Tutorials

• Here is a new visualization tutorial demonstrating the new functionality.

• I've also added a section that uses the funciton to the current eye-tracking tutorial.

Tests

Per the failing tests: I had a quick look and it seems related to a (new?) deprecation warning from Numba?

[larsoner]

For the test can you add ignore:Code using Numba extension API.*: to mne/conftest.py ? Agreed it's unrelated to this PR but should get things green. I can't look at the code today but agree we should next week unless everyone else is happy today, in which case feel free to merge without me looking

[scott-huberty]

For the test can you add ignore:Code using Numba extension API.*: to mne/conftest.py ?

Ok will do!

I can't look at the code today but agree we should next week unless everyone else is happy today, in which case feel free to merge without me looking

No rush on my side

[drammock]

The heatmap tutorial I've added currently sits in the Tutorials section. It could probably instead live in the How-to examples section (and maybe it would be a better fit there?). Do you have any opinion on where this tutorial should live?

Good question. It's how-to like in that it only really demonstrates how to do one thing. It's tutorial like in that the code and explanations are interleaved and somewhat verbose and there are demarcated sections. If this were in examples, it would be better IMO to omit details about the experimental paradigm, and probably just show 2 figures each with only 1 subplot: one full heatmap and one heatmap overlayed on an image. That would also let you get rid of the custom image plotting function, which would shorten the recipe. Basically for the recipes I advise to distill as much as possible down to the core commands necessary to complete the task; users can extrapolate to their use case from there.

If you're willing to do the distillations and move to the examples folder I think that would make sense. If you're sick of it LMK and I can probably find time to do it this week.

[scott-huberty]

If you're willing to do the distillations and move to the examples folder I think that would make sense. If you're sick of it LMK and I can probably find time to do it this week.

No problem I can do that this week. I agree It will probably be a net-positive to simplify that tutorial so users can quickly get what they need.

[scott-huberty]

Hey @drammock , another question. In mne.viz.eyetracking.heatmap I import from scipy.ndimage import gaussian_filter at the top of the file. should I instead be using lazy_loader to do:

import lazy
sp = lazy.load('scipy')
...
sp.ndimage.gaussian_filter( ... )

I'm still a little confused on how to use lazy_loader..

[drammock]

should I instead be using lazy_loader

Nope. It's possible to do it that way, but not necessary. For us, lazy loader only ever gets used in the init files

[drammock]

just a few nitpicks / small refinements. thanks @scott-huberty the conversion to a "recipe" style example went well I think!

[drammock]

@larsoner I'm happy with this one but you have requested changes here.