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_filesstr or list of str.

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_strategystr, 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.

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

  • Non-steady-state volumes (if present)

  • Motion outliers detected by scrubbing

See also

nilearn.interfaces.fmriprep.load_confounds

Notes

  1. 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*

  2. 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/usage.html#fmriprep.cli.parser-_build_parser-[deprecated]-options-for-running-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

Extracting signals from a brain parcellation