Function to convert eyegaze units to radians (#12237)

Co-authored-by: Eric Larson <[email protected]>
Co-authored-by: Daniel McCloy <[email protected]>
Co-authored-by: Britta Westner <[email protected]>

Author: 4 people

.pre-commit-config.yaml

@@ -11,18 +11,14 @@ repos:
         name: ruff lint mne preview
         args: ["--fix", "--preview", "--select=NPY201"]
         files: ^mne/
-      - id: ruff-format
-        name: ruff format mne
-        files: ^mne/
       - id: ruff
-        name: ruff lint tutorials and examples
+        name: ruff lint doc, tutorials, and examples
         # D103: missing docstring in public function
         # D400: docstring first line must end with period
         args: ["--ignore=D103,D400", "--fix"]
-        files: ^tutorials/|^examples/
+        files: ^doc/|^tutorials/|^examples/
       - id: ruff-format
-        name: ruff format tutorials and examples
-        files: ^tutorials/|^examples/
+        files: ^mne/|^doc/|^tutorials/|^examples/
 
   # Codespell
   - repo: https://github.com/codespell-project/codespell

doc/api/preprocessing.rst

@@ -162,6 +162,8 @@ Projections:
    Calibration
    read_eyelink_calibration
    set_channel_types_eyetrack
+   convert_units
+   get_screen_visual_angle
    interpolate_blinks
 
 EEG referencing:

doc/changes/devel/12237.newfeature.rst

@@ -0,0 +1,2 @@
+Added a helper function :func:`mne.preprocessing.eyetracking.convert_units` to convert eyegaze data from pixel-on-screen values to radians of visual angle. Also added a helper function :func:`mne.preprocessing.eyetracking.get_screen_visual_angle` to get the visual angle that the participant screen subtends, by `Scott Huberty`_.
+

doc/conf.py

@@ -29,12 +29,13 @@
 from mne.tests.test_docstring_parameters import error_ignores
 from mne.utils import (
     _assert_no_instances,
-    linkcode_resolve,  # noqa, analysis:ignore
+    linkcode_resolve,
     run_subprocess,
     sizeof_fmt,
 )
 from mne.viz import Brain  # noqa
 
+assert linkcode_resolve is not None  # avoid flake warnings, used by numpydoc
 matplotlib.use("agg")
 faulthandler.enable()
 os.environ["_MNE_BROWSER_NO_BLOCK"] = "true"
@@ -62,12 +63,12 @@
 
 # We need to triage which date type we use so that incremental builds work
 # (Sphinx looks at variable changes and rewrites all files if some change)
-copyright = (
+copyright = (  # noqa: A001
     f'2012–{td.year}, MNE Developers. Last updated <time datetime="{td.isoformat()}" class="localized">{td.strftime("%Y-%m-%d %H:%M %Z")}</time>\n'  # noqa: E501
     '<script type="text/javascript">$(function () { $("time.localized").each(function () { var el = $(this); el.text(new Date(el.attr("datetime")).toLocaleString([], {dateStyle: "medium", timeStyle: "long"})); }); } )</script>'  # noqa: E501
 )
 if os.getenv("MNE_FULL_DATE", "false").lower() != "true":
-    copyright = f"2012–{td.year}, MNE Developers. Last updated locally."
+    copyright = f"2012–{td.year}, MNE Developers. Last updated locally."  # noqa: A001
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -293,6 +294,7 @@
     "RawNIRX": "mne.io.Raw",
     "RawPersyst": "mne.io.Raw",
     "RawSNIRF": "mne.io.Raw",
+    "Calibration": "mne.preprocessing.eyetracking.Calibration",
     # dipy
     "dipy.align.AffineMap": "dipy.align.imaffine.AffineMap",
     "dipy.align.DiffeomorphicMap": "dipy.align.imwarp.DiffeomorphicMap",
@@ -445,16 +447,18 @@
 # -- Sphinx-gallery configuration --------------------------------------------
 
 
-class Resetter(object):
+class Resetter:
     """Simple class to make the str(obj) static for Sphinx build env hash."""
 
     def __init__(self):
         self.t0 = time.time()
 
     def __repr__(self):
+        """Make a stable repr."""
         return f"<{self.__class__.__name__}>"
 
     def __call__(self, gallery_conf, fname, when):
+        """Do the reset."""
         import matplotlib.pyplot as plt
 
         try:
@@ -1753,7 +1757,7 @@ def reset_warnings(gallery_conf, fname):
 def check_existing_redirect(path):
     """Make sure existing HTML files are redirects, before overwriting."""
     if path.is_file():
-        with open(path, "r") as fid:
+        with open(path) as fid:
             for _ in range(8):
                 next(fid)
             line = fid.readline()

doc/sphinxext/contrib_avatars.py

@@ -15,9 +15,9 @@ def generate_contrib_avatars(app, config):
 MNE_ADD_CONTRIBUTOR_IMAGE=true in your environment to generate it.</p>"""
     else:
         from selenium import webdriver
+        from selenium.common.exceptions import WebDriverException
         from selenium.webdriver.common.by import By
         from selenium.webdriver.support.ui import WebDriverWait
-        from selenium.common.exceptions import WebDriverException
 
         try:
             options = webdriver.ChromeOptions()

doc/sphinxext/gen_commands.py

@@ -2,10 +2,9 @@
 # Copyright the MNE-Python contributors.
 import glob
 from importlib import import_module
-import os
 from pathlib import Path
 
-from mne.utils import _replace_md5, ArgvSetter
+from mne.utils import ArgvSetter, _replace_md5
 
 
 def setup(app):

doc/sphinxext/gen_names.py

@@ -25,7 +25,7 @@ def generate_name_links_rst(app=None):
     )
     with open(out_fname, "w", encoding="utf8") as fout:
         fout.write(":orphan:\n\n")
-        with open(names_path, "r") as fin:
+        with open(names_path) as fin:
             for line in fin:
                 if line.startswith(".. _"):
                     fout.write(f"- {line[4:]}")

doc/sphinxext/gh_substitutions.py

@@ -4,7 +4,7 @@
 from docutils.parsers.rst.roles import set_classes
 
 
-def gh_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
+def gh_role(name, rawtext, text, lineno, inliner, options={}, content=[]):  # noqa: B006
     """Link to a GitHub issue.
 
     adapted from

doc/sphinxext/mne_substitutions.py

@@ -4,12 +4,12 @@
 from docutils.parsers.rst import Directive
 from docutils.statemachine import StringList
 
-from mne.defaults import DEFAULTS
 from mne._fiff.pick import (
-    _PICK_TYPES_DATA_DICT,
-    _DATA_CH_TYPES_SPLIT,
     _DATA_CH_TYPES_ORDER_DEFAULT,
+    _DATA_CH_TYPES_SPLIT,
+    _PICK_TYPES_DATA_DICT,
 )
+from mne.defaults import DEFAULTS
 
 
 class MNESubstitution(Directive):  # noqa: D101

doc/sphinxext/newcontrib_substitutions.py

@@ -3,7 +3,7 @@
 from docutils.nodes import reference, strong, target
 
 
-def newcontrib_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
+def newcontrib_role(name, rawtext, text, lineno, inliner, options={}, content=[]):  # noqa: B006
     """Create a role to highlight new contributors in changelog entries."""
     newcontrib = f"new contributor {text}"
     alias_text = f" <{text}_>"