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)

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

Bases: RuntimeWarning

A generic warning related to BIDS datasets.

xcp_d.utils.bids.check_pipeline_version(pipeline_name, cvers, data_desc)

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

Returns:

message – A warning string if there is a difference between versions, otherwise None.

Return type:

str or None

xcp_d.utils.bids.collect_confounds(bold_file: str, preproc_dataset: BIDSLayout, derivatives_datasets: dict[str, Path | BIDSLayout] | None, confound_spec: dict | None)

Gather confounds files from derivatives datasets and compose a cache.

xcp_d.utils.bids.collect_data(layout, input_type, participant_label, bids_filters, file_format, anat_session, func_sessions)

Collect data from a BIDS dataset.

Parameters:

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

• input_type ({“fmriprep”, “dcan”, “hcp”, “nibabies”, “ukb”}) – 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

• bids_filters

• file_format

• anat_session

• func_sessions

Returns:

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

• subj_data (dict)

xcp_d.utils.bids.collect_mesh_data(layout, participant_label, bids_filters, anat_session)

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 fsnative-space files.

Parameters:

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

• participant_label (str) – Subject ID.

• anat_session (str or Query.NONE)

Returns:

• mesh_available (bool) – True if surface mesh files (pial and smoothwm) 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.

• software ({“MCRIBS”, “FreeSurfer”}) – The software used to generate the surfaces.

• mesh_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.collect_morphometry_data(layout, participant_label, bids_filters, anat_session)

Collect morphometry surface files from preprocessed derivatives.

This function will look for fsLR-space, 91k-resolution morphometry CIFTI files.

Parameters:

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

• participant_label (str) – Subject ID.

• anat_session (str or Query.NONE)

Returns:

• morph_file_types (list of str) – List of surface morphometry file types (e.g., cortical thickness) already in fsLR space. These files will be (1) parcellated and (2) passed along, without modification, to the XCP-D derivatives.

• morphometry_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.collect_participants(layout, participant_label=None, strict=False)

Collect a list of participants from a BIDS dataset.

Parameters:

• bids_dir (pybids.layout.BIDSLayout)

• participant_label (None, str, or list, 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, bold_file, file_format, target_space)

Collect data associated with a given BOLD file.

Parameters:

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

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

• file_format – Whether to collect files associated with a CIFTI image (True) or a NIFTI (False).

• target_space – Used to find NIfTIs in the appropriate space if cifti is True.

Returns:

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

Return type:

dict

xcp_d.utils.bids.get_entity(filename, entity)

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_preproc_pipeline_info(input_type, fmri_dir)

Get preprocessing pipeline information from the dataset_description.json file.

Parameters:

• input_type (str) – Type of input dataset.

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

Returns:

info_dict – Dictionary containing the name, version, and references of the preprocessing pipeline.

Return type:

dict

xcp_d.utils.bids.group_across_runs(in_files)

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

We only ignore direction for the sake of HCP. This may lead to small problems for non-HCP datasets that differentiate scans based on both run and direction.

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_atlas_dataset_description(atlas_dir)

Write dataset_description.json file for Atlas derivatives.

Parameters:

atlas_dir (str) – Path to the output XCP-D Atlases dataset.

xcp_d.utils.bids.write_derivative_description(fmri_dir, output_dir, atlases=None, dataset_links=None)

Write dataset_description.json file for derivatives.

Parameters:

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

• output_dir (str) – Path to the output XCP-D dataset.

• atlases (list of str, optional) – Names of requested XCP-D atlases.

• dataset_links (dict, optional) – Dictionary of dataset links to include in the dataset description.