DOC: Improving accessibility of confounds description

docs/outputs.rst

@@ -142,7 +142,43 @@ sampled to those subject spaces.
 Confounds
 ---------
 
-See implementation on :mod:`~fmriprep.workflows.bold.confounds.init_bold_confs_wf`.
+The :abbr:`BOLD (blood-oxygen level dependent)` signal measured with fMRI is a mixture of fluctuations
+of both neuronal and non-neuronal origin. Neuronal signals are measured indirectly as changes
+in the local concentration of oxygenated hemoglobin. Non-neuronal fluctuations in fMRI data
+may appear as a result of head motion, scanner noise, or physiological fluctuations
+(related to cardiac or respiratory effects) (see Greve et al. [Greve2013]_ for detailed review of the possible
+sources of noise in fMRI signal).
+
+*Confounds* (or nuisance regressors) are variables representing potential fluctuations
+of non-neuronal origin. Such non-neuronal fluctuations may drive spurious results in fMRI data analysis,
+including standard activation :abbr:`GLM (General Linear Model` and functional connectivity analyses.
+It is possible to minimize confounding effects of non-neuronal signals by including them as nuisance regressors
+in the :abbr:`GLM (General Linear Model` design matrix or regressing them out from
+the fMRI data - a procedure known as *denoising*.
+There is currently no consensus on an optimal denoising strategy in the fMRI community.
+Rather, different strategies have been proposed, which achieve different levels of trade-off between
+how much of the non-neuronal fluctuations are effectively removed, and how much of neuronal fluctuations
+are damaged in the process. The fMRIprep pipeline generates a large array of possible confounds.
+
+The best known confounding variables in neuroimaging are the six head motion parameters
+(three rotations and three translations) - the common output of the head motion correction
+(also known as *realignment*) of popular fMRI preprocessing software
+such as `SPM <https://www.fil.ion.ucl.ac.uk/spm/software/spm12/>`_
+or `FSL <https://fsl.fmrib.ox.ac.uk/fsl/fslwiki>`_. One of the biggest advantages of fMRPrep
+is the automatic calculation of multiple potential confounding variables beyond standard head motion parameters.
+
+Confounding variables calculated in fMRIPrep are stored separately for each subject,
+session and run in `TSV (tab-separated value)` files - one column for each confound variable.
+Such tabular files may include over 100 columns of potential confound regressors.
+
+.. warning::
+   Do not include all columns of `confounds_regressors.tsv` table
+   into your design matrix or denoising procedure. Filter the table first,
+   to include only the confounds you want to remove from your fMRI signal.
+   The choice of confounding variables may depend on the analysis you want to perform,
+   and may be not straightforward as no gold standard procedure exists.
+   For detailed description of various denoising strategies and their performance,
+   see Parkes et al. ([Parkes2018]_) and Ciric et al. ([Ciric2017]_).
 
 
 For each :abbr:`BOLD (blood-oxygen level dependent)` run processed with fMRIPrep, a
@@ -161,40 +197,102 @@ Each row of the file corresponds to one time point found in the
 corresponding :abbr:`BOLD (blood-oxygen level dependent)` time-series
 (stored in ``<output_folder>/fmriprep/sub-<sub_id>/func/sub-<sub_id>_task-<task_id>_run-<run_id>_desc-preproc_bold.nii.gz``).
 
