xcp_d.workflows.postprocessing module

Workflows for post-processing BOLD data.

xcp_d.workflows.postprocessing.init_denoise_bold_wf(TR, low_pass, high_pass, bpf_order, bandpass_filter, smoothing, cifti, mem_gb, omp_nthreads, name='denoise_bold_wf')[source]

Denoise BOLD data.

Workflow Graph

(Source code)

Parameters:

  • TR (float) – Repetition time of the BOLD run, in seconds.

  • 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 if bandpass_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.

  • 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 if bandpass_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.

  • bpf_order (int) – Number of filter coefficients for Butterworth bandpass filter. Bandpass filtering will only be performed if bandpass_filter is True. This parameter is used in conjunction with lower_bpf/high_pass and upper_bpf/low_pass.

  • 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.

  • 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.

  • 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.

  • 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 “denoise_bold_wf”.

Inputs:

  • preprocessed_bold

  • temporal_mask (str) – Temporal mask; all values above fd_thresh set to 1. This is a TSV file with one column: ‘framewise_displacement’.

  • mask

  • confounds_file

Outputs:

  • uncensored_denoised_bold (str) – Path to the uncensored, denoised BOLD file. This file is the result of denoising the full (uncensored) preprocessed BOLD data using betas estimated using the censored BOLD data and nuisance regressors.

    This output should not be used for analysis. It is primarily used for DCAN QC plots.

  • interpolated_filtered_bold (str) – Path to the censored, denoised, interpolated, and filtered BOLD file. This file is the result of denoising the censored preprocessed BOLD data, followed by cubic spline interpolation and band-pass filtering.

    This output should not be used for analysis. It is primarily for DCAN QC plots.

  • censored_denoised_bold (str) – Path to the censored, denoised, interpolated, filtered, and re-censored BOLD file. This file is the result of denoising the censored preprocessed BOLD data, followed by cubic spline interpolation, band-pass filtering, and re-censoring.

    This output is the primary derivative for analysis.

  • smoothed_denoised_bold (str) – Path to the censored, denoised, interpolated, filtered, re-censored, and smoothed BOLD file. This file is the result of denoising the censored preprocessed BOLD data, followed by cubic spline interpolation, band-pass filtering, re-censoring, and spatial smoothing.

xcp_d.workflows.postprocessing.init_despike_wf(TR, cifti, mem_gb, omp_nthreads, name='despike_wf')[source]

Despike BOLD data with AFNI’s 3dDespike.

Despiking truncates large spikes in the BOLD times series. Despiking reduces/limits the amplitude or magnitude of large spikes, but preserves those data points with an imputed reduced amplitude. Despiking is done before regression and filtering to minimize the impact of spikes. Despiking is applied to whole volumes and data, and different from temporal censoring. It can be added to the command line arguments with --despike.

Workflow Graph

(Source code)

Parameters:

  • TR (float) – Repetition time of the BOLD run, in seconds.

  • 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.

  • 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 “despike_wf”.

Inputs:

bold_file (str) – A NIFTI or CIFTI BOLD file to despike.

Outputs:

bold_file (str) – The despiked NIFTI or CIFTI BOLD file.

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

(Source code)

Parameters:

  • output_dir (str) – Path to the output directory for xcp_d derivatives. This should not include the xcp_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 and band_stop_max will be removed with a notch filter. In this case, both band_stop_min and band_stop_max must be defined.

    If “lp”, frequencies above band_stop_min will be removed with a Butterworth filter. In this case, only band_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 if motion_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 with motion_filter_order and band_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 if motion_filter_type is not None. This parameter is only used if motion-filter-type is set to “notch”. This parameter is used in conjunction with motion_filter_order and band_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 if motion_filter_type is not None. This parameter is used in conjunction with band_stop_max and band_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 the source_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 above fd_thresh set to 1. This is a TSV file with one column: ‘framewise_displacement’.

  • temporal_mask_metadata (dict)

xcp_d.workflows.postprocessing.init_resd_smoothing_wf(smoothing, cifti, mem_gb, omp_nthreads, name='resd_smoothing_wf')[source]

Smooth BOLD residuals.

Workflow Graph

(Source code)

Parameters:

  • 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.

  • 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.

  • 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 “resd_smoothing_wf”.

Inputs:

bold_file

Outputs:

smoothed_bold