Merge remote-tracking branch 'upstream/main' into bugfix

larsoner · larsoner · commit b0d9f835921b · 2025-11-20T11:07:53.000-05:00
* upstream/main: ENH: Parse EyeLink BUTTON Events (e.g. from a game controller) (mne-tools#13499) FIX: Fix regression with mne.viz.plot_evoked (mne-tools#13481) DOC: related software doc (mne-tools#13498) FIX: Replace use of deprecated Numpy func in GDF reader (Supersedes mne-tools#13415) (mne-tools#13497) DOC: Link to membership from governance page (mne-tools#13496) [pre-commit.ci] pre-commit autoupdate (mne-tools#13495) BUG: Fix issue with Montage.plot (mne-tools#13494)
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -1,7 +1,7 @@
 repos:
   # Ruff mne
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.14.4
+    rev: v0.14.5
     hooks:
       - id: ruff-check
         name: ruff lint mne
diff --git a/doc/changes/dev/13481.bugfix.rst b/doc/changes/dev/13481.bugfix.rst
@@ -0,0 +1 @@
+Fix bug with :func:`mne.viz.plot_evoked` when using ``gfp="only"`` or ``gfp=True``, by `Michael Straube`_.
diff --git a/doc/changes/dev/13494.bugfix.rst b/doc/changes/dev/13494.bugfix.rst
@@ -0,0 +1 @@
+Fix bug where :meth:`mne.channels.DigMontage.plot` would error when ``axes`` was passed by `Christian O'Reilly`_.
diff --git a/doc/changes/dev/13497.bugfix.rst b/doc/changes/dev/13497.bugfix.rst
@@ -0,0 +1 @@
+Fixed a bug where ``mne.io.read_raw_gdf`` failed with NumPy ≥1.24 due to the removal of ``np.fromstring`` binary mode. Replaced with ``np.frombuffer`` for compatibility, by :newcontrib:`Dev Parikh`.
diff --git a/doc/changes/dev/13499.newfeature.rst b/doc/changes/dev/13499.newfeature.rst
@@ -0,0 +1 @@
+Added support for parsing Eyelink ``BUTTON`` events (i.e. external controller button presses) to :func:`~mne.io.read_raw_eyelink` by :newcontrib:`Wouter Kroot`
diff --git a/doc/changes/names.inc b/doc/changes/names.inc
@@ -67,6 +67,7 @@
 .. _David Sabbagh: https://github.com/DavidSabbagh
 .. _Demetres Kostas: https://github.com/kostasde
 .. _Denis Engemann: https://denis-engemann.de
+.. _Dev Parikh: https://github.com/devparikh0506
 .. _Dinara Issagaliyeva: https://github.com/dissagaliyeva
 .. _Diptyajit Das: https://github.com/dasdiptyajit
 .. _Dirk Gütlin: https://github.com/DiGyt
@@ -339,6 +340,7 @@
 .. _Victoria Peterson: https://github.com/vpeterson
 .. _Wei Xu: https://github.com/psyxw
 .. _Will Turner: https://bootstrapbill.github.io
+.. _Wouter Kroot: https://github.com/WouterKroot
 .. _Xabier de Zuazo: https://github.com/zuazo
 .. _Xiaokai Xia: https://github.com/dddd1007
 .. _Yaroslav Halchenko: http://haxbylab.dartmouth.edu/ppl/yarik.html
diff --git a/doc/development/governance.rst b/doc/development/governance.rst
@@ -53,8 +53,8 @@ page :ref:`governance-people`.
 Maintainer Team
 ---------------
 
-The Maintainer Team is responsible for implementing changes to the software and
-supporting the user community. Duties:
+The Maintainer Team (:ref:`members <maintainer-team-people>`) is responsible for
+implementing changes to the software and supporting the user community. Duties:
 
 - Infrastructure/large-scale software decisions, in partnership with the Steering
   Council
@@ -73,8 +73,8 @@ automatically.
 Steering Council
 ----------------
 
-The Steering Council is responsible for guiding and shepherding the project on a
-day-to-day basis. Duties:
+The Steering Council (:ref:`members <steering-council-people>`) is responsible for
+guiding and shepherding the project on a day-to-day basis. Duties:
 
 - Obtaining funding (either by writing grants specifically for MNE development, or
   convincing others to include funds for MNE development in their research grants)
@@ -102,8 +102,8 @@ afforded to maintainers (passwords, merge rights, etc).
 Chair of the Steering Council
 -----------------------------
 
-The Chair of the Steering Council is responsible for liaising between the Steering
-Council and the community. Duties:
+The Chair (:ref:`member <steering-council-people>`) of the Steering Council is
+responsible for liaising between the Steering Council and the community. Duties:
 
 - Convening the Steering Council meetings
 - Calling for votes when consensus fails
@@ -113,8 +113,8 @@ Council and the community. Duties:
 External Advisory Board
 -----------------------
 
-The External Advisory Board is responsible for high-level roadmap and funding
-guidance. Duties:
+The External Advisory Board (:ref:`members <advisory-board-people>`) is responsible for
+high-level roadmap and funding guidance. Duties:
 
 - Attendance at Advisory Board meetings (approx. every 1-2 years)
 - Periodically communicating with Steering Council to impart guidance
diff --git a/doc/overview/people.rst b/doc/overview/people.rst
@@ -5,6 +5,8 @@
 Current Project Leadership and Institutional Partners
 =====================================================
 
+.. _maintainer-team-people:
+
 Maintainer Team
 ---------------
 
@@ -24,13 +26,17 @@ Maintainer Team
 * `Robert Luke`_
 * `Stefan Appelhoff`_
 
+.. _steering-council-people:
+
 Steering Council
 ----------------
 
 * `Britta Westner`_
 * `Daniel McCloy`_ (chair)
 * `Eric Larson`_
 
+.. _advisory-board-people:
+
 Advisory Board
 --------------
 
diff --git a/doc/sphinxext/related_software.py b/doc/sphinxext/related_software.py
@@ -37,7 +37,7 @@
 
 # If it's not available on PyPI, add it to this dict:
 MANUAL_PACKAGES = {
-    # TODO: These packages are not pip-installable as of 2024/07/17, so we have to
+    # TODO: These packages are not pip-installable as of 2025/11/19, so we have to
     # manually populate them -- should open issues on their package repos.
     "best-python": {
         "Home-page": "https://github.com/multifunkim/best-python",
@@ -54,68 +54,34 @@
     # This package does not provide wheels, so don't force CircleCI to build it.
     # If it eventually provides binary wheels we could add it to
     # `tools/circleci_dependencies.sh` and remove from here.
+    # https://github.com/Eelbrain/Eelbrain/issues/130
     "eelbrain": {
         "Home-page": "https://eelbrain.readthedocs.io/en/stable/",
         "Summary": "Open-source Python toolkit for MEG and EEG data analysis.",
     },
-    # mne-kit-gui requires mayavi (ugh)
-    "mne-kit-gui": {
-        "Home-page": "https://github.com/mne-tools/mne-kit-gui",
-        "Summary": "A module for KIT MEG coregistration.",
-    },
-    # fsleyes requires wxpython, which needs to build
-    "fsleyes": {
-        "Home-page": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FSLeyes",
-        "Summary": "FSLeyes is the FSL image viewer.",
-    },
-    # dcm2niix must be built from source
-    "dcm2niix": {
-        "Home-page": "https://github.com/rordenlab/dcm2niix",
-        "Summary": "DICOM to NIfTI converter",
-    },
     # TODO: these do not set a valid homepage or documentation page on PyPI
     "python-picard": {  # https://github.com/mind-inria/picard/issues/60
         "Home-page": "https://github.com/mind-inria/picard",
         "Summary": "Preconditioned ICA for Real Data",
     },
-    "eeg_positions": {
-        "Home-page": "https://eeg-positions.readthedocs.io",
-        "Summary": "Compute and plot standard EEG electrode positions.",
-    },
-    "mne-faster": {
-        "Home-page": "https://github.com/wmvanvliet/mne-faster",
-        "Summary": "MNE-FASTER: automatic bad channel/epoch/component detection.",  # noqa: E501
-    },
     "mne-features": {
         "Home-page": "https://mne.tools/mne-features",
         "Summary": "MNE-Features software for extracting features from multivariate time series",  # noqa: E501
     },
-    "mne-rsa": {
-        "Home-page": "https://users.aalto.fi/~vanvlm1/mne-rsa",
-        "Summary": "Code for performing Representational Similarity Analysis on MNE-Python data structures.",  # noqa: E501
-    },
     "mffpy": {
         "Home-page": "https://github.com/BEL-Public/mffpy",
         "Summary": "Reader and Writer for Philips' MFF file format.",
     },
-    "emd": {
-        "Home-page": "https://emd.readthedocs.io/en/stable",
-        "Summary": "Empirical Mode Decomposition in Python.",
-    },
-    # Needs a release with homepage set properly
-    "meegkit": {
-        "Home-page": "https://nbara.github.io/python-meegkit",
-        "Summary": "Denoising tools for M/EEG processing.",
-    },
     # not on PyPI
     "conpy": {
         "Home-page": "https://github.com/aaltoimaginglanguage/conpy",
         "Summary": "Functions and classes for performing connectivity analysis on MEG data.",  # noqa: E501
     },
 }
 
-REQUIRE_METADATA = os.getenv("MNE_REQUIRE_RELATED_SOFTWARE_INSTALLED", "false").lower()
-REQUIRE_METADATA = REQUIRE_METADATA in ("true", "1")
+REQUIRE_INSTALLED = os.getenv("MNE_REQUIRE_RELATED_SOFTWARE_INSTALLED", "false").lower()
+REQUIRE_INSTALLED = REQUIRE_INSTALLED in ("true", "1")
+REQUIRE_METADATA = REQUIRE_INSTALLED
 
 # These packages pip-install with a different name than the package name
 RENAMES = {
@@ -201,7 +167,7 @@ def _get_packages() -> dict[str, str]:
             if "Home-page" in md:
                 url = md["Home-page"]
             else:
-                for prefix in ("homepage", "documentation"):
+                for prefix in ("homepage", "documentation", "user documentation"):
                     for key, val in md.items():
                         if key == "Project-URL" and val.lower().startswith(
                             f"{prefix}, "
@@ -217,6 +183,12 @@ def _get_packages() -> dict[str, str]:
                     continue
             out[package]["url"] = url
             out[package]["description"] = md["Summary"].replace("\n", "")
+    if not REQUIRE_INSTALLED:
+        reasons = [
+            reason
+            for reason in reasons
+            if "not found, needs to be installed" not in reason
+        ]
     reason_str = "\n".join(reasons)
     if reason_str and REQUIRE_METADATA:
         raise ExtensionError(
@@ -263,6 +235,9 @@ def setup(app):
 
 
 if __name__ == "__main__":  # pragma: no cover
+    # running `python doc/sphinxext/related_software.py` for testing
+    # require metadata for any installed packages (for debugging)
+    REQUIRE_METADATA = True
     items = list(RelatedSoftwareDirective.run(None)[0].children)
     print(f"Got {len(items)} related software packages:")
     for item in items:
diff --git a/doc/sphinxext/related_software.txt b/doc/sphinxext/related_software.txt
@@ -5,6 +5,7 @@ autoreject
 bycycle
 conpy
 curryreader
+dcm2niix
 eeg_positions
 emd
 fooof
diff --git a/doc/sphinxext/related_software_nodeps.txt b/doc/sphinxext/related_software_nodeps.txt
@@ -0,0 +1,4 @@
+# deps with onerous requirements (tensorflow, wxPython, mayavi)
+cross-domain-saliency-maps
+fsleyes
+mne-kit-gui
diff --git a/mne/io/edf/edf.py b/mne/io/edf/edf.py
@@ -1734,9 +1734,9 @@ def _read_gdf_header(fname, exclude, include=None):
                 edf_info["data_offset"] + edf_info["n_records"] * edf_info["bytes_tot"]
             )
             fid.seek(etp)  # skip data to go to event table
-            etmode = fid.read(1).decode()
-            if etmode != "":
-                etmode = np.fromstring(etmode, UINT8).tolist()[0]
+            etmode = fid.read(1)
+            if isinstance(etmode, (bytes, bytearray)) and len(etmode) == 1:
+                etmode = np.frombuffer(etmode, dtype=UINT8).tolist()[0]
 
                 if edf_info["number"] < 1.94:
                     sr = read_from_file_or_buffer(fid, UINT8, 3)
diff --git a/mne/io/edf/tests/test_gdf.py b/mne/io/edf/tests/test_gdf.py
@@ -199,3 +199,13 @@ def test_gdf_read_from_file_like():
 
     with pytest.raises(Exception, match="Bad GDF file provided."):
         read_raw_gdf(BytesIO(), preload=True)
+
+
+@testing.requires_testing_data
+@pytest.mark.filterwarnings("ignore:Highpass cutoff frequency")
+def test_gh_13414():
+    """Test handling bytes objects when reading GDF events."""
+    fpath = data_path / "GDF" / "test_gdf_1.99.gdf"
+    raw = read_raw_gdf(fpath)
+    # Should be 1 event in this GDF file.
+    assert len(raw.annotations) == 1
diff --git a/mne/io/eyelink/_utils.py b/mne/io/eyelink/_utils.py
@@ -400,7 +400,24 @@ def _create_dataframes_for_block(block, apply_offsets):
             msgs.append([ts, offset, msg])
         df_dict["messages"] = pd.DataFrame(msgs)
 
-        # TODO: Make dataframes for other eyelink events (Buttons)
+    # make dataframes for other button events
+    if block["events"]["BUTTON"]:
+        button_events = block["events"]["BUTTON"]
+        parsed = []
+        for entry in button_events:
+            parsed.append(
+                {
+                    "time": float(entry[0]),  # onset
+                    "button_id": int(entry[1]),
+                    "button_pressed": int(entry[2]),  # 1 = press, 0 = release
+                }
+            )
+        df_dict["buttons"] = pd.DataFrame(parsed)
+        n_button = len(df_dict.get("buttons", []))
+        logger.info(f"Found {n_button} button event(s) in this file.")
+    else:
+        logger.info("No button events found in this file.")
+
     return df_dict
 
 
@@ -499,7 +516,6 @@ def _combine_block_dataframes(processed_blocks: list[dict]):
 
     for df_type in all_df_types:
         block_dfs = []
-
         for block in processed_blocks:
             if df_type in block["dfs"]:
                 # We will update the dfs in-place to conserve memory
@@ -849,7 +865,7 @@ def _make_eyelink_annots(df_dict, create_annots, apply_offsets):
             "pupil_right",
         ),
     }
-    valid_descs = ["blinks", "saccades", "fixations", "messages"]
+    valid_descs = ["blinks", "saccades", "fixations", "buttons", "messages"]
     msg = (
         "create_annotations must be True or a list containing one or"
         f" more of {valid_descs}."
@@ -875,6 +891,7 @@ def _make_eyelink_annots(df_dict, create_annots, apply_offsets):
             descriptions = key[:-1]  # i.e "blink", "fixation", "saccade"
             if key == "blinks":
                 descriptions = "BAD_" + descriptions
+
             ch_names = df["eye"].map(eye_ch_map).tolist()
             this_annot = Annotations(
                 onset=onsets,
@@ -890,21 +907,44 @@ def _make_eyelink_annots(df_dict, create_annots, apply_offsets):
                 onsets = df["time"]
             durations = [0] * onsets
             descriptions = df["event_msg"]
+            this_annot = Annotations(
+                onset=onsets, duration=durations, description=descriptions
+            )
+        elif (key == "buttons") and (key in descs):
+            required_cols = {"time", "button_id", "button_pressed"}
+            if not required_cols.issubset(df.columns):
+                raise ValueError(f"Missing column: {required_cols - set(df.columns)}")
+            # Give user a hint
+            n_presses = df["button_pressed"].sum()
+            logger.info("Found %d button press events.", n_presses)
+
+            df = df.sort_values("time")
+            onsets = df["time"]
+            durations = np.zeros_like(onsets)
+            descriptions = df.apply(_get_button_description, axis=1)
+
             this_annot = Annotations(
                 onset=onsets, duration=durations, description=descriptions
             )
         else:
-            continue  # TODO make df and annotations for Buttons
+            continue
         if not annots:
             annots = this_annot
         elif annots:
             annots += this_annot
     if not annots:
         warn(f"Annotations for {descs} were requested but none could be made.")
         return
+
     return annots
 
 
+def _get_button_description(row):
+    button_id = int(row["button_id"])
+    action = "press" if row["button_pressed"] == 1 else "release"
+    return f"button_{button_id}_{action}"
+
+
 def _make_gap_annots(raw_extras, key="recording_blocks"):
     """Create Annotations for gap periods between recording blocks."""
     df = raw_extras["dfs"][key]
diff --git a/mne/io/eyelink/tests/test_eyelink.py b/mne/io/eyelink/tests/test_eyelink.py
diff --git a/mne/viz/evoked.py b/mne/viz/evoked.py
diff --git a/mne/viz/montage.py b/mne/viz/montage.py
diff --git a/mne/viz/tests/test_montage.py b/mne/viz/tests/test_montage.py
diff --git a/tools/circleci_dependencies.sh b/tools/circleci_dependencies.sh
diff --git a/tutorials/evoked/30_eeg_erp.py b/tutorials/evoked/30_eeg_erp.py

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+Fix bug with :func:`mne.viz.plot_evoked` when using ``gfp="only"`` or ``gfp=True``, by `Michael Straube`_.
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+Fix bug where :meth:`mne.channels.DigMontage.plot` would error when ``axes`` was passed by `Christian O'Reilly`_.
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+Fixed a bug where ``mne.io.read_raw_gdf`` failed with NumPy ≥1.24 due to the removal of ``np.fromstring`` binary mode. Replaced with ``np.frombuffer`` for compatibility, by :newcontrib:`Dev Parikh`.
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+Added support for parsing Eyelink ``BUTTON`` events (i.e. external controller button presses) to :func:`~mne.io.read_raw_eyelink` by :newcontrib:`Wouter Kroot`