-Columns represent the different confounds: ``csf`` and ``white_matter`` are the average signal
-inside the anatomically-derived :abbr:`CSF (cerebro-spinal fluid)` and :abbr:`WM (white matter)`
-masks across time;
-``global_signal`` corresponds to the mean time series within the brain mask; two columns relate to
-the derivative of RMS variance over voxels (or :abbr:`DVARS (defined in Power, et al. 2012)`), and
-both the original (``dvars``) and standardized (``std_dvars``) are provided;
-``framewise_displacement`` is a quantification of the estimated bulk-head motion;
-``trans_x``, ``trans_y``, ``trans_z``, ``rot_x``, ``rot_y``, ``rot_z`` are the 6 rigid-body
-motion-correction parameters estimated by fMRIPrep;
-if present, ``non_steady_state_outlier_XX`` columns indicate non-steady state volumes with a single
-``1`` value and ``0`` elsewhere (*i.e.*, there is one ``non_steady_state_outlier_XX`` column per
-outlier/volume);
-additional noise components are calculated using :abbr:`CompCor (Component Based Noise Correction)`,
-according to both the anatomical (``a_comp_cor_XX``) and temporal (``t_comp_cor_XX``) variants;
-and the motion-related components identified by
-:abbr:`ICA (independent components analysis)`-:abbr:`AROMA (Automatic Removal Of Motion Artifacts)`
-(if enabled) are indicated with ``aroma_motion_XX``.
+Confound regressors description
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Basic confouds
+==================
+
+- ``trans_x``, ``trans_y``, ``trans_z``, ``rot_x``, ``rot_y``, ``rot_z`` - the 6 rigid-body motion
+  parameters (3 translations and 3 rotation) estimated relative to a reference image;
+
+- ``csf`` - the average signal within anatomically-derived eroded :abbr:`CSF (cerebro-spinal fluid)` mask;
+
+- ``white_matter`` - the average signal within  the anatomically-derived eroded :abbr:`WM (white matter)` masks;
+
+- ``global_signal`` -  the average signal within the brain mask.
+
+Parameter expansion of basic confounds
+=====================
+Regressing out the standard six motion parameters may not be sufficient to remove all variance related to head motion
+from the fMRI signal. Thus, Friston et al. ([Friston1996]_) and Satterthwaite et al. ([Satterthwaite2013]_)
+proposed *24-motion-parameter* expansion, with a goal of removing from fMRI signal as much of the motion-related
+variance as possible. To make this technique more accessible, fMRIPrep automaticaly calculates motion parameter
+expansion ([Satterthwaite2013]_), providing timeseries corresponding to first *temporal derivatives* of six motion
+parameters, together with their *quadratic terms*, resulting in the total 24 head motion parameters
+(6 standard motion parameters + 6 temporal derivatives of six motion parameters + 12 quadratic terms of 6 motion
+parameters and their 6 temporal derivatives). Additionally, fMRIPrep returns temporal derivatives and quadratic
+terms for the ``csf``, ``white_matter`` and ``global_signal`` to enable applying 36-parameter denoising strategy
+proposed by Satterthwaite et al. ([Satterthwaite2013]_).
+
+Derivatives and quadratic terms are stored under column
+names with suffixes: ``_derivative1`` and powers ``_power2``. These were calculated for head motion estimates
+(``trans_`` and ``rot_``) and compartment signals
+(``white_matter``, ``csf``, and ``global_signal``).
+
+
+Confounds for outlier detection
+======================================
+
+- ``framewise_displacement`` - is a quantification of the estimated bulk-head motion calculated using
+  formula proposed by Power et al. ([Power2012]_);
+- ``dvars`` - the derivative of RMS variance over voxels (or :abbr:`DVARS`)([Power2012]_)
+- ``std_dvars`` - standardized DVARS;
+- ``non_steady_state_outlier_XX`` - columns indicate non-steady state volumes with a single
+  ``1`` value and ``0`` elsewhere (*i.e.*, there is one ``non_steady_state_outlier_XX`` column per
+  outlier/volume).
+
+All these confounds can be used to detect potential outlier time points - frames with high motion or spikes.
+Detected outliers can be further removed from time-series using methods such as: volume *censoring* - entirely
+discarding problematic time points ([Power2012]_), regressing signal from outlier points in denoising procedure,
+or including outlier points in the subsequent first-level analysis when building the design matrix.
+Averaged value of confound (for example, mean ``framewise_displacement``)
+can be added as a regressor in group level analysis ([Yan2013]_).
 
-Four separate CompCor decompositions are performed to compute noise components: one temporal
-decomposition and three anatomical decompositions across three different noise ROIs: an eroded
-white matter compartment, an eroded CSF compartment, and a combined mask derived from the union
-of these.
-In general, only a subset of these decompositions should be used for further denoising.
-The original Behzadi aCompCor implementation ([Behzadi2007]_) can be applied using
-components from the combined ROI, while the more recent Muschelli implementation
-([Muschelli2014]_) can be applied using the WM and CSF ROIs.
-To determine the provenance of each component, consult the metadata file (see below).
-
-All these confounds can be used to perform *scrubbing* and *censoring* of outliers,
-in the subsequent first-level analysis when building the design matrix,
-and in group level analysis.
 *Spike regressors* for outlier censoring can also be generated from within fMRIPrep using
-the command line options ``--fd-spike-threshold`` and ``--dvars-spike-threshold``.
-Spike regressors are stored in separate ``motion_outlier_XX`` columns.
+the command line options ``--fd-spike-threshold`` and ``--dvars-spike-threshold``
+(default: FD > 0.5 mm or DVARS > 1.5). Spike regressors are stored in separate ``motion_outlier_XX``
+columns.
+
+ICA-AROMA confounds
+========================
+
+
+- ``aroma_motion_XX`` - the motion-related components identified by :abbr:`ICA (independent components analysis)`
+  -:abbr:`AROMA (Automatic Removal Of Motion Artifacts)` (if enabled with a flag ``--use-aroma``) .
+
+.. warning::
+    If you are already using ICA-AROMA cleaned data (``~desc-smoothAROMAnonaggr_bold.nii.gz``),
+    do not include ICA-AROMA confounds during your design specification or denoising procedure.
+
+
+CompCor confounds
+=====================
+
+:abbr:`CompCor (Component Based Noise Correction)` is a component-based noise correlation method. In the method,
+principal components are derived from :abbr:`ROI (Region of Interest)` which is unlikely to include signal
+related to neuronal activity, such as :abbr:`CSF (cerebro-spinal fluid)` and abbr:`WM (white matter)`
+masks. Signals extracted from CompCor components can be further regressed out from the fMRI data during
+denoising procedure ([Behzadi2007]_).
+
+- ``a_comp_cor_XX`` - additional noise components are calculated using anatomical :abbr:`CompCor
+  (Component Based Noise Correction)`;
+- ``t_comp_cor_XX``) - additional noise components are calculated using anatomical :abbr:`CompCor
+  (Component Based Noise Correction)`.
+
+Four separate CompCor decompositions are performed to compute noise components: one temporal
+decomposition (``t_comp_cor_XX``) and three anatomical decompositions (``a_comp_cor_XX``) across
+three different noise ROIs: an eroded white matter mask, an eroded CSF mask, and a combined mask derived
+from the union of these.
+
+
+.. warning::
+    Only a subset of these CompCor decompositions should be used for further denoising.
+    The original Behzadi aCompCor implementation ([Behzadi2007]_) can be applied using
+    components from the combined masks, while the more recent Muschelli implementation
+    ([Muschelli2014]_) can be applied using
+    the :abbr:`WM (white matter)` and :abbr:`CSF (cerebro-spinal fluid)` masks. To determine the provenance
+    of each component, consult the metadata file (see below).
 
 Each confounds data file will also have a corresponding metadata file (``~desc-confounds_regressors.json``).
 Metadata files contain additional information about columns in the confounds TSV file: ::
