aslprep.niworkflows.utils.bids module

Helpers for handling BIDS-like neuroimaging structures

exception BIDSError(message, bids_root)[source]: Bases: ValueError

exception BIDSWarning[source]: Bases: RuntimeWarning

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’) # doctest: +ELLIPSIS ‘Previous output generated …’

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

collect_data(bids_dir, participant_label, task=None, echo=None, bids_validate=False, 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’]

collect_participants(bids_dir, participant_label=None, strict=False, bids_validate=False)[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: …

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’

>>>

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

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'