From c7dff62a6ac22b8a5ce3027aa8f50194ad312e0d Mon Sep 17 00:00:00 2001 From: kfinc Date: Fri, 22 Nov 2019 12:19:14 +0100 Subject: [PATCH 01/21] [DOC] Added introduction to confounds variables --- docs/outputs.rst | 58 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 57 insertions(+), 1 deletion(-) diff --git a/docs/outputs.rst b/docs/outputs.rst index e65e99ebd..e7e364506 100644 --- a/docs/outputs.rst +++ b/docs/outputs.rst @@ -142,7 +142,44 @@ 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 [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 General Linear Model (GLM) and functional connectivity analyses. +It is possible to minimize confounding effects of non-neuronal signals by including them as nuisance regressors +in the GLM design matrix (activation analysis) or regressing them out from +the fMRI data - a procedure known as *denoising* (functional connectivity analysis). +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 main categories and denoising strategies available are reviewed below. + +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 (realignment) +of popular fMRI preprocessing software such as SPM or FSL. 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. +Such tabular files may include over 100 columns of potential confound regressors. +We can classify them into three main classes, related to: +(1) head motion, (2) physiological effects, and (3) scanner effects. + +.. 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 exist. + For detailed description of various denoising strategies and their performance, + see [Parkes2018]_ and [Ciric2017]_. For each :abbr:`BOLD (blood-oxygen level dependent)` run processed with fMRIPrep, a @@ -291,15 +328,34 @@ 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 `_ + .. [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 `_ + + .. [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 `_ + .. [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 `_ + .. [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 `_ + .. [Power2016] Power JD, A simple but useful way to assess fMRI scan qualities. NeuroImage. 2016. doi: `10.1016/j.neuroimage.2016.08.009 `_ + + + + + From 8bd311f57ed927d69345c344222f6f1f2203d464 Mon Sep 17 00:00:00 2001 From: kfinc Date: Fri, 22 Nov 2019 16:52:22 +0100 Subject: [PATCH 02/21] [DOC] Added introduction to confounds variables --- docs/outputs.rst | 136 ++++++++++++++++++++++++++++++++++------------- 1 file changed, 99 insertions(+), 37 deletions(-) diff --git a/docs/outputs.rst b/docs/outputs.rst index e7e364506..47adb150c 100644 --- a/docs/outputs.rst +++ b/docs/outputs.rst @@ -146,14 +146,14 @@ The :abbr:`BOLD (blood-oxygen level dependent)` signal measured with fMRI is a m 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 [Greve2013]_ for detailed review of the possible +(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 General Linear Model (GLM) and functional connectivity analyses. +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 GLM design matrix (activation analysis) or regressing them out from +in the :abbr:`GLM (General Linear Model` design matrix (activation analysis) or regressing them out from the fMRI data - a procedure known as *denoising* (functional connectivity analysis). 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 @@ -163,23 +163,22 @@ The main categories and denoising strategies available are reviewed below. 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 (realignment) -of popular fMRI preprocessing software such as SPM or FSL. One of the biggest advantages of fMRPrep +of popular fMRI preprocessing software such as `SPM `_ +or `FSL `_. 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. +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. -We can classify them into three main classes, related to: -(1) head motion, (2) physiological effects, and (3) scanner effects. .. 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 exist. + and may be not straightforward as no gold standard procedure exists. For detailed description of various denoising strategies and their performance, - see [Parkes2018]_ and [Ciric2017]_. + see Parkes et al. [Parkes2018]_ and Ciric et al. [Ciric2017]_. For each :abbr:`BOLD (blood-oxygen level dependent)` run processed with fMRIPrep, a @@ -198,33 +197,70 @@ Each row of the file corresponds to one time point found in the corresponding :abbr:`BOLD (blood-oxygen level dependent)` time-series (stored in ``/fmriprep/sub-/func/sub-_task-_run-_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 +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 inside the anatomically-derived eroded :abbr:`CSF (cerebro-spinal fluid)` eroded mask; + +- ``white_matter`` - the average signal inside the anatomically-derived eroded :abbr:`WM (white matter)` masks; + +- ``global_signal`` - time series within the brain mask; + +Parameter expansion of basic confounds +===================== +Regressing out the standard six motion parameters may be not sufficient to remove all variance related to motion +from the fMRI signal, therefore Friston et al. [Friston1996]_) and Satterthwaite et al. [Satterthwaite2013]_ proposed +24-motion-parameter expansion. To take this into account, fMRIPrep’s confound table additionally includes the +first temporal derivatives of six motion parameters, together with their quadratic terms, +resulting in 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). +Derivatives and quadratic terms are stored under column names wih suffixes: ``_derivative1`` and powers ``_power2``, +and are calculated for head motion estimates (``trans_`` and ``rot_``) and compartment signals +(``wm``,``csf``, and ``global_signal``). These expansion terms are included in some confound regression pipelines +in addition to the first-order term. + +CompCor +============== + +:abbr:`CompCor (Component Based Noise Correction)` is a component-based noise correlation method. In the method +principal components are are derived from :abbr:`ROI (Region of Interest)` which is unlikely to include signal +related to brain activity. Signal from CompCor components can be further regressed out from the +wich principal components of signal within noise ROI ([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)`; + +.. warning:: + Four separate CompCor decompositions are performed to compute noise components: one temporal + decomposition (``t_comp_cor_XX``) and three anatomical decompositions across three different noise ROIs: an eroded + white matter mask, an eroded CSF mask, and a combined mask derived from the union + of these. 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 masks, while the more recent Muschelli implementation + ([Muschelli2014]_) can be applied using + the :abbr:`WM (white matter)` and :abbr:`CSF (cerebro-spinal fluid)` masks. + + +Outlier confounds +======================== + +- (``dvars``) - the derivative of RMS variance over voxels (or :abbr:`DVARS (defined in Power, et al. 2012)` +- ``std_dvars`` - standardized DVARS +- ``framewise_displacement`` - is a quantification of the estimated bulk-head motion estimated using [Power2012]_ +formula; +- ``non_steady_state_outlier_XX`` - if present, 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``. - -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, @@ -233,6 +269,19 @@ and in group level analysis. the command line options ``--fd-spike-threshold`` and ``--dvars-spike-threshold``. Spike regressors are stored in separate ``motion_outlier_XX`` columns. +ICA-AROMA confounds +======================== + +To determine the provenance of each component, consult the metadata file (see below). +- ``aroma_motion_XX`` - the motion-related components identified by :abbr:`ICA (independent components analysis)` +-:abbr:`AROMA (Automatic Removal Of Motion Artifacts)` +(if enabled with ``--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. + + 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: :: @@ -341,20 +390,33 @@ See implementation on :mod:`~fmriprep.workflows.bold.confounds.init_bold_confs_w confound regression strategies for the control of motion artifact in studies of functional connectivity. Neuroimage. 2017. doi: `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 + .. [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 `_ .. [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 `_ - .. [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. + .. [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 `_ .. [Power2016] Power JD, A simple but useful way to assess fMRI scan qualities. NeuroImage. 2016. doi: `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 `_ + + .. [Friston1996] Movement‐Related effects in fMRI time‐series, + Magnetic Resonance in Medicine. 1996. doi: `10.1002/mrm.191035031 < https://doi.org/10.1002/mrm.1910350312>`_ + + + + + + From 91fc0be21b7e94922949f1f9f4db518e00d9abe8 Mon Sep 17 00:00:00 2001 From: kfinc Date: Fri, 22 Nov 2019 21:44:59 +0100 Subject: [PATCH 03/21] [DOC] More references and description --- docs/outputs.rst | 160 ++++++++++++++++++++++++++--------------------- 1 file changed, 89 insertions(+), 71 deletions(-) diff --git a/docs/outputs.rst b/docs/outputs.rst index 47adb150c..bdb28634e 100644 --- a/docs/outputs.rst +++ b/docs/outputs.rst @@ -153,17 +153,17 @@ sources of noise in fMRI signal). 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 (activation analysis) or regressing them out from -the fMRI data - a procedure known as *denoising* (functional connectivity analysis). +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 main categories and denoising strategies available are reviewed below. 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 (realignment) -of popular fMRI preprocessing software such as `SPM `_ +(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 fMRPrep is the automatic calculation of multiple potential confounding variables beyond standard head motion parameters. @@ -178,7 +178,7 @@ Such tabular files may include over 100 columns of potential confound regressors 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]_. + see Parkes et al. ([Parkes2018]_) and Ciric et al. ([Ciric2017]_). For each :abbr:`BOLD (blood-oxygen level dependent)` run processed with fMRIPrep, a @@ -206,82 +206,94 @@ 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 inside the anatomically-derived eroded :abbr:`CSF (cerebro-spinal fluid)` eroded mask; +- ``csf`` - the average signal within anatomically-derived eroded :abbr:`CSF (cerebro-spinal fluid)` mask; -- ``white_matter`` - the average signal inside the anatomically-derived eroded :abbr:`WM (white matter)` masks; +- ``white_matter`` - the average signal within the anatomically-derived eroded :abbr:`WM (white matter)` masks; -- ``global_signal`` - time series within the brain mask; +- ``global_signal`` - the average signal within the brain mask. Parameter expansion of basic confounds ===================== -Regressing out the standard six motion parameters may be not sufficient to remove all variance related to motion -from the fMRI signal, therefore Friston et al. [Friston1996]_) and Satterthwaite et al. [Satterthwaite2013]_ proposed -24-motion-parameter expansion. To take this into account, fMRIPrep’s confound table additionally includes the -first temporal derivatives of six motion parameters, together with their quadratic terms, -resulting in 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). -Derivatives and quadratic terms are stored under column names wih suffixes: ``_derivative1`` and powers ``_power2``, -and are calculated for head motion estimates (``trans_`` and ``rot_``) and compartment signals -(``wm``,``csf``, and ``global_signal``). These expansion terms are included in some confound regression pipelines -in addition to the first-order term. - -CompCor -============== - -:abbr:`CompCor (Component Based Noise Correction)` is a component-based noise correlation method. In the method -principal components are are derived from :abbr:`ROI (Region of Interest)` which is unlikely to include signal -related to brain activity. Signal from CompCor components can be further regressed out from the -wich principal components of signal within noise ROI ([Behzadi2007]_) +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]_). - -- ``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)`; - -.. warning:: - Four separate CompCor decompositions are performed to compute noise components: one temporal - decomposition (``t_comp_cor_XX``) and three anatomical decompositions across three different noise ROIs: an eroded - white matter mask, an eroded CSF mask, and a combined mask derived from the union - of these. 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 masks, while the more recent Muschelli implementation - ([Muschelli2014]_) can be applied using - the :abbr:`WM (white matter)` and :abbr:`CSF (cerebro-spinal fluid)` masks. - - -Outlier confounds -======================== - -- (``dvars``) - the derivative of RMS variance over voxels (or :abbr:`DVARS (defined in Power, et al. 2012)` -- ``std_dvars`` - standardized DVARS -- ``framewise_displacement`` - is a quantification of the estimated bulk-head motion estimated using [Power2012]_ -formula; -- ``non_steady_state_outlier_XX`` - if present, 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 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 ======================== -To determine the provenance of each component, consult the metadata file (see below). + - ``aroma_motion_XX`` - the motion-related components identified by :abbr:`ICA (independent components analysis)` --:abbr:`AROMA (Automatic Removal Of Motion Artifacts)` -(if enabled with ``--use-aroma``) . + -: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: :: @@ -393,14 +405,22 @@ See implementation on :mod:`~fmriprep.workflows.bold.confounds.init_bold_confs_w .. [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 `_ + .. [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 `_ .. [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, + and sensitivity of motion correction strategies for resting-state functional MRI. NeuroImage. 2018. doi: `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 `_ + .. [Power2016] Power JD, A simple but useful way to assess fMRI scan qualities. NeuroImage. 2016. doi: `10.1016/j.neuroimage.2016.08.009 `_ @@ -409,12 +429,10 @@ See implementation on :mod:`~fmriprep.workflows.bold.confounds.init_bold_confs_w of motion artifact in the preprocessing of resting-state functional connectivity data. NeuroImage. 2013. doi: `10.1016/j.neuroimage.2012.08.052 `_ - .. [Friston1996] Movement‐Related effects in fMRI time‐series, - Magnetic Resonance in Medicine. 1996. doi: `10.1002/mrm.191035031 < https://doi.org/10.1002/mrm.1910350312>`_ - - - - + .. [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 `_ From be8062c6ef9649653d6f8c65803f1944b99715fb Mon Sep 17 00:00:00 2001 From: kfinc Date: Fri, 29 Nov 2019 11:12:07 +0100 Subject: [PATCH 04/21] [DOC] Start each sentence from a new line --- docs/outputs.rst | 57 ++++++++++++++++++++++++++---------------------- 1 file changed, 31 insertions(+), 26 deletions(-) diff --git a/docs/outputs.rst b/docs/outputs.rst index bdb28634e..bc321147c 100644 --- a/docs/outputs.rst +++ b/docs/outputs.rst @@ -142,15 +142,17 @@ 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, +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 @@ -158,14 +160,16 @@ 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. +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 fMRPrep -is the automatic calculation of multiple potential confounding variables beyond standard head motion parameters. +or `FSL `_. +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. @@ -173,8 +177,8 @@ 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. + 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, @@ -215,19 +219,21 @@ Basic confouds 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]_) +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 +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 +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 +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``). @@ -269,10 +275,11 @@ ICA-AROMA confounds 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 +: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 @@ -389,8 +396,6 @@ 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, From 70f84a3fa5de3b13ab19bb8730db1f5e85dc64ac Mon Sep 17 00:00:00 2001 From: kfinc Date: Fri, 29 Nov 2019 11:21:32 +0100 Subject: [PATCH 05/21] [DOC] fMRIPrep to italic --- docs/outputs.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/outputs.rst b/docs/outputs.rst index bc321147c..fd2cbb87b 100644 --- a/docs/outputs.rst +++ b/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 ``/fmriprep/sub-.html``. +*FMRIPrep* outputs summary reports, written to ``/fmriprep/sub-.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>`_ @@ -161,7 +161,7 @@ There is currently no consensus on an optimal denoising strategy in the fMRI com 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 *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 @@ -171,7 +171,7 @@ or `FSL `_. 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, +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. @@ -185,7 +185,7 @@ Such tabular files may include over 100 columns of potential confound regressors see Parkes et al. ([Parkes2018]_) and Ciric et al. ([Ciric2017]_). -For each :abbr:`BOLD (blood-oxygen level dependent)` run processed with fMRIPrep, a +For each :abbr:`BOLD (blood-oxygen level dependent)` run processed with *fMRIPrep*, a ``/fmriprep/sub-/func/sub-_task-_run-_desc-confounds_regressors.tsv`` file will be generated. These are :abbr:`TSV (tab-separated values)` tables, which look like the example below: :: @@ -223,12 +223,12 @@ 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 +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`` +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]_). @@ -255,7 +255,7 @@ or including outlier points in the subsequent first-level analysis when building 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 +*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. @@ -362,9 +362,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 From f891f74b63ab6d2dbbba2f9da32ddee57245dfac Mon Sep 17 00:00:00 2001 From: kfinc Date: Fri, 29 Nov 2019 11:33:06 +0100 Subject: [PATCH 06/21] [DOC] Moved links to links.rst, fixed typo --- docs/links.rst | 3 ++- docs/outputs.rst | 6 +++--- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/links.rst b/docs/links.rst index 73938f3f1..c1133d162 100644 --- a/docs/links.rst +++ b/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/ \ No newline at end of file diff --git a/docs/outputs.rst b/docs/outputs.rst index fd2cbb87b..ebfa08cd7 100644 --- a/docs/outputs.rst +++ b/docs/outputs.rst @@ -166,9 +166,9 @@ 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 fMRPrep is the automatic calculation of multiple potential confounding variables +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, From 846058ba0d9213a380ffe9171de817af850c8fe1 Mon Sep 17 00:00:00 2001 From: Karolina Finc Date: Fri, 29 Nov 2019 11:34:52 +0100 Subject: [PATCH 07/21] Update docs/outputs.rst Co-Authored-By: Oscar Esteban --- docs/outputs.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/outputs.rst b/docs/outputs.rst index ebfa08cd7..17f134f92 100644 --- a/docs/outputs.rst +++ b/docs/outputs.rst @@ -172,7 +172,7 @@ One of the biggest advantages of *fMRIPrep* is the automatic calculation of mult 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. +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:: @@ -443,4 +443,3 @@ to which tissue-specific regressors correlate with global signal. - From fc9db06f346a47f73373661fc52d8dcac991e422 Mon Sep 17 00:00:00 2001 From: Karolina Finc Date: Fri, 29 Nov 2019 11:40:50 +0100 Subject: [PATCH 08/21] Update docs/outputs.rst Co-Authored-By: Oscar Esteban --- docs/outputs.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/outputs.rst b/docs/outputs.rst index 17f134f92..7df63a9d7 100644 --- a/docs/outputs.rst +++ b/docs/outputs.rst @@ -153,7 +153,7 @@ or physiological fluctuations (related to cardiac or respiratory effects) *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. +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*. @@ -442,4 +442,3 @@ to which tissue-specific regressors correlate with global signal. - From 5e638be0341ce3771522d3145d5138082a60e09c Mon Sep 17 00:00:00 2001 From: Karolina Finc Date: Fri, 29 Nov 2019 11:41:27 +0100 Subject: [PATCH 09/21] Update docs/outputs.rst Co-Authored-By: Oscar Esteban --- docs/outputs.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/outputs.rst b/docs/outputs.rst index 7df63a9d7..12fc59125 100644 --- a/docs/outputs.rst +++ b/docs/outputs.rst @@ -158,7 +158,7 @@ It is possible to minimize confounding effects of non-neuronal signals by includ 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 +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. @@ -441,4 +441,3 @@ to which tissue-specific regressors correlate with global signal. - From 6c569e5bdd67225366bce1d297472564327ad91b Mon Sep 17 00:00:00 2001 From: Karolina Finc Date: Fri, 29 Nov 2019 11:42:00 +0100 Subject: [PATCH 10/21] Update docs/outputs.rst Co-Authored-By: Oscar Esteban --- docs/outputs.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/outputs.rst b/docs/outputs.rst index 12fc59125..77ef9aaf6 100644 --- a/docs/outputs.rst +++ b/docs/outputs.rst @@ -155,7 +155,7 @@ or physiological fluctuations (related to cardiac or respiratory effects) 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 +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 @@ -440,4 +440,3 @@ to which tissue-specific regressors correlate with global signal. NeuroImage. 2013. doi: `10.1016/j.neuroimage.2013.03.004 `_ - From f4b0511fc2da3a15ff160bc552dcdeac0bf42972 Mon Sep 17 00:00:00 2001 From: kfinc Date: Fri, 29 Nov 2019 11:47:16 +0100 Subject: [PATCH 11/21] [DOC] Style corrections --- docs/outputs.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/outputs.rst b/docs/outputs.rst index ebfa08cd7..7cbbb7f04 100644 --- a/docs/outputs.rst +++ b/docs/outputs.rst @@ -148,10 +148,10 @@ The :abbr:`BOLD (blood-oxygen level dependent)` signal measured with fMRI is a m 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). +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 potential fluctuations of non-neuronal origin. +*Confounds* (or nuisance regressors) are variables representing 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 From 2363fab87eacbfae05f333e429478dfd268ccbc0 Mon Sep 17 00:00:00 2001 From: kfinc Date: Fri, 29 Nov 2019 11:59:36 +0100 Subject: [PATCH 12/21] [DOC] Style corrections --- docs/outputs.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/outputs.rst b/docs/outputs.rst index a194c2a3c..f33c84071 100644 --- a/docs/outputs.rst +++ b/docs/outputs.rst @@ -142,8 +142,6 @@ 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. @@ -151,7 +149,7 @@ Non-neuronal fluctuations in fMRI data may appear as a result of head motion, sc 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 of non-neuronal origin. +*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 @@ -166,8 +164,7 @@ 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_. +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. @@ -396,6 +393,8 @@ 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, From eef248240a9ec5d728412ab3aa35491a04fe1f9d Mon Sep 17 00:00:00 2001 From: Oscar Esteban Date: Wed, 4 Dec 2019 13:53:30 -0800 Subject: [PATCH 13/21] Apply suggestions from code review [skip ci] Co-Authored-By: William Hedley Thompson --- docs/outputs.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/outputs.rst b/docs/outputs.rst index f33c84071..e306c8627 100644 --- a/docs/outputs.rst +++ b/docs/outputs.rst @@ -160,13 +160,14 @@ Rather, different strategies have been proposed, which achieve different comprom 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. +Note, *fMRIPrep* does not perform any denoising itself and it is up to the user to perform this step. -The best known confounding variables in neuroimaging are the six head motion parameters +The most well established 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. +beyond the 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. @@ -195,7 +196,7 @@ These are :abbr:`TSV (tab-separated values)` tables, which look like the example Each row of the file corresponds to one time point found in the -corresponding :abbr:`BOLD (blood-oxygen level dependent)` time-series +corresponding :abbr:`BOLD (blood-oxygen level dependent)` time series (stored in ``/fmriprep/sub-/func/sub-_task-_run-_desc-preproc_bold.nii.gz``). Confound regressors description @@ -215,7 +216,7 @@ Basic confouds Parameter expansion of basic confounds ===================== -Regressing out the standard six motion parameters may not be sufficient to remove all variance related to head motion +Only accounting for 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 @@ -246,7 +247,7 @@ Confounds for outlier detection 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 +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``) @@ -438,4 +439,3 @@ See implementation on :mod:`~fmriprep.workflows.bold.confounds.init_bold_confs_w on functional connectomics. NeuroImage. 2013. doi: `10.1016/j.neuroimage.2013.03.004 `_ - From ed17228d3b81ee92080b1a37b3039ffca77ce31c Mon Sep 17 00:00:00 2001 From: oesteban Date: Wed, 4 Dec 2019 14:02:55 -0800 Subject: [PATCH 14/21] docs: fix build --- docs/outputs.rst | 67 ++++++++++++++++++++---------------------------- 1 file changed, 28 insertions(+), 39 deletions(-) diff --git a/docs/outputs.rst b/docs/outputs.rst index e306c8627..aa207e671 100644 --- a/docs/outputs.rst +++ b/docs/outputs.rst @@ -5,7 +5,6 @@ ------------------- Outputs of fMRIPrep ------------------- - *FMRIPrep* generates three broad classes of outcomes: 1. **Visual QA (quality assessment) reports**: @@ -30,7 +29,6 @@ Derivatives specification (see `BIDS Derivatives RC1`_). Visual Reports -------------- - *FMRIPrep* outputs summary reports, written to ``/fmriprep/sub-.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). @@ -39,7 +37,6 @@ Each report is self contained and thus can be easily shared with collaborators ( Preprocessed data (fMRIPrep *derivatives*) ------------------------------------------ - Preprocessed, or derivative, data are written to ``/fmriprep/sub-/``. The `BIDS Derivatives RC1`_ specification describes the naming and metadata conventions we follow. @@ -117,7 +114,6 @@ are saved: FreeSurfer Derivatives ---------------------- - A FreeSurfer subjects directory is created in ``/freesurfer``. :: @@ -138,10 +134,8 @@ FreeSurfer are copied into this subjects directory, if any functional data are sampled to those subject spaces. - Confounds --------- - 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. @@ -194,16 +188,14 @@ These are :abbr:`TSV (tab-separated values)` tables, which look like the example 665.3969 0.0 488.03 1.085204 16.323903999999995 0.0348966 0.010819676200000001 0.0651895837 -0.09556632150000001 -0.033148835 -0.4768871111 0.20641088559999998 0.2818768463 0.4303863764 0.41323714850000004 -0.2115232212 -0.0037154909000000004 0.10636180070000001 0.0 0.0 0.0 0.0457372 0.0 -0.0 0.0 -1.341359143 0.1636017242 662.82715 0.0 487.37302 1.01591 15.281561 0.0333937 0.3328022893 -0.2220965269 -0.0912891436 0.2326688125 0.279138129 -0.111878887 0.16901660629999998 0.0550480212 0.1798747037 -0.25383302620000003 0.1646403629 0.3953613889 0.0 0.010164 -0.0103568 0.0424513 0.0 -0.0 0.00019174 -0.1554834655 0.6451987913 - Each row of the file corresponds to one time point found in the corresponding :abbr:`BOLD (blood-oxygen level dependent)` time series (stored in ``/fmriprep/sub-/func/sub-_task-_run-_desc-preproc_bold.nii.gz``). 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; @@ -215,9 +207,9 @@ Basic confouds - ``global_signal`` - the average signal within the brain mask. Parameter expansion of basic confounds -===================== -Only accounting for the standard six motion parameters may not be sufficient to remove all variance related to head motion -from the fMRI signal. +====================================== +Only accounting for 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. @@ -234,9 +226,8 @@ Derivatives and quadratic terms are stored under column names with suffixes: ``_ 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]_); @@ -259,8 +250,7 @@ the command line options ``--fd-spike-threshold`` and ``--dvars-spike-threshold` 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``) . @@ -271,8 +261,7 @@ ICA-AROMA confounds 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)` @@ -290,7 +279,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 @@ -302,24 +290,27 @@ from the union of these. 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: :: - { - "a_comp_cor_00": { - "CumulativeVarianceExplained": 0.1081970825, - "Mask": "combined", - "Method": "aCompCor", - "Retained": true, - "SingularValue": 25.8270209974, - "VarianceExplained": 0.1081970825 - }, - "dropped_0": { - "CumulativeVarianceExplained": 0.5965809597, - "Mask": "combined", - "Method": "aCompCor", - "Retained": false, - "SingularValue": 20.7955177198, - "VarianceExplained": 0.0701465624 +.. code-block:: JSON + + { + "a_comp_cor_00": { + "CumulativeVarianceExplained": 0.1081970825, + "Mask": "combined", + "Method": "aCompCor", + "Retained": true, + "SingularValue": 25.8270209974, + "VarianceExplained": 0.1081970825 + }, + "dropped_0": { + "CumulativeVarianceExplained": 0.5965809597, + "Mask": "combined", + "Method": "aCompCor", + "Retained": false, + "SingularValue": 20.7955177198, + "VarianceExplained": 0.0701465624 + } } - } + For CompCor decompositions, entries include: @@ -337,7 +328,6 @@ For CompCor decompositions, entries include: Confounds and "carpet"-plot on the visual reports ------------------------------------------------- - Some of the estimated confounds, as well as a "carpet" visualization of the :abbr:`BOLD (blood-oxygen level-dependent)` time-series (see [Power2016]_). This plot is included for each run within the corresponding visual report. @@ -438,4 +428,3 @@ See implementation on :mod:`~fmriprep.workflows.bold.confounds.init_bold_confs_w 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 `_ - From 0c38544c96ee88cca164264a4431d08560fcada4 Mon Sep 17 00:00:00 2001 From: oesteban Date: Wed, 4 Dec 2019 16:22:02 -0800 Subject: [PATCH 15/21] docs: fix various problems (indentations, code-block, etc.) --- docs/outputs.rst | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/outputs.rst b/docs/outputs.rst index aa207e671..e714fc7b2 100644 --- a/docs/outputs.rst +++ b/docs/outputs.rst @@ -2,10 +2,10 @@ .. _outputs: -------------------- -Outputs of fMRIPrep -------------------- -*FMRIPrep* generates three broad classes of outcomes: +--------------------- +Outputs of *fMRIPrep* +--------------------- +*fMRIPrep* generates three broad classes of outcomes: 1. **Visual QA (quality assessment) reports**: one :abbr:`HTML (hypertext markup language)` per subject, @@ -24,19 +24,19 @@ Outputs of fMRIPrep 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 ``/fmriprep/sub-.html``. +*fMRIPrep* outputs summary reports, written to ``/fmriprep/sub-.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>`_ -Preprocessed data (fMRIPrep *derivatives*) ------------------------------------------- +Derivatives of *fMRIPrep* (preprocessed data) +--------------------------------------------- Preprocessed, or derivative, data are written to ``/fmriprep/sub-/``. The `BIDS Derivatives RC1`_ specification describes the naming and metadata conventions we follow. @@ -182,11 +182,11 @@ For each :abbr:`BOLD (blood-oxygen level dependent)` run processed with *fMRIPre file will be generated. These are :abbr:`TSV (tab-separated values)` tables, which look like the example below: :: - csf white_matter global_signal std_dvars dvars framewise_displacement t_comp_cor_00 t_comp_cor_01 t_comp_cor_02 t_comp_cor_03 t_comp_cor_04 t_comp_cor_05 a_comp_cor_00 a_comp_cor_01 a_comp_cor_02 a_comp_cor_03 a_comp_cor_04 a_comp_cor_05 non_steady_state_outlier00 trans_x trans_y trans_z rot_x rot_y rot_z aroma_motion_02 aroma_motion_04 - 682.75275 0.0 491.64752000000004 n/a n/a n/a 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 1.0 0.0 0.0 0.0 -0.00017029 -0.0 0.0 0.0 0.0 - 669.14166 0.0 489.4421 1.168398 17.575331 0.07211929999999998 -0.4506846719 0.1191909139 -0.0945884724 0.1542023065 -0.2302324641 0.0838194238 -0.032426848599999995 0.4284323184 -0.5809158299 0.1382414008 -0.1203486637 0.3783661265 0.0 0.0 0.0207752 0.0463124 -0.000270924 -0.0 0.0 -2.402958171 -0.7574011893 - 665.3969 0.0 488.03 1.085204 16.323903999999995 0.0348966 0.010819676200000001 0.0651895837 -0.09556632150000001 -0.033148835 -0.4768871111 0.20641088559999998 0.2818768463 0.4303863764 0.41323714850000004 -0.2115232212 -0.0037154909000000004 0.10636180070000001 0.0 0.0 0.0 0.0457372 0.0 -0.0 0.0 -1.341359143 0.1636017242 - 662.82715 0.0 487.37302 1.01591 15.281561 0.0333937 0.3328022893 -0.2220965269 -0.0912891436 0.2326688125 0.279138129 -0.111878887 0.16901660629999998 0.0550480212 0.1798747037 -0.25383302620000003 0.1646403629 0.3953613889 0.0 0.010164 -0.0103568 0.0424513 0.0 -0.0 0.00019174 -0.1554834655 0.6451987913 + csf white_matter global_signal std_dvars dvars framewise_displacement t_comp_cor_00 t_comp_cor_01 t_comp_cor_02 t_comp_cor_03 t_comp_cor_04 t_comp_cor_05 a_comp_cor_00 a_comp_cor_01 a_comp_cor_02 a_comp_cor_03 a_comp_cor_04 a_comp_cor_05 non_steady_state_outlier00 trans_x trans_y trans_z rot_x rot_y rot_z aroma_motion_02 aroma_motion_04 + 682.75275 0.0 491.64752000000004 n/a n/a n/a 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 1.0 0.0 0.0 0.0 -0.00017029 -0.0 0.0 0.0 0.0 + 669.14166 0.0 489.4421 1.168398 17.575331 0.07211929999999998 -0.4506846719 0.1191909139 -0.0945884724 0.1542023065 -0.2302324641 0.0838194238 -0.032426848599999995 0.4284323184 -0.5809158299 0.1382414008 -0.1203486637 0.3783661265 0.0 0.0 0.0207752 0.0463124 -0.000270924 -0.0 0.0 -2.402958171 -0.7574011893 + 665.3969 0.0 488.03 1.085204 16.323903999999995 0.0348966 0.010819676200000001 0.0651895837 -0.09556632150000001 -0.033148835 -0.4768871111 0.20641088559999998 0.2818768463 0.4303863764 0.41323714850000004 -0.2115232212 -0.0037154909000000004 0.10636180070000001 0.0 0.0 0.0 0.0457372 0.0 -0.0 0.0 -1.341359143 0.1636017242 + 662.82715 0.0 487.37302 1.01591 15.281561 0.0333937 0.3328022893 -0.2220965269 -0.0912891436 0.2326688125 0.279138129 -0.111878887 0.16901660629999998 0.0550480212 0.1798747037 -0.25383302620000003 0.1646403629 0.3953613889 0.0 0.010164 -0.0103568 0.0424513 0.0 -0.0 0.00019174 -0.1554834655 0.6451987913 Each row of the file corresponds to one time point found in the corresponding :abbr:`BOLD (blood-oxygen level dependent)` time series @@ -288,9 +288,9 @@ from the union of these. 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: :: +Metadata files contain additional information about columns in the confounds TSV file: -.. code-block:: JSON +.. code-block:: json { "a_comp_cor_00": { @@ -350,9 +350,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 @@ -401,8 +401,8 @@ See implementation on :mod:`~fmriprep.workflows.bold.confounds.init_bold_confs_w Psychometrika. 2013. doi: `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>`_ + time‐series. Magnetic Resonance in Medicine. 1996. + doi: `10.1002/mrm.191035031 `_ .. [Muschelli2014] Muschelli J, Nebel MB, Caffo BS, Barber AD, Pekar JJ, Mostofsky SH, Reduction of motion-related artifacts in resting state fMRI using aCompCor. From ea6aa31431731afc127bd0b688bd25116ef28fdf Mon Sep 17 00:00:00 2001 From: oesteban Date: Wed, 4 Dec 2019 18:46:04 -0800 Subject: [PATCH 16/21] docs: final details (file trees, confounds tsv files, etc.) --- docs/outputs.rst | 196 +++++++++++++++++++++++++++-------------------- 1 file changed, 112 insertions(+), 84 deletions(-) diff --git a/docs/outputs.rst b/docs/outputs.rst index e714fc7b2..cb2968b20 100644 --- a/docs/outputs.rst +++ b/docs/outputs.rst @@ -21,7 +21,7 @@ Outputs of *fMRIPrep* the same-subject's T1w space or into MNI space. 3. **Additional data for subsequent analysis**, for instance the transformations - between different spaces or the estimated confounds. + between different spaces or the estimated confounds_. *fMRIPrep* outputs conform to the :abbr:`BIDS (brain imaging data structure)` @@ -34,7 +34,6 @@ 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>`_ - Derivatives of *fMRIPrep* (preprocessed data) --------------------------------------------- Preprocessed, or derivative, data are written to @@ -42,98 +41,144 @@ Preprocessed, or derivative, data are written to The `BIDS Derivatives RC1`_ specification describes the naming and metadata conventions we follow. Anatomical derivatives are placed in each subject's ``anat`` subfolder: +:: -- ``anat/sub-_[space-_]desc-preproc_T1w.nii.gz`` -- ``anat/sub-_[space-_]desc-brain_mask.nii.gz`` -- ``anat/sub-_[space-_]dseg.nii.gz`` -- ``anat/sub-_[space-_]label-CSF_probseg.nii.gz`` -- ``anat/sub-_[space-_]label-GM_probseg.nii.gz`` -- ``anat/sub-_[space-_]label-WM_probseg.nii.gz`` - -Template-normalized derivatives use the space label ``MNI152NLin2009cAsym``, while derivatives in + sub-/ + anat/ + sub-[_space-]_desc-preproc_T1w.nii.gz + sub-[_space-]_desc-brain_mask.nii.gz + sub-[_space-]_dseg.nii.gz + sub-[_space-]_label-CSF_probseg.nii.gz + sub-[_space-]_label-GM_probseg.nii.gz + sub-[_space-]_label-WM_probseg.nii.gz + +Spatially-standardized derivatives are denoted with a space label, +such as ``MNI152NLin2009cAsym``, while derivatives in the original ``T1w`` space omit the ``space-`` keyword. Additionally, the following transforms are saved: +:: -- ``anat/sub-_from-MNI152NLin2009cAsym_to-T1w_mode-image_xfm.h5`` -- ``anat/sub-_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5`` + sub-/ + anat/ + sub-_from-MNI152NLin2009cAsym_to-T1w_mode-image_xfm.h5 + sub-_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5 If FreeSurfer reconstructions are used, the following surface files are generated: +:: -- ``anat/sub-_hemi-[LR]_smoothwm.surf.gii`` -- ``anat/sub-_hemi-[LR]_pial.surf.gii`` -- ``anat/sub-_hemi-[LR]_midthickness.surf.gii`` -- ``anat/sub-_hemi-[LR]_inflated.surf.gii`` + sub-/ + anat/ + sub-_hemi-[LR]_smoothwm.surf.gii + sub-_hemi-[LR]_pial.surf.gii + sub-_hemi-[LR]_midthickness.surf.gii + sub-_hemi-[LR]_inflated.surf.gii -And the affine translation between ``T1w`` space and FreeSurfer's reconstruction (``fsnative``) is -stored in: +And the affine translation (and inverse) between the original T1w sampling and FreeSurfer's +conformed space for surface reconstruction (``fsnative``) is stored in: +:: -- ``anat/sub-_from-T1w_to-fsnative_mode-image_xfm.txt`` + sub-/ + anat/ + sub-_from-fsnative_to-T1w_mode-image_xfm.txt + sub-_from-T1w_to-fsnative_mode-image_xfm.txt -Functional derivatives are stored in the ``func`` subfolder. +Functional derivatives are stored in the ``func/`` subfolder. All derivatives contain ``task-`` (mandatory) and ``run-`` (optional), and these will be indicated with ``[specifiers]``. +:: -- ``func/sub-_[specifiers]_space-_boldref.nii.gz`` -- ``func/sub-_[specifiers]_space-_desc-brain_mask.nii.gz`` -- ``func/sub-_[specifiers]_space-_desc-preproc_bold.nii.gz`` + sub-/ + func/ + sub-_[specifiers]_space-_boldref.nii.gz + sub-_[specifiers]_space-_desc-brain_mask.nii.gz + sub-_[specifiers]_space-_desc-preproc_bold.nii.gz Volumetric output spaces include ``T1w`` and ``MNI152NLin2009cAsym`` (default). -Confounds are saved as a :abbr:`TSV (tab-separated value)` file: +For each :abbr:`BOLD (blood-oxygen level dependent)` run processed with *fMRIPrep*, an +accompanying *confounds* file will be generated. +Confounds_ are saved as a :abbr:`TSV (tab-separated value)` file: +:: -- ``func/sub-_[specifiers]_desc-confounds_regressors.nii.gz`` + sub-/ + func/ + sub-_[specifiers]_desc-confounds_regressors.tsv + sub-_[specifiers]_desc-confounds_regressors.json + +These :abbr:`TSV (tab-separated values)` tables look like the example below, +where each row of the file corresponds to one time point found in the +corresponding :abbr:`BOLD (blood-oxygen level dependent)` time series. +:: + + csf white_matter global_signal std_dvars dvars framewise_displacement t_comp_cor_00 t_comp_cor_01 t_comp_cor_02 t_comp_cor_03 t_comp_cor_04 t_comp_cor_05 a_comp_cor_00 a_comp_cor_01 a_comp_cor_02 a_comp_cor_03 a_comp_cor_04 a_comp_cor_05 non_steady_state_outlier00 trans_x trans_y trans_z rot_x rot_y rot_z aroma_motion_02 aroma_motion_04 + 682.75275 0.0 491.64752000000004 n/a n/a n/a 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 1.0 0.0 0.0 0.0 -0.00017029 -0.0 0.0 0.0 0.0 + 669.14166 0.0 489.4421 1.168398 17.575331 0.07211929999999998 -0.4506846719 0.1191909139 -0.0945884724 0.1542023065 -0.2302324641 0.0838194238 -0.032426848599999995 0.4284323184 -0.5809158299 0.1382414008 -0.1203486637 0.3783661265 0.0 0.0 0.0207752 0.0463124 -0.000270924 -0.0 0.0 -2.402958171 -0.7574011893 + 665.3969 0.0 488.03 1.085204 16.323903999999995 0.0348966 0.010819676200000001 0.0651895837 -0.09556632150000001 -0.033148835 -0.4768871111 0.20641088559999998 0.2818768463 0.4303863764 0.41323714850000004 -0.2115232212 -0.0037154909000000004 0.10636180070000001 0.0 0.0 0.0 0.0457372 0.0 -0.0 0.0 -1.341359143 0.1636017242 + 662.82715 0.0 487.37302 1.01591 15.281561 0.0333937 0.3328022893 -0.2220965269 -0.0912891436 0.2326688125 0.279138129 -0.111878887 0.16901660629999998 0.0550480212 0.1798747037 -0.25383302620000003 0.1646403629 0.3953613889 0.0 0.010164 -0.0103568 0.0424513 0.0 -0.0 0.00019174 -0.1554834655 0.6451987913 If FreeSurfer reconstructions are used, the ``(aparc+)aseg`` segmentations are aligned to the subject's T1w space and resampled to the BOLD grid, and the BOLD series are resampled to the midthickness surface mesh: +:: -- ``func/sub-_[specifiers]_space-T1w_desc-aparcaseg_dseg.nii.gz`` -- ``func/sub-_[specifiers]_space-T1w_desc-aseg_dseg.nii.gz`` -- ``func/sub-_[specifiers]_space-_hemi-[LR].func.gii`` + sub-/ + func/ + sub-_[specifiers]_space-T1w_desc-aparcaseg_dseg.nii.gz + sub-_[specifiers]_space-T1w_desc-aseg_dseg.nii.gz + sub-_[specifiers]_space-_hemi-[LR].func.gii Surface output spaces include ``fsnative`` (full density subject-specific mesh), ``fsaverage`` and the down-sampled meshes ``fsaverage6`` (41k vertices) and ``fsaverage5`` (10k vertices, default). -If CIFTI outputs are requested, the BOLD series is also saved as ``dtseries.nii`` CIFTI2 files: +If CIFTI outputs are requested (with the ``--cifti-outputs`` argument), +the BOLD series are also saved as ``dtseries.nii`` CIFTI2 files: +:: -- ``func/sub-_[specifiers]_bold.dtseries.nii`` + sub-/ + func/ + sub-_[specifiers]_bold.dtseries.nii +CIFTI is a container format that holds both volumetric (regularly sampled in a grid) +and surface (sampled on a triangular mesh) samples. Sub-cortical time series are volumetric (supported spaces: ``MNI152NLin2009cAsym``), while cortical -time series are sampled to surface (supported spaces: ``fsaverage5``, ``fsaverage6``) +time series are sampled on the surface (supported spaces: ``fsaverage5``, ``fsaverage6``) Finally, if ICA-AROMA is used, the MELODIC mixing matrix and the components classified as noise are saved: +:: -- ``func/sub-_[specifiers]_AROMAnoiseICs.csv`` -- ``func/sub-_[specifiers]_desc-MELODIC_mixing.tsv`` - + sub-/ + func/ + sub-_[specifiers]_AROMAnoiseICs.csv + sub-_[specifiers]_desc-MELODIC_mixing.tsv .. _fsderivs: FreeSurfer Derivatives ---------------------- -A FreeSurfer subjects directory is created in ``/freesurfer``. - +A FreeSurfer subjects directory is created in ``/freesurfer``. :: - freesurfer/ - fsaverage{,5,6}/ - mri/ - surf/ + / + fmriprep/ ... - sub-/ - mri/ - surf/ + freesurfer/ + fsaverage{,5,6}/ + mri/ + surf/ + ... + sub-/ + mri/ + surf/ + ... ... - ... Copies of the ``fsaverage`` subjects distributed with the running version of FreeSurfer are copied into this subjects directory, if any functional data are sampled to those subject spaces. - Confounds --------- The :abbr:`BOLD (blood-oxygen level dependent)` signal measured with fMRI is a mixture of fluctuations @@ -174,23 +219,7 @@ Such tabular files may include over 100 columns of potential confound regressors 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 -``/fmriprep/sub-/func/sub-_task-_run-_desc-confounds_regressors.tsv`` -file will be generated. -These are :abbr:`TSV (tab-separated values)` tables, which look like the example below: :: - - csf white_matter global_signal std_dvars dvars framewise_displacement t_comp_cor_00 t_comp_cor_01 t_comp_cor_02 t_comp_cor_03 t_comp_cor_04 t_comp_cor_05 a_comp_cor_00 a_comp_cor_01 a_comp_cor_02 a_comp_cor_03 a_comp_cor_04 a_comp_cor_05 non_steady_state_outlier00 trans_x trans_y trans_z rot_x rot_y rot_z aroma_motion_02 aroma_motion_04 - 682.75275 0.0 491.64752000000004 n/a n/a n/a 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 1.0 0.0 0.0 0.0 -0.00017029 -0.0 0.0 0.0 0.0 - 669.14166 0.0 489.4421 1.168398 17.575331 0.07211929999999998 -0.4506846719 0.1191909139 -0.0945884724 0.1542023065 -0.2302324641 0.0838194238 -0.032426848599999995 0.4284323184 -0.5809158299 0.1382414008 -0.1203486637 0.3783661265 0.0 0.0 0.0207752 0.0463124 -0.000270924 -0.0 0.0 -2.402958171 -0.7574011893 - 665.3969 0.0 488.03 1.085204 16.323903999999995 0.0348966 0.010819676200000001 0.0651895837 -0.09556632150000001 -0.033148835 -0.4768871111 0.20641088559999998 0.2818768463 0.4303863764 0.41323714850000004 -0.2115232212 -0.0037154909000000004 0.10636180070000001 0.0 0.0 0.0 0.0457372 0.0 -0.0 0.0 -1.341359143 0.1636017242 - 662.82715 0.0 487.37302 1.01591 15.281561 0.0333937 0.3328022893 -0.2220965269 -0.0912891436 0.2326688125 0.279138129 -0.111878887 0.16901660629999998 0.0550480212 0.1798747037 -0.25383302620000003 0.1646403629 0.3953613889 0.0 0.010164 -0.0103568 0.0424513 0.0 -0.0 0.00019174 -0.1554834655 0.6451987913 - -Each row of the file corresponds to one time point found in the -corresponding :abbr:`BOLD (blood-oxygen level dependent)` time series -(stored in ``/fmriprep/sub-/func/sub-_task-_run-_desc-preproc_bold.nii.gz``). + see [Parkes2018]_ and [Ciric2017]_. Confound regressors description ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -208,19 +237,19 @@ Basic confouds Parameter expansion of basic confounds ====================================== -Only accounting for the standard six motion parameters may not be sufficient to remove all variance related to +Only accounting for 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]_) +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 +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]_). +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 @@ -230,19 +259,20 @@ 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; + formula proposed by [Power2012]_; +- ``dvars`` - the derivative of RMS variance over voxels (or :abbr:`DVARS (derivative of + RMS variance over voxels)`) [Power2012]_; +- ``std_dvars`` - standardized :abbr:`DVARS (derivative of RMS variance over voxels)`; - ``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, +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]_). +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`` @@ -259,19 +289,18 @@ ICA-AROMA confounds 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]_). +In the method, principal components are calculated within an :abbr:`ROI (Region of Interest)` +that 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 with a +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 +- ``t_comp_cor_XX`` - additional noise components are calculated using temporal :abbr:`CompCor (Component Based Noise Correction)`. Four separate CompCor decompositions are performed to compute noise components: one temporal @@ -281,9 +310,9 @@ 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 + 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 + [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). @@ -311,12 +340,11 @@ Metadata files contain additional information about columns in the confounds TSV } } - For CompCor decompositions, entries include: - ``Method``: anatomical or temporal CompCor. - - ``Mask``: denotes the ROI where the decomposition that generated the component - was performed: ``CSF``, ``WM``, or ``combined`` for anatomical CompCor. + - ``Mask``: denotes the :abbr:`ROI (region of interest)` where the decomposition that generated + the component was performed: ``CSF``, ``WM``, or ``combined`` for anatomical CompCor. - ``SingularValue``: singular value of the component. - ``VarianceExplained``: the fraction of variance explained by the component across the decomposition ROI mask. - ``CumulativeVarianceExplained``: the total fraction of variance explained by this particular component @@ -329,7 +357,7 @@ For CompCor decompositions, entries include: Confounds and "carpet"-plot on the visual reports ------------------------------------------------- Some of the estimated confounds, as well as a "carpet" visualization of the -:abbr:`BOLD (blood-oxygen level-dependent)` time-series (see [Power2016]_). +:abbr:`BOLD (blood-oxygen level-dependent)` time series [Power2016]_. This plot is included for each run within the corresponding visual report. An example of these plots follows: From 47c16097112bcbaf431630b707dec4a12c9c4249 Mon Sep 17 00:00:00 2001 From: Oscar Esteban Date: Thu, 5 Dec 2019 12:13:36 -0800 Subject: [PATCH 17/21] Apply suggestions from code review Co-Authored-By: Chris Markiewicz --- docs/outputs.rst | 34 ++++++++++++---------------------- 1 file changed, 12 insertions(+), 22 deletions(-) diff --git a/docs/outputs.rst b/docs/outputs.rst index cb2968b20..ee8a1a888 100644 --- a/docs/outputs.rst +++ b/docs/outputs.rst @@ -56,16 +56,14 @@ Spatially-standardized derivatives are denoted with a space label, such as ``MNI152NLin2009cAsym``, while derivatives in the original ``T1w`` space omit the ``space-`` keyword. -Additionally, the following transforms are saved: -:: +Additionally, the following transforms are saved:: sub-/ anat/ sub-_from-MNI152NLin2009cAsym_to-T1w_mode-image_xfm.h5 sub-_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5 -If FreeSurfer reconstructions are used, the following surface files are generated: -:: +If FreeSurfer reconstructions are used, the following surface files are generated:: sub-/ anat/ @@ -75,8 +73,7 @@ If FreeSurfer reconstructions are used, the following surface files are generate sub-_hemi-[LR]_inflated.surf.gii And the affine translation (and inverse) between the original T1w sampling and FreeSurfer's -conformed space for surface reconstruction (``fsnative``) is stored in: -:: +conformed space for surface reconstruction (``fsnative``) is stored in:: sub-/ anat/ @@ -85,8 +82,7 @@ conformed space for surface reconstruction (``fsnative``) is stored in: Functional derivatives are stored in the ``func/`` subfolder. All derivatives contain ``task-`` (mandatory) and ``run-`` (optional), and -these will be indicated with ``[specifiers]``. -:: +these will be indicated with ``[specifiers]``:: sub-/ func/ @@ -98,8 +94,7 @@ Volumetric output spaces include ``T1w`` and ``MNI152NLin2009cAsym`` (default). For each :abbr:`BOLD (blood-oxygen level dependent)` run processed with *fMRIPrep*, an accompanying *confounds* file will be generated. -Confounds_ are saved as a :abbr:`TSV (tab-separated value)` file: -:: +Confounds_ are saved as a :abbr:`TSV (tab-separated value)` file:: sub-/ func/ @@ -108,8 +103,7 @@ Confounds_ are saved as a :abbr:`TSV (tab-separated value)` file: These :abbr:`TSV (tab-separated values)` tables look like the example below, where each row of the file corresponds to one time point found in the -corresponding :abbr:`BOLD (blood-oxygen level dependent)` time series. -:: +corresponding :abbr:`BOLD (blood-oxygen level dependent)` time series:: csf white_matter global_signal std_dvars dvars framewise_displacement t_comp_cor_00 t_comp_cor_01 t_comp_cor_02 t_comp_cor_03 t_comp_cor_04 t_comp_cor_05 a_comp_cor_00 a_comp_cor_01 a_comp_cor_02 a_comp_cor_03 a_comp_cor_04 a_comp_cor_05 non_steady_state_outlier00 trans_x trans_y trans_z rot_x rot_y rot_z aroma_motion_02 aroma_motion_04 682.75275 0.0 491.64752000000004 n/a n/a n/a 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 1.0 0.0 0.0 0.0 -0.00017029 -0.0 0.0 0.0 0.0 @@ -119,8 +113,7 @@ corresponding :abbr:`BOLD (blood-oxygen level dependent)` time series. If FreeSurfer reconstructions are used, the ``(aparc+)aseg`` segmentations are aligned to the subject's T1w space and resampled to the BOLD grid, and the BOLD series are resampled to the -midthickness surface mesh: -:: +midthickness surface mesh:: sub-/ func/ @@ -133,8 +126,7 @@ Surface output spaces include ``fsnative`` (full density subject-specific mesh), ``fsaverage5`` (10k vertices, default). If CIFTI outputs are requested (with the ``--cifti-outputs`` argument), -the BOLD series are also saved as ``dtseries.nii`` CIFTI2 files: -:: +the BOLD series are also saved as ``dtseries.nii`` CIFTI2 files:: sub-/ func/ @@ -146,8 +138,7 @@ Sub-cortical time series are volumetric (supported spaces: ``MNI152NLin2009cAsym time series are sampled on the surface (supported spaces: ``fsaverage5``, ``fsaverage6``) Finally, if ICA-AROMA is used, the MELODIC mixing matrix and the components classified as noise -are saved: -:: +are saved:: sub-/ func/ @@ -158,8 +149,7 @@ are saved: FreeSurfer Derivatives ---------------------- -A FreeSurfer subjects directory is created in ``/freesurfer``. -:: +A FreeSurfer subjects directory is created in ``/freesurfer``:: / fmriprep/ @@ -192,7 +182,7 @@ For a detailed review of the possible sources of noise in the BOLD signal, refer 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 +in the GLM 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 @@ -267,7 +257,7 @@ Confounds for outlier detection ``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. +All these confounds can be used to detect potential outlier time points - frames with high motion or intensity 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. From 96885545694652b751f6eec29eca504e3b204f1b Mon Sep 17 00:00:00 2001 From: oesteban Date: Thu, 5 Dec 2019 14:48:27 -0800 Subject: [PATCH 18/21] docs: include some @effigies' and @adelavega's review comments, better organization --- docs/outputs.rst | 346 +++++++++++++++++++++++++---------------------- 1 file changed, 185 insertions(+), 161 deletions(-) diff --git a/docs/outputs.rst b/docs/outputs.rst index ee8a1a888..61a198312 100644 --- a/docs/outputs.rst +++ b/docs/outputs.rst @@ -5,27 +5,32 @@ --------------------- Outputs of *fMRIPrep* --------------------- -*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. - - 2. **Pre-processed imaging data** which are derivatives of the original - anatomical and functional images after various preparation procedures - have been applied. For example, - :abbr:`INU (intensity non-uniformity)`-corrected versions of the T1-weighted - image (per subject), the brain mask, or :abbr:`BOLD (blood-oxygen level dependent)` - images after head-motion correction, slice-timing correction and aligned into - the same-subject's T1w space or into MNI space. - - 3. **Additional data for subsequent analysis**, for instance the transformations - between different spaces or the estimated confounds_. - - *fMRIPrep* outputs conform to the :abbr:`BIDS (brain imaging data structure)` Derivatives specification (see `BIDS Derivatives RC1`_). +*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. + +2. **Derivatives (preprocessed data)** the input fMRI data ready for + analysis, i.e., after the various preparation procedures + have been applied. + For example, :abbr:`INU (intensity non-uniformity)`-corrected versions + of the T1-weighted image (per subject), the brain mask, + or :abbr:`BOLD (blood-oxygen level dependent)` + images after head-motion correction, slice-timing correction and aligned into + the same-subject's T1w space or in some standard space. + +3. **Confounds**: this is a special family of derivatives that can be utilized + to inform subsequent denoising steps. + + .. 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). Visual Reports -------------- @@ -40,8 +45,9 @@ Preprocessed, or derivative, data are written to ``/fmriprep/sub-/``. The `BIDS Derivatives RC1`_ specification describes the naming and metadata conventions we follow. -Anatomical derivatives are placed in each subject's ``anat`` subfolder: -:: +Anatomical derivatives +~~~~~~~~~~~~~~~~~~~~~~ +Anatomical derivatives are placed in each subject's ``anat`` subfolder:: sub-/ anat/ @@ -80,6 +86,32 @@ conformed space for surface reconstruction (``fsnative``) is stored in:: sub-_from-fsnative_to-T1w_mode-image_xfm.txt sub-_from-T1w_to-fsnative_mode-image_xfm.txt +.. _fsderivs: + +FreeSurfer derivatives +~~~~~~~~~~~~~~~~~~~~~~ +A FreeSurfer subjects directory is created in ``/freesurfer``:: + + / + fmriprep/ + ... + freesurfer/ + fsaverage{,5,6}/ + mri/ + surf/ + ... + sub-/ + mri/ + surf/ + ... + ... + +Copies of the ``fsaverage`` subjects distributed with the running version of +FreeSurfer are copied into this subjects directory, if any functional data are +sampled to those subject spaces. + +Functional derivatives +~~~~~~~~~~~~~~~~~~~~~~ Functional derivatives are stored in the ``func/`` subfolder. All derivatives contain ``task-`` (mandatory) and ``run-`` (optional), and these will be indicated with ``[specifiers]``:: @@ -90,30 +122,14 @@ these will be indicated with ``[specifiers]``:: sub-_[specifiers]_space-_desc-brain_mask.nii.gz sub-_[specifiers]_space-_desc-preproc_bold.nii.gz -Volumetric output spaces include ``T1w`` and ``MNI152NLin2009cAsym`` (default). - -For each :abbr:`BOLD (blood-oxygen level dependent)` run processed with *fMRIPrep*, an -accompanying *confounds* file will be generated. -Confounds_ are saved as a :abbr:`TSV (tab-separated value)` file:: - - sub-/ - func/ - sub-_[specifiers]_desc-confounds_regressors.tsv - sub-_[specifiers]_desc-confounds_regressors.json - -These :abbr:`TSV (tab-separated values)` tables look like the example below, -where each row of the file corresponds to one time point found in the -corresponding :abbr:`BOLD (blood-oxygen level dependent)` time series:: - - csf white_matter global_signal std_dvars dvars framewise_displacement t_comp_cor_00 t_comp_cor_01 t_comp_cor_02 t_comp_cor_03 t_comp_cor_04 t_comp_cor_05 a_comp_cor_00 a_comp_cor_01 a_comp_cor_02 a_comp_cor_03 a_comp_cor_04 a_comp_cor_05 non_steady_state_outlier00 trans_x trans_y trans_z rot_x rot_y rot_z aroma_motion_02 aroma_motion_04 - 682.75275 0.0 491.64752000000004 n/a n/a n/a 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 1.0 0.0 0.0 0.0 -0.00017029 -0.0 0.0 0.0 0.0 - 669.14166 0.0 489.4421 1.168398 17.575331 0.07211929999999998 -0.4506846719 0.1191909139 -0.0945884724 0.1542023065 -0.2302324641 0.0838194238 -0.032426848599999995 0.4284323184 -0.5809158299 0.1382414008 -0.1203486637 0.3783661265 0.0 0.0 0.0207752 0.0463124 -0.000270924 -0.0 0.0 -2.402958171 -0.7574011893 - 665.3969 0.0 488.03 1.085204 16.323903999999995 0.0348966 0.010819676200000001 0.0651895837 -0.09556632150000001 -0.033148835 -0.4768871111 0.20641088559999998 0.2818768463 0.4303863764 0.41323714850000004 -0.2115232212 -0.0037154909000000004 0.10636180070000001 0.0 0.0 0.0 0.0457372 0.0 -0.0 0.0 -1.341359143 0.1636017242 - 662.82715 0.0 487.37302 1.01591 15.281561 0.0333937 0.3328022893 -0.2220965269 -0.0912891436 0.2326688125 0.279138129 -0.111878887 0.16901660629999998 0.0550480212 0.1798747037 -0.25383302620000003 0.1646403629 0.3953613889 0.0 0.010164 -0.0103568 0.0424513 0.0 -0.0 0.00019174 -0.1554834655 0.6451987913 +**Regularly gridded outputs (images)**. +Volumetric output spaces labels (```` above, and in the following) include +``T1w`` and ``MNI152NLin2009cAsym`` (default). +**Surfaces, segmentations and parcellations from FreeSurfer**. If FreeSurfer reconstructions are used, the ``(aparc+)aseg`` segmentations are aligned to the subject's T1w space and resampled to the BOLD grid, and the BOLD series are resampled to the -midthickness surface mesh:: +mid-thickness surface mesh:: sub-/ func/ @@ -125,6 +141,11 @@ Surface output spaces include ``fsnative`` (full density subject-specific mesh), ``fsaverage`` and the down-sampled meshes ``fsaverage6`` (41k vertices) and ``fsaverage5`` (10k vertices, default). +**Grayordinates files**. +CIFTI is a container format that holds both volumetric (regularly sampled in a grid) +and surface (sampled on a triangular mesh) samples. +Sub-cortical time series are volumetric (supported spaces: ``MNI152NLin2009cAsym``), while cortical +time series are sampled on the surface (supported spaces: ``fsaverage5``, ``fsaverage6``). If CIFTI outputs are requested (with the ``--cifti-outputs`` argument), the BOLD series are also saved as ``dtseries.nii`` CIFTI2 files:: @@ -132,42 +153,34 @@ the BOLD series are also saved as ``dtseries.nii`` CIFTI2 files:: func/ sub-_[specifiers]_bold.dtseries.nii -CIFTI is a container format that holds both volumetric (regularly sampled in a grid) -and surface (sampled on a triangular mesh) samples. -Sub-cortical time series are volumetric (supported spaces: ``MNI152NLin2009cAsym``), while cortical -time series are sampled on the surface (supported spaces: ``fsaverage5``, ``fsaverage6``) -Finally, if ICA-AROMA is used, the MELODIC mixing matrix and the components classified as noise -are saved:: +**Extracted confounding time series**. +For each :abbr:`BOLD (blood-oxygen level dependent)` run processed with *fMRIPrep*, an +accompanying *confounds* file will be generated. +Confounds_ are saved as a :abbr:`TSV (tab-separated value)` file:: sub-/ func/ - sub-_[specifiers]_AROMAnoiseICs.csv - sub-_[specifiers]_desc-MELODIC_mixing.tsv + sub-_[specifiers]_desc-confounds_regressors.tsv + sub-_[specifiers]_desc-confounds_regressors.json -.. _fsderivs: +These :abbr:`TSV (tab-separated values)` tables look like the example below, +where each row of the file corresponds to one time point found in the +corresponding :abbr:`BOLD (blood-oxygen level dependent)` time series:: -FreeSurfer Derivatives ----------------------- -A FreeSurfer subjects directory is created in ``/freesurfer``:: + csf white_matter global_signal std_dvars dvars framewise_displacement t_comp_cor_00 t_comp_cor_01 t_comp_cor_02 t_comp_cor_03 t_comp_cor_04 t_comp_cor_05 a_comp_cor_00 a_comp_cor_01 a_comp_cor_02 a_comp_cor_03 a_comp_cor_04 a_comp_cor_05 non_steady_state_outlier00 trans_x trans_y trans_z rot_x rot_y rot_z aroma_motion_02 aroma_motion_04 + 682.75275 0.0 491.64752000000004 n/a n/a n/a 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 1.0 0.0 0.0 0.0 -0.00017029 -0.0 0.0 0.0 0.0 + 669.14166 0.0 489.4421 1.168398 17.575331 0.07211929999999998 -0.4506846719 0.1191909139 -0.0945884724 0.1542023065 -0.2302324641 0.0838194238 -0.032426848599999995 0.4284323184 -0.5809158299 0.1382414008 -0.1203486637 0.3783661265 0.0 0.0 0.0207752 0.0463124 -0.000270924 -0.0 0.0 -2.402958171 -0.7574011893 + 665.3969 0.0 488.03 1.085204 16.323903999999995 0.0348966 0.010819676200000001 0.0651895837 -0.09556632150000001 -0.033148835 -0.4768871111 0.20641088559999998 0.2818768463 0.4303863764 0.41323714850000004 -0.2115232212 -0.0037154909000000004 0.10636180070000001 0.0 0.0 0.0 0.0457372 0.0 -0.0 0.0 -1.341359143 0.1636017242 + 662.82715 0.0 487.37302 1.01591 15.281561 0.0333937 0.3328022893 -0.2220965269 -0.0912891436 0.2326688125 0.279138129 -0.111878887 0.16901660629999998 0.0550480212 0.1798747037 -0.25383302620000003 0.1646403629 0.3953613889 0.0 0.010164 -0.0103568 0.0424513 0.0 -0.0 0.00019174 -0.1554834655 0.6451987913 - / - fmriprep/ - ... - freesurfer/ - fsaverage{,5,6}/ - mri/ - surf/ - ... - sub-/ - mri/ - surf/ - ... - ... +Finally, if ICA-AROMA is used, the MELODIC mixing matrix and the components classified as noise +are saved:: -Copies of the ``fsaverage`` subjects distributed with the running version of -FreeSurfer are copied into this subjects directory, if any functional data are -sampled to those subject spaces. + sub-/ + func/ + sub-_[specifiers]_AROMAnoiseICs.csv + sub-_[specifiers]_desc-MELODIC_mixing.tsv Confounds --------- @@ -178,25 +191,26 @@ Non-neuronal fluctuations in fMRI data may appear as a result of head motion, sc 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. +*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 GLM design matrix or regressing them out from +It is possible to minimize confounding effects of non-neuronal signals by including +them as nuisance regressors in the GLM 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. -Note, *fMRIPrep* does not perform any denoising itself and it is up to the user to perform this step. -The most well established confounding variables in neuroimaging are the six head motion parameters -(three rotations and three translations) - the common output of the head motion correction +The most well established 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 the standard head motion parameters. +Beyond the standard head-motion parameters, the fMRIPrep pipeline generates a large array +of possible confounds, which enable researchers to choose the most suitable denoising +strategy for their downstream analyses. 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. @@ -213,40 +227,41 @@ Such tabular files may include over 100 columns of potential confound regressors 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 -====================================== -Only accounting for 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 +**Basic confounds**. The most commonly used confounding time series: + +- Estimated head-motion parameters: + ``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; + +- Global signals: + + - ``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**. +The standard six-motion parameters may not account for all the variance related +to head-motion. +[Friston1996]_ and [Satterthwaite2013]_ proposed an expansion of the six fundamental +head-motion parameters. +To make this technique more accessible, *fMRIPrep* automatically calculates motion parameter +expansion [Satterthwaite2013]_, providing time series corresponding to the first +*temporal derivatives* of the six base motion parameters, together with their +*quadratic terms*, resulting in the total 24 head motion parameters +(six base motion parameters + six temporal derivatives of six motion parameters + +12 quadratic terms of six motion parameters and their six temporal derivatives). +Additionally, *fMRIPrep* returns temporal derivatives and quadratic terms for the +three global signals (``csf``, ``white_matter`` and ``global_signal``) +to enable applying the 36-parameter denoising strategy proposed by [Satterthwaite2013]_. + +Derivatives and quadratic terms are stored under column names with +suffixes: ``_derivative1`` and powers ``_power2``. +These are calculated for head-motion estimates (``trans_`` and ``rot_``) and global signals (``white_matter``, ``csf``, and ``global_signal``). -Confounds for outlier detection -=============================== +**Outlier detection**. +These confounds can be used to detect potential outlier time points - +frames with sudden and large motion or intensity spikes. - ``framewise_displacement`` - is a quantification of the estimated bulk-head motion calculated using formula proposed by [Power2012]_; @@ -257,30 +272,31 @@ Confounds for outlier detection ``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 intensity 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]_. +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 also be added as regressors 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. +(default: FD > 0.5 mm or DVARS > 1.5). +Spike regressors are stored in separate ``motion_outlier_XX`` columns. -ICA-AROMA confounds -=================== +**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 :abbr:`ICA (independent components analysis)` - -:abbr:`AROMA (Automatic Removal Of Motion Artifacts)` (if enabled with a flag ``--use-aroma``) . +- ``aroma_motion_XX`` - the motion-related components identified by ICA-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 -================= +**CompCor confounds**. :abbr:`CompCor (Component Based Noise Correction)` is a component-based noise correlation method. In the method, principal components are calculated within an :abbr:`ROI (Region of Interest)` that is unlikely to include signal related to neuronal activity, such as :abbr:`CSF (cerebro-spinal fluid)` @@ -306,7 +322,8 @@ from the union of these. 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``). +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: .. code-block:: json @@ -345,13 +362,13 @@ For CompCor decompositions, entries include: ``dropped`` prefix. Confounds and "carpet"-plot on the visual reports -------------------------------------------------- -Some of the estimated confounds, as well as a "carpet" visualization of the +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The visual reports provide several sections per task and run to aid designing +a denoising strategy for subsequent analysis. +Some of the estimated confounds are plotted with a "carpet" visualization of the :abbr:`BOLD (blood-oxygen level-dependent)` time series [Power2016]_. -This plot is included for each run within the corresponding visual report. An example of these plots follows: - .. figure:: _static/sub-01_task-mixedgamblestask_run-01_bold_carpetplot.svg :scale: 100% @@ -359,7 +376,7 @@ An example of these plots follows: global signals ('GlobalSignal', 'WM', 'GM'), standardized DVARS ('stdDVARS'), and framewise-displacement ('FramewiseDisplacement'). At the bottom, a 'carpetplot' summarizing the BOLD series. - The colormap on the left-side of the carpetplot denotes signals located + The color-map on the left-side of the carpetplot denotes signals located in cortical gray matter regions (blue), subcortical gray matter (orange), cerebellum (green) and the union of white-matter and CSF compartments (red). @@ -394,7 +411,7 @@ to which tissue-specific regressors correlate with global signal. :scale: 100% The left-hand panel shows the matrix of correlations among selected confound - time series as a heatmap. + time series as a heat-map. Note the zero-correlation blocks near the diagonal; these correspond to each CompCor decomposition. The right-hand panel displays the correlation of selected confound time series @@ -406,43 +423,50 @@ See implementation on :mod:`~fmriprep.workflows.bold.confounds.init_bold_confs_w .. 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 `_ + .. [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 `_ .. [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 `_ + 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 `_ - .. [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 `_ + .. [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 `_ - .. [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 `_ + .. [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 `_ .. [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 `_ + Reduction of motion-related artifacts in resting state fMRI using aCompCor. NeuroImage. 2014. + doi:`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 `_ + and sensitivity of motion correction strategies for resting-state functional MRI. NeuroImage. 2018. + doi:`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 `_ - - .. [Power2016] Power JD, A simple but useful way to assess fMRI scan qualities. - NeuroImage. 2016. doi: `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 `_ - - .. [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 `_ + correlations in functional connectivity MRI networks arise from subject motion. NeuroImage. 2012. + doi:`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 `_ + + .. [Prium2015] Pruim RHR, Mennes M, van Rooij D, Llera A, Buitelaar JK, Beckmann CF. + ICA-AROMA: A robust ICA-based strategy for removing motion artifacts from fMRI data. + Neuroimage. 2015 May 15;112:267–77. + doi:`10.1016/j.neuroimage.2015.02.064 <10.1016/j.neuroimage.2015.02.064>`_. + + .. [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 `_ + + .. [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 `_ From eee82f06f127aa8189ee0766fbf84eb0af95283a Mon Sep 17 00:00:00 2001 From: oesteban Date: Thu, 5 Dec 2019 21:45:45 -0800 Subject: [PATCH 19/21] fix: link to ICA-AROMA paper --- docs/outputs.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/outputs.rst b/docs/outputs.rst index 61a198312..2d0a0b632 100644 --- a/docs/outputs.rst +++ b/docs/outputs.rst @@ -459,7 +459,7 @@ See implementation on :mod:`~fmriprep.workflows.bold.confounds.init_bold_confs_w .. [Prium2015] Pruim RHR, Mennes M, van Rooij D, Llera A, Buitelaar JK, Beckmann CF. ICA-AROMA: A robust ICA-based strategy for removing motion artifacts from fMRI data. Neuroimage. 2015 May 15;112:267–77. - doi:`10.1016/j.neuroimage.2015.02.064 <10.1016/j.neuroimage.2015.02.064>`_. + doi:`10.1016/j.neuroimage.2015.02.064 `_. .. [Satterthwaite2013] Satterthwaite TD, Elliott MA, Gerraty RT, Ruparel K, Loughead J, Calkins ME, Eickhoff SB, Hakonarson H, Gur RC, Gur RE, Wolf DH, From 47b72153468f2f784169607538fa3b23590c6b79 Mon Sep 17 00:00:00 2001 From: oesteban Date: Thu, 5 Dec 2019 21:52:21 -0800 Subject: [PATCH 20/21] fix: add link to NeuroStars discussion. https://neurostars.org/t/fmrirep-outputs-very-high-number-of-acompcors-up-to-1000/5451 --- docs/outputs.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/outputs.rst b/docs/outputs.rst index 2d0a0b632..c84fcc071 100644 --- a/docs/outputs.rst +++ b/docs/outputs.rst @@ -297,7 +297,8 @@ ICA-AROMA can be enabled with the flag ``--use-aroma``. 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. +:abbr:`CompCor (Component Based Noise Correction)` is a :abbr:`PCA (principal component analysis)`, +hence component-based, noise pattern recognition method. In the method, principal components are calculated within an :abbr:`ROI (Region of Interest)` that is unlikely to include signal related to neuronal activity, such as :abbr:`CSF (cerebro-spinal fluid)` and :abbr:`WM (white matter)` masks. @@ -321,6 +322,10 @@ from the union of these. [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``). From 6c362df69751d92acba08bc72c277ef9c28aca42 Mon Sep 17 00:00:00 2001 From: oesteban Date: Thu, 5 Dec 2019 21:59:34 -0800 Subject: [PATCH 21/21] fix: cast some warnings to danger, minor related fixes --- docs/outputs.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/outputs.rst b/docs/outputs.rst index c84fcc071..4505c7765 100644 --- a/docs/outputs.rst +++ b/docs/outputs.rst @@ -216,13 +216,14 @@ Confounding variables calculated in *fMRIPrep* are stored separately for each su 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 +.. danger:: + Do not include all columns of ``~_desc-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. + Filter the table first, to include only the confounds (or components thereof) + 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, + For a detailed description of various denoising strategies and their performance, see [Parkes2018]_ and [Ciric2017]_. Confound regressors description @@ -272,7 +273,6 @@ frames with sudden and large motion or intensity spikes. ``1`` value and ``0`` elsewhere (*i.e.*, there is one ``non_steady_state_outlier_XX`` column per outlier/volume). - 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 @@ -292,7 +292,7 @@ ICA-AROMA can be enabled with the flag ``--use-aroma``. - ``aroma_motion_XX`` - the motion-related components identified by ICA-AROMA. -.. warning:: +.. 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.