Merge branch 'main' into main

Author: JuliusWelzel

.github/release.yaml

@@ -0,0 +1,6 @@
+changelog:
+  exclude:
+    authors:
+      - dependabot[bot]
+      - pre-commit-ci[bot]
+      - github-actions[bot]

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.12.12
+    rev: v0.13.1
     hooks:
       - id: ruff
         name: ruff mne_bids/
@@ -33,7 +33,7 @@ repos:
       - id: check-docstring-first
 
   - repo: https://github.com/pappasam/toml-sort
-    rev: v0.24.2
+    rev: v0.24.3
     hooks:
       - id: toml-sort-fix
         files: pyproject.toml

CITATION.cff

@@ -214,6 +214,10 @@ authors:
       family-names: Ritz
       affiliation: 'Princeton Neuroscience Institute, Princeton University, Princeton, USA'
       orcid: 'https://orcid.org/0009-0003-1477-4912'
+    - given-names: Alex
+      family-names: Lopez Marquez
+      affiliation: 'Institut Guttmann, Barcelona, Spain'
+      orcid: 'https://orcid.org/0000-0002-3353-280X'
     - given-names: Nathan
       family-names: Azrak
       orcid: 'https://orcid.org/0000-0001-7695-4634'

doc/_static/versions.json

@@ -1,12 +1,17 @@
 [
     {
-        "name": "0.17 (devel)",
+        "name": "0.18 (devel)",
         "version": "dev",
         "url": "https://mne.tools/mne-bids/dev/"
     },
     {
-        "name": "0.16 (stable)",
+        "name": "0.17 (stable)",
         "version": "stable",
+        "url": "https://mne.tools/mne-bids/v0.17/"
+    },
+    {
+        "name": "0.16",
+        "version": "0.16",
         "url": "https://mne.tools/mne-bids/v0.16/"
     },
     {

doc/authors.rst

@@ -1,5 +1,6 @@
 .. _Aaron Earle-Richardson: https://github.com/Aaronearlerichardson
 .. _Adam Li: https://github.com/adam2392
+.. _Alex Lopez Marquez: https://github.com/alm180
 .. _Alex Rockhill: https://github.com/alexrockhill
 .. _Alexandre Gramfort: http://alexandre.gramfort.net
 .. _Amaia Benitez: https://github.com/AmaiaBA
@@ -55,6 +56,7 @@
 .. _Teon Brooks: https://teonbrooks.com
 .. _Thomas Hartmann: https://github.com/thht
 .. _Tom Donoghue: https://github.com/TomDonoghue
+.. _waldie11: https://github.com/waldie11
 .. _William Turner: https://bootstrapbill.github.io/
 .. _Yorguin Mantilla: https://github.com/yjmantilla
 .. _Julius Welzel: https://github.com/JuliusWelzel

doc/whats_new.rst

@@ -4,12 +4,14 @@
 
 .. currentmodule:: mne_bids
 
+.. include:: authors.rst
+
 What's new?
 ===========
 
-.. _changes_0_17:
+.. _changes_0_18:
 
-Version 0.17 (unreleased)
+Version 0.18 (unreleased)
 -------------------------
 
 👩🏽‍💻 Authors
@@ -24,59 +26,40 @@ The following authors contributed for the first time. Thank you so much! 🤩
 * `Harrison Ritz`_
 * `Julius Welzel`_
 * `Nathan Azrak`_
+* `Alex Lopez Marquez`_
 
 
 The following authors had contributed before. Thank you for sticking around! 🤘
 
-* `Stefan Appelhoff`_
-* `Daniel McCloy`_
-* `Scott Huberty`_
-* `Pierre Guetschel`_
-* `Teon Brooks`_
+* TBD
+
 
 Detailed list of changes
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 🚀 Enhancements
 ^^^^^^^^^^^^^^^
 
-- :func:`mne_bids.write_raw_bids()` can now handle mne `Raw` objects with `eyegaze` and `pupil` channels, by `Christian O'Reilly`_ (:gh:`1344`)
-- :func:`mne_bids.get_entity_vals()` has a new parameter ``ignore_suffixes`` to easily ignore sidecar files, by `Daniel McCloy`_ (:gh:`1362`)
-- Empty-room matching now preferentially finds recordings in the subject directory tagged as `task-noise` before looking in the `sub-emptyroom` directories. This adds support for a part of the BIDS specification for ER recordings, by `Berk Gerçek`_ (:gh:`1364`)
-- Path matching is now implemenented in a more efficient manner within :meth:`mne_bids.BIDSPath.match()` and :func:`mne_bids.find_matching_paths()`, by `Arne Gottwald` (:gh:`1355`)
-- :func:`mne_bids.get_entity_vals()` has a new parameter ``include_match`` to prefilter item matching and ignore non-matched items from begin of directory scan, by `Arne Gottwald` (:gh:`1355`)
-- Data from ``events.tsv`` can now be read into an OrderedDict using :func:`mne_bids.events_file_to_annotation_kwargs()`, by `Matthias Dold` (:gh:`1389`)
-- Read the optionally present extra columns from ``events.tsv`` and pass them to :class:`mne.Annotations`, by `Pierre Guetschel` (:gh:`1401`)
-- ``_filter_fnames()`` now correctly checks the default extension, correcting suffix filtering, by `Nathan Azrak` (:gh:`1427`)
-
+- :func:`mne_bids.write_raw_bids()` has a new parameter `electrodes_tsv_task` which allows adding the `task` entity to the `electrodes.tsv` filepath, by `Alex Lopez Marquez`_ (:gh:`1424`)
 
 🧐 API and behavior changes
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-- :func:`mne_bids.make_dataset_description` will now auto-generate basic ``GeneratedBy`` fields if ``generated_by=None``. To suppress the auto-generated fields, pass an empty list. By `Daniel McCloy`_ (:gh:`1384`)
-- Add requirements that ``root``, ``subject``, ``task`` attributes must be set when using :func:`mne_bids.read_raw_bids` to avoid implicit behavior and file ambiguity, by `Teon Brooks`_ (:gh:`1414`)
+- None yet
 
 🛠 Requirements
 ^^^^^^^^^^^^^^^
 
-- MNE-BIDS now requires ``mne`` 1.8 or higher.
+- None yet
 
 🪲 Bug fixes
 ^^^^^^^^^^^^
 
-- :func:`mne_bids.read_raw_bids` can optionally return an ``event_id`` dictionary suitable for use with :func:`mne.events_from_annotations`, and if a ``values`` column is present in ``events.tsv`` it will be used as the source of the integer event ID codes, by `Daniel McCloy`_ (:gh:`1349`)
-- BIDS dictates that the recording entity should be displayed as "_recording-" in the filename. This PR makes :class:`mne_bids.BIDSPath`  correctly display "_recording-" (instead of "_rec-") in BIDSPath.fpath. By `Scott Huberty`_ (:gh:`1348`)
-- :func:`mne_bids.make_dataset_description` now correctly encodes the dataset description as UTF-8 on disk, by `Scott Huberty`_ (:gh:`1357`)
-- Corrects extension when filtering filenames in :meth:`mne_bids.BIDSPath.match()` and :func:`mne_bids.find_matching_paths()`, by `Arne Gottwald` (:gh:`1355`)
-- Fix :class:`mne_bids.BIDSPath` partially matching a value, by `Pierre Guetschel` (:gh:`1388`)
-- Ensures that ``check`` parameter in :meth:`mne_bids.BIDSPath.update()` is passed to :class:`mne_bids.BIDSPath`, by `Teon Brooks`_ (:gh:`1411`)
-- minor: added `T2w` to the suffix allowlist, by `Harrison Ritz`_ (:gh:`1420`)
+- Fixed a bug that modified the name and help message of some of the available commands, by `Alex Lopez Marquez`_ (:gh:`1441`)
 
 ⚕️ Code health
 ^^^^^^^^^^^^^^
 
-- Tests that were adding or deleting files to/from a session-scoped dataset now properly clean up after themselves, by `Daniel McCloy`_ (:gh:`1347`)
+- Made :func:`mne_bids.copyfiles.copyfile_brainvision` output more meaningful error messages when encountering problematic files, by `Stefan Appelhoff`_ (:gh:`1444`)
 
 :doc:`Find out what was new in previous releases <whats_new_previous_releases>`
-
-.. include:: authors.rst

doc/whats_new_previous_releases.rst

@@ -9,6 +9,83 @@
 What was new in previous releases?
 ==================================
 
+.. _changes_0_17:
+
+Version 0.17 (2025-09-10)
+-------------------------
+
+👩🏽‍💻 Authors
+~~~~~~~~~~~~~~~
+
+The following authors contributed for the first time. Thank you so much! 🤩
+
+* `Nathan Azrak`_
+* `Matthias Dold`_
+* `Berk Gerçek`_
+* `Arne Gottwald`_
+* `Christian O'Reilly`_
+* `Harrison Ritz`_
+* `waldie11`_
+
+The following authors had contributed before. Thank you for sticking around! 🤘
+
+* `Stefan Appelhoff`_
+* `Teon Brooks`_
+* `Pierre Guetschel`_
+* `Richard Höchenberger`_
+* `Scott Huberty`_
+* `Eric Larson`_
+* `Daniel McCloy`_
+
+
+Detailed list of changes
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+🚀 Enhancements
+^^^^^^^^^^^^^^^
+
+- :func:`mne_bids.write_raw_bids()` can now handle mne `Raw` objects with `eyegaze` and `pupil` channels, by `Christian O'Reilly`_ (:gh:`1344`)
+- :func:`mne_bids.get_entity_vals()` has a new parameter ``ignore_suffixes`` to easily ignore sidecar files, by `Daniel McCloy`_ (:gh:`1362`)
+- Empty-room matching now preferentially finds recordings in the subject directory tagged as `task-noise` before looking in the `sub-emptyroom` directories. This adds support for a part of the BIDS specification for ER recordings, by `Berk Gerçek`_ (:gh:`1364`)
+- Path matching is now implemenented in a more efficient manner within :meth:`mne_bids.BIDSPath.match()` and :func:`mne_bids.find_matching_paths()`, by `Arne Gottwald` (:gh:`1355`)
+- :func:`mne_bids.get_entity_vals()` has a new parameter ``include_match`` to prefilter item matching and ignore non-matched items from begin of directory scan, by `Arne Gottwald` (:gh:`1355`)
+- Data from ``events.tsv`` can now be read into an OrderedDict using :func:`mne_bids.events_file_to_annotation_kwargs()`, by `Matthias Dold` (:gh:`1389`)
+- Read the optionally present extra columns from ``events.tsv`` and pass them to :class:`mne.Annotations`, by `Pierre Guetschel` (:gh:`1401`)
+- ``_filter_fnames()`` now correctly checks the default extension, correcting suffix filtering, by `Nathan Azrak` (:gh:`1427`)
+
+
+🧐 API and behavior changes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- :func:`mne_bids.make_dataset_description` will now auto-generate basic ``GeneratedBy`` fields if ``generated_by=None``. To suppress the auto-generated fields, pass an empty list. By `Daniel McCloy`_ (:gh:`1384`)
+- Add requirements that ``root``, ``subject``, ``task`` attributes must be set when using :func:`mne_bids.read_raw_bids` to avoid implicit behavior and file ambiguity, by `Teon Brooks`_ (:gh:`1414`)
+
+🛠 Requirements
+^^^^^^^^^^^^^^^
+
+- MNE-BIDS now requires ``mne`` 1.8 or higher.
+
+🪲 Bug fixes
+^^^^^^^^^^^^
+
+- :func:`mne_bids.read_raw_bids` can optionally return an ``event_id`` dictionary suitable for use with :func:`mne.events_from_annotations`, and if a ``values`` column is present in ``events.tsv`` it will be used as the source of the integer event ID codes, by `Daniel McCloy`_ (:gh:`1349`)
+- BIDS dictates that the recording entity should be displayed as "_recording-" in the filename. This PR makes :class:`mne_bids.BIDSPath`  correctly display "_recording-" (instead of "_rec-") in BIDSPath.fpath. By `Scott Huberty`_ (:gh:`1348`)
+- :func:`mne_bids.make_dataset_description` now correctly encodes the dataset description as UTF-8 on disk, by `Scott Huberty`_ (:gh:`1357`)
+- Corrects extension when filtering filenames in :meth:`mne_bids.BIDSPath.match()` and :func:`mne_bids.find_matching_paths()`, by `Arne Gottwald` (:gh:`1355`)
+- Fix :class:`mne_bids.BIDSPath` partially matching a value, by `Pierre Guetschel` (:gh:`1388`)
+- Ensures that ``check`` parameter in :meth:`mne_bids.BIDSPath.update()` is passed to :class:`mne_bids.BIDSPath`, by `Teon Brooks`_ (:gh:`1411`)
+- minor: added `T2w` to the suffix allowlist, by `Harrison Ritz`_ (:gh:`1420`)
+
+⚕️ Code health
+^^^^^^^^^^^^^^
+
+- Tests that were adding or deleting files to/from a session-scoped dataset now properly clean up after themselves, by `Daniel McCloy`_ (:gh:`1347`)
+
+:doc:`Find out what was new in previous releases <whats_new_previous_releases>`
+
+.. include:: authors.rst
+
+
 .. _changes_0_16:
 
 Version 0.16 (2024-11-16)

mne_bids/commands/run.py

@@ -11,7 +11,7 @@
 
 mne_bin_dir = Path(mne_bids.__file__).parent
 valid_command_paths = sorted((mne_bin_dir / "commands").glob("mne_bids_*.py"))
-valid_commands = [cmd.stem.lstrip("mne_bids_") for cmd in valid_command_paths]
+valid_commands = [cmd.stem.removeprefix("mne_bids_") for cmd in valid_command_paths]
 
 
 def print_help():

mne_bids/copyfiles.py

@@ -108,17 +108,24 @@ def _get_brainvision_paths(vhdr_path):
         vmrk_file = vmrk_file_match.groups()[0]
 
     # Make sure we are dealing with file names as is customary, not paths
-    # Paths are problematic when copying the files to another system. Instead,
-    # always use the file name and keep the file triplet in the same directory
-    assert os.sep not in eeg_file
-    assert os.sep not in vmrk_file
+    for fi in [eeg_file, vmrk_file]:
+        if os.sep in fi:
+            raise RuntimeError(
+                f"Detected a path separator in a file link: {fi}.\n\n"
+                "Paths are problematic when copying the files to another system. "
+                "Instead, always use the file name and keep the "
+                "BrainVision file triplet (eeg/dat, vhdr, vmrk) in the same directory."
+            )
 
     # Assert the paths exist
     head, tail = op.split(vhdr_path)
     eeg_file_path = op.join(head, eeg_file)
     vmrk_file_path = op.join(head, vmrk_file)
-    assert op.exists(eeg_file_path)
-    assert op.exists(vmrk_file_path)
+    for fpath in [eeg_file_path, vmrk_file_path]:
+        if not Path(fpath).exists():
+            raise FileNotFoundError(
+                f"{fpath} referenced in {vhdr_path} but it does not exist."
+            )
 
     # Return the paths
     return (eeg_file_path, vmrk_file_path)
@@ -355,14 +362,24 @@ def copyfile_brainvision(vhdr_src, vhdr_dest, anonymize=None, verbose=None):
     # Write new header and marker files, fixing the file pointer links
     # For that, we need to replace an old "basename" with a new one
     # assuming that all .eeg/.dat, .vhdr, .vmrk share one basename
-    __, basename_src = op.split(fname_src)
-    assert op.split(eeg_file_path)[-1] in [basename_src + ".eeg", basename_src + ".dat"]
-    assert basename_src + ".vmrk" == op.split(vmrk_file_path)[-1]
-    __, basename_dest = op.split(fname_dest)
+    basename_src = Path(fname_src).name
+    eeg_expected = [f"{basename_src}.eeg", f"{basename_src}.dat"]
+    vmrk_expected = [f"{basename_src}.vmrk"]
+    if Path(eeg_file_path).name not in eeg_expected:
+        raise RuntimeError(
+            f"Unexpected path to data file in {vhdr_src}:\n    "
+            f"-->{Path(eeg_file_path).name}\nExpected one of {eeg_expected}."
+        )
+    if Path(vmrk_file_path).name not in vmrk_expected:
+        raise RuntimeError(
+            f"Unexpected path to marker file in {vhdr_src}:\n    "
+            f"-->{Path(vmrk_file_path).name}\nExpected one of {vmrk_expected}."
+        )
+    basename_dest = Path(fname_dest).name
     search_lines = [
-        "DataFile=" + basename_src + ".eeg",
-        "DataFile=" + basename_src + ".dat",
-        "MarkerFile=" + basename_src + ".vmrk",
+        f"DataFile={basename_src}.eeg",
+        f"DataFile={basename_src}.dat",
+        f"MarkerFile={basename_src}.vmrk",
     ]
 
     with open(vhdr_src, encoding=enc) as fin:

mne_bids/dig.py

@@ -385,7 +385,14 @@ def _write_coordsystem_json(
     _write_json(fname, fid_json, overwrite=True)
 
 
-def _write_dig_bids(bids_path, raw, montage=None, acpc_aligned=False, overwrite=False):
+def _write_dig_bids(
+    bids_path,
+    raw,
+    montage=None,
+    acpc_aligned=False,
+    electrodes_tsv_task=False,
+    overwrite=False,
+):
     """Write BIDS formatted DigMontage from Raw instance.
 
     Handles coordsystem.json and electrodes.tsv writing
@@ -405,6 +412,9 @@ def _write_dig_bids(bids_path, raw, montage=None, acpc_aligned=False, overwrite=
         must be transformed from the "head" coordinate frame.
     acpc_aligned : bool
         Whether "mri" space is aligned to ACPC.
+    electrodes_tsv_task : bool
+        Whether to add the ``task-`` entity to the ``electrodes.tsv`` filename.
+        Defaults to ``False``.
     overwrite : bool
         Whether to overwrite the existing file.
         Defaults to False.
@@ -500,12 +510,16 @@ def _write_dig_bids(bids_path, raw, montage=None, acpc_aligned=False, overwrite=
         "acquisition": bids_path.acquisition,
         "space": None if bids_path.datatype == "nirs" else coord_frame,
     }
+    # add `task-` to the electrodes.tsv file if requested
+    electrode_file_entities = coord_file_entities.copy()
+    if electrodes_tsv_task and bids_path.task is not None:
+        electrode_file_entities["task"] = bids_path.task
     channels_suffix = "optodes" if bids_path.datatype == "nirs" else "electrodes"
     _channels_fun = (
         _write_optodes_tsv if bids_path.datatype == "nirs" else _write_electrodes_tsv
     )
     channels_path = BIDSPath(
-        **coord_file_entities, suffix=channels_suffix, extension=".tsv"
+        **electrode_file_entities, suffix=channels_suffix, extension=".tsv"
     )
     coordsystem_path = BIDSPath(
         **coord_file_entities, suffix="coordsystem", extension=".json"