Function to convert eyegaze units to radians

[scott-huberty]

closes #12112
closes #12391
This PR implements a function mne.preprocessing.eyetracking.convert_units to help users convert pixel data to radians, which is nice for us because radians are an SI unit, and it may come in handy down the line because converting pixel data to degrees/radians of visual angle is often done prior to calculating eye-tracking related derivatives (saccade amplitude, saccade velocity, etc).

Perhaps the best way to make sure this is behaving as expected is to plot a heatmap before and after unit conversion. But i'll need to refactor the mne.viz.eyetracking.plot_gaze to handle the scenario where data are in radians and not pixels.

[scott-huberty]

Hi @drammock , @britta-wstnr , @mscheltienne Happy new year!

I think this PR is ready for review. To recap previous discussions, the major concerns were:

• 1. The conversion from on-screen pixel values to degrees/radians of visual angle is not a linear transformation.
• 2. Converting between these units may yield different gaze-heatmaps/analytical results, particularly if the transformation is highly non-linear, leading to unexpected outcomes for users.

Consider simulating eyegaze data with fixations at three locations on a horizontal plane. The transformation becomes notably non-linear when the visual angle becomes too large (i.e the participant is too close to the screen or the screen is very large).

Pixels	Degrees	Degrees (too close to screen)

Fortunately, if the visual angle to the screen is within reasonable limits (< 30°), the relationship between pixel coordinates and visual angle is approximately linear (refer to the image below). Most eyetracker setups include a chin-rest to stabilize head position, and standard screens provided by manufacturers, so I think for most use cases the visual angle will be < 30° (but we could throw a warning if it is above this).

Since reporting the visual angle is fairly common in eye-tracking literature, so I still think this is a useful feature to provide.

Updated tutorial with demonstration of unit conversion
Convert units API
updated plot_gaze API
get_screen_visual_angle API

[larsoner]

pip-pre failures are unrelated, I opened #12372 to track it

[scott-huberty]

The failure actually looks related. If a warning is raised only sometimes, you can use with _record_warnings(): to ignore it

Hmm okay. I actually want the warning to be raised (AFAIK _record_warnings will just always ignore the warning without testing that it is raised like I want it to?)

I added a test that simulated a scenario where the unit conversion resulted in values greater than .52 rad (30 deg), so a warning should be thrown. The simulated rad values should be 1.10 so it can't be a matter of numerical precision.. Trying to figure it out but I'm not sure why the error isn't thrown on the Ubuntu old VM.

[larsoner]

In this case I usually create a env in conda with the specs from the old env like:

conda create -n old python=3.9 numpy=1.21.2 scipy=1.7.1 matplotlib=3.5.0 pandas=1.3.2 scikit-learn=1.0 pip
conda activate old
pip install pytest pytest-cov

then you can hopefully run the tests locally to replicate the error and then inspect etc.

[scott-huberty]

In this case I usually create a env in conda with the specs from the old env like:

conda create -n old python=3.9 numpy=1.21.2 scipy=1.7.1 matplotlib=3.5.0 pandas=1.3.2 scikit-learn=1.0 pip
conda activate old
pip install pytest pytest-cov

then you can hopefully run the tests locally to replicate the error and then inspect etc.

OK, unfortunately I can't replicate the test failiure locally on a Linux machine with the same specs as the ubuntu old env:

local environment specs

>>> mne.sys_info()
Platform             Linux-6.1.58+-x86_64-with-glibc2.31
Python               3.9.18 | packaged by conda-forge | (main, Dec 23 2023, 16:33:10)  [GCC 12.3.0]
Executable           /home/scotteric_hub/miniforge3/envs/old/bin/python
CPU                   (2 cores)
Memory               Unavailable (requires "psutil" package)
Core
├☑ mne               1.7.0.dev86+g4ccd30fed (devel, latest release is 1.6.1)
├☑ numpy             1.21.2 (OpenBLAS 0.3.25 with 2 threads)
├☑ scipy             1.7.1
├☑ matplotlib        3.5.0 (backend=agg)
├☑ pooch             1.8.0
└☑ jinja2            3.1.3

Numerical (optional)
├☑ sklearn           1.0.2
├☑ pandas            1.3.2
└☐ unavailable       numba, nibabel, nilearn, dipy, openmeeg, cupy

In 00ab0db I added a couple asserts to check that the values are what I expect during the test (they are), which should raise the warning.

So to me this suggests that the issue is with pytest or the warnings module. For example, pytest is looking for a UserWarning but maybe in the ubuntu old environment a RuntimeWarning is being thrown or something.. Just guessing... I can keep poking around but i'm not sure if it's worth the time for a warning. WDYT?

[scott-huberty]

Ahah.. interesting. It looks like the warning we want is getting reported by pytest: https://github.com/mne-tools/mne-python/actions/runs/7644559198/job/20829160758?pr=12237#step:16:3509

but it isn't getting captured by our test line with pytest.raises(UserWarning, match="Some visual angle values"):

[larsoner]

Yes feel free to sneak in a fix for #12391

[britta-wstnr]

Sorry for being so late to the radians party ... Only found some typos, otherwise LGTM!

[scott-huberty]

all suggested revisions have been incorporated, are we okay to merge?

[larsoner]

Just two tiny changes I pushed, marking for merge when green, thanks @scott-huberty !

[larsoner]

@scott-huberty pushed a commit to add this to the top rather than have all the text indented in the Notes. It should make Notes more readable by itself and also call better attention to it by putting this at the top.

[larsoner]

@scott-huberty this is the other change I made -- if not x: continue rather than if x: <indent everything another 4 spaces. I find it the same readability but less indented which is nice

[scott-huberty]

Good idea thx!