Skip to content

Commit

Permalink
docs: Merge pull request #1906 from poldracklab/docs/issue-1049
Browse files Browse the repository at this point in the history 
DOC: Refinement of confounds documentation after #1877
  • Loading branch information
@oesteban
oesteban committed Dec 11, 2019
2 parents 9d8ef51 + 5fe23ae commit ca65f35
Showing 1 changed file with 102 additions and 22 deletions.
124 changes: 102 additions & 22 deletions docs/outputs.rst
View file
Expand Up @@ -29,8 +29,11 @@ Derivatives specification (see `BIDS Derivatives RC1`_).
.. important::
In order to remain agnostic to any possible subsequent analysis,
*fMRIPrep* does not perform any denoising (e.g., spatial smoothing) itself.
The only exception to this principle is the ICA-AROMA's *non-aggressive* denoising
(see below).
There are two exceptions to this principle (described in their corresponding
sections below):

- ICA-AROMA's *non-aggressive* denoised outputs, and
- CompCor regressors, which are calculated after temporal high-pass filtering.

Visual Reports
--------------
Expand Down Expand Up @@ -292,16 +295,35 @@ 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.

**AROMA confounds**.
:abbr:`AROMA (Automatic Removal Of Motion Artifacts)` is an :abbr:`ICA (independent components analysis)`
based procedure to identify confounding time series related to head-motion [Prium2015]_.
ICA-AROMA can be enabled with the flag ``--use-aroma``.
**Discrete cosine-basis regressors**.
Physiological and instrumental (scanner) noise sources are generally present in fMRI
data, typically taking the form of low-frequency signal drifts.
To account for these drifts, temporal high-pass filtering is the immediate option.
Alternatively, low-frequency regressors can be included in the statistical model to account
for these confounding signals.
Using the :abbr:`DCT (discrete cosine transform)` basis functions, *fMRIPrep* generates
these low-frequency predictors:

- ``aroma_motion_XX`` - the motion-related components identified by ICA-AROMA.
- ``cosine_XX`` - DCT-basis regressors.

.. danger::
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.
One characteristic of the cosine regressors is that they are identical for two different
datasets with the same :abbr:`TR (repetition time)` and the same *effective* number of
time points (*effective* length).
It is relevant to mention *effective* because initial time points identified as *nonsteady
states* are removed before generating the cosine regressors.

.. caution::
If your analysis includes separate high-pass filtering, do not include
``cosine_XX`` regressors in your design matrix.

.. admonition:: See also

- A detailed explanation about temporal high-pass filtering is provided with
the `BrainVoyager User Guide
<https://www.brainvoyager.com/bvqx/doc/UsersGuide/Preprocessing/TemporalHighPassFiltering.html>`_.
- `This comment
<https://github.com/poldracklab/fmriprep/issues/1899#issuecomment-561687460>`__
on an issue regarding CompCor regressors.

**CompCor confounds**.
:abbr:`CompCor (Component Based Noise Correction)` is a :abbr:`PCA (principal component analysis)`,
Expand All @@ -322,18 +344,6 @@ decomposition (``t_comp_cor_XX``) and three anatomical decompositions (``a_comp_
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).
Make sure you check on `this didactic discussion on NeuroStars.org
<https://neurostars.org/t/fmrirep-outputs-very-high-number-of-acompcors-up-to-1000/5451>`__
where Patrick Sadil gets into details about PCA and how that base technique applies
to CompCor in general and *fMRIPrep*'s implementation in particular.

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:
Expand Down Expand Up @@ -373,6 +383,67 @@ For CompCor decompositions, entries include:
Entries that are not saved in the data file for denoising are still stored in metadata with the
``dropped`` prefix.

.. caution::
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 (described above).

