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]#

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

>>> import json
>>> data = {"PipelineDescription": {"Version": "1.1.1rc5"}}
>>> desc_file = Path(tmpdir) / 'sample_dataset_description.json'
>>> _ = desc_file.write_text(json.dumps(data))

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, task=None, echo=None, bids_validate=True, bids_filters=None)[source]#: Uses pybids to retrieve the input data for a given participant >>> bids_root, _ = collect_data(str(datadir / ‘ds054’), ‘100185’, … bids_validate=False) >>> bids_root[‘fmap’] # doctest: +ELLIPSIS [’…/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’] # doctest: +ELLIPSIS [’…/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’] # doctest: +ELLIPSIS [’…/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’] # doctest: +ELLIPSIS [’…/ds054/sub-100185/anat/sub-100185_T1w.nii.gz’] >>> bids_root[‘t2w’] # doctest: +ELLIPSIS [] >>> bids_root, _ = collect_data(str(datadir / ‘ds051’), ‘01’, … bids_validate=False, bids_filters={‘t1w’:{‘run’: 1}}) >>> bids_root[‘t1w’] # doctest: +ELLIPSIS [’…/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: >>> 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) # doctest: +IGNORE_EXCEPTION_DETAIL 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

>>> 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]#

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

>>> 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.

Example

>>> 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'