Processing Pipeline Details

Input data

The default inputs to XCP-D are the outputs of fMRIPrep (--input-type fmriprep) and Nibabies (--input-type nibabies). XCP-D can also postprocess HCP data (--input-type hcp).

Processing Steps

See Execution and Input Formats for information on input dataset structures.

Anatomical processing


XCP-D performs minimal postprocessing on anatomical derivatives from the preprocessing pipeline. This includes applying existing transforms to preprocessed T1w and T2w volumes, in order to warp them from native T1w space to the target standard space, while retaining the original resolution.

Surface normalization


If the --warp-surfaces-native2std is used, then fsnative surface files from the preprocessing derivatives will be warped to fsLR-32k space.


This step will only succeed if FreeSurfer derivatives are also available.

Identification of high-motion outlier volumes

init_prepare_confounds_wf(), GenerateConfounds

XCP-D uses framewise displacement to identify high-motion outlier volumes. These outlier volumes are removed from the BOLD data prior to denoising.

The threshold used to identify outlier volumes can be set with the --fd-thresh parameter.


If a BOLD run does not have enough low-motion data, then the post-processing workflow will automatically stop early, and no derivatives for that run will be written out.

Motion parameter filtering [OPTIONAL]

init_prepare_confounds_wf(), GenerateConfounds, load_motion()

Motion parameters may be contaminated with respiratory effects [1]. In order to address this issue, XCP-D optionally allows users to specify a band-stop or low-pass filter to remove respiration-related signals from the motion parameters, prior to framewise displacement calculation. Please refer to Fair et al.[2] and Gratton et al.[3] for more information.


Starting in version 0.4.0, if motion parameters are filtered in this step, the filtered motion parameters (including FD, and any squared or derivative regressors) will be used in the confound regression step.

The two options for the motion-filtering parameter are “notch” (the band-stop filter) and “lp” (the low-pass filter).

The cutoff points for either the notch filter (the beginning and end of the frequency band to remove) or the low-pass filter (the highest frequency to retain) can be set by the user (see Command-Line Arguments), and may depend on the age of the participant.

Below are some recommendations for cutoff values when using the notch filter.

Respiratory Filter

Age Range

Cutoff Range (Breaths per Minute)

< 1 year

30 to 60

1 to 2 years

25 - 50

2 - 6 years

20 - 35

6-12 years

15 - 25

12 - 18 years

12 - 20

19 - 65 years

12 - 18

65 - 80 years

12 - 28

> 80 years

10 - 30

If using the low-pass filter for single-band data, a recommended cutoff is 6 BPM (i.e., 0.1 Hertz), per Gratton et al.[3].

Framewise displacement calculation and thresholding

init_prepare_confounds_wf(), GenerateConfounds, compute_fd()

Framewise displacement is then calculated according to the formula from Power et al.[4]. Two parameters that impact FD calculation and thresholding are (1) the head radius used to convert rotation degrees to millimeters and (2) the framewise displacement threshold. The former may be set with the --head-radius parameter, which also has an “auto” option, in which a brain mask from the preprocessing derivatives is loaded and (treating the brain as a sphere) the radius is directly calculated (see estimate_brain_radius()). The latter is set with the --fd-thresh parameter.

In this step, volumes with a framewise displacement value over the --fd-thresh parameter will be flagged as “high motion outliers”. These volumes will later be removed from the denoised data.

Confound regressor selection

init_prepare_confounds_wf(), GenerateConfounds()

The confound regressor configurations in the table below are implemented in XCP-D, with 36P as the default. In addition to the standard confound regressors selected from fMRIPrep outputs, custom confounds can be added as described in Custom Confounds. If you want to use custom confounds, without any of the nuisance regressors described here, use --nuisance-regressors custom.

If you want to skip the denoising step completely, you can use --nuisance-regressors none.


Starting in version 0.4.0, if motion parameters were filtered earlier in the workflow, the filtered motion parameters (including FD, and any squared or derivative regressors) will be used in the confound regression step.



Six Motion Estimates

White Matter


Global Signal



Linear Trend



X, X2, dX, dX2




X, X2, dX, dX2







X, X2, dX, dX2

X, X2, dX, dX2

X, X2, dX, dX2

X, X2, dX, dX2




X, dX


10 com, 5WM, 5CSF




X, dX

10 com, 5WM, 5CSF




X, dX








X, dX







For more information about confound regressor selection, please refer to Ciric et al.[5].


