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.
- exception xcp_d.utils.bids.BIDSWarning[source]
Bases:
RuntimeWarning
A generic warning related to BIDS datasets.
- xcp_d.utils.bids.check_pipeline_version(pipeline_name, cvers, data_desc)[source]
Search for existing BIDS pipeline output and compares against current pipeline version.
- Parameters:
cvers (
str
) – Current pipeline versiondata_desc (
str
oros.PathLike
) – Path to pipeline output’sdataset_description.json
- Returns:
message – A warning string if there is a difference between versions, otherwise
None
.- Return type:
- xcp_d.utils.bids.collect_data(layout, input_type, participant_label, bids_filters, cifti)[source]
Collect data from a BIDS dataset.
- Parameters:
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
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_mesh_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 fsnative-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.standard_space_mesh (
bool
) – True if standard-space (fsLR) surface mesh files were found. False if they were not.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)[source]
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.
- Returns:
morph_file_types (
list
ofstr
) – 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)[source]
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, cifti, target_space)[source]
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.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).target_space – Used to find NIfTIs in the appropriate space if
cifti
isTrue
.
- Returns:
run_data – A dictionary of file types (e.g., “confounds”) and associated filenames.
- Return type:
- xcp_d.utils.bids.get_entity(filename, entity)[source]
Extract a given entity from a BIDS filename via string manipulation.
- xcp_d.utils.bids.get_freesurfer_dir(fmri_dir)[source]
Find FreeSurfer or MCRIBS derivatives associated with preprocessing pipeline.
NOTE: This is a Node function.
- Parameters:
fmri_dir (
str
) – Path to preprocessed derivatives.- Returns:
seg_path (
str
) – Path to FreeSurfer or MCRIBS derivatives.seg
- Raises:
ValueError – If more than one potential FreeSurfer derivative folder is found.
NotADirectoryError – If no FreeSurfer derivatives are 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 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.
- xcp_d.utils.bids.write_atlas_dataset_description(atlas_dir)[source]
Write dataset_description.json file for Atlas derivatives.
- Parameters:
atlas_dir (
str
) – Path to the output XCP-D Atlases dataset.