niworkflows.utils.bids module¶

Helpers for handling BIDS-like neuroimaging structures.

exception niworkflows.utils.bids.BIDSError(message, bids_root)[source]¶: Bases: ValueError

exception niworkflows.utils.bids.BIDSWarning[source]¶: Bases: RuntimeWarning

niworkflows.utils.bids.check_pipeline_version(cvers, data_desc)[source]¶

Search for existing BIDS pipeline output and compares against current pipeline version.

Parameters:

cvers (str) – Current pipeline version
data_desc (str or os.PathLike) – Path to pipeline output’s dataset_description.json

Examples

>>> check_pipeline_version('1.1.1rc5', 'sample_dataset_description.json') is None
True
>>> check_pipeline_version('1.1.1rc5+129.gbe0e5158', 'sample_dataset_description.json')
>>> check_pipeline_version('1.2', 'sample_dataset_description.json')  
'Previous output generated ...'

Returns:: message – A warning string if there is a difference between versions, otherwise None.
Return type:: str or None

niworkflows.utils.bids.collect_data(bids_dir, participant_label, session_id=None, task=None, echo=None, group_echos=True, bids_validate=True, bids_filters=None, queries=None)[source]¶

Uses pybids to retrieve the input data for a given participant

Parameters:

bids_dir (str or bids.layout.BIDSLayout) – The BIDS directory
participant_label (str) – The participant identifier
session_id (str, None, or bids.layout.Query) – The session identifier. By default, all sessions will be used.
task (str or None) – The task identifier (for BOLD queries)
echo (int or None) – The echo identifier (for BOLD queries)
bids_validate (bool) – Whether the bids_dir is validated upon initialization
bids_filters (dict or None) – Custom filters to alter default queries

Examples

>>> bids_root, _ = collect_data(str(datadir / 'ds054'), '100185',
...                             bids_validate=False)
>>> bids_root['fmap']  
['.../ds054/sub-100185/fmap/sub-100185_magnitude1.nii.gz', '.../ds054/sub-100185/fmap/sub-100185_magnitude2.nii.gz', '.../ds054/sub-100185/fmap/sub-100185_phasediff.nii.gz']
>>> bids_root['bold']  
['.../ds054/sub-100185/func/sub-100185_task-machinegame_run-01_bold.nii.gz', '.../ds054/sub-100185/func/sub-100185_task-machinegame_run-02_bold.nii.gz', '.../ds054/sub-100185/func/sub-100185_task-machinegame_run-03_bold.nii.gz', '.../ds054/sub-100185/func/sub-100185_task-machinegame_run-04_bold.nii.gz', '.../ds054/sub-100185/func/sub-100185_task-machinegame_run-05_bold.nii.gz', '.../ds054/sub-100185/func/sub-100185_task-machinegame_run-06_bold.nii.gz']
>>> bids_root['sbref']  
['.../ds054/sub-100185/func/sub-100185_task-machinegame_run-01_sbref.nii.gz', '.../ds054/sub-100185/func/sub-100185_task-machinegame_run-02_sbref.nii.gz', '.../ds054/sub-100185/func/sub-100185_task-machinegame_run-03_sbref.nii.gz', '.../ds054/sub-100185/func/sub-100185_task-machinegame_run-04_sbref.nii.gz', '.../ds054/sub-100185/func/sub-100185_task-machinegame_run-05_sbref.nii.gz', '.../ds054/sub-100185/func/sub-100185_task-machinegame_run-06_sbref.nii.gz']
>>> bids_root['t1w']  
['.../ds054/sub-100185/anat/sub-100185_T1w.nii.gz']
>>> bids_root['t2w']  
[]
>>> bids_root, _ = collect_data(str(datadir / 'ds051'), '01',
...                             bids_validate=False,
...                             bids_filters={'t1w':{'run': 1, 'session': None}})
>>> bids_root['t1w']  
['.../ds051/sub-01/anat/sub-01_run-01_T1w.nii.gz']

niworkflows.utils.bids.collect_participants(bids_dir, participant_label=None, strict=False, bids_validate=True)[source]¶

List the participants under the BIDS root and checks that participants designated with the participant_label argument exist in that folder. Returns the list of participants to be finally processed. Requesting all subjects in a BIDS directory root:

Examples

>>> collect_participants(str(datadir / 'ds114'), bids_validate=False)
['01', '02', '03', '04', '05', '06', '07', '08', '09', '10']

Requesting two subjects, given their IDs:

>>> collect_participants(str(datadir / 'ds114'), participant_label=['02', '04'],
...                      bids_validate=False)
['02', '04']

Requesting two subjects, given their IDs (works with ‘sub-’ prefixes):

>>> collect_participants(str(datadir / 'ds114'), participant_label=['sub-02', 'sub-04'],
...                      bids_validate=False)
['02', '04']

Requesting two subjects, but one does not exist:

>>> collect_participants(str(datadir / 'ds114'), participant_label=['02', '14'],
...                      bids_validate=False)
['02']
>>> collect_participants(
...     str(datadir / 'ds114'), participant_label=['02', '14'],
...     strict=True, bids_validate=False)  
Traceback (most recent call last):
BIDSError:
...

niworkflows.utils.bids.get_metadata_for_nifti(in_file, bids_dir=None, validate=True)[source]¶

Fetch metadata for a given NIfTI file.

Examples

>>> metadata = get_metadata_for_nifti(
...     datadir / 'ds054' / 'sub-100185' / 'fmap' / 'sub-100185_phasediff.nii.gz',
...     validate=False)
>>> metadata['Manufacturer']
'SIEMENS'

