Refactor _handle_events_reading to allow extracting annotation information stand-alone

CITATION.cff

@@ -206,6 +206,10 @@ authors:
       family-names: Gerçek
       affiliation: 'University of Geneva, Department of Fundamental Neuroscience'
       orcid: 'https://orcid.org/0000-0003-1063-6769'
+    - given-names: Matthias
+      family-names: Dold
+      affiliation: 'Donders Institute for Brain, Cognition and Behaviour, Radboud University, Nijmegen, Netherlands'
+      orcid: 'https://orcid.org/0009-0003-1477-4912'
     - given-names: Alexandre
       family-names: Gramfort
       affiliation: 'Université Paris-Saclay, Inria, CEA, Palaiseau, France'

doc/authors.rst

@@ -35,6 +35,7 @@
 .. _Mara Wolter: https://github.com/marakw
 .. _Marijn van Vliet: https://github.com/wmvanvliet
 .. _Mathieu Scheltienne: https://github.com/mscheltienne
+.. _Matthias Dold: https://github.com/matthiasdold
 .. _Matt Sanderson: https://github.com/monkeyman192
 .. _Maximilien Chaumon: https://github.com/dnacombo
 .. _Moritz Gerster: http://moritz-gerster.com

doc/whats_new.rst

@@ -20,6 +20,7 @@ The following authors contributed for the first time. Thank you so much! 🤩
 * `Christian O'Reilly`_
 * `Berk Gerçek`_
 * `Arne Gottwald`_
+* `Matthias Dold`_
 
 The following authors had contributed before. Thank you for sticking around! 🤘
 
@@ -39,6 +40,7 @@ Detailed list of changes
 - 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`)
+- `_handle_events_reading()` was refactored to now exposed the filtering of the `events.tsv` data as a separate function :func:`mne_bids.read.events_file_to_annotation_kwargs`, by `Matthias Dold` (:gh:`1389`)
 
 
 🧐 API and behavior changes

mne_bids/read.py

@@ -523,8 +523,8 @@ def _handle_info_reading(sidecar_fname, raw):
     return raw
 
 
-def _handle_events_reading(events_fname, raw):
-    """Read associated events.tsv and convert valid events to annotations on Raw."""
+def events_file_to_annotation_kwargs(events_fname: str) -> dict:
+    """Read the `events.tsv` file and extract onset, duration, and description."""
     logger.info(f"Reading events from {events_fname}.")
     events_dict = _from_tsv(events_fname)
 
@@ -601,9 +601,21 @@ def _handle_events_reading(events_fname, raw):
         [0 if du == "n/a" else du for du in events_dict["duration"]], dtype=float
     )
 
+    return {"onset": ons, "duration": durs, "description": descrs, "event_id": event_id}
+
+
+def _handle_events_reading(events_fname, raw):
+    """Read associated events.tsv and convert valid events to annotations on Raw."""
+    annotations_info = events_file_to_annotation_kwargs(events_fname)
+    event_id = annotations_info["event_id"]
+
     # Add events as Annotations, but keep essential Annotations present in raw file
     annot_from_raw = raw.annotations.copy()
-    annot_from_events = mne.Annotations(onset=ons, duration=durs, description=descrs)
+    annot_from_events = mne.Annotations(
+        onset=annotations_info["onset"],
+        duration=annotations_info["duration"],
+        description=annotations_info["description"],
+    )
     raw.set_annotations(annot_from_events)
 
     annot_idx_to_keep = [