In XCP-D versions prior to 0.3.1, the selected AROMA confounds were incorrect. We strongly advise users of these versions not to use the aroma or aroma_gsr options.

Dummy scan removal [OPTIONAL]

init_prepare_confounds_wf(), RemoveDummyVolumes

XCP-D allows the first N volumes to be removed before processing. These volumes are usually refered to as dummy volumes. Most default scanning sequences include dummy volumes that are not reconstructed. However, some users still prefer to remove the first few reconstructed volumes.

Users may provide the number of volumes directly with the --dummy-scans <INT> parameter, or they may rely on the preprocessing pipeline’s estimated non-steady-state volume indices with --dummy-scans auto.

Despiking [OPTIONAL]


Despiking is a process in which large spikes in the BOLD times series are truncated. Despiking reduces/limits the amplitude or magnitude of the large spikes but preserves those data points with an imputed reduced amplitude. This is done before regression and filtering, in order to minimize the impact of large amplitude changes in the data. It can be added to the command line arguments with --despike.


DenoiseNifti, DenoiseCifti

Temporal censoring [OPTIONAL]

Prior to confound regression, high-motion volumes will be removed from the BOLD data. These volumes will also be removed from the nuisance regressors. Please refer to Power et al.[6] for more information.


Censoring can be disabled by setting --fd-thresh 0.

Confound regression


Starting in version 0.4.0, if motion parameters were filtered earlier in the workflow, the filtered motion parameters (including FD, and any squared or derivative regressors) will be used in the confound regression step.

Prior to confound regression, all nuisance regressors, except the intercept regressor, will be mean-centered.

Handling of signal regressors

In some cases, nuisance regressors share variance with signal regressors, in which case additional processing must be done before regression. One example of this is denoising using components from a spatial independent components analysis. With spatial ICA, each component’s spatial weights are orthogonal to all other components, but the time series for the component may be correlated with other components. In common ICA-based denoising methods, such as AROMA or ME-ICA with tedana, components are classified as either “noise” or “signal”. However, the “noise” components will often share variance with the “signal” components, so simply regressing the noise components out of the BOLD data, without considering the signal components, may remove signal of interest.

To address this issue, XCP-D will look for signal regressors in the selected confounds. If any signal regressors are detected (i.e., if any columns in the confounds file have a signal__ prefix), then the noise regressors will be orthogonalized with respect to the signal regressors, to produce “pure evil” regressors.

This is done automatically for XCP-D’s built-in nuisance strategies which include AROMA components, but users must manually add the signal__ prefix to any signal regressors in their custom confounds files, if they choose to use them.

After censoring, mean-centering, and potential orthogonalization, confound regression will be performed with a linear least-squares approach. The parameter estimates for each of the confounds will be retained, along with the residuals from the regression. The residuals from regressing the censored BOLD data on the censored confounds will be referred to as the denoised BOLD.

Additionally, the parameter estimates from each of the censored confounds will be used calculate residuals using the full (i.e., uncensored) confounds and BOLD data. The residuals from this step will be referred to as the uncensored, denoised BOLD. The uncensored, denoised BOLD is later used for DCAN QC figures, but it is not written out to the output directory.


An interpolated version of the denoised BOLD is then created by filling in the high-motion outlier volumes with cubic spline interpolated data, as implemented in Nilearn.


In versions 0.4.0rc2 - 0.5.0, XCP-D used cubic spline interpolation, followed by bandpass filtering.

However, cubic spline interpolation can introduce large spikes and drops in the signal when the censored volumes are at the beginning or end of the run, which are then propagated to the filtered data.

To address this, XCP-D now replaces interpolated volumes at the edges of the run with the closest non-outlier volume’s data, as of 0.5.1.

The resulting interpolated, denoised BOLD is primarily used for bandpass filtering.

Bandpass filtering [OPTIONAL]

The interpolated, denoised BOLD is then bandpass filtered using a Butterworth filter. The resulting filtered, interpolated, denoised BOLD will only be written out to the output directory if the --dcan-qc flag is used, as users should not use interpolated data directly.

Bandpass filtering can be disabled with the --disable-bandpass-filter flag.



After bandpass filtering, high motion volumes are removed from the filtered, interpolated, denoised BOLD once again, to produce filtered, denoised BOLD. This is the primary output of XCP-D.

Resting-state derivative generation

For each BOLD run, resting-state derivatives are generated. These include regional homogeneity (ReHo) and amplitude of low-frequency fluctuation (ALFF).



