FIX: Set calibration plot axes to screen resolution if available (#13558)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Eric Larson <larson.eric.d@gmail.com>
Co-authored-by: Scott Huberty <seh33@uw.edu>

Author: 4 people

doc/changes/dev/13558.bugfix.rst

@@ -0,0 +1 @@
+Fix axis limits in :meth:`mne.preprocessing.eyetracking.Calibration.plot` to use screen resolution if available, by :newcontrib:`Gnaneswar Lopinti`.

doc/changes/names.inc

@@ -106,6 +106,7 @@
 .. _Gennadiy Belonosov: https://github.com/Genuster
 .. _Geoff Brookshire: https://github.com/gbrookshire
 .. _George O'Neill: https://georgeoneill.github.io
+.. _Gnaneswar Lopinti: https://github.com/flying-spagetti
 .. _Gonzalo Reina: https://orcid.org/0000-0003-4219-2306
 .. _Guillaume Dumas: https://mila.quebec/en/person/guillaume-dumas
 .. _Guillaume Favelier: https://github.com/GuillaumeFavelier

mne/preprocessing/eyetracking/calibration.py

@@ -169,6 +169,10 @@ def plot(self, show_offsets=True, axes=None, show=True):
 
         # Invert y-axis because the origin is in the top left corner
         ax.invert_yaxis()
+        if self["screen_resolution"] is not None:
+            w, h = self["screen_resolution"]
+            ax.set_xlim(0, w)
+            ax.set_ylim(h, 0)
         ax.scatter(px, py, color="gray")
         ax.scatter(gaze_x, gaze_y, color="red", alpha=0.5)
 

tutorials/preprocessing/90_eyetracking_data.py

@@ -74,7 +74,7 @@
 # will return a list of :class:`~mne.preprocessing.eyetracking.Calibration` instances,
 # one for each calibration. We can index that list to access a specific calibration.
 
-cals = read_eyelink_calibration(et_fpath)
+cals = read_eyelink_calibration(et_fpath, screen_resolution=(1920, 1080))
 print(f"number of calibrations: {len(cals)}")
 first_cal = cals[0]  # let's access the first (and only in this case) calibration
 print(first_cal)
@@ -97,20 +97,28 @@
 # and the offsets (in visual degrees) between the calibration position and the actual
 # gaze position of each calibration point.
 
+# %%
 first_cal.plot()
 
+# %%
+# .. hint::
+#   If you supply the eyetracker monitor’s screen resolution to
+#   :class:`~mne.preprocessing.eyetracking.Calibration`,
+#   :meth:`~mne.preprocessing.eyetracking.Calibration.plot` will automatically set the
+#   canvas bounds accordingly.
+
 # %%
 # Standardizing eyetracking data to SI units
 # ------------------------------------------
 #
 # EyeLink stores eyegaze positions in pixels, and pupil size in arbitrary units.
 # MNE-Python expects eyegaze positions to be in radians of visual angle, and pupil
 # size to be in meters. We can convert the eyegaze positions to radians using
-# :func:`~mne.preprocessing.eyetracking.convert_units`. We'll pass the calibration
-# object we created above, after specifying the screen resolution, screen size, and
-# screen distance.
+# :func:`~mne.preprocessing.eyetracking.convert_units`. In addition to the
+# screen resolution, we need to supply the eyetracker screen size and screen distance
+# to our :class:`~mne.preprocessing.eyetracking.Calibration` object, before calling the
+# convert units function.
 
-first_cal["screen_resolution"] = (1920, 1080)
 first_cal["screen_size"] = (0.53, 0.3)
 first_cal["screen_distance"] = 0.9
 mne.preprocessing.eyetracking.convert_units(raw_et, calibration=first_cal, to="radians")