DOC: Improving accessibility of confounds description

docs/links.rst

@@ -17,4 +17,5 @@
 .. _`Docker installation`: https://docs.docker.com/install/
 .. _`Docker Hub`: https://hub.docker.com/r/poldracklab/fmriprep/tags
 .. _Singularity: https://github.com/singularityware/singularity
-.. _TACC: https://www.tacc.utexas.edu/
+..  _SPM: https://www.fil.ion.ucl.ac.uk/spm/software/spm12/
+.. _TACC: https://www.tacc.utexas.edu/

docs/outputs.rst

@@ -6,12 +6,12 @@
 Outputs of fMRIPrep
 -------------------
 
-FMRIPrep generates three broad classes of outcomes:
+*FMRIPrep* generates three broad classes of outcomes:
 
   1. **Visual QA (quality assessment) reports**:
      one :abbr:`HTML (hypertext markup language)` per subject,
      that allows the user a thorough visual assessment of the quality
-     of processing and ensures the transparency of fMRIPrep operation.
+     of processing and ensures the transparency of *fMRIPrep* operation.
 
   2. **Pre-processed imaging data** which are derivatives of the original
      anatomical and functional images after various preparation procedures
@@ -25,13 +25,13 @@ FMRIPrep generates three broad classes of outcomes:
      between different spaces or the estimated confounds.
 
 
-fMRIPrep outputs conform to the :abbr:`BIDS (brain imaging data structure)`
+*FMRIPrep* outputs conform to the :abbr:`BIDS (brain imaging data structure)`
 Derivatives specification (see `BIDS Derivatives RC1`_).
 
 Visual Reports
 --------------
 
-FMRIPrep outputs summary reports, written to ``<output dir>/fmriprep/sub-<subject_label>.html``.
+*FMRIPrep* outputs summary reports, written to ``<output dir>/fmriprep/sub-<subject_label>.html``.
 These reports provide a quick way to make visual inspection of the results easy.
 Each report is self contained and thus can be easily shared with collaborators (for example via email).
 `View a sample report. <_static/sample_report.html>`_
@@ -142,10 +142,47 @@ sampled to those subject spaces.
 Confounds
 ---------
 
-See implementation on :mod:`~fmriprep.workflows.bold.confounds.init_bold_confs_wf`.
-
-
-For each :abbr:`BOLD (blood-oxygen level dependent)` run processed with fMRIPrep, a
+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).
+For a detailed review of the possible sources of noise in the BOLD signal, refer to [Greve2013]_.
+
+*Confounds* (or nuisance regressors) are variables representing fluctuations with a potential 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 compromises 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_ or FSL_.
+One of the biggest advantages of *fMRIPrep* 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 :abbr:`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
 ``<output_folder>/fmriprep/sub-<sub_id>/func/sub-<sub_id>_task-<task_id>_run-<run_id>_desc-confounds_regressors.tsv``
 file will be generated.
 These are :abbr:`TSV (tab-separated values)` tables, which look like the example below: ::
@@ -161,40 +198,105 @@ 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]_).
+
+*Spike regressors* for outlier censoring can also be generated from within *fMRIPrep* using
+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 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.
+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: ::
@@ -257,9 +359,9 @@ to the fraction of variance that they explain across the nuisance ROI.
 This is used by *fMRIPrep* to determine whether each component should be saved for
 use in denoising operations: a component is saved if it contributes to explaining
 the top 50 percent of variance in the nuisance ROI.
-*fMRIPrep* can be configured to save all components instead using the command line
+*FMRIPrep* can be configured to save all components instead using the command line
 option ``--return-all-components``.
-*fMRIPrep* reports include a plot of the cumulative variance explained by each
+*FMRIPrep* reports include a plot of the cumulative variance explained by each
 component, ordered by descending singular value.
 
 .. figure:: _static/sub-01_task-rest_compcor.svg
@@ -291,15 +393,49 @@ 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>`_
+
+