ALFF will only be calculated if the bandpass filter is enabled (i.e., if the --disable-bandpass-filter flag is not used) and censoring is disabled (i.e., if --fd-thresh is set to a value less than or equal to zero).

Smoothed ALFF derivatives will also be generated if the --smoothing flag is used.


init_reho_nifti_wf(), init_reho_cifti_wf()

Parcellation and functional connectivity estimation

init_functional_connectivity_nifti_wf(), init_functional_connectivity_cifti_wf()

The filtered, denoised BOLD is fed into a functional connectivity workflow, which extracts parcel-wise time series from the BOLD using several atlases. These atlases are documented in Outputs of XCP-D.

The resulting parcellated time series for each atlas is then used to generate static functional connectivity matrices, as measured with Pearson correlation coefficients.

For CIFTI data, both tab-delimited text file (TSV) and CIFTI versions of the parcellated time series and correlation matrices are written out.

Functional connectivity estimates from specified amounts of data [OPTIONAL]

Functional connectivity estimates may exhibit non-linear relationships with the number of data points, such that including a regressor controlling for the number of post-censoring volumes per run in group-level models may not adequately address the issue.

In Eggebrecht et al.[7] and Feczko et al.[8], the authors’ solution was to randomly select a subset of volumes from each run before calculating correlations, so that every run had the same number of data points contributing to its functional connectivity estimate.

We have implemented this behavior via the optional --exact-time parameter, which allows the user to provide a list of durations, in seconds, to be used for functional connectivity estimates. These subsampled correlation matrices will be written out with desc-<numberOfVolumes>volumes in the filenames. The correlation matrices without the desc entity still include all of the post-censoring volumes.

The --random-seed parameter can control the random seed used to select the reduced set of volumes, which improves reproducibility.

Smoothing [OPTIONAL]


The filtered, denoised BOLD may optionally be smoothed with a Gaussian kernel. This smoothing kernel is set with the --smoothing parameter.

Concatenation of functional derivatives [OPTIONAL]


If the --combineruns flag is included, then BOLD runs will be grouped by task and concatenated. Several concatenated derivatives will be generated, including the filtered, denoised BOLD, the smoothed, filtered, denoised BOLD, the temporal mask, and the filtered motion parameters.


If a run does not have enough low-motion data and is skipped, then the concatenation workflow will not include that run.


If a set of related runs do not have enough low-motion data, then the concatenation workflow will automatically stop early, and no concatenated derivatives for that set of runs will be written out.

Quality control


The quality control (QC) in XCP-D estimates the quality of BOLD data before and after regression and also estimates BOLD-T1w coregistration and BOLD-Template normalization qualites. The QC metrics include the following:

  1. Motion parameters summary: mean FD, mean and maximum RMS

  2. Mean DVARs before and after regression and its relationship to FD

  3. BOLD-T1w coregistration quality - Dice similarity index, Coverage and Pearson correlation

  4. BOLD-Template normalization quality - Dice similarity index, Coverage and Pearson correlation


XCP-D generates four main types of outputs for every subject.

First, XCP-D generates an HTML “executive summary” that displays relevant information about the anatomical data and the BOLD data before and after regression. The anatomical image viewer allows the user to see the segmentation overlaid on the anatomical image. Next, for each session, the user can see the segmentation registered onto the BOLD images. Beside the segmentations, users can see the pre-regression and post-regression “carpet” plot, as well as DVARS, FD, the global signal. The number of volumes remaining at various FD thresholds are shown.

Second, XCP-D generates an HTML “report” for each subject and session. The report contains a Processing Summary with QC values, with the BOLD volume space, the TR, mean FD, mean RMSD, and mean and maximum RMS, the correlation between DVARS and FD before and after processing, and the number of volumes censored. Next, pre and post regression “carpet” plots are alongside DVARS and FD. An About section that notes the release version of XCP-D, a Methods section that can be copied and pasted into the user’s paper, which is customized based on command line options, and an Error section, which will read “No errors to report!” if no errors are found.

Third, XCP-D outputs processed BOLD data, including denoised unsmoothed and smoothed timeseries in MNI152NLin2009cAsym and fsLR-32k spaces, parcellated time series, functional connectivity matrices, and ALFF and ReHo (smoothed and unsmoothed).

Fourth, the anatomical data (processed T1w processed and segmentation files) are copied from fMRIPrep. If both images are not in MNI152NLin6Asym space, they are resampled to MNI space. The fMRIPrep surfaces (gifti files) in each subject are also resampled to standard space (fsLR-32K).

See Outputs of XCP-D for details about XCP-D outputs.