xcp_d.utils.bids module

Utilities for fmriprep bids derivatives and layout.

Most of the code is copied from niworkflows. A PR will be submitted to niworkflows at some point.

exception xcp_d.utils.bids.BIDSError(message, bids_root)[source]

Bases: ValueError

A generic error related to BIDS datasets.

Parameters:

  • message (str) – The error message.

  • bids_root (str) – The path to the BIDS dataset.

exception xcp_d.utils.bids.BIDSWarning[source]

Bases: RuntimeWarning

A generic warning related to BIDS datasets.

xcp_d.utils.bids.collect_data(bids_dir, input_type, participant_label, task=None, bids_validate=False, bids_filters=None, cifti=False, layout=None)[source]

Collect data from a BIDS dataset.

Parameters:

  • bids_dir

  • input_type ({“fmriprep”, “dcan”, “hcp”, “nibabies”}) – The format of the incoming preprocessed BIDS derivatives. DCAN- and HCP-format derivatives will automatically be converted to a more BIDS-compliant format. fMRIPrep and Nibabies derivatives are assumed to be roughly equivalent in terms of file organization and naming.

  • participant_label

  • task

  • bids_validate

  • bids_filters

  • cifti (bool) – Post-process surface data (CIFTIs) instead of volumetric data (NIFTIs). This parameter is overridden when DCAN- or HCP-format data are provided. Default is False.

  • layout (bids.layout.BIDSLayout) – BIDSLayout indexing the ingested (e.g., fMRIPrep-format) derivatives.

Returns:

  • layout (bids.layout.BIDSLayout) – BIDSLayout indexing the ingested (e.g., fMRIPrep-format) derivatives.

  • subj_data (dict)

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

Collect a list of participants from a BIDS dataset.

Parameters:

  • bids_dir (str or pybids.layout.BIDSLayout)

  • participant_label (None or str, optional)

  • strict (bool, optional)

  • bids_validate (bool, optional)

Return type:

found_label

Examples

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’] …

xcp_d.utils.bids.collect_run_data(layout, input_type, bold_file, cifti, primary_anat)[source]

Collect data associated with a given BOLD file.

Parameters:

  • layout (bids.layout.BIDSLayout) – BIDSLayout indexing the ingested (e.g., fMRIPrep-format) derivatives.

  • input_type ({“fmriprep”, “dcan”, “hcp”, “nibabies”}) – The format of the incoming preprocessed BIDS derivatives. DCAN- and HCP-format derivatives will automatically be converted to a more BIDS-compliant format. fMRIPrep and Nibabies derivatives are assumed to be roughly equivalent in terms of file organization and naming.

  • bold_file (str) – Path to the BOLD file.

  • cifti (bool) – Post-process surface data (CIFTIs) instead of volumetric data (NIFTIs). This parameter is overridden when DCAN- or HCP-format data are provided. Default is False. Whether to collect files associated with a CIFTI image (True) or a NIFTI (False).

  • primary_anat ({“T1w”, “T2w”}) – The anatomical modality to use for the anat-to-native transform.

Returns:

run_data – A dictionary of file types (e.g., “confounds”) and associated filenames.

Return type:

dict

xcp_d.utils.bids.collect_surface_data(layout, participant_label)[source]

Collect surface files from preprocessed derivatives.

This function will try to collect fsLR-space, 32k-resolution surface files first. If these standard-space surface files aren’t available, it will default to native T1w-space files.

Parameters:

  • layout (bids.layout.BIDSLayout) – BIDSLayout indexing the ingested (e.g., fMRIPrep-format) derivatives.

  • participant_label (str) – Subject ID.

Returns:

  • mesh_available (bool) – True if surface mesh files (pial and smoothwm) were found. False if they were not.

  • shape_available (bool) – True if surface shape files (curv, sulc, and thickness) were found. False if they were not.

  • standard_space_mesh (bool) – True if standard-space (fsLR) surface mesh files were found. False if they were not.

  • surface_files (dict) – Dictionary of surface file identifiers and their paths. If the surface files weren’t found, then the paths will be Nones.

xcp_d.utils.bids.get_entity(filename, entity)[source]

Extract a given entity from a BIDS filename via string manipulation.

Parameters:

  • filename (str) – Path to the BIDS file.

  • entity (str) – The entity to extract from the filename.

Returns:

entity_value – The BOLD file’s entity value associated with the requested entity.

Return type:

str or None

xcp_d.utils.bids.get_freesurfer_dir(fmri_dir)[source]

Find FreeSurfer derivatives associated with preprocessing pipeline.

NOTE: This is a Node function.

Parameters:

fmri_dir (str) – Path to preprocessed derivatives.

Returns:

freesurfer_path – Path to FreeSurfer derivatives.

Return type:

str

Raises:

  • ValueError – If more than one potential FreeSurfer derivative folder is found.

  • NotADirectoryError – If no FreeSurfer derivatives are found.

xcp_d.utils.bids.get_freesurfer_sphere(freesurfer_path, subject_id, hemisphere)[source]

Find FreeSurfer sphere file.

NOTE: This is a Node function.

Parameters:

  • freesurfer_path (str) – Path to the FreeSurfer derivatives.

  • subject_id (str) – Subject ID. This may or may not be prefixed with “sub-“.

  • hemisphere ({“L”, “R”}) – The hemisphere to grab.

Returns:

sphere_raw – Sphere file for the requested subject and hemisphere.

Return type:

str

Raises:

FileNotFoundError – If the sphere file cannot be found.

xcp_d.utils.bids.get_preproc_pipeline_info(input_type, fmri_dir)[source]

Get preprocessing pipeline information from the dataset_description.json file.

xcp_d.utils.bids.group_across_runs(in_files)[source]

Group preprocessed BOLD files by unique sets of entities, ignoring run.

Parameters:

in_files (list of str) – A list of preprocessed BOLD files to group.

Returns:

out_files – The grouped BOLD files. Each sublist corresponds to a single set of runs.

Return type:

list of list of str

xcp_d.utils.bids.write_dataset_description(fmri_dir, xcpd_dir)[source]

Write dataset_description.json file for derivatives.

Parameters:

  • fmri_dir (str) – Path to the BIDS derivative dataset being ingested.

  • xcpd_dir (str) – Path to the output xcp-d dataset.