There are many valid ways of selecting CompCor components for further denoising.
In general, the components with the largest singular values (i.e., those that
explain the largest fraction of variance in the data) should be selected.
*fMRIPrep* outputs components in descending order of singular value.
Common approaches include selecting a fixed number of components (e.g., the
first 5 or 6), using a quantitative or qualitative criterion (e.g., elbow, broken
stick, or condition number), or using sufficiently many components that a minimum
cumulative fraction of variance is explained (e.g., 50%).

.. caution::
Similarly, if you are using anatomical or temporal CompCor it may not make sense
to use the ``csf``, or ``white_matter`` global regressors -
see `#1049 <https://github.com/poldracklab/fmriprep/issues/1049>`_.
Conversely, using the overall ``global_signal`` confound in addition to CompCor's
regressors can be beneficial (see [Parkes2018]_).

.. danger::
*fMRIPrep* does high-pass filtering before running anatomical or temporal CompCor.
Therefore, when using CompCor regressors, the corresponding ``cosine_XX`` regressors
should also be included in the design matrix.

.. admonition:: See also

This didactic `discussion on NeuroStars.org
<https://neurostars.org/t/fmrirep-outputs-very-high-number-of-acompcors-up-to-1000/5451>`__
where Patrick Sadil gets into details about PCA and how that base technique applies
to CompCor in general and *fMRIPrep*'s implementation in particular.

**AROMA confounds**.
:abbr:`AROMA (Automatic Removal Of Motion Artifacts)` is an :abbr:`ICA (independent components analysis)`
based procedure to identify confounding time series related to head-motion [Prium2015]_.
ICA-AROMA can be enabled with the flag ``--use-aroma``.

- ``aroma_motion_XX`` - the motion-related components identified by ICA-AROMA.

.. danger::
If you are already using AROMA-cleaned data (``~desc-smoothAROMAnonaggr_bold.nii.gz``),
do not include ICA-AROMA confounds during your design specification or denoising procedure.

Additionally, as per [Hallquist2013]_ and [Lindquist2019]_, when using AROMA-cleaned data
most of the confound regressors should be recalculated (this feature is a work-in-progress,
follow up on `#1905 <https://github.com/poldracklab/fmriprep/issues/1905>`__).
Surprisingly, `our simulations
<https://github.com/poldracklab/fmriprep-notebooks/blob/9933a628dfb759dc73e61701c144d67898b92de0/05%20-%20Discussion%20AROMA%20confounds%20-%20issue-817%20%5BJ.%20Kent%5D.ipynb>`__
(with thanks to JD. Kent) suggest that using the confounds as currently calculated by
*fMRIPrep* --before denoising-- would be just fine.

.. caution::
*Nonsteady-states* (or *dummy scans*) in the beginning of every run
are dropped **before** ICA-AROMA is performed.
Therefore, any subsequent analysis of ICA-AROMA outputs must drop the same
number of *nonsteady-states*.

Confounds and "carpet"-plot on the visual reports
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The visual reports provide several sections per task and run to aid designing
Expand Down Expand Up @@ -453,6 +524,15 @@ See implementation on :mod:`~fmriprep.workflows.bold.confounds.init_bold_confs_w
Movement‐Related effects in fMRI time‐series. Magnetic Resonance in Medicine. 1996.
doi:`10.1002/mrm.191035031 <https://doi.org/10.1002/mrm.1910350312>`_
.. [Hallquist2013] Hallquist MN, Hwang K, Luna B. The Nuisance of Nuisance Regression.
NeuroImage. 2013. doi:`10.1016/j.neuroimage.2013.05.116
<https://doi.org/10.1016/j.neuroimage.2013.05.116>`_
.. [Lindquist2019] Lindquist, MA, Geuter, S, and Wager, TD, Caffo, BS,
Modular preprocessing pipelines can reintroduce artifacts into fMRI data.
Human Brain Mapping. 2019. doi: `10.1002/hbm.24528
<https://doi.org/10.1002/hbm.24528>`_
.. [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>`_
Expand Down

0 comments on commit ca65f35

Please sign in to comment.