@@ -291,15 +389,53 @@ to which tissue-specific regressors correlate with global signal.
     are those with greatest correlation with the global signal.
     This information can be used to diagnose partial volume effects.
 
+See implementation on :mod:`~fmriprep.workflows.bold.confounds.init_bold_confs_wf`.
+
 .. topic:: References
 
   .. [Behzadi2007] Behzadi 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.042 <http://doi.org/10.1016/j.neuroimage.2007.04.042>`_
 
+  .. [Ciric2017] Ciric 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.020 <https://doi.org/10.1016/j.neuroimage.2017.03.020>`_
+
+  .. [Greve2013] Greve DN, Brown GG, Mueller BA, Glover G, Liu TT, A Survey of the Sources of Noise in fMRI
+     Psychometrika. 2013. doi: `10.1007/s11336-013-9344-2 <http://dx.doi.org/10.1007/s11336-013-9344-2>`_
+
+  .. [Friston1996] Friston KJ1, Williams S, Howard R, Frackowiak RS, Turner R, Movement‐Related effects in fMRI
+     time‐series.
+     Magnetic Resonance in Medicine. 1996. doi: `10.1002/mrm.191035031 < https://doi.org/10.1002/mrm.1910350312>`_
+
   .. [Muschelli2014] Muschelli J, Nebel MB, Caffo BS, Barber AD, Pekar JJ, Mostofsky SH,
      Reduction of motion-related artifacts in resting state fMRI using aCompCor.
      NeuroImage. 2014. doi: `10.1016/j.neuroimage.2014.03.028 <http://doi.org/10.1016/j.neuroimage.2014.03.028>`_
 
+  .. [Parkes2018] Parkes L, Fulcher B, Yücel M, Fornito A, An evaluation of the efficacy, reliability,
+     and sensitivity of motion correction strategies for resting-state functional MRI.
+     NeuroImage. 2018. doi: `10.1016/j.neuroimage.2017.12.073 <https://doi.org/10.1016/j.neuroimage.2017.12.073>`_
+
+  .. [Power2012] Power JD, Barnes KA, Snyder AZ, Schlaggar BL, Petersen, SA, Spurious but systematic
+     correlations in functional connectivity MRI networks arise from subject motion.
+     NeuroImage. 2012. doi: `10.1016/j.neuroimage.2011.10.018 <https://doi.org/10.1016/j.neuroimage.2011.10.018>`_
+
   .. [Power2016] Power JD, A simple but useful way to assess fMRI scan qualities.
      NeuroImage. 2016. doi: `10.1016/j.neuroimage.2016.08.009 <http://doi.org/10.1016/j.neuroimage.2016.08.009>`_
+
+  .. [Satterthwaite2013] Satterthwaite TD, Elliott MA, Gerraty RT, Ruparel K, Loughead J, Calkins ME, Eickhoff SB,
+     Hakonarson H, Gur RC, Gur RE, Wolf DH, An improved framework for confound regression and filtering for control
+     of motion artifact in the preprocessing of resting-state functional connectivity data.
+     NeuroImage. 2013. doi: `10.1016/j.neuroimage.2012.08.052 <https://doi.org/10.1016/j.neuroimage.2012.08.052>`_
+
+  .. [Yan2013] Yan CG, Cheung B, Kelly C, Colcombe S, Craddock RC, Di Martino A, Li Q, Zuo XN, Castellanos FX,
+     Milham MP, A comprehensive assessment of regional variation in the impact of head micromovements
+     on functional connectomics.
+     NeuroImage. 2013. doi: `10.1016/j.neuroimage.2013.03.004 <https://doi.org/10.1016/j.neuroimage.2013.03.004>`_
+
+
+
+
+
+