Package: load-confounds
load_confoundsLoad a sensible subset of the fMRI confounds generated withfMRIprepin python (Esteban et al., 2018).Warning: This package is at an alpha stage of development. The API may still be subject to changes.InstallationInstall withpip(Python >=3.5):pipinstallload_confoundsTL;DRLoad confounds for a minimal denosing strategy commonly used in resting state functional connectivity.
(Full motion parameters, WM/CSF signals, and high pass filter)fromload_confoundsimportMinimalfromnilearn.input_dataimportNiftiMasker# load_confounds auto-detects the companion .tsv file (which needs to be in the same directory)file="path/to/file/sub-01_ses-001_bold.nii.gz"confounds=Minimal().load(file)# Use the confounds to load preprocessed time series with nilearnmasker=NiftiMasker(smoothing_fwhm=5,standardize=True)img=masker.fit_transform(file,confounds=confounds)It is also possible to fine-tune a subset of noise components and their parameters:fromload_confoundsimportConfoundsconfounds=Confounds(strategy=['high_pass','motion','global'],motion="full").load(file)You can check our tutorial on MyBinder for more infoNoise componentsThe following noise components are supported. Check the docstring ofConfoundsfor more info on the parameters for each type of noise.motionthe motion parameters including 6 translation/rotation (basic), and optionally derivatives, squares, and squared derivatives (full).high_passbasis of discrete cosines covering slow time drift frequency band.wm_csfthe average signal of white matter and cerebrospinal fluid masks (basic), and optionally derivatives, squares, and squared derivatives (full).globalthe global signal (basic), and optionally derivatives, squares, and squared derivatives (full).compcorthe results of a PCA applied on a mask based on either anatomy (anat), temporal variance (temp), or both (combined).ica_aromathe results of an idependent component analysis (ICA) followed by identification of noise components. This can be implementing by incorporating ICA regressors (basic) or directly loading a denoised file generated by fMRIprep (full).scrubregressors coding for time frames with excessive motion, using threshold on frame displacement and standardized DVARS (basic) and suppressing short time windows using the (Power et al., 2014) appreach (full).Predefined strategiesMinimalMinimalis suitable for data with minimal motion. Only includes motion parameters, wm and csf, with the option to add global.ScrubbingLikeMinimal, but with scrubbing. Pros: Actual impact on data is pretty limited, but still good and offers the most control on what's being discarded. Cons: high loss of degrees of freedom, and messes up with the time axis in a way that may be difficult to handle for downstream analyses.CompCorCompCorincludes anatomical or temporal compcor. The default is anatomical compcor with fully expanded motion parameters. Pros: large impact of denoising, efficient denoising, controlled loss of degrees of freedom. Cons: low control on what is being discarded (who knows what signal actually show up in the PCA for a given subject).ICAAROMAICA-AROMA are only applicable to fMRIprep output generated with--use-aroma. Pros: pretty similar to CompCor, with better control of discarded components (those can be visually reviewed even though this is time consuming. Cons: may require retraining the noise detector and also requires to believe that ICA does efficiently separate noise from signal, which is not that clear, and the quality of separation may also vary substantially across subjects.A note on nifti files and file collectionsNote that if a.nii.gzfile is specified,load_confoundswill automatically look for the companiontsvconfound file generated by fMRIprep. It is also possible to specify a list of confound (or imaging) files, in which caseload_confoundswill return a list of numpy ndarray.A note on low pass filteringLow pass filtering is a common operation in resting-state fMRI analysis, and is featured in all preprocessing strategies of the Ciric et al. (2017) paper. fMRIprep does not output the discrete cosines for low pass filtering. Instead, this operation can be implemented directly with the nilearn masker, using the argumentlow_pass. Be sure to also specify the argumenttrin the nilearn masker if you uselow_pass.A note on high pass filtering and detrendingNilearn masker features two arguments to remove slow time drifts:high_passanddetrend. Both of these operations are redundant with thehigh_passregressors generated by fMRIprep, and included in allload_confoundsstrategies. Do not use nilearn'shigh_passordetrendoptions with these strategies. It is however possible to use a flexibleConfoundsloader to exclude thehigh_passnoise components, and then rely on nilearn's high pass filterning or detrending options. This is not advised withcompcororica_aromaanalysis, which have been generated with thehigh_passcomponents of fMRIprep.A note on demeaning confoundsUnless you use thedetrendorhigh_passoptions of nilearn maskers, it may be important to demean the confounds. This is done by default byload_confounds, and is required to properly regress out confounds using nilearn with thestandardize=False,standardize=Trueorstandardize="zscore"options. If you want to usestandardize="psc", you will need to turn off the demeaning inload_confounds, which can be achieved using, e.g.:fromload_confoundsimportParams6conf=Params6(demean=False)A note on the choice of strategiesWe decided to focus our strategy catalogue on a reasonable but limited set of choices, and followed (mostly) the Ciric et al. (2017) reference. However, there are other strategies proposed in benchmarks such as (Parkes et al. 2018, Mascali et al. 2020).  Advanced users can still explore these other choices using the flexibleConfoundsAPI, which can be used to reproduce most denoising strategies in a single short and readable command.A note on denoising benchmarksThere has been a number of benchmarks you may want to refer to in order to select a denoising strategy (e.g. Ciric et al., 2017; Parkes et al. 2018; Mascali et al., 2020; Raval et al., 2020). However, a number of caveats do apply and the conclusions of these studies may not directly apply toload_confoundsstrategies. First, the noise regressors generated by fMRIprep do not necessarily follow the same implementations as these papers did. For example, the wayload_confoundsimplements scrubbing is by adding regressors, while Ciric et al. (2017) excluded outlier time points prior to regressing other confounds. There are also other aspects of the fMRI preprocessing pipelines which are not controlled byload_confounds. For example, Ciric et al. (2017) did apply image distortion correction in all preprocessing strategies. This step is controlled by fMRIprep, and cannot be changed throughload_confounds.A note about ICA-AROMA denoisingICA-AROMA related strategies are only applicable to fMRIprep output generated with--use-aroma. The approach predefined inload_confoundsis the non-aggressive apporach, and the recommanded way of applying ICA-AROMA. fMRIprep produces files with suffixdesc-smoothAROMAnonaggr_bold. Other noise regressors needed are retrieved by the predefined strategy inload_confounds. For details of the implementation, please refer to the documentation ofload_confounds.ICAAROMA.The aggressive approach was described in Pruim et al. (2015) and achieve denoising in one step byload_confound. Noise independent components along with other source of noise are included in confound regressors. The aggressive approachmustbe applied to the regular minimally processed fMRIprep output suffixeddesc-prepro_bold. The name "aggressive" reflects that this approach doesn't consider the potential good signals regressed out by the noise independent compoenents. Please refer to tableRecreating strategies from Ciric et al. 2017for the relevant options.Recreating strategies from Ciric et al. 2017load_confoundscan recreate the following strategies. The following table highlights the relevant options:Strategyhigh_passmotionwm_csfglobalcompcorica_aromascrubParams2xbasicParams6xbasicParams9xbasicbasicbasicParams9ScrubxbasicbasicfullParams24xfullParams36xfullfullfullParams36ScrubxfullfullfullAnatCompCorxfullanatTempCompCorxtempICAAROMAxbasicfullAROMAGSRxbasicbasicfullAggrICAAROMAxbasicbasicbasicFundingDevelopment of this library was supported in part by the Canadian Consortium on Neurodegeneration in Aging (CCNA) and in part by the Courtois Foundation.ReferencesBehzadi Y, Restom K, Liau J, Liu TT. A component based noise correction method (CompCor) for BOLD and perfusion based fMRI. Neuroimage. 2007. doi:10.1016/j.neuroimage.2007.04.042Ciric R, Wolf DH, Power JD, Roalf DR, Baum GL, Ruparel K, Shinohara RT, Elliott MA, Eickhoff SB, Davatzikos C., Gur RC, Gur RE, Bassett DS, Satterthwaite TD. Benchmarking of participant-level confound regression strategies for the control of motion artifact in studies of functional connectivity. Neuroimage. 2017. doi:10.1016/j.neuroimage.2017.03.020Esteban O, Markiewicz CJ, Blair RW, Moodie CA, Isik AI, Erramuzpe A, Kent JD, Goncalves M, DuPre E, Snyder M, Oya H, Ghosh SS, Wright J, Durnez J, Poldrack RA, Gorgolewski KJ. fMRIPrep: a robust preprocessing pipeline for functional MRI. Nat Meth. 2018. doi:10.1038/s41592-018-0235-4Fox MD, Snyder AZ, Vincent JL, Corbetta M, Van Essen DC, Raichle ME. The human brain is intrinsically organized into dynamic, anticorrelated functional networks. Proceedings of the National Academy of Sciences. 2005; doi:10.1073/pnas.0504136102.Mascali, D, Moraschi, M, DiNuzzo, M, et al. Evaluation of denoising strategies for task‐based functional connectivity: Equalizing residual motion artifacts between rest and cognitively demanding tasks. Hum Brain Mapp. 2020; 1– 24. doi:10.1002/hbm.25332Parkes, L., Fulcher, B., Yucel, M., & Fornito, A. (2018). An evaluation of the efficacy, reliability, and sensitivity of motion correction strategies for resting-state functional MRI. NeuroImage, 171, 415-436. doi:10.1016/j.neuroimage.2017.12.073Power JD, Mitra A, Laumann TO, Snyder AZ, Schlaggar BL, Petersen SE. Methods to detect, characterize, and remove motion artifact in resting state fMRI. Neuroimage 2014 84:320-41. doi:10.1016/j.neuroimage.2013.08.048Pruim, R. H., Mennes, M., van Rooij, D., Llera, A., Buitelaar, J. K., & Beckmann, C. F. (2015). ICA-AROMA: A robust ICA-based strategy for removing motion artifacts from fMRI data. Neuroimage, 112, 267-277. doi:10.1016/j.neuroimage.2015.02.064V. Raval, K. P. Nguyen, C. Mellema and A. Montillo, "Improved motion correction for functional MRI using an omnibus regression model," 2020 IEEE 17th International Symposium on Biomedical Imaging (ISBI), 2020, pp. 1044-1047, doi:10.1109/ISBI45749.2020.9098688.Contributors ✨Thanks goes to these wonderful people (emoji key):François Paugam🚇💻👀⚠️🔣HanadS💻⚠️🔣🚇📖🤔Elizabeth DuPre🤔Hao-Ting Wang🤔💻🔣📖⚠️🐛Pierre Bellec💻🐛🤔🚇⚠️🔣📋🚧📆Steven Meisler🐛⚠️🔣💻📖🤔Chris Markiewicz🤔Shima Rastegarnia🐛Thibault PIRONT💻m-w-w📖This project follows theall-contributorsspecification. Contributions of any kind welcome!