xcp_d.workflows.base module
The primary workflows for xcp_d.
- xcp_d.workflows.base.init_subject_wf(fmri_dir, subject_id, input_type, process_surfaces, combineruns, cifti, task_id, bids_filters, bandpass_filter, high_pass, low_pass, bpf_order, motion_filter_type, motion_filter_order, band_stop_min, band_stop_max, smoothing, head_radius, params, output_dir, custom_confounds_folder, dummy_scans, fd_thresh, despike, dcan_qc, min_coverage, min_time, omp_nthreads, layout, name)[source]
Organize the postprocessing pipeline for a single subject.
- Workflow Graph
- Parameters:
fmri_dir (
str
) – Path to the preprocessed derivatives dataset. For example, “/path/to/dset/derivatives/fmriprep/”.subject_id (
str
) – The participant ID. This SHOULD NOT include thesub-
prefix.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.
process_surfaces (
bool
, optional) – If True, a workflow will be run to warp native-space (fsnative) reconstructed cortical surfaces (surf.gii files) produced by Freesurfer into standard (fsLR) space. These surface files are primarily used for visual quality control. By default, this workflow is disabled.combineruns
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.task_id (
str
or None) – Task ID of BOLD series to be selected for postprocess , orNone
to postprocess allbids_filters (dict or None)
bandpass_filter (
bool
) – If True, a Butterworth bandpass filter will be applied to the fMRI data after interpolation, but before regression. If False, bandpass filtering will not be performed.high_pass (
float
) – Lower cut-off frequency for the Butterworth bandpass filter, in Hertz. The bandpass filter is applied to the fMRI data after post-processing and denoising. Bandpass filtering will only be performed ifbandpass_filter
is True. This internal parameter corresponds to the command-line parameter--lower-bpf
. If set to <= 0, high-pass filtering will be disabled.Default value is 0.01.
low_pass (
float
) – Upper cut-off frequency for the Butterworth bandpass filter, in Hertz. The bandpass filter is applied to the fMRI data after post-processing and denoising. Bandpass filtering will only be performed ifbandpass_filter
is True. This internal parameter corresponds to the command-line parameter--upper-bpf
. If set to <= 0, low-pass filtering will be disabled.Default value is 0.08.
bpf_order (
int
) – Number of filter coefficients for Butterworth bandpass filter. Bandpass filtering will only be performed ifbandpass_filter
is True. This parameter is used in conjunction withlower_bpf
/high_pass
andupper_bpf
/low_pass
.motion_filter_type ({None, “lp”, “notch”}) – Type of filter to use for removing respiratory artifact from motion regressors.
If None, no filter will be applied.
If the filter type is set to “notch”, frequencies between
band_stop_min
andband_stop_max
will be removed with a notch filter. In this case, bothband_stop_min
andband_stop_max
must be defined.If “lp”, frequencies above
band_stop_min
will be removed with a Butterworth filter. In this case, onlyband_stop_min
must be defined.motion_filter_order (
int
) – Number of filter coefficients for the motion parameter filter. Motion filtering is only performed ifmotion_filter_type
is not None. This parameter is used in conjunction withband_stop_max
andband_stop_min
.band_stop_min (
float
or None) – Lower frequency for the motion parameter filter, in breaths-per-minute (bpm). Motion filtering is only performed ifmotion_filter_type
is not None. If used with the “lp”motion_filter_type
, this parameter essentially corresponds to a low-pass filter (the maximum allowed frequency in the filtered data). This parameter is used in conjunction withmotion_filter_order
andband_stop_max
.Here is a list of recommended values, based on participant age:
Age Range (years)
Recommended Value
< 1
30
1 - 2
25
2 - 6
20
6 - 12
15
12 - 18
12
19 - 65
12
65 - 80
12
> 80
10
When
motion_filter_type
is set to “lp” (low-pass filter), another commonly-used value for this parameter is 6 BPM (equivalent to 0.1 Hertz), based on Gratton et al.[1].band_stop_max (
float
or None) – Upper frequency for the motion parameter filter, in breaths-per-minute (bpm). Motion filtering is only performed ifmotion_filter_type
is not None. This parameter is only used ifmotion-filter-type
is set to “notch”. This parameter is used in conjunction withmotion_filter_order
andband_stop_min
.Here is a list of recommended values, based on participant age:
Age Range (years)
Recommended Value
< 1
60
1 - 2
50
2 - 6
35
6 - 12
25
12 - 18
20
19 - 65
18
65 - 80
28
> 80
30
smoothing (
float
) – The full width at half maximum (FWHM), in millimeters, of the Gaussian smoothing kernel that will be applied to the post-processed and denoised data. ALFF and ReHo outputs will also be smoothing with this kernel.head_radius (
float
or “auto”) – Radius of the head, in millimeters, for framewise displacement calculation.xcp_d
’s default head radius is 50. The recommended value for infants is 35. A value of ‘auto’ is also supported, in which case the brain radius is estimated from the preprocessed brain mask.params ({“36P”, “24P”, “27P”, “acompcor”, “acompcor_gsr”, “aroma”, “aroma_gsr”, “custom”}, optional) – Shorthand for the parameter set to extract from the confounds TSV. Default is “36P”, most expansive option.
output_dir (
str
) – Path to the output directory forxcp_d
derivatives. This should not include thexcp_d
folder. For example, “/path/to/dset/derivatives/”.custom_confounds_folder (
str
or None) – Path to folder containing custom nuisance regressors. Must be a folder containing confounds files, in which case the file with the name matching the preprocessing confounds file will be selected.dummy_scans (
int
or “auto”) – Number of volumes to remove from the beginning of each run. If set to ‘auto’, xcp_d will extract non-steady-state volume indices from the preprocessing derivatives’ confounds file.fd_thresh (
float
) – Framewise displacement threshold for censoring, in millimeters. Any framewise displacement values higher than the threshold are flagged as “high motion”. If set to <=0, no censoring will be performed. Default is 0.2 mm.despike (
bool
) – If True, the BOLD data will be despiked before censoring/denoising/filtering/interpolation. If False, no despiking will be performed.For NIFTI data, despiking is performed with AFNI’s 3dDespike. For CIFTI data, the data will be converted to NIFTI format, 3dDespike will be run, and then the despiked data will be converted back to CIFTI format.
dcan_qc (
bool
) – This flag determines if DCAN-related QC steps will be taken. Enabling this flag will trigger the following steps:Brainsprite figures will be generated.
The executive summary will be generated.
DCAN QC files will be generated.
min_coverage (
float
) – Coverage threshold to apply to parcels in each atlas. Any parcels with lower coverage than the threshold will be replaced with NaNs. Must be a value between zero and one. Default is 0.5.min_time (
float
) – Post-scrubbing threshold to apply to individual runs in the dataset. This threshold determines the minimum amount of time, in seconds, needed to post-process a given run, once high-motion outlier volumes are removed. This will have no impact if scrubbing is disabled (i.e., if the FD threshold is zero or negative). This parameter can be disabled by providing a zero or a negative value. Default is 100.omp_nthreads (
int
) – Maximum number of threads an individual process may use.layout (
bids.layout.BIDSLayout
) – BIDSLayout indexing the ingested (e.g., fMRIPrep-format) derivatives.name (
str
, optional) – Name of the workflow. This is used for working directories and workflow graphs.
References
- xcp_d.workflows.base.init_xcpd_wf(fmri_dir, output_dir, work_dir, subject_list, analysis_level, task_id, bids_filters, bandpass_filter, high_pass, low_pass, bpf_order, fd_thresh, motion_filter_type, motion_filter_order, band_stop_min, band_stop_max, despike, head_radius, params, smoothing, custom_confounds_folder, dummy_scans, cifti, omp_nthreads, layout=None, process_surfaces=False, dcan_qc=False, input_type='fmriprep', min_coverage=0.5, min_time=100, combineruns=False, name='xcpd_wf')[source]
Build and organize execution of xcp_d pipeline.
It also connects the subworkflows under the xcp_d workflow.
- Workflow Graph
- Parameters:
layout (
bids.layout.BIDSLayout
) – BIDSLayout indexing the ingested (e.g., fMRIPrep-format) derivatives.bandpass_filter (
bool
) – If True, a Butterworth bandpass filter will be applied to the fMRI data after interpolation, but before regression. If False, bandpass filtering will not be performed.high_pass (
float
) – Lower cut-off frequency for the Butterworth bandpass filter, in Hertz. The bandpass filter is applied to the fMRI data after post-processing and denoising. Bandpass filtering will only be performed ifbandpass_filter
is True. This internal parameter corresponds to the command-line parameter--lower-bpf
. If set to <= 0, high-pass filtering will be disabled.Default value is 0.01.
low_pass (
float
) – Upper cut-off frequency for the Butterworth bandpass filter, in Hertz. The bandpass filter is applied to the fMRI data after post-processing and denoising. Bandpass filtering will only be performed ifbandpass_filter
is True. This internal parameter corresponds to the command-line parameter--upper-bpf
. If set to <= 0, low-pass filtering will be disabled.Default value is 0.08.
despike (
bool
) – If True, the BOLD data will be despiked before censoring/denoising/filtering/interpolation. If False, no despiking will be performed.For NIFTI data, despiking is performed with AFNI’s 3dDespike. For CIFTI data, the data will be converted to NIFTI format, 3dDespike will be run, and then the despiked data will be converted back to CIFTI format.
bpf_order (
int
) – Number of filter coefficients for Butterworth bandpass filter. Bandpass filtering will only be performed ifbandpass_filter
is True. This parameter is used in conjunction withlower_bpf
/high_pass
andupper_bpf
/low_pass
.analysis_level ({“participant”}) – The analysis level for
xcp_d
. Must be specified as “participant” since xcp_d performs analyses at the participant level.motion_filter_type ({None, “lp”, “notch”}) – Type of filter to use for removing respiratory artifact from motion regressors.
If None, no filter will be applied.
If the filter type is set to “notch”, frequencies between
band_stop_min
andband_stop_max
will be removed with a notch filter. In this case, bothband_stop_min
andband_stop_max
must be defined.If “lp”, frequencies above
band_stop_min
will be removed with a Butterworth filter. In this case, onlyband_stop_min
must be defined.motion_filter_order (
int
) – Number of filter coefficients for the motion parameter filter. Motion filtering is only performed ifmotion_filter_type
is not None. This parameter is used in conjunction withband_stop_max
andband_stop_min
.band_stop_min (
float
or None) – Lower frequency for the motion parameter filter, in breaths-per-minute (bpm). Motion filtering is only performed ifmotion_filter_type
is not None. If used with the “lp”motion_filter_type
, this parameter essentially corresponds to a low-pass filter (the maximum allowed frequency in the filtered data). This parameter is used in conjunction withmotion_filter_order
andband_stop_max
.Here is a list of recommended values, based on participant age:
Age Range (years)
Recommended Value
< 1
30
1 - 2
25
2 - 6
20
6 - 12
15
12 - 18
12
19 - 65
12
65 - 80
12
> 80
10
When
motion_filter_type
is set to “lp” (low-pass filter), another commonly-used value for this parameter is 6 BPM (equivalent to 0.1 Hertz), based on Gratton et al.[1].band_stop_max (
float
or None) – Upper frequency for the motion parameter filter, in breaths-per-minute (bpm). Motion filtering is only performed ifmotion_filter_type
is not None. This parameter is only used ifmotion-filter-type
is set to “notch”. This parameter is used in conjunction withmotion_filter_order
andband_stop_min
.Here is a list of recommended values, based on participant age:
Age Range (years)
Recommended Value
< 1
60
1 - 2
50
2 - 6
35
6 - 12
25
12 - 18
20
19 - 65
18
65 - 80
28
> 80
30
omp_nthreads (
int
) – Maximum number of threads an individual process may use.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.task_id (
str
or None) – Task ID of BOLD series to be selected for postprocess , orNone
to postprocess allbids_filters (dict or None)
output_dir (
str
) – Path to the output directory forxcp_d
derivatives. This should not include thexcp_d
folder. For example, “/path/to/dset/derivatives/”.fd_thresh (
float
) – Framewise displacement threshold for censoring, in millimeters. Any framewise displacement values higher than the threshold are flagged as “high motion”. If set to <=0, no censoring will be performed. Default is 0.2 mm.run_uuid (
str
) – Unique identifier for execution instancesubject_list (list) – List of subject labels
work_dir (
str
) – Directory in which to store workflow execution state and temporary files.head_radius (
float
or “auto”) – Radius of the head, in millimeters, for framewise displacement calculation.xcp_d
’s default head radius is 50. The recommended value for infants is 35. A value of ‘auto’ is also supported, in which case the brain radius is estimated from the preprocessed brain mask.params ({“36P”, “24P”, “27P”, “acompcor”, “acompcor_gsr”, “aroma”, “aroma_gsr”, “custom”}, optional) – Shorthand for the parameter set to extract from the confounds TSV. Default is “36P”, most expansive option.
smoothing (
float
) – The full width at half maximum (FWHM), in millimeters, of the Gaussian smoothing kernel that will be applied to the post-processed and denoised data. ALFF and ReHo outputs will also be smoothing with this kernel.custom_confounds_folder (
str
or None) – Path to folder containing custom nuisance regressors. Must be a folder containing confounds files, in which case the file with the name matching the preprocessing confounds file will be selected.dummy_scans (
int
or “auto”) – Number of volumes to remove from the beginning of each run. If set to ‘auto’, xcp_d will extract non-steady-state volume indices from the preprocessing derivatives’ confounds file.process_surfaces (
bool
, optional) – If True, a workflow will be run to warp native-space (fsnative) reconstructed cortical surfaces (surf.gii files) produced by Freesurfer into standard (fsLR) space. These surface files are primarily used for visual quality control. By default, this workflow is disabled.dcan_qc (
bool
) – This flag determines if DCAN-related QC steps will be taken. Enabling this flag will trigger the following steps:Brainsprite figures will be generated.
The executive summary will be generated.
DCAN QC files will be generated.
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.
min_coverage (
float
) – Coverage threshold to apply to parcels in each atlas. Any parcels with lower coverage than the threshold will be replaced with NaNs. Must be a value between zero and one. Default is 0.5.min_time (
float
) – Post-scrubbing threshold to apply to individual runs in the dataset. This threshold determines the minimum amount of time, in seconds, needed to post-process a given run, once high-motion outlier volumes are removed. This will have no impact if scrubbing is disabled (i.e., if the FD threshold is zero or negative). This parameter can be disabled by providing a zero or a negative value. Default is 100.combineruns
name (
str
, optional) – Name of the workflow. This is used for working directories and workflow graphs.
References