Expose ignore_json, add ignore_nosub to file match/search funcs (#1281)

* _return_root_paths now only looks in subfolders of root starting with 'sub-'

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* changed length of l. 2444

* Update mne_bids/path.py

Co-authored-by: Richard Höchenberger <[email protected]>

* make it a parameter and expose it

* add missing entries to mailmap, and sort

* add Kaare to authors

* add changelog entry

---------

Co-authored-by: kaare-mikkelsen <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: kaare-mikkelsen <[email protected]>
Co-authored-by: Richard Höchenberger <[email protected]>

.mailmap

@@ -8,26 +8,35 @@ Ariel Rokem <[email protected]>
 Chris Holdgraf <[email protected]>
 Chris Holdgraf <[email protected]> <[email protected]>
 Clemens Brunner <[email protected]>
+Dominik Welke <[email protected]>
+Dominik Welke <[email protected]> dominikwelke <[email protected]>
+Eduard Ort <[email protected]>
+Eduard Ort <[email protected]> <[email protected]>
+Evgenii Kalenkovich <[email protected]>
+Ezequiel Mikulan <[email protected]>
+Franziska von Albedyll <[email protected]>
+Franziska von Albedyll <[email protected]> <[email protected]>
+Fu-Te Wong <[email protected]>
+Julius Welzel <[email protected]>
+Kaare Mikkelsen <[email protected]>
+Kaare Mikkelsen <[email protected]> <[email protected]>
 Kambiz Tavabi <[email protected]>
+Laetitia Fesselier <[email protected]>
+Laetitia Fesselier <[email protected]> <[email protected]>
 Mainak Jas <[email protected]>
 Mainak Jas <[email protected]> <[email protected]>
 Marijn van Vliet <[email protected]>
+Mathieu Scheltienne <[email protected]>
+Mathieu Scheltienne <[email protected]> <[email protected]>
+Matt Sanderson <[email protected]>
 Maximilien Chaumon <[email protected]>
 Maximilien Chaumon <[email protected]> <[email protected]>
-Romain Quentin <rom.quentin@gmail.com>
+Pierre Guetschel <[email protected].com>
 Richard Höchenberger <[email protected]>
+Richard Koehler <[email protected]>
+Robert Luke <[email protected]>
+Romain Quentin <[email protected]>
 Sophie Herbst <[email protected]>
 Stefan Appelhoff <[email protected]>
 Teon Brooks <[email protected]>
-Dominik Welke <[email protected]>
-Dominik Welke <[email protected]> dominikwelke <[email protected]>
-Ezequiel Mikulan <[email protected]>
-Fu-Te Wong <[email protected]>
-Matt Sanderson <[email protected]>
-Robert Luke <[email protected]>
-Evgenii Kalenkovich <[email protected]>
-Eduard Ort <[email protected]>
-Eduard Ort <[email protected]> <[email protected]>
 Tom Donoghue <[email protected]>
-Franziska von Albedyll <[email protected]>
-Franziska von Albedyll <[email protected]> <[email protected]>

CITATION.cff

@@ -179,6 +179,10 @@ authors:
       family-names: Welzel
       affiliation: 'Department of Neurology, Kiel University, Germany'
       orcid: 'https://orcid.org/0000-0003-4782-5360'
+    - given-names: Kaare
+      family-names: Mikkelsen
+      affiliation: 'Department of Electrical and Computer Engineering, Aarhus University, Denmark'
+      orcid: 'https://orcid.org/0000-0002-7360-8629'
     - given-names: Amaia
       family-names: Benitez
       affiliation: 'Magnetoencephalography Core, National Institutes of Health, Bethesda, Maryland, USA'

doc/authors.rst

@@ -46,4 +46,5 @@
 .. _Pierre Guetschel: https://github.com/PierreGtch
 .. _Mara Wolter: https://github.com/marakw
 .. _Julius Welzel: https://github.com/JuliusWelzel
+.. _Kaare Mikkelsen: https://github.com/kaare-mikkelsen
 .. _Amaia Benitez: https://github.com/AmaiaBA

doc/whats_new.rst

@@ -17,6 +17,7 @@ Version 0.16 (unreleased)
 
 The following authors contributed for the first time. Thank you so much! 🤩
 
+* `Kaare Mikkelsen`_
 * `Amaia Benitez`_
 
 The following authors had contributed before. Thank you for sticking around! 🤘
@@ -31,7 +32,7 @@ Detailed list of changes
 🚀 Enhancements
 ^^^^^^^^^^^^^^^
 
-- nothing yet
+- :meth:`mne_bids.BIDSPath.match()` and :func:`mne_bids.find_matching_paths` now have additional parameters ``ignore_json`` and ``ignore_nosub``, to give users more control over which type of files are matched, by `Kaare Mikkelsen`_ (:gh:`1281`)
 
 🧐 API and behavior changes
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^

mne_bids/path.py

@@ -695,7 +695,9 @@ def rm(self, *, safe_remove=True, verbose=None):
             raise RuntimeError("The root must not be None to remove files.")
 
         # Planning:
-        paths_matched = self.match(ignore_json=False, check=self.check)
+        paths_matched = self.match(
+            ignore_json=False, ignore_nosub=False, check=self.check
+        )
         subjects = set()
         paths_to_delete = list()
         paths_to_update = {}
@@ -1005,7 +1007,7 @@ def update(self, *, check=None, **kwargs):
             raise e
         return self
 
-    def match(self, ignore_json=True, check=False):
+    def match(self, *, ignore_json=True, ignore_nosub=False, check=False):
         """Get a list of all matching paths in the root directory.
 
         Performs a recursive search, starting in ``.root`` (if set), based on
@@ -1015,6 +1017,9 @@ def match(self, ignore_json=True, check=False):
         ----------
         ignore_json : bool
             If ``True``, ignores json files. Defaults to ``True``.
+        ignore_nosub : bool
+            If ``True``, ignores all files that are not of the form ``root/sub-*``.
+            Defaults to ``False``.
         check : bool
             If ``True``, only returns paths that conform to BIDS. If ``False``
             (default), the ``.check`` attribute of the returned
@@ -1035,7 +1040,10 @@ def match(self, ignore_json=True, check=False):
             )
 
         paths = _return_root_paths(
-            self.root, datatype=self.datatype, ignore_json=ignore_json
+            self.root,
+            datatype=self.datatype,
+            ignore_json=ignore_json,
+            ignore_nosub=ignore_nosub,
         )
 
         fnames = _filter_fnames(
@@ -2325,6 +2333,9 @@ def find_matching_paths(
     extensions=None,
     datatypes=None,
     check=False,
+    *,
+    ignore_json=False,
+    ignore_nosub=False,
 ):
     """Get list of all matching paths for all matching entity values.
 
@@ -2384,14 +2395,21 @@ def find_matching_paths(
         (default), the ``.check`` attribute of the returned
         :class:`mne_bids.BIDSPath` object will be set to ``True`` for paths that
         do conform to BIDS, and to ``False`` for those that don't.
+    ignore_json : bool
+        If ``True``, ignores json files. Defaults to ``False``.
+    ignore_nosub : bool
+        If ``True``, ignores all files that are not of the form ``root/sub-*``.
+        Defaults to ``False``.
 
     Returns
     -------
     bids_paths : list of mne_bids.BIDSPath
         The matching paths.
 
     """
-    fpaths = _return_root_paths(root, datatype=datatypes, ignore_json=False)
+    fpaths = _return_root_paths(
+        root, datatype=datatypes, ignore_json=ignore_json, ignore_nosub=ignore_nosub
+    )
 
     fpaths_filtered = _filter_fnames(
         fpaths,
@@ -2413,16 +2431,29 @@ def find_matching_paths(
     return bids_paths
 
 
-def _return_root_paths(root, datatype=None, ignore_json=True):
-    """Return all paths in root.
+def _return_root_paths(root, datatype=None, ignore_json=True, ignore_nosub=False):
+    """Return all file paths in root.
 
     Can be filtered by datatype (which is present in the path but not in
     the BIDSPath basename). Can also be list of datatypes.
+
+    Parameters
+    ----------
     root : pathlib.Path | str
         The root of the BIDS path.
     datatype : str | array-like of str | None
         The BIDS data type, e.g., ``'anat'``, ``'func'``, ``'eeg'``, ``'meg'``,
         ``'ieeg'``.
+    ignore_json : bool
+        If ``True`` (default), do not return files ending with ``.json``.
+    ignore_nosub : bool
+        If ``True``, return only files of the form ``root/sub-*``. Defaults to
+        ``False``.
+
+    Returns
+    -------
+    paths : list of pathlib.Path
+        All paths in `root`, filtered according to the function parameters.
     """
     root = Path(root)  # if root is str
 
@@ -2433,13 +2464,19 @@ def _return_root_paths(root, datatype=None, ignore_json=True):
         search_str = "*.*"
 
     paths = root.rglob(search_str)
-    # Only keep files (not directories), and omit the JSON sidecars
-    # if ignore_json is True.
+    # Only keep files (not directories), ...
+    # and omit the JSON sidecars if `ignore_json` is True.
     if ignore_json:
         paths = [p for p in paths if p.is_file() and p.suffix != ".json"]
     else:
         paths = [p for p in paths if p.is_file()]
 
+    # only keep files which are of the form root/sub-*,
+    # such that we only look in 'sub'-folders:
+    if ignore_nosub:
+        root_sub = str(root / "sub-")
+        paths = [p for p in paths if str(p).startswith(root_sub)]
+
     return paths