From a20e75c6224204f17d6b910e30d22d15844d219a Mon Sep 17 00:00:00 2001 From: oesteban Date: Fri, 6 Dec 2019 10:32:22 -0800 Subject: [PATCH 1/7] DOC: Refinement of confounds documentation after #1877 This PR addresses further issues: - Address warnings 2) and 3) of #1049 - Close #1049, and I've opened #1905 to follow up conversations - Add documentation about DCT regressors, close #1167. - Address items 2) and 3) of #1521. --- docs/outputs.rst | 96 ++++++++++++++++++++++++++++++++++++------------ 1 file changed, 72 insertions(+), 24 deletions(-) diff --git a/docs/outputs.rst b/docs/outputs.rst index 4505c7765..eb1e5a4c9 100644 --- a/docs/outputs.rst +++ b/docs/outputs.rst @@ -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 -------------- @@ -285,16 +288,36 @@ 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``. - -- ``aroma_motion_XX`` - the motion-related components identified by ICA-AROMA. - -.. 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. +**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 regression to account +for these confounding signals. +Using the :abbr:`DCT (discrete cosine transform)` basis functions, *fMRIPrep* generates +these low-frequency predictors: + +- ``cosine_XX`` - DCT-basis regressors. + +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 the analysis includes your own high-pass filtering step, the ``cosine_XX`` + regressors may interfere (meaning, they may re-introduce drifts) if included + in the design matrix. + +.. admonition:: See also + + - A detailed explanation about temporal high-pass filtering is provided with + the `BrainVoyager User Guide + `_. + - `This comment + `__ + on an issue regarding CompCor regressors. **CompCor confounds**. :abbr:`CompCor (Component Based Noise Correction)` is a :abbr:`PCA (principal component analysis)`, @@ -315,18 +338,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 - `__ - 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: @@ -366,6 +377,43 @@ 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). + +.. caution:: + Similarly, if you are using anatomical or temporal CompCor it may not make sense + to use global signal regressors (``csf``, ``white_matter``, or ``global_signal``) - + see `#1049 `_. + +.. danger:: + *fMRIPrep* does high-pass filtering before running anatomical or temporal CompCor. + Therefore, when using CompCor regressors, the corresponding ``cosine_XX`` regressors + should be included too in the design matrix. + + +.. admonition:: See also + + This didactic `discussion on NeuroStars.org + `__ + 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 ICA-AROMA cleaned data (``~desc-smoothAROMAnonaggr_bold.nii.gz``), + do not include ICA-AROMA confounds during your design specification or denoising procedure. + Confounds and "carpet"-plot on the visual reports ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The visual reports provide several sections per task and run to aid designing From a82a808eaabde143e1c58c521130fabbe808311b Mon Sep 17 00:00:00 2001 From: oesteban Date: Fri, 6 Dec 2019 11:15:20 -0800 Subject: [PATCH 2/7] fix: very minor changes --- docs/outputs.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/outputs.rst b/docs/outputs.rst index eb1e5a4c9..a8ec16529 100644 --- a/docs/outputs.rst +++ b/docs/outputs.rst @@ -292,7 +292,7 @@ Spike regressors are stored in separate ``motion_outlier_XX`` columns. 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 regression to account +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: @@ -395,7 +395,6 @@ For CompCor decompositions, entries include: Therefore, when using CompCor regressors, the corresponding ``cosine_XX`` regressors should be included too in the design matrix. - .. admonition:: See also This didactic `discussion on NeuroStars.org From 8fd308d034b7e396218060eeb54c1d33696867e5 Mon Sep 17 00:00:00 2001 From: Oscar Esteban Date: Tue, 10 Dec 2019 09:38:54 -0800 Subject: [PATCH 3/7] Apply suggestions from code review Co-Authored-By: Chris Markiewicz --- docs/outputs.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/outputs.rst b/docs/outputs.rst index a8ec16529..a9f04644a 100644 --- a/docs/outputs.rst +++ b/docs/outputs.rst @@ -314,7 +314,7 @@ states* are removed before generating the cosine regressors. - A detailed explanation about temporal high-pass filtering is provided with the `BrainVoyager User Guide - `_. + `_. - `This comment `__ on an issue regarding CompCor regressors. @@ -393,7 +393,7 @@ For CompCor decompositions, entries include: .. danger:: *fMRIPrep* does high-pass filtering before running anatomical or temporal CompCor. Therefore, when using CompCor regressors, the corresponding ``cosine_XX`` regressors - should be included too in the design matrix. + should also be included in the design matrix. .. admonition:: See also From 58a0557c5f3b3c27bff0579178a785294d95dc8d Mon Sep 17 00:00:00 2001 From: oesteban Date: Tue, 10 Dec 2019 09:46:38 -0800 Subject: [PATCH 4/7] Address @effigies' comments --- docs/outputs.rst | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/outputs.rst b/docs/outputs.rst index a9f04644a..d7fec6a00 100644 --- a/docs/outputs.rst +++ b/docs/outputs.rst @@ -306,9 +306,8 @@ It is relevant to mention *effective* because initial time points identified as states* are removed before generating the cosine regressors. .. caution:: - If the analysis includes your own high-pass filtering step, the ``cosine_XX`` - regressors may interfere (meaning, they may re-introduce drifts) if included - in the design matrix. + If your analysis includes separate high-pass filtering, do not include + ``cosine_XX`` regressors in your design matrix. .. admonition:: See also @@ -413,6 +412,12 @@ ICA-AROMA can be enabled with the flag ``--use-aroma``. 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. +.. 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 From 70eb72565f12c87915b707ffc6e9905eac1ef0d1 Mon Sep 17 00:00:00 2001 From: oesteban Date: Tue, 10 Dec 2019 14:13:39 -0800 Subject: [PATCH 5/7] docs: add @rciric's suggestions --- docs/outputs.rst | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/outputs.rst b/docs/outputs.rst index d7fec6a00..f560eac0b 100644 --- a/docs/outputs.rst +++ b/docs/outputs.rst @@ -384,10 +384,21 @@ For CompCor decompositions, entries include: 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 global signal regressors (``csf``, ``white_matter``, or ``global_signal``) - + to use the ``csf``, or ``white_matter`` global regressors - see `#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. From 2ab938ffe0362cebccd6895e535d0831ffbd9f3e Mon Sep 17 00:00:00 2001 From: oesteban Date: Wed, 11 Dec 2019 10:59:22 -0800 Subject: [PATCH 6/7] docs: address @jdkent's comments on ICA-AROMA and other confounds --- docs/outputs.rst | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/outputs.rst b/docs/outputs.rst index f560eac0b..92821c63f 100644 --- a/docs/outputs.rst +++ b/docs/outputs.rst @@ -420,9 +420,17 @@ 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 ICA-AROMA cleaned data (``~desc-smoothAROMAnonaggr_bold.nii.gz``), + If you are already using ICA-AROMA's cleaned-data (``~desc-smoothAROMAnonaggr_bold.nii.gz``), do not include ICA-AROMA confounds during your design specification or denoising procedure. + Additionally, as per [Hallquist2013]_, when using ICA-AROMA's cleaned-data most of the + confound regressors should be recalculated (this feature is a work-in-progress, follow up on + `#1905 `__). + Surprisingly, `our simulations + `__ + (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. @@ -509,6 +517,10 @@ 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 `_ + .. [Hallquist2013] Hallquist MN, Hwang K, Luna B. The Nuisance of Nuisance Regression. + NeuroImage. 2013. doi:`10.1016/j.neuroimage.2013.05.116 + `_ + .. [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 `_ From 5fe23ae0ced4cc983ba1a2c5bccb31a4ace8be07 Mon Sep 17 00:00:00 2001 From: Oscar Esteban Date: Wed, 11 Dec 2019 14:59:31 -0800 Subject: [PATCH 7/7] Apply suggestions from code review Co-Authored-By: Chris Markiewicz Co-Authored-By: James Kent --- docs/outputs.rst | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/outputs.rst b/docs/outputs.rst index 92821c63f..78f608656 100644 --- a/docs/outputs.rst +++ b/docs/outputs.rst @@ -420,12 +420,12 @@ 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 ICA-AROMA's cleaned-data (``~desc-smoothAROMAnonaggr_bold.nii.gz``), + 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]_, when using ICA-AROMA's cleaned-data most of the - confound regressors should be recalculated (this feature is a work-in-progress, follow up on - `#1905 `__). + 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 `__). Surprisingly, `our simulations `__ (with thanks to JD. Kent) suggest that using the confounds as currently calculated by @@ -521,6 +521,11 @@ See implementation on :mod:`~fmriprep.workflows.bold.confounds.init_bold_confs_w NeuroImage. 2013. doi:`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 + `_ + .. [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 `_