Merge branch 'main' into main

Author: sappelhoff

.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'

README.md

@@ -58,3 +58,4 @@ Please also cite one of the following papers to credit BIDS, depending on which
 - [EEG-BIDS](https://doi.org/10.1038/s41597-019-0104-8)
 - [iEEG-BIDS](https://doi.org/10.1038/s41597-019-0105-7)
 - [NIRS-BIDS](https://doi.org/10.31219/osf.io/7nmcp)
+- [Motion-BIDS](https://doi.org/10.1038/s41597-024-03559-8)

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
@@ -58,3 +59,4 @@
 .. _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

@@ -19,11 +19,13 @@ Version 0.18 (unreleased)
 
 The following authors contributed for the first time. Thank you so much! 🤩
 
-* TBD
+* `Julius Welzel`_
+* `Alex Lopez Marquez`_
+
 
 The following authors had contributed before. Thank you for sticking around! 🤘
 
-* TBD
+* `Stefan Appelhoff`_
 
 
 Detailed list of changes
@@ -32,13 +34,13 @@ Detailed list of changes
 🚀 Enhancements
 ^^^^^^^^^^^^^^^
 
-- None yet
-
+- :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`)
+- Extended the configuration to recognise `motion` as a valid BIDS datatype by `Julius Welzel`_ (:gh:`1430`)
 
 🧐 API and behavior changes
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-- None yet
+-  `tracksys` accepted as argument in :class:`mne_bids.BIDSPath()` by `Julius Welzel`_ (:gh:`1430`)
 
 🛠 Requirements
 ^^^^^^^^^^^^^^^
@@ -48,11 +50,11 @@ Detailed list of changes
 🪲 Bug fixes
 ^^^^^^^^^^^^
 
-- None yet
+- Fixed a bug that modified the name and help message of some of the available commands, by `Alex Lopez Marquez`_ (:gh:`1441`)
 
 ⚕️ Code health
 ^^^^^^^^^^^^^^
 
-- None yet
+- 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>`

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/config.py

@@ -6,7 +6,7 @@
 from mne import io
 from mne.io.constants import FIFF
 
-BIDS_VERSION = "1.7.0"
+BIDS_VERSION = "1.9.0"
 
 PYBV_VERSION = "0.7.3"
 EEGLABIO_VERSION = "0.0.2"
@@ -15,17 +15,19 @@
 
 EPHY_ALLOWED_DATATYPES = ["meg", "eeg", "ieeg", "nirs"]
 
-ALLOWED_DATATYPES = EPHY_ALLOWED_DATATYPES + ["anat", "beh"]
+ALLOWED_DATATYPES = EPHY_ALLOWED_DATATYPES + ["anat", "beh", "motion"]
 
 MEG_CONVERT_FORMATS = ["FIF", "auto"]
 EEG_CONVERT_FORMATS = ["BrainVision", "auto"]
 IEEG_CONVERT_FORMATS = ["BrainVision", "auto"]
 NIRS_CONVERT_FORMATS = ["auto"]
+MOTION_CONVERT_FORMATS = ["tsv", "auto"]
 CONVERT_FORMATS = {
     "meg": MEG_CONVERT_FORMATS,
     "eeg": EEG_CONVERT_FORMATS,
     "ieeg": IEEG_CONVERT_FORMATS,
     "nirs": NIRS_CONVERT_FORMATS,
+    "motion": MOTION_CONVERT_FORMATS,
 }
 
 # Orientation of the coordinate system dependent on manufacturer
@@ -147,12 +149,17 @@
     ".snirf",  # SNIRF
 ]
 
+allowed_extensions_motion = [
+    ".tsv",  # Tab-separated values
+]
+
 # allowed extensions (data formats) in BIDS spec
 ALLOWED_DATATYPE_EXTENSIONS = {
     "meg": allowed_extensions_meg,
     "eeg": allowed_extensions_eeg,
     "ieeg": allowed_extensions_ieeg,
     "nirs": allowed_extensions_nirs,
+    "motion": allowed_extensions_motion,
 }
 
 # allow additional extensions that are not BIDS
@@ -190,6 +197,7 @@
     "physio",
     "stim",  # behavioral
     "nirs",
+    "motion",  # motion
 ]
 
 # converts suffix to known path modalities
@@ -227,6 +235,7 @@
     "description",
     "suffix",
     "extension",
+    "tracking_system",
 )
 ALLOWED_PATH_ENTITIES_SHORT = {
     "sub": "subject",
@@ -239,6 +248,7 @@
     "recording": "recording",
     "split": "split",
     "desc": "description",
+    "tracksys": "tracking_system",
 }
 
 # Annotations to never remove during reading or writing
@@ -316,6 +326,7 @@
 ALLOWED_SPACES["ieeg"] = BIDS_SHARED_COORDINATE_FRAMES + BIDS_IEEG_COORDINATE_FRAMES
 ALLOWED_SPACES["anat"] = None
 ALLOWED_SPACES["beh"] = None
+ALLOWED_SPACES["motion"] = None
 
 # See: https://bids-specification.readthedocs.io/en/latest/appendices/entity-table.html#encephalography-eeg-ieeg-and-meg  # noqa: E501
 ENTITY_VALUE_TYPE = {
@@ -331,6 +342,7 @@
     "description": "label",
     "suffix": "label",
     "extension": "label",
+    "tracking_system": "label",
 }
 
 # mapping from supported BIDs coordinate frames -> MNE

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"

mne_bids/path.py

@@ -385,6 +385,7 @@ def __init__(
         space=None,
         split=None,
         description=None,
+        tracking_system=None,
         root=None,
         suffix=None,
         extension=None,
@@ -421,6 +422,7 @@ def __init__(
             space=space,
             split=split,
             description=description,
+            tracking_system=tracking_system,
             root=root,
             datatype=datatype,
             suffix=suffix,
@@ -442,6 +444,7 @@ def entities(self):
             "recording": self.recording,
             "split": self.split,
             "description": self.description,
+            "tracking_system": self.tracking_system,
         }
 
     @property
@@ -575,6 +578,15 @@ def description(self) -> str | None:
     def description(self, value):
         self.update(description=value)
 
+    @property
+    def tracking_system(self) -> str | None:
+        """The tracking system entity."""
+        return self._tracking_system
+
+    @tracking_system.setter
+    def tracking_system(self, value):
+        self.update(tracking_system=value)
+
     @property
     def suffix(self) -> str | None:
         """The filename suffix."""
@@ -881,7 +893,9 @@ def fpath(self):
                 if self.suffix is None or self.suffix in ALLOWED_DATATYPES:
                     # now only use valid datatype extension
                     if self.extension is None:
-                        valid_exts = sum(ALLOWED_DATATYPE_EXTENSIONS.values(), [])
+                        valid_exts = ALLOWED_DATATYPE_EXTENSIONS.get(
+                            self.datatype, sum(ALLOWED_DATATYPE_EXTENSIONS.values(), [])
+                        )
                     else:
                         valid_exts = [self.extension]
                     matching_paths = [
@@ -2325,6 +2339,7 @@ def _filter_fnames(
     description=None,
     suffix=None,
     extension=None,
+    tracking_system=None,
 ):
     """Filter a list of BIDS filenames / paths based on BIDS entity values.
 
@@ -2351,6 +2366,7 @@ def _filter_fnames(
     description = _ensure_tuple(description)
     suffix = _ensure_tuple(suffix)
     extension = _ensure_tuple(extension)
+    tracking_system = _ensure_tuple(tracking_system)
 
     leading_path_str = r".*\/?"  # nothing or something ending with a `/`
     sub_str = r"sub-(" + "|".join(subject) + ")" if subject else r"sub-([^_]+)"
@@ -2375,6 +2391,11 @@ def _filter_fnames(
     )
     suffix_str = r"_(" + "|".join(suffix) + ")" if suffix else r"_([^_]+)"
     ext_str = r"(" + "|".join(extension) + ")$" if extension else r"\.([^_]+)"
+    tracksys_str = (
+        r"tracksys-(" + "|".join(tracking_system) + ")"
+        if tracking_system
+        else r"(|tracksys-([^_]+))"
+    )
 
     regexp = (
         leading_path_str
@@ -2390,6 +2411,7 @@ def _filter_fnames(
         + desc_str
         + suffix_str
         + ext_str
+        + tracksys_str
     )
 
     # Convert to str so we can apply the regexp ...