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#
- nilearn.interfaces.fmriprep.load_confounds(img_files, strategy=('motion', 'high_pass', 'wm_csf'), motion='full', scrub=5, fd_threshold=0.2, std_dvars_threshold=3, wm_csf='basic', global_signal='basic', compcor='anat_combined', n_compcor='all', ica_aroma='full', demean=True)[source]#
Use confounds from fMRIPrep.
To enable easy confound variables loading from fMRIPrep outputs, load_confounds provides an interface that groups subsets of confound variables into noise components and their parameters. It is possible to fine-tune a subset of noise components and their parameters through this function.
The implementation will only support fMRIPrep functional derivative directory from the 1.2.x series. The compcor noise component requires 1.4.x series or above.
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-complied names, 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.
- strategytuple or list of strings.
Default (“motion”, “high_pass”, “wm_csf”) The type of noise components to include.
“motion”: head motion estimates. Associated parameter: motion
“wm_csf” confounds derived from white matter and cerebrospinal fluid. Associated parameter: wm_csf
“global_signal” confounds derived from the global signal. Associated parameter: global_signal
“compcor” confounds derived from CompCor 1. When using this noise component, “high_pass” must also be applied. Associated parameter: compcor, n_compcor
“ica_aroma” confounds derived from ICA-AROMA 2. Associated parameter: ica_aroma
“scrub” regressors for 3 scrubbing approach. Associated parameter: scrub, fd_threshold, std_dvars_threshold
For each component above, associated parameters will be applied if specified. If associated parameters are not specified, any values supplied to the parameters are ignored. For example, strategy=(‘motion’, ‘global_signal’) will allow users to supply input to associated parameter motion and global_signal; if users pass wm_csf parameter, it will not be applied as it is not part of the strategy.
There are two additional noise components with no optional parameters.
“non_steady_state” denotes volumes collected before the fMRI scanner has reached a stable state.
“high_pass” adds discrete cosines transformation basis regressors to handle low-frequency signal drifts.
Non-steady-state volumes will always be checked. There’s no need to supply this component to the strategy.
- motion{‘basic’, ‘power2’, ‘derivatives’, ‘full’}
Type of confounds extracted from head motion estimates.
“basic” translation/rotation (6 parameters)
“power2” translation/rotation + quadratic terms (12 parameters)
“derivatives” translation/rotation + derivatives (12 parameters)
“full” translation/rotation + derivatives + quadratic terms + power2d derivatives (24 parameters)
- wm_csf{‘basic’, ‘power2’, ‘derivatives’, ‘full’}
Type of confounds extracted from masks of white matter and cerebrospinal fluids.
“basic” the averages in each mask (2 parameters)
“power2” averages and quadratic terms (4 parameters)
“derivatives” averages and derivatives (4 parameters)
“full” averages + derivatives + quadratic terms + power2d derivatives (8 parameters)
- global_signal{‘basic’, ‘power2’, ‘derivatives’, ‘full’}
Type of confounds extracted from the global signal.
“basic” just the global signal (1 parameter)
“power2” global signal and quadratic term (2 parameters)
“derivatives” global signal and derivative (2 parameters)
“full” global signal + derivatives + quadratic terms + power2d derivatives (4 parameters)
- scrubint, default 5
After accounting for time frames with excessive motion, further remove segments shorter than the given number. The default value is 5 (referred as full scrubbing in 3). When the value is 0, temove time frames based on excessive framewise displacement and DVARS only. One-hot encoding vectors are added as regressors for each scrubbed frame.
- fd_thresholdfloat, default 0.2
Framewise displacement threshold for scrub (default = 0.2 mm)
- std_dvars_thresholdfloat, default 3
Standardized DVARS threshold for scrub (default = 3). DVARs is defined as root mean squared intensity difference of volume N to volume N+1 4. D referring to temporal derivative of timecourses, VARS referring to root mean squared variance over voxels.
- compcor{‘anat_combined’, ‘anat_separated’, ‘temporal’, ‘temporal_anat_combined’, ‘temporal_anat_separated’}
Warning
Require fmriprep >= v:1.4.0.
Type of confounds extracted from a component based noise correction method 1.
“anat_combined” noise components calculated using a white matter and CSF combined anatomical mask
“anat_separated” noise components calculated using white matter mask and CSF mask compcor separately; two sets of scores are concatenated
“temporal” noise components calculated using temporal compcor
“temporal_anat_combined” components of “temporal” and “anat_combined”
“temporal_anat_separated” components of “temporal” and “anat_separated”
- n_compcor“all” or int, default “all”
The number of noise components to be extracted. For acompcor_combined=False, and/or compcor=”full”, this is the number of components per mask. “all”: select all components (50% variance explained by fMRIPrep defaults)
- ica_aroma{‘full’, ‘basic’}
“full”: use fMRIPrep output ~desc-smoothAROMAnonaggr_bold.nii.gz.
“basic”: use noise independent components only.
- demeanboolean, default True
If True, the confounds are standardized to a zero mean (over time). When using
nilearn.maskers.NiftiMaskerwith default parameters, the recommended option is True. When usingnilearn.signal.cleanwith default parameters, the recommended option is False. When sample_mask is not None, the mean is calculated on retained volumes.
- 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 volumns require 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. Volumns are removed if flagged as following:Non-steady-state volumes (if present)
Motion outliers detected by scrubbing
Notes
The noise components implemented in this class are adapted from 5. Band-pass filter is replaced by high-pass filter. Low-pass filters can be implemented, e.g., through NifitMaskers. Other aspects of the preprocessing listed in 5 are controlled through fMRIPrep, e.g. distortion correction.
References
- 1(1,2)
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.
- 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.
- 3(1,2)
Jonathan D. Power, Anish Mitra, Timothy O. Laumann, Abraham Z. Snyder, Bradley L. Schlaggar, and Steven E. Petersen. Methods to detect, characterize, and remove motion artifact in resting state fMRI. NeuroImage, 84:320–341, 2014. URL: http://www.sciencedirect.com/science/article/pii/S1053811913009117, doi:10.1016/j.neuroimage.2013.08.048.
- 4
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.
- 5(1,2)
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.
