Note
This page is a reference documentation. It only explains the function signature, and not how to use it. Please refer to the user guide for the big picture.
nilearn.interfaces.fmriprep.load_confounds_strategy¶
- nilearn.interfaces.fmriprep.load_confounds_strategy(img_files, denoise_strategy='simple', **kwargs)[source]¶
Use preset strategy to load confounds from fMRIPrep.
load_confounds_strategy provides an interface to select confounds based on past literature with limited parameters for user customization.
Added in version 0.9.0.
- Parameters:
- img_files
str
orlist
ofstr
. Processed nii.gz/dtseries.nii/func.gii file reside in a fMRIPrep generated functional derivative directory (i.e.The associated confound files should be in the same directory as the image file). As long as the image file, confound related tsv and json are in the same directory with BIDS-compliant names,
nilearn.interfaces.fmriprep.load_confounds
can retrieve the relevant files correctly.nii.gz or dtseries.nii: path to files, optionally as a list.
func.gii: list of a pair of paths to files, optionally as a list of lists.
- denoise_strategy
str
, default=”simple” Name of preset denoising strategies. Each strategy has a set of associated configurable parameters. For customiseable parameters, please see the table in Notes.
‘simple’: Load confounds for a simple denoising strategy commonly used in resting state functional connectivity, described in Fox et al.[1]. With the global signal regression, this approach can remove confounds without compromising the temporal degrees of freedom.
‘scrubbing’: Load confounds for scrubbing described in Power et al.[2]. This approach can reliably remove the impact of high motion volumes in functional connectome, however, it might not be suitable with subjects with high motion (more than 50% timeseries flagged as high motion). One should adjust the threshold based on the characteristics of the dataset, or remove high motion subjects from the dataset.
‘compcor’: Load confounds using the CompCor strategy from Behzadi et al.[3]. CompCor estimates noise through principal component analysis on regions that are unlikely to contain signal. Thus it might not be a suitable approach for researchers who want explicit description of the source of noise. Empirically, Compcor has shown similar effect of removing physiological noise as methods that explicitly model and remove physiology signals. Compcor can suffer from loss of temporal degrees of freedom when using explained variance as the noise component estimation as the number of compcor component can be really high. Please refer to fMRIPrep documentation for more details.
Added in version 0.10.3: golobal_signal is now a tunable parameter for compcor.
‘ica_aroma’: Load confounds for non-aggresive ICA-AROMA strategy described in Pruim et al.[4]. The strategy requires fMRIPrep outputs generated with –use-aroma suffixed with desc-smoothAROMAnonaggr_bold. ICA-AROMA increases the run time of fMRIPrep, however, the strategy performs well in various benchmarks (Ciric et al.[5], Parkes et al.[6]). See Notes for more details about this option.
- Other keyword arguments:
See additional parameters associated with denoise_strategy in Notes and refer to the documentation of
nilearn.interfaces.fmriprep.load_confounds
.
- img_files
- Returns:
- confounds
pandas.DataFrame
, orlist
ofpandas.DataFrame
A reduced version of fMRIPrep confounds based on selected strategy and flags. The columns contains the labels of the regressors.
- sample_maskNone,
numpy.ndarray
or,list
ofnumpy.ndarray
or None When no volume requires removal, the value is None. Otherwise, shape: (number of scans - number of volumes removed, ) The index of the niimgs along time/fourth dimension for valid volumes for subsequent analysis. This attribute should be passed to parameter sample_mask of
nilearn.maskers.NiftiMasker
ornilearn.signal.clean
. Volumes are removed if flagged as following:Non-steady-state volumes (if present)
Motion outliers detected by scrubbing
- confounds
Notes
The following table details the default options of each preset strategies. Parameters with * denote customizable parameters. Please see
nilearn.interfaces.fmriprep.load_confounds
.strategy
high_pass
motion
wm_csf
global_signal
scrub
fd_threshold
std_dvars_threshold
compcor
n_compcor
ica_aroma
demean
simple
True
full*
basic*
None*
N/A
N/A
N/A
N/A
N/A
N/A
True*
scrubbing
True
full*
full
None*
5*
0.2*
3*
N/A
N/A
N/A
True*
compcor
True
full*
N/A
None*
N/A
N/A
N/A
anat_combined*
all*
N/A
True*
ica_aroma
True
N/A
basic*
None*
N/A
N/A
N/A
N/A
N/A
full
True*
ICA-AROMA is implemented in two steps in Pruim et al.[4]:
i. A non-aggressive denoising immediately after ICA classification. A linear regression estimates signals with all independent components as predictors. A partial regression is then applied to remove variance associated with noise independent components. fMRIPrep performs this step and generates files in MNI152NLin6Asym template, suffixed with desc-smoothAROMAnonaggr_bold.
One can produce desc-smoothAROMAnonaggr_bold in other spatial templates, please refer to fMRIPrep documentation on ICA-AROMA https://fmriprep.org/en/latest/workflows.html#ica-aroma
ii. Confound regression step (mean signals from WM and CSF). Confound regressors generated by this function with denoise_strategy=”ica_aroma”.
For more discussion regarding choosing the nuisance regressors before or after denoising with ICA-AROMA has a detriment on outcome measures, please see notebook 5. https://github.com/nipreps/fmriprep-notebooks/
References
Examples using nilearn.interfaces.fmriprep.load_confounds_strategy
¶
Extracting signals from a brain parcellation