[ENH] Add function to enable smart path search #1098 (#1103)

CITATION.cff

@@ -151,6 +151,10 @@ authors:
       family-names: Engemann
       affiliation: 'Roche Pharma Research and Early Development (pRED), Basel, Switzerland'
       orcid: 'https://orcid.org/0000-0002-7223-1014'
+    - given-names: Moritz
+      family-names: Gerster
+      affiliation: 'Max Planck Institute for Human Cognitive and Brain Sciences, Leipzig, Germany'
+      orcid: 'https://orcid.org/0000-0001-9343-6986'
     - given-names: Alexandre
       family-names: Gramfort
       affiliation: 'Université Paris-Saclay, Inria, CEA, Palaiseau, France'

doc/api.rst

@@ -44,6 +44,7 @@ mne_bids
    inspect_dataset
    update_sidecar_json
    anonymize_dataset
+   find_matching_paths
 
 mne_bids.stats
 --------------

doc/authors.rst

@@ -39,3 +39,4 @@
 .. _Denis Engemann: https://github.com/dengemann
 .. _Bruno Hebling Vieira: https://bhvieira.github.io/
 .. _Daniel McCloy: http://dan.mccloy.info
+.. _Moritz Gerster: http://moritz-gerster.com

doc/whats_new.rst

@@ -24,7 +24,7 @@ Version 0.12 (unreleased)
 
 The following authors contributed for the first time. Thank you so much! 🤩
 
-* ...
+* `Moritz Gerster`_
 
 The following authors had contributed before. Thank you for sticking around! 🤘
 
@@ -44,6 +44,7 @@ Detailed list of changes
 - Add :meth:`mne_bids.BIDSPath.find_matching_sidecar` to find the sidecar file associated with a given file path by `Eric Larson`_ (:gh:`1093`)
 - When writing data via :func:`~mne_bids.write_raw_bids`, it is now possible to specify a custom mapping of :class:`mne.Annotations` descriptions to event codes via the ``event_id`` parameter. Previously, passing this parameter would always require to also pass ``events``, and using a custom event code mapping for annotations was impossible, by `Richard Höchenberger`_ (:gh:`1084`)
 - Improve error message when :obj:`~mne_bids.BIDSPath.fpath` cannot be uniquely resolved by `Eric Larson`_ (:gh:`1097`)
+- Add :func:`mne_bids.find_matching_paths` to retrieve all `BIDSPaths` matching user-specified entities. The functionality partially overlaps with what's offered through :meth:`mne_bids.BIDSPath.match()`, but is more versatile, by `Moritz Gerster`_ (:gh:`1103`)
 
 🧐 API and behavior changes
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^

examples/read_bids_datasets.py

@@ -39,7 +39,8 @@
 import openneuro
 
 from mne.datasets import sample
-from mne_bids import BIDSPath, read_raw_bids, print_dir_tree, make_report
+from mne_bids import (BIDSPath, read_raw_bids, print_dir_tree, make_report,
+                      find_matching_paths, get_entity_vals)
 
 # %%
 # Download a subject's data from an OpenNeuro BIDS dataset
@@ -92,17 +93,24 @@
 # For now, we're interested only in the EEG data in the BIDS root directory
 # of the Parkinson's disease patient dataset. There were two sessions, one
 # where the patients took their regular anti-Parkinsonian medications and
-# one where they abstained for more than twelve hours. Let's start with the
-# off-medication session.
+# one where they abstained for more than twelve hours. For now, we are
+# not interested in the on-medication session.
 
+sessions = get_entity_vals(bids_root, 'session', ignore_sessions='on')
 datatype = 'eeg'
-session = 'off'
-bids_path = BIDSPath(root=bids_root, session=session, datatype=datatype)
+extensions = [".bdf", ".tsv"]  # ignore .json files
+bids_paths = find_matching_paths(bids_root, datatypes=datatype,
+                                 sessions=sessions, extensions=extensions)
 
 # %%
 # We can now retrieve a list of all MEG-related files in the dataset:
+print(bids_paths)
 
-print(bids_path.match())
+# %%
+# Note that this is the same as running:
+session = 'off'
+bids_path = BIDSPath(root=bids_root, session=session, datatype=datatype)
+print(bids_path.match(ignore_json=True))
 
 # %%
 # The returned list contains ``BIDSpaths`` of 3 files:
@@ -127,8 +135,7 @@
 task = 'rest'
 suffix = 'eeg'
 
-bids_path = BIDSPath(subject=subject, session=session, task=task,
-                     suffix=suffix, datatype=datatype, root=bids_root)
+bids_path = bids_path.update(subject=subject, task=task, suffix=suffix)
 
 # %%
 # Now let's print the contents of ``bids_path``.

examples/update_bids_datasets.py

@@ -21,7 +21,7 @@
 # We are importing everything we need for this example:
 from mne.datasets import somato
 
-from mne_bids import (BIDSPath, read_raw_bids,
+from mne_bids import (read_raw_bids, find_matching_paths,
                       print_dir_tree, make_report, update_sidecar_json)
 
 # %%
@@ -60,20 +60,15 @@
 # ``BIDSPath`` object. We then pass in a dictionary (or JSON file) to update
 # all matching metadata fields within the BIDS dataset.
 
-# create a BIDSPath object
+# Search for all matching BIDSPaths in the root directory
 bids_root = somato.data_path()
-datatype = 'meg'
-subject = '01'
-task = 'somato'
 suffix = 'meg'
+extension = '.fif'
 
-bids_path = BIDSPath(subject=subject, task=task, suffix=suffix,
-                     datatype=datatype, root=bids_root)
-sidecar_path = bids_path.copy().update(extension='.json')
-
+bids_paths = find_matching_paths(bids_root, suffixes=suffix,
+                                 extensions=extension)
 # We can now retrieve a list of all MEG-related files in the dataset:
-# we will specifically now update the sidecar json file.
-print(bids_path.match())
+print(bids_paths)
 
 # Define a sidecar update as a dictionary
 entries = {
@@ -90,6 +85,8 @@
 # ``entries``.
 #
 # Now update all sidecar fields according to our updating dictionary
+bids_path = bids_paths[0]
+sidecar_path = bids_path.copy().update(extension='.json')
 update_sidecar_json(bids_path=sidecar_path, entries=entries)
 
 # %%

mne_bids/__init__.py

@@ -5,7 +5,8 @@
 from mne_bids.report import make_report
 from mne_bids.path import (BIDSPath, get_datatypes, get_entity_vals,
                            print_dir_tree, get_entities_from_fname,
-                           search_folder_for_text, get_bids_path_from_fname)
+                           search_folder_for_text, get_bids_path_from_fname,
+                           find_matching_paths)
 from mne_bids.read import get_head_mri_trans, read_raw_bids
 from mne_bids.utils import get_anonymization_daysback
 from mne_bids.write import (make_dataset_description, write_anat,