Merge pull request #678 from mgxd/enh/collect-data-session

ENH: Add optional session filter when collecting data

Author: effigies

niworkflows/utils/bids.py

@@ -26,6 +26,7 @@
 import re
 import warnings
 from bids import BIDSLayout
+from bids.layout import Query
 from packaging.version import Version
 
 
@@ -149,6 +150,7 @@ def collect_participants(
 def collect_data(
     bids_dir,
     participant_label,
+    session_id=Query.OPTIONAL,
     task=None,
     echo=None,
     bids_validate=True,
@@ -161,6 +163,23 @@ def collect_data(
 
         >>> data_dir_canary()
 
+    Parameters
+    ----------
+    bids_dir : :obj:`str` or :obj:`bids.layout.BIDSLayout`
+        The BIDS directory
+    participant_label : :obj:`str`
+        The participant identifier
+    session_id : :obj:`str`, None, or :obj:`bids.layout.Query`
+        The session identifier. By default, all sessions will be used.
+    task : :obj:`str` or None
+        The task identifier (for BOLD queries)
+    echo : :obj:`int` or None
+        The echo identifier (for BOLD queries)
+    bids_validate : :obj:`bool`
+        Whether the `bids_dir` is validated upon initialization
+    bids_filters: :obj:`dict` or None
+        Custom filters to alter default queries
+
     Examples
     --------
     >>> bids_root, _ = collect_data(str(datadir / 'ds054'), '100185',
@@ -222,6 +241,7 @@ def collect_data(
             layout.get(
                 return_type="file",
                 subject=participant_label,
+                session=session_id,
                 extension=[".nii", ".nii.gz"],
                 **query,
             )