niworkflows.utils.bids.group_multiecho(bold_sess)[source]¶

Multiplex multi-echo EPIs into arrays.

Dual-echo is a special case of multi-echo, which is treated as single-echo data.

Examples

>>> bold_sess = ["sub-01_task-rest_echo-1_run-01_bold.nii.gz",
...              "sub-01_task-rest_echo-2_run-01_bold.nii.gz",
...              "sub-01_task-rest_echo-1_run-02_bold.nii.gz",
...              "sub-01_task-rest_echo-2_run-02_bold.nii.gz",
...              "sub-01_task-rest_echo-3_run-02_bold.nii.gz",
...              "sub-01_task-rest_run-03_bold.nii.gz"]
>>> group_multiecho(bold_sess)  
['sub-01_task-rest_echo-1_run-01_bold.nii.gz',
 'sub-01_task-rest_echo-2_run-01_bold.nii.gz',
['sub-01_task-rest_echo-1_run-02_bold.nii.gz',
 'sub-01_task-rest_echo-2_run-02_bold.nii.gz',
 'sub-01_task-rest_echo-3_run-02_bold.nii.gz'],
 'sub-01_task-rest_run-03_bold.nii.gz']

>>> bold_sess.insert(2, "sub-01_task-rest_echo-3_run-01_bold.nii.gz")
>>> group_multiecho(bold_sess)  
[['sub-01_task-rest_echo-1_run-01_bold.nii.gz',
  'sub-01_task-rest_echo-2_run-01_bold.nii.gz',
  'sub-01_task-rest_echo-3_run-01_bold.nii.gz'],
 ['sub-01_task-rest_echo-1_run-02_bold.nii.gz',
  'sub-01_task-rest_echo-2_run-02_bold.nii.gz',
  'sub-01_task-rest_echo-3_run-02_bold.nii.gz'],
  'sub-01_task-rest_run-03_bold.nii.gz']

>>> bold_sess += ["sub-01_task-beh_echo-1_run-01_bold.nii.gz",
...               "sub-01_task-beh_echo-2_run-01_bold.nii.gz",
...               "sub-01_task-beh_echo-1_run-02_bold.nii.gz",
...               "sub-01_task-beh_echo-2_run-02_bold.nii.gz",
...               "sub-01_task-beh_echo-3_run-02_bold.nii.gz",
...               "sub-01_task-beh_run-03_bold.nii.gz"]
>>> group_multiecho(bold_sess)  
[['sub-01_task-rest_echo-1_run-01_bold.nii.gz',
  'sub-01_task-rest_echo-2_run-01_bold.nii.gz',
  'sub-01_task-rest_echo-3_run-01_bold.nii.gz'],
 ['sub-01_task-rest_echo-1_run-02_bold.nii.gz',
  'sub-01_task-rest_echo-2_run-02_bold.nii.gz',
  'sub-01_task-rest_echo-3_run-02_bold.nii.gz'],
  'sub-01_task-rest_run-03_bold.nii.gz',
  'sub-01_task-beh_echo-1_run-01_bold.nii.gz',
  'sub-01_task-beh_echo-2_run-01_bold.nii.gz',
 ['sub-01_task-beh_echo-1_run-02_bold.nii.gz',
  'sub-01_task-beh_echo-2_run-02_bold.nii.gz',
  'sub-01_task-beh_echo-3_run-02_bold.nii.gz'],
  'sub-01_task-beh_run-03_bold.nii.gz']

Some tests from https://neurostars.org/t/fmriprep-from-singularity-unboundlocalerror/3299/7

>>> bold_sess = ['sub-01_task-AudLoc_echo-1_bold.nii',
...              'sub-01_task-AudLoc_echo-2_bold.nii',
...              'sub-01_task-FJT_echo-1_bold.nii',
...              'sub-01_task-FJT_echo-2_bold.nii',
...              'sub-01_task-LDT_echo-1_bold.nii',
...              'sub-01_task-LDT_echo-2_bold.nii',
...              'sub-01_task-MotLoc_echo-1_bold.nii',
...              'sub-01_task-MotLoc_echo-2_bold.nii']
>>> group_multiecho(bold_sess) == bold_sess
True

>>> bold_sess += ['sub-01_task-MotLoc_echo-3_bold.nii']
>>> groups = group_multiecho(bold_sess)
>>> len(groups[:-1])
6
>>> [isinstance(g, list) for g in groups]
[False, False, False, False, False, False, True]
>>> len(groups[-1])
3

niworkflows.utils.bids.relative_to_root(path)[source]¶

Calculate the BIDS root folder given one file path’s.

Examples

>>> str(relative_to_root(
...     "/sub-03/sourcedata/sub-01/anat/sub-01_T1.nii.gz"
... ))
'sub-01/anat/sub-01_T1.nii.gz'

>>> str(relative_to_root(
...     "/sub-03/anat/sourcedata/sub-01/ses-preop/anat/sub-01_ses-preop_T1.nii.gz"
... ))
'sub-01/ses-preop/anat/sub-01_ses-preop_T1.nii.gz'

>>> str(relative_to_root(
...     "sub-01/anat/sub-01_T1.nii.gz"
... ))
'sub-01/anat/sub-01_T1.nii.gz'

>>> str(relative_to_root("anat/sub-01_T1.nii.gz"))
'anat/sub-01_T1.nii.gz'