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 customisation.
New in version 0.9.0.
- Parameters
- img_filespath to processed image files, optionally as a list.
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_confoundscan 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{‘simple’, ‘srubbing’, ‘compcor’, ‘ica_aroma’}
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 1. With the global signal regression, this approach can remove confounds without compromising the temporal degrees of freedom.
‘srubbing’: Load confounds for scrubbing describbed in 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 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.
‘ica_aroma’: Load confounds for non-aggresive ICA-AROMA strategy described in 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 (5, 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.
- Returns
- confoundspandas.DataFrame, or list of
A reduced version of fMRIPrep confounds based on selected strategy and flags. An intercept is automatically added to the list of confounds. The columns contains the labels of the regressors.
- sample_maskNone, numpy.ndarray, or list of
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.NiftiMaskerornilearn.signal.clean. Volumes are removed if flagged as following:Non-steady-state volumes (if present)
Motion outliers detected by scrubbing
Notes
The following table details the default options of each preset strategies. Parameters with * denote customisable 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
N/A
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 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
- 1
Michael D. Fox, Abraham Z. Snyder, Justin L Vincent, Maurizio Corbetta, David C. Van Essen, and Marcus E. Raichle. The human brain is intrinsically organized into dynamic, anticorrelated functional networks. Proceedings of the National Academy of Sciences, 102(27):9673–9678, July 2005. doi:10.1073/pnas.0504136102.
- 2
Jonathan D. Power, Kelly A. Barnes, Abraham Z. Snyder, Bradley L. Schlaggar, and Steven E. Petersen. Spurious but systematic correlations in functional connectivity MRI networks arise from subject motion. NeuroImage, 59(3):2142–2154, 2012. URL: http://www.ncbi.nlm.nih.gov/pubmed/22019881 http://www.pubmedcentral.nih.gov/articlerender.fcgi?artid=PMC3254728, doi:10.1016/j.neuroimage.2011.10.018.
- 3
Yashar Behzadi, Khaled Restom, Joy Liau, and Thomas T. Liu. A component based noise correction method (compcor) for bold and perfusion based fmri. NeuroImage, 37(1):90–101, 2007. URL: https://www.sciencedirect.com/science/article/pii/S1053811907003837, doi:https://doi.org/10.1016/j.neuroimage.2007.04.042.
- 4(1,2)
Raimon H. R. Pruim, Maarten Mennes, Daan van Rooij, Alberto Llera, Jan K. Buitelaar, and Christian F. Beckmann. ICA-AROMA: a robust ICA-based strategy for removing motion artifacts from fMRI data. Neuroimage, 112:267–277, 2015. doi:10.1016/j.neuroimage.2015.02.064.
- 5
Rastko Ciric, Daniel H. Wolf, Jonathan D. Power, David R. Roalf, Graham L. Baum, Kosha Ruparel, Russell T. Shinohara, Mark A. Elliott, Simon B. Eickhoff, Christos Davatzikos, Ruben C. Gur, Raquel E. Gur, Danielle S. Bassett, and Theodore D. Satterthwaite. Benchmarking of participant-level confound regression strategies for the control of motion artifact in studies of functional connectivity. NeuroImage, 154(1):174–187, 2017. doi:10.1016/j.neuroimage.2017.03.020.
- 6
Linden Parkes, Ben Fulcher, Murat Yücel, and Alex Fornito. An evaluation of the efficacy, reliability, and sensitivity of motion correction strategies for resting-state functional MRI. NeuroImage, 171:415–436, May 2018. doi:10.1016/j.neuroimage.2017.12.073.
