xcp_d.utils.confounds module
Confound matrix selection based on Ciric et al. 2007.
- xcp_d.utils.confounds.describe_censoring(motion_filter_type, motion_filter_order, band_stop_min, band_stop_max, head_radius, fd_thresh)[source]
Build a text description of the motion parameter filtering and FD censoring process.
- Parameters:
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.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
.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
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.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.
- Returns:
desc – A text description of the censoring procedure.
- Return type:
- xcp_d.utils.confounds.describe_regression(params, custom_confounds_file, motion_filter_type)[source]
Build a text description of the regression that will be performed.
- Parameters:
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.
custom_confounds_file (
str
or None) – Path to custom nuisance regressors.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.
- Returns:
desc – A text description of the regression.
- Return type:
- xcp_d.utils.confounds.get_custom_confounds(custom_confounds_folder, fmriprep_confounds_file)[source]
Identify a custom confounds file.
- Parameters:
custom_confounds_folder (
str
or None) – Path to folder containing custom nuisance regressors. Must be a folder containing confounds files, in which case the file with the name matching the preprocessing confounds file will be selected.fmriprep_confounds_file (
str
) – Confounds TSV file from preprocessing derivatives. We expect the custom confounds file to have the same name.
- Returns:
custom_confounds_file – Path to custom nuisance regressors.
- Return type:
str
or None
- xcp_d.utils.confounds.load_confound_matrix(params, img_file, confounds_file, confounds_json_file, custom_confounds=None)[source]
Load a subset of the confounds associated with a given file.
- Parameters:
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.
img_file (
str
) – The path to the bold file. Used to load the AROMA mixing matrix, if necessary.confounds_file (
str
) – The fMRIPrep confounds file. Used to load most confounds.confounds_json_file (
str
) – The JSON file associated with the fMRIPrep confounds file.custom_confounds (
str
or None, optional) – Custom confounds TSV if there is one. Default is None.
- Returns:
confounds_df – The loaded and selected confounds. If “AROMA” is requested, then this DataFrame will include signal components as well. These will be named something like “signal_[XX]”.
- Return type:
- 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)[source]
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
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. 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 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
.
- Returns:
motion_confounds_df – The six motion regressors. The three rotations are listed first, then the three translations.
- Return type:
References
- xcp_d.utils.confounds.motion_regression_filter(data, TR, motion_filter_type, band_stop_min, band_stop_max, motion_filter_order=4)[source]
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
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. 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 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
.
- 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 bymotion_filter_order
, although the original paper used a first-order filter. The original paper also used zero-padding with a padding size of 100. We use constant-padding, with the default padding size determined byscipy.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. The filter is applied with constant-padding, using the default padding size determined byscipy.signal.filtfilt()
.References