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)

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.

Added in version 0.9.0.

Parameters:

img_filesstr or list of str

Path of 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 str, 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 (Behzadi et al.[1]). When using this noise component, “high_pass” must also be applied. Associated parameter: compcor, n_compcor

• “ica_aroma” confounds derived from ICA-AROMA (Pruim et al.[2]). Associated parameter: ica_aroma

• “scrub” regressors for Power et al.[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.

motionstr, default=”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_csfstr, default=”basic”

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_signalstr, default=”basic”

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 referred as full scrubbing in Power et al.[3]. When the value is 0, remove time frames based on excessive framewise displacement and DVARS only.

fd_thresholdfloat, default=0.2

Deprecated since version 0.10.3: The default value will be changed to 0.5 in 0.13.0

Framewise displacement threshold for scrub in mm.

std_dvars_thresholdfloat, default=3

Deprecated since version 0.10.3: The default value will be changed to 1.5 in 0.13.0

Standardized DVARS threshold for scrub. The default threshold matching fMRIPrep. DVARs is defined as root mean squared intensity difference of volume N to volume N+1 Power et al.[4]. D referring to temporal derivative of timecourses, VARS referring to root mean squared variance over voxels.

compcorstr, default=”anat_combined”

Warning

Require fMRIPrep >= v:1.4.0.

Type of confounds extracted from a component based noise correction method Behzadi et al.[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_compcorstr 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_aromastr, default=”full”

• “full”: use fMRIPrep output ~desc-smoothAROMAnonaggr_bold.nii.gz.

• “basic”: use noise independent components only.

demeanbool, default=True

If True, the confounds are standardized to a zero mean (over time). When using nilearn.maskers.NiftiMasker with default parameters, the recommended option is True. When using nilearn.signal.clean with 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 pandas.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 of numpy.ndarray or None

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.NiftiMasker or nilearn.signal.clean. Volumns are removed if flagged as following:

• Non-steady-state volumes (if present)

• Motion outliers detected by scrubbing

See also

nilearn.interfaces.fmriprep.load_confounds_strategy

Notes

The noise components implemented in this class are adapted from Ciric et al.[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 Ciric et al.[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: https://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: https://pubmed.ncbi.nlm.nih.gov/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.

Examples using nilearn.interfaces.fmriprep.load_confounds

Extracting signals from a brain parcellation

Extracting signals from a brain parcellation

Understanding parameters of the first-level model

Understanding parameters of the first-level model