xcp_d.workflows.postprocessing.init_prepare_confounds_wf

xcp_d.workflows.postprocessing.init_prepare_confounds_wf(output_dir, TR, params, dummy_scans, random_seed, exact_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')

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, png, svg, pdf)

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.

• random_seed (int or None) – Random seed for the workflow. This is currently only used with the --exact-time parameter, when randomly selecting volumes to censor for correlation matrices.

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

• confounds_metadata (dict)

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