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.
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 (pandas.DataFrame or None) – 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]”.
If params is “none”, confounds_df will be None.
confounds_metadata (dict) – Metadata for the columns in the confounds file.
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.
Returns:
motion_confounds_df – The six motion regressors.
The three rotations are listed first, then the three translations.
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.
Returns:
data – Filtered data. Same shape as the original data.
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.
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.
The filter is applied with constant-padding, using the default padding size determined by
scipy.signal.filtfilt().