add optional task- to electrodes.tsv

Author: alm180

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: Alexandre
       family-names: Gramfort
       affiliation: 'Université Paris-Saclay, Inria, CEA, Palaiseau, France'

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

doc/whats_new.rst

@@ -22,6 +22,7 @@ The following authors contributed for the first time. Thank you so much! 🤩
 * `Arne Gottwald`_
 * `Matthias Dold`_
 * `Harrison Ritz`_
+* `Alex Lopez Marquez`_
 
 The following authors had contributed before. Thank you for sticking around! 🤘
 
@@ -44,6 +45,7 @@ Detailed list of changes
 - :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`)
+- :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

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 ``BIDSPath`` of
+        the ``electrodes.tsv`` file. 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/write.py

@@ -1432,6 +1432,7 @@ def write_raw_bids(
     event_id=None,
     event_metadata=None,
     extra_columns_descriptions=None,
+    electrodes_tsv_task=False,
     *,
     anonymize=None,
     format="auto",
@@ -1535,6 +1536,9 @@ def write_raw_bids(
     extra_columns_descriptions : dict | None
         A dictionary that maps column names of the ``event_metadata`` to descriptions.
         Each column of ``event_metadata`` must have a corresponding entry in this.
+    electrodes_tsv_task : bool
+        Add the ``task-`` entity to the ``BIDSPath`` of the
+        ``electrodes.tsv`` file. Defaults to ``False``.
     anonymize : dict | None
         If `None` (default), no anonymization is performed.
         If a dictionary, data will be anonymized depending on the dictionary
@@ -2050,7 +2054,9 @@ def write_raw_bids(
         # We only write electrodes.tsv and accompanying coordsystem.json
         # if we have an available DigMontage
         if montage is not None or (raw.info["dig"] is not None and raw.info["dig"]):
-            _write_dig_bids(bids_path, raw, montage, acpc_aligned, overwrite)
+            _write_dig_bids(
+                bids_path, raw, montage, acpc_aligned, electrodes_tsv_task, overwrite
+            )
     else:
         logger.info(
             f"Writing of electrodes.tsv is not supported "