xcp_d.workflows.postprocessing.init_prepare_confounds_wf
- xcp_d.workflows.postprocessing.init_prepare_confounds_wf(output_dir, TR, params, dummy_scans, motion_filter_type, band_stop_min, band_stop_max, motion_filter_order, head_radius, fd_thresh, custom_confounds_file, mem_gb, omp_nthreads, name='prepare_confounds_wf')[source]
Prepare confounds.
This workflow loads and consolidates confounds, removes dummy volumes, filters motion parameters, calculates framewise displacement, and flags outlier volumes.
- Workflow Graph
- Parameters:
output_dir (
str
) – Path to the output directory forxcp_d
derivatives. This should not include thexcp_d
folder. For example, “/path/to/dset/derivatives/”.TR (
float
) – Repetition time of the BOLD run, in seconds.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.
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.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.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
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
.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. This will already be estimated before this workflow.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.custom_confounds_file (
str
or None) – Path to custom nuisance regressors.mem_gb (
float
) – Memory limit, in gigabytes.omp_nthreads (
int
) – Maximum number of threads an individual process may use.name (
str
, optional) – Name of the workflow. This is used for working directories and workflow graphs. Default is “prepare_confounds_wf”.
- Inputs:
name_source (
str
) – Path to the file that will be used as thesource_file
for derivatives. This is generally the preprocessed BOLD file. This file does not need to exist (e.g., in the case of a concatenated version of the filename).preprocessed_bold (
str
)fmriprep_confounds_file (
str
) – Confounds TSV file from preprocessing derivatives.fmriprep_confounds_json (
str
) – JSON file associated with the fMRIPrep confounds TSV.custom_confounds_file (
str
or None) – Path to custom nuisance regressors.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. Set from the parameter.
- Outputs:
preprocessed_bold (
str
)fmriprep_confounds_file (
str
) – Confounds TSV file from preprocessing derivatives.confounds_file (
str
) – The selected confounds, potentially including custom confounds, after dummy scan removal.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. If originally set to “auto”, this output will have the actual number of dummy volumes.filtered_motion (
str
) – Framewise displacement timeseries, potentially after bandstop or low-pass filtering. This is a TSV file with one column: ‘framewise_displacement’.motion_metadata (
dict
)temporal_mask (
str
) – Temporal mask; all values abovefd_thresh
set to 1. This is a TSV file with one column: ‘framewise_displacement’.temporal_mask_metadata (
dict
)