xcp_d.utils.confounds module

Confound matrix selection based on Ciric et al. 2007.

xcp_d.utils.confounds.filter_motion(data, TR, motion_filter_type, band_stop_min, band_stop_max, motion_filter_order)

Filter translation and rotation motion parameters.

Parameters:

• data ((T, R) numpy.ndarray) – Data to filter. T = time, R = motion regressors The filter will be applied independently to each variable, across time.

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

• 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. If not “notch” or “lp”, an exception will be raised.

• 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. For “lp” filters, the order is divided by 2 as filtfilt applies the filter twice. For “notch” filters, the order is divided by 4 as iirnotch is a second-order filter and filtfilt applies the filter twice.

Returns:

data – Filtered data. Same shape as the original data.

Return type:

(T, R) numpy.ndarray

Notes

Low-pass filtering (motion_filter_type = "lp") is performed with a Butterworth filter, as in Gratton et al.[1]. The order of the Butterworth filter is determined by motion_filter_order, although the original paper used a first-order filter. Since filtfilt applies the filter twice, motion_filter_order is divided by 2 before applying the filter. The original paper also used zero-padding with a padding size of 100. We use constant-padding, with the default padding size determined by scipy.signal.filtfilt().

Band-stop filtering (motion_filter_type = "notch") is performed with a notch filter, as in Fair et al.[2]. This filter uses the mean of the stopband frequencies as the target frequency, and the range between the two frequencies as the bandwidth. Because iirnotch is a second-order filter and filtfilt applies the filter twice, motion_filter_order is divided by 4 before applying the filter. The filter is applied with constant-padding, using the default padding size determined by scipy.signal.filtfilt().

References

[1] (1,2,3)

Caterina Gratton, Ally Dworetsky, Rebecca S Coalson, Babatunde Adeyemo, Timothy O Laumann, Gagan S Wig, Tania S Kong, Gabriele Gratton, Monica Fabiani, Deanna M Barch, and others. Removal of high frequency contamination from motion estimates in single-band fmri saves data without biasing functional connectivity. Neuroimage, 217:116866, 2020. URL: https://doi.org/10.1016/j.neuroimage.2020.116866, doi:10.1016/j.neuroimage.2020.116866.

[2]

Damien A Fair, Oscar Miranda-Dominguez, Abraham Z Snyder, Anders Perrone, Eric A Earl, Andrew N Van, Jonathan M Koller, Eric Feczko, M Dylan Tisdall, Andre van der Kouwe, and others. Correction of respiratory artifacts in mri head motion estimates. Neuroimage, 208:116400, 2020. URL: https://doi.org/10.1016/j.neuroimage.2019.116400, doi:10.1016/j.neuroimage.2019.116400.

xcp_d.utils.confounds.load_motion(confounds_df, TR, motion_filter_type=None, band_stop_min=None, band_stop_max=None, motion_filter_order=4)

Load the six basic motion regressors (three rotations, three translations).

Parameters:

• confounds_df (pandas.DataFrame) – The confounds DataFrame from which to extract the six basic motion regressors.

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

• 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. If “lp” or “notch”, that filtering will be done in this function. Otherwise, no filtering will be applied.

• 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. For “lp” filters, the order is divided by 2 as filtfilt applies the filter twice. For “notch” filters, the order is divided by 4 as iirnotch is a second-order filter and filtfilt applies the filter twice.

Returns:

motion_confounds_df – The six motion regressors. The three rotations are listed first, then the three translations. Plus rmsd, and possibly filtered motion regressors.

Return type:

pandas.DataFrame

References

xcp_d.utils.confounds.volterra(df)

Perform Volterra expansion.