From 0f1fa946e84ff391813363d07492054df8a95624 Mon Sep 17 00:00:00 2001 From: Logan Date: Sun, 3 Nov 2019 16:40:23 -0600 Subject: [PATCH 01/55] edited gitignore after testing --- .gitignore | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.gitignore b/.gitignore index af64fb138..190531668 100644 --- a/.gitignore +++ b/.gitignore @@ -105,3 +105,5 @@ ENV/ # vscode .vscode +.pytest_cache/v/cache/stepwise +.pytest_cache/v/cache/nodeids From 2e327cdea94c9a19e91cb691fa1c45c609b3fc7b Mon Sep 17 00:00:00 2001 From: Logan Date: Sun, 3 Nov 2019 16:40:23 -0600 Subject: [PATCH 02/55] Revert "edited gitignore after testing" This reverts commit 28098e1ec37859f0dfb4b71e20230cfa71e84859. --- .gitignore | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/.gitignore b/.gitignore index 190531668..41e4de67c 100644 --- a/.gitignore +++ b/.gitignore @@ -104,6 +104,4 @@ ENV/ .mypy_cache/ # vscode -.vscode -.pytest_cache/v/cache/stepwise -.pytest_cache/v/cache/nodeids +.vscode \ No newline at end of file From 42185ef4e68d0dc96d36ab014222e6888b9c1aac Mon Sep 17 00:00:00 2001 From: Logan Date: Wed, 6 Nov 2019 10:45:50 -0500 Subject: [PATCH 03/55] fixing typo and clarity --- docs/approach.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/approach.rst b/docs/approach.rst index 7ac9803ec..fb3b89cfb 100644 --- a/docs/approach.rst +++ b/docs/approach.rst @@ -23,7 +23,7 @@ Multi-echo data ``````````````` Here are the echo-specific time series for a single voxel in an example -resting-state scan with 5 echoes. +resting-state scan with 8 echoes. .. image:: /_static/a01_echo_timeseries.png @@ -201,7 +201,7 @@ This way, low-variance information (originally discarded by TEDPCA) is retained in the data, but is ignored by the TEDICA process. This results in echo- and voxel-specific betas for each of the components. -TE-dependence (:math:`R_2`) and TE-independence (:math:`S_0`) models can then +TE-dependence (:math:`R_2` or :math:`1/T_{2}^*`) and TE-independence (:math:`S_0`) models can then be fit to these betas. For more information on how these models are estimated, see :ref:`dependence models`. These models allow calculation of F-statistics for the :math:`R_2` and :math:`S_0` From 8375c938b9d1b33d2752c48c1721d0435323990d Mon Sep 17 00:00:00 2001 From: Logan Date: Wed, 6 Nov 2019 10:58:41 -0500 Subject: [PATCH 04/55] cleaning up approach introduction --- docs/multi-echo.rst | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/multi-echo.rst b/docs/multi-echo.rst index d760385f3..da3366777 100644 --- a/docs/multi-echo.rst +++ b/docs/multi-echo.rst @@ -1,14 +1,15 @@ Multi-echo fMRI =============== -In most echo-planar image (EPI) fMRI sequences, only one brain image is acquired -at each repetition time, at the rate of radio frequency (RF). In contrast, in -multi-echo (ME) fMRI, data are acquired for multiple echo times, resulting in -multiple volumes with varying levels of contrast acquired per RF. +Most echo-planar image (EPI) sequences collect a single brain image following +a radio frequency (RF) pulse, at a rate known as the repetition time (TR). +This typical approach is known as single-echo fMRI. In contrast, multi-echo (ME) +fMRI refers to collecting data at multiple echo times, resulting in +multiple volumes with varying levels of contrast acquired per RF pulse. The physics of multi-echo fMRI ------------------------------ -Multi-echo fMRI data is obtained by acquiring multiple TEs (commonly called -`echo times`_) for each MRI volume +Multi-echo fMRI data is obtained by acquiring multiple echo times (commonly called +`TEs`_) for each MRI volume during data collection. While fMRI signal contains important neural information (termed the blood oxygen-level dependent, or `BOLD signal`_, From 21899e2a56c63cf42f01ce0710ac2d1713db86a2 Mon Sep 17 00:00:00 2001 From: Logan Date: Wed, 6 Nov 2019 11:03:50 -0500 Subject: [PATCH 05/55] more cleanup in approach --- docs/multi-echo.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/multi-echo.rst b/docs/multi-echo.rst index da3366777..7f21ba6be 100644 --- a/docs/multi-echo.rst +++ b/docs/multi-echo.rst @@ -32,18 +32,18 @@ Specifically, by collecting multi-echo data, researchers are able to compare res (1) single-echo, (2) optimally combined, and (3) denoised data. Each of these levels of analysis have their own advantages. -For single-echo: currently, field standards are largely set using single-echo EPI. +Single-echo data: currently, field standards are largely set using single-echo EPI. Because multi-echo is composed of multiple single-echo time series, each of these can be analyzed separately. This allows researchers to benchmark their results. -For optimally combined: Rather than analyzing single-echo time series separately, +Optimally combined data: Rather than analyzing single-echo time series separately, we can combine them into a "optimally combined time series". For more information on this combination, see `processing pipeline details`_. Optimally combined data exhibits higher SNR and improves statistical power of analyses in regions traditionally affected by drop-out. -For denoised: Collecting multi-echo data allows access to unique denoising metrics. -``tedana`` is one ICA-based denoising pipeline built on this information. +Denoised data: Collecting multi-echo data allows access to unique denoising methods. +``tedana`` is one ICA-based denoising pipeline built especially for multi-echo data. Other ICA-based denoising methods like ICA-AROMA (`Pruim et al. (2015)`_) have been shown to significantly improve the quality of cleaned signal. From f742ab75bb8e47f4c63c46a8ed22864d76aadc8b Mon Sep 17 00:00:00 2001 From: Logan Date: Wed, 6 Nov 2019 11:43:40 -0500 Subject: [PATCH 06/55] adding initial plot to pubs page --- docs/publications.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/publications.rst b/docs/publications.rst index 1cf208257..ff60dce04 100644 --- a/docs/publications.rst +++ b/docs/publications.rst @@ -7,6 +7,24 @@ The following spreadsheet is an on-going effort to track all publications that use multi-echo fMRI. This is a volunteer led effort so, if you know of an excluded publication, whether or not it is yours, please add it. +The figure below highlights the average TEs used in currently published papers using multiecho +at 3T. + +Average TE at 3T +-------- + +.. plot:: + import matplotlib.pyplot as plt + import pandas as pd + import pandas as pd + metable= = pd.read_csv('https://docs.google.com/spreadsheets/d/1WERojJyxFoqcg_tndUm5Kj0H1UfUc9Ban0jFGGfPaBk/export?gid=0&format=csv', + header=0 + ) + TEs = [metable.TE1.mean(), metable.TE2.mean(), metable.TE3.mean(), metable.TE4.mean(), metable.TE5.mean()] + plt.bar([1, 2, 3, 4, 5], TEs) + plt.show() +""" + You can view and suggest additions to this spreadsheet `here`_ .. raw:: html From f6637b699160deb9cc77d303aa2c5ce0d1a521ad Mon Sep 17 00:00:00 2001 From: Logan Date: Wed, 6 Nov 2019 11:46:01 -0500 Subject: [PATCH 07/55] correcting plots --- docs/publications.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/publications.rst b/docs/publications.rst index ff60dce04..a4b957c18 100644 --- a/docs/publications.rst +++ b/docs/publications.rst @@ -10,6 +10,9 @@ excluded publication, whether or not it is yours, please add it. The figure below highlights the average TEs used in currently published papers using multiecho at 3T. +""" +... + Average TE at 3T -------- From d02a2c6c5395e15c1599928f46b9f898c07c7e07 Mon Sep 17 00:00:00 2001 From: Logan Date: Wed, 6 Nov 2019 11:47:27 -0500 Subject: [PATCH 08/55] removing comment parts --- docs/publications.rst | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/docs/publications.rst b/docs/publications.rst index a4b957c18..ba2f40697 100644 --- a/docs/publications.rst +++ b/docs/publications.rst @@ -10,11 +10,6 @@ excluded publication, whether or not it is yours, please add it. The figure below highlights the average TEs used in currently published papers using multiecho at 3T. -""" -... - -Average TE at 3T --------- .. plot:: import matplotlib.pyplot as plt @@ -26,7 +21,7 @@ Average TE at 3T TEs = [metable.TE1.mean(), metable.TE2.mean(), metable.TE3.mean(), metable.TE4.mean(), metable.TE5.mean()] plt.bar([1, 2, 3, 4, 5], TEs) plt.show() -""" + You can view and suggest additions to this spreadsheet `here`_ From 9f55ea6058153441ece04fa962bb2e430b31fcb3 Mon Sep 17 00:00:00 2001 From: Logan Date: Wed, 6 Nov 2019 14:30:51 -0500 Subject: [PATCH 09/55] getting live plots working on publication page --- docs/conf.py | 3 ++- docs/publications.rst | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 97650cd0f..aa4eb12eb 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -48,7 +48,8 @@ 'sphinx.ext.todo', 'numpydoc', 'sphinx.ext.ifconfig', - 'sphinx.ext.linkcode'] + 'sphinx.ext.linkcode', + 'matplotlib.sphinxext.plot_directive'] import sphinx from distutils.version import LooseVersion diff --git a/docs/publications.rst b/docs/publications.rst index ba2f40697..fac4bf891 100644 --- a/docs/publications.rst +++ b/docs/publications.rst @@ -12,8 +12,8 @@ at 3T. .. plot:: + import matplotlib.pyplot as plt - import pandas as pd import pandas as pd metable= = pd.read_csv('https://docs.google.com/spreadsheets/d/1WERojJyxFoqcg_tndUm5Kj0H1UfUc9Ban0jFGGfPaBk/export?gid=0&format=csv', header=0 From 5d0c03866f57945919bac15c6d549e32e9a15673 Mon Sep 17 00:00:00 2001 From: Logan Date: Wed, 6 Nov 2019 14:31:52 -0500 Subject: [PATCH 10/55] clean up and adding more WIP details --- docs/multi-echo.rst | 33 ++++++++++++++++++++++++++++----- 1 file changed, 28 insertions(+), 5 deletions(-) diff --git a/docs/multi-echo.rst b/docs/multi-echo.rst index 7f21ba6be..bc3053b36 100644 --- a/docs/multi-echo.rst +++ b/docs/multi-echo.rst @@ -1,5 +1,5 @@ -Multi-echo fMRI -=============== +What is Multi-echo fMRI +======================= Most echo-planar image (EPI) sequences collect a single brain image following a radio frequency (RF) pulse, at a rate known as the repetition time (TR). This typical approach is known as single-echo fMRI. In contrast, multi-echo (ME) @@ -9,8 +9,7 @@ multiple volumes with varying levels of contrast acquired per RF pulse. The physics of multi-echo fMRI ------------------------------ Multi-echo fMRI data is obtained by acquiring multiple echo times (commonly called -`TEs`_) for each MRI volume -during data collection. +`TEs`_) for each MRI volume during data collection. While fMRI signal contains important neural information (termed the blood oxygen-level dependent, or `BOLD signal`_, it also contains "noise" (termed non-BOLD signal) caused by things like @@ -20,7 +19,7 @@ echos allows us to assess whether components of the fMRI signal are BOLD- or non-BOLD. For a comprehensive review, see `Kundu et al. (2017)`_. -.. _echo times: http://mriquestions.com/tr-and-te.html +.. _TEs: http://mriquestions.com/tr-and-te.html .. _BOLD signal: http://www.fil.ion.ucl.ac.uk/spm/course/slides10-zurich/Kerstin_BOLD.pdf .. _Kundu et al. (2017): https://paperpile.com/shared/eH3PPu @@ -125,6 +124,30 @@ We suggest new multi-echo fMRI users examine the :ref:`spreadsheet of publicatio multi-echo fMRI to identify studies with similar acquisition priorities, and use the parameters from those studies as a starting point. +Collecting Multi-echo Data +-------------------------- +For Siemens users, there are two options for Works In Progress (WIPs) Sequences. +The Center for Magnetic Resonance Research at the University of Minnesota +provides a custom MR sequence that allows users to collect multiple echoes +(termed **Contrasts**). The sequence and documentation can be `found here`_. For details +on obtaining a license follow `this link`_. By default the number of contrasts is 1, +yielding a signal echo sequence. In order to collect multiple echoes, increase number of +Contrasts on the **Sequence Tab, Part 1** on the MR console. + +In addition, the Martinos Center at Harvard also has a MR sequence available, with the +details `available here`_. The number of echoes can be specified on the **Sequence, Special** tab +in this sequence. + +.. _found here: https://www.cmrr.umn.edu/multiband/ +.. _this link: http://license.umn.edu/technologies/cmrr_center-for-magnetic-resonance-research-software-for-siemens-mri-scanners +.. _available here: https://www.nmr.mgh.harvard.edu/software/c2p/sms + +.. note:: + In order to increase the number of contrasts ("echoes") you may need to first increase the TR, shorten the + first TE and/or enable in-plane acceleration. For typically used parameters see the + `parameters and publications page`_ +.. _parameters and publications page: https://tedana.readthedocs.io/en/latest/publications.html + Resources --------- From 64fce8316ad384fe1a3a788843366c060b867974 Mon Sep 17 00:00:00 2001 From: Logan Date: Wed, 6 Nov 2019 14:32:06 -0500 Subject: [PATCH 11/55] completing live TE plot from spreasheet --- docs/publications.rst | 37 +++++++++++++++++++------------------ 1 file changed, 19 insertions(+), 18 deletions(-) diff --git a/docs/publications.rst b/docs/publications.rst index fac4bf891..7e8135739 100644 --- a/docs/publications.rst +++ b/docs/publications.rst @@ -1,27 +1,28 @@ .. _spreadsheet of publications: -Multi-echo fMRI Publications -============================ - -The following spreadsheet is an on-going effort to track all publications that -use multi-echo fMRI. This is a volunteer led effort so, if you know of an -excluded publication, whether or not it is yours, please add it. - -The figure below highlights the average TEs used in currently published papers using multiecho -at 3T. +ME-fMRI Parameters & Publications +================================= +The following page highlights a selection of parameters collected from published papers that have +used multi-echo fMRI. The subsequent spreadsheet is an on-going effort to track all of these publication. +This is a volunteer led effort so, if you know of a excluded publication, whether or not it is yours, +please add it. .. plot:: - import matplotlib.pyplot as plt - import pandas as pd - metable= = pd.read_csv('https://docs.google.com/spreadsheets/d/1WERojJyxFoqcg_tndUm5Kj0H1UfUc9Ban0jFGGfPaBk/export?gid=0&format=csv', - header=0 - ) - TEs = [metable.TE1.mean(), metable.TE2.mean(), metable.TE3.mean(), metable.TE4.mean(), metable.TE5.mean()] - plt.bar([1, 2, 3, 4, 5], TEs) - plt.show() - + import matplotlib.pyplot as plt + import pandas as pd + metable = pd.read_csv('https://docs.google.com/spreadsheets/d/1WERojJyxFoqcg_tndUm5Kj0H1UfUc9Ban0jFGGfPaBk/export?gid=0&format=csv', + header=0 ) + TEs = [metable.TE1.mean(), metable.TE2.mean(), metable.TE3.mean(), metable.TE4.mean(), metable.TE5.mean()] + TE_labels = ['TE1', 'TE2', 'TE3', 'TE4', 'TE5'] + plt.bar([1, 2, 3, 4, 5], TEs) + plt.title('Echo Times at 3T', fontsize=16) + pub_count = metable.TE1.count() + plt.text(0.5,60, 'Average from {} studies'.format(pub_count)) + plt.xlabel('Echo Number') + plt.ylabel('Echo Time (ms)') + plt.show() You can view and suggest additions to this spreadsheet `here`_ From ecccb9c671af6d4f2fb8914530f760a2e6445227 Mon Sep 17 00:00:00 2001 From: Logan Date: Wed, 6 Nov 2019 14:40:13 -0500 Subject: [PATCH 12/55] changing outputs to nii.gz --- docs/approach.rst | 12 +++++++----- docs/outputs.rst | 50 +++++++++++++++++++++++------------------------ 2 files changed, 32 insertions(+), 30 deletions(-) diff --git a/docs/approach.rst b/docs/approach.rst index fb3b89cfb..ad7538ca2 100644 --- a/docs/approach.rst +++ b/docs/approach.rst @@ -134,7 +134,7 @@ between the distributions for other echoes. .. image:: /_static/a09_optimal_combination_value_distributions.png The time series for the optimally combined data also looks like a combination -of the other echoes (which it is). +of the other echoes (which it is). This optimally combined data is written out as `ts_OC.nii.gz` .. image:: /_static/a10_optimal_combination_timeseries.png @@ -156,7 +156,7 @@ components analysis (PCA). The goal of this step is to make it easier for the later ICA decomposition to converge. Dimensionality reduction is a common step prior to ICA. TEDPCA applies PCA to the optimally combined data in order to decompose it into component maps and -time series. +time series (saved as `mepca_mix.1D`). Here we can see time series for some example components (we don't really care about the maps): .. image:: /_static/a11_pca_component_timeseries.png @@ -182,7 +182,7 @@ TE-independent (i.e., have low Rho). After component selection is performed, the retained components and their associated betas are used to reconstruct the optimally combined data, resulting -in a dimensionally reduced version of the dataset. +in a dimensionally reduced version of the dataset which is then used in the `TEDICA` step. .. image:: /_static/a12_pca_reduced_data.png @@ -191,7 +191,8 @@ TEDICA Next, ``tedana`` applies TE-dependent independent components analysis (ICA) in order to identify and remove TE-independent (i.e., non-BOLD noise) components. The dimensionally reduced optimally combined data are first subjected to ICA in -order to fit a mixing matrix to the whitened data. +order to fit a mixing matrix to the whitened data. This generates a number if +independent timeseries (saved as `meica_mix.1D`). .. image:: /_static/a13_ica_component_timeseries.png @@ -215,7 +216,8 @@ models (referred to as :math:`\kappa` and :math:`\rho`, respectively). A decision tree is applied to :math:`\kappa`, :math:`\rho`, and other metrics in order to classify ICA components as TE-dependent (BOLD signal), TE-independent -(non-BOLD noise), or neither (to be ignored). +(non-BOLD noise), or neither (to be ignored). These classifications are saved in +`comp_table_ica.txt`. The actual decision tree is dependent on the component selection algorithm employed. ``tedana`` includes two options: `kundu_v2_5` (which uses hardcoded thresholds applied to each of the metrics) and `kundu_v3_2` (which trains a classifier to diff --git a/docs/outputs.rst b/docs/outputs.rst index a0c7c0d1b..99cea9291 100644 --- a/docs/outputs.rst +++ b/docs/outputs.rst @@ -7,24 +7,24 @@ tedana derivatives ====================== ===================================================== Filename Content ====================== ===================================================== -t2sv.nii Limited estimated T2* 3D map. +t2sv.nii.gz Limited estimated T2* 3D map. The difference between the limited and full maps is that, for voxels affected by dropout where only one echo contains good data, the full map uses the single echo's value while the limited map has a NaN. -s0v.nii Limited S0 3D map. +s0v.nii.gz Limited S0 3D map. The difference between the limited and full maps is that, for voxels affected by dropout where only one echo contains good data, the full map uses the single echo's value while the limited map has a NaN. -ts_OC.nii Optimally combined time series. -dn_ts_OC.nii Denoised optimally combined time series. Recommended +ts_OC.nii.gz Optimally combined time series. +dn_ts_OC.nii.gz Denoised optimally combined time series. Recommended dataset for analysis. -lowk_ts_OC.nii Combined time series from rejected components. -midk_ts_OC.nii Combined time series from "mid-k" rejected components. -hik_ts_OC.nii High-kappa time series. This dataset does not +lowk_ts_OC.nii.gz Combined time series from rejected components. +midk_ts_OC.nii.gz Combined time series from "mid-k" rejected components. +hik_ts_OC.nii.gz High-kappa time series. This dataset does not include thermal noise or low variance components. Not the recommended dataset for analysis. comp_table_pca.txt TEDPCA component table. A tab-delimited file with @@ -37,9 +37,9 @@ meica_mix.1D Mixing matrix (component time series) from ICA mixing matrix and the one above are that components may be sorted differently and signs of time series may be flipped. -betas_OC.nii Full ICA coefficient feature set. -betas_hik_OC.nii High-kappa ICA coefficient feature set -feats_OC2.nii Z-normalized spatial component maps +betas_OC.nii.gz Full ICA coefficient feature set. +betas_hik_OC.nii.gz High-kappa ICA coefficient feature set +feats_OC2.nii.gz Z-normalized spatial component maps comp_table_ica.txt TEDICA component table. A tab-delimited file with summary metrics and inclusion/exclusion information for each component from the ICA decomposition. @@ -52,22 +52,22 @@ If ``verbose`` is set to True: ====================== ===================================================== Filename Content ====================== ===================================================== -t2ss.nii Voxel-wise T2* estimates using ascending numbers +t2ss.nii.gz Voxel-wise T2* estimates using ascending numbers of echoes, starting with 2. -s0vs.nii Voxel-wise S0 estimates using ascending numbers +s0vs.nii.gz Voxel-wise S0 estimates using ascending numbers of echoes, starting with 2. -t2svG.nii Full T2* map/time series. The difference between +t2svG.nii.gz Full T2* map/time series. The difference between the limited and full maps is that, for voxels affected by dropout where only one echo contains good data, the full map uses the single echo's value while the limited map has a NaN. Only used for optimal combination. -s0vG.nii Full S0 map/time series. Only used for optimal +s0vG.nii.gz Full S0 map/time series. Only used for optimal combination. -hik_ts_e[echo].nii High-Kappa time series for echo number ``echo`` -midk_ts_e[echo].nii Mid-Kappa time series for echo number ``echo`` -lowk_ts_e[echo].nii Low-Kappa time series for echo number ``echo`` -dn_ts_e[echo].nii Denoised time series for echo number ``echo`` +hik_ts_e[echo].nii.gz High-Kappa time series for echo number ``echo`` +midk_ts_e[echo].nii.gz Mid-Kappa time series for echo number ``echo`` +lowk_ts_e[echo].nii.gz Low-Kappa time series for echo number ``echo`` +dn_ts_e[echo].nii.gz Denoised time series for echo number ``echo`` ====================== ===================================================== If ``gscontrol`` includes 'gsr': @@ -75,12 +75,12 @@ If ``gscontrol`` includes 'gsr': ====================== ===================================================== Filename Content ====================== ===================================================== -T1gs.nii Spatial global signal +T1gs.nii.gz Spatial global signal glsig.1D Time series of global signal from optimally combined data. -tsoc_orig.nii Optimally combined time series with global signal +tsoc_orig.nii.gz Optimally combined time series with global signal retained. -tsoc_nogs.nii Optimally combined time series with global signal +tsoc_nogs.nii.gz Optimally combined time series with global signal removed. ====================== ===================================================== @@ -89,10 +89,10 @@ If ``gscontrol`` includes 't1c': ====================== ===================================================== Filename Content ====================== ===================================================== -sphis_hik.nii T1-like effect -hik_ts_OC_T1c.nii T1 corrected high-kappa time series by regression -dn_ts_OC_T1c.nii T1 corrected denoised time series -betas_hik_OC_T1c.nii T1-GS corrected high-kappa components +sphis_hik.nii.gz T1-like effect +hik_ts_OC_T1c.nii.gz T1 corrected high-kappa time series by regression +dn_ts_OC_T1c.nii.gz T1 corrected denoised time series +betas_hik_OC_T1c.nii.gz T1-GS corrected high-kappa components meica_mix_T1c.1D T1-GS corrected mixing matrix ====================== ===================================================== From 00a6b07b4a4503e749d4a2987c7ca7ac4a163c18 Mon Sep 17 00:00:00 2001 From: Logan Date: Wed, 6 Nov 2019 15:35:16 -0500 Subject: [PATCH 13/55] adding TR and Vox dim subplots --- docs/publications.rst | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/docs/publications.rst b/docs/publications.rst index 7e8135739..c219ff3f7 100644 --- a/docs/publications.rst +++ b/docs/publications.rst @@ -8,22 +8,42 @@ used multi-echo fMRI. The subsequent spreadsheet is an on-going effort to track This is a volunteer led effort so, if you know of a excluded publication, whether or not it is yours, please add it. +The following plots reflect the average values for studies conducted at 3 Tesla. + .. plot:: import matplotlib.pyplot as plt import pandas as pd + import numpy as np metable = pd.read_csv('https://docs.google.com/spreadsheets/d/1WERojJyxFoqcg_tndUm5Kj0H1UfUc9Ban0jFGGfPaBk/export?gid=0&format=csv', header=0 ) TEs = [metable.TE1.mean(), metable.TE2.mean(), metable.TE3.mean(), metable.TE4.mean(), metable.TE5.mean()] TE_labels = ['TE1', 'TE2', 'TE3', 'TE4', 'TE5'] plt.bar([1, 2, 3, 4, 5], TEs) - plt.title('Echo Times at 3T', fontsize=16) + plt.title('Echo Times', fontsize=18) pub_count = metable.TE1.count() plt.text(0.5,60, 'Average from {} studies'.format(pub_count)) plt.xlabel('Echo Number') plt.ylabel('Echo Time (ms)') plt.show() + + plt.hist(metable.TR.to_numpy()) + plt.title('Repetition Times', fontsize = 18) + plt.xlabel('Repetition Time (s)') + plt.ylabel('Count') + plt.show() + + + x_vox = metable.x.to_numpy() + y_vox = metable.y.to_numpy() + z_vox = metable.z.to_numpy() + plt.hist(np.nanmean([x_vox, y_vox, z_vox],0)) + plt.title('Voxel dimensions', fontsize = 18) + plt.xlabel('Average Voxel dimension (mm)') + plt.ylabel('Count') + plt.show() + You can view and suggest additions to this spreadsheet `here`_ .. raw:: html From bce67e67cfd8f28b14b7e506bd7880600d461fe8 Mon Sep 17 00:00:00 2001 From: Logan Date: Wed, 6 Nov 2019 15:35:41 -0500 Subject: [PATCH 14/55] initial adding of output details --- docs/approach.rst | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/docs/approach.rst b/docs/approach.rst index ad7538ca2..fc0c19535 100644 --- a/docs/approach.rst +++ b/docs/approach.rst @@ -62,7 +62,12 @@ value for that voxel in the adaptive mask. Monoexponential decay model fit ``````````````````````````````` The next step is to fit a monoexponential decay model to the data in order to -estimate voxel-wise :math:`T_{2}^*` and :math:`S_0`. +estimate voxel-wise :math:`T_{2}^*` and :math:`S_0`. :math:`S_0` corresponds +to the total signal in each voxel before decay and can reflect coil sensivity. +:math:`T_{2}^*` corresponds to the rate at which a voxel decays over time, which +is related to signal dropout and BOLD sensitivity. Estimates of the parameters are +saved as **t2sv.nii.gz** and **s0v.nii.gz**. + While :math:`T_{2}^*` and :math:`S_0` in fact fluctuate over time, estimating them on a volume-by-volume basis with only a small number of echoes is not feasible (i.e., the estimates would be extremely noisy). @@ -70,7 +75,7 @@ As such, we estimate average :math:`T_{2}^*` and :math:`S_0` maps and use those throughout the workflow. In order to make it easier to fit the decay model to the data, ``tedana`` -transforms the data. +transforms the data by default. The BOLD data are transformed as :math:`log(|S|+1)`, where :math:`S` is the BOLD signal. The echo times are also multiplied by -1. @@ -134,7 +139,7 @@ between the distributions for other echoes. .. image:: /_static/a09_optimal_combination_value_distributions.png The time series for the optimally combined data also looks like a combination -of the other echoes (which it is). This optimally combined data is written out as `ts_OC.nii.gz` +of the other echoes (which it is). This optimally combined data is written out as **ts_OC.nii.gz** .. image:: /_static/a10_optimal_combination_timeseries.png @@ -156,7 +161,7 @@ components analysis (PCA). The goal of this step is to make it easier for the later ICA decomposition to converge. Dimensionality reduction is a common step prior to ICA. TEDPCA applies PCA to the optimally combined data in order to decompose it into component maps and -time series (saved as `mepca_mix.1D`). +time series (saved as **mepca_mix.1D**). Here we can see time series for some example components (we don't really care about the maps): .. image:: /_static/a11_pca_component_timeseries.png @@ -192,7 +197,8 @@ Next, ``tedana`` applies TE-dependent independent components analysis (ICA) in order to identify and remove TE-independent (i.e., non-BOLD noise) components. The dimensionally reduced optimally combined data are first subjected to ICA in order to fit a mixing matrix to the whitened data. This generates a number if -independent timeseries (saved as `meica_mix.1D`). +independent timeseries (saved as **meica_mix.1D**), as well as beta maps which show +the spatially loading of these components on the brain (**betas_OC.nii.gz**). .. image:: /_static/a13_ica_component_timeseries.png @@ -223,6 +229,9 @@ The actual decision tree is dependent on the component selection algorithm emplo applied to each of the metrics) and `kundu_v3_2` (which trains a classifier to select components). +Components that are classified as noise are projected out of the optimally combined data, +yielding a denoised timeseries, which is saved as `dn_ts_OC.nii.gz`. + .. image:: /_static/a15_denoised_data_timeseries.png Removal of spatially diffuse noise (optional) From 20249de7e905d7278690330a78a4cc7a02f5941f Mon Sep 17 00:00:00 2001 From: Logan Date: Wed, 6 Nov 2019 15:36:15 -0500 Subject: [PATCH 15/55] fixing tables --- docs/outputs.rst | 60 ++++++++++++++++++++++++------------------------ 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/docs/outputs.rst b/docs/outputs.rst index 99cea9291..d8422137a 100644 --- a/docs/outputs.rst +++ b/docs/outputs.rst @@ -7,24 +7,24 @@ tedana derivatives ====================== ===================================================== Filename Content ====================== ===================================================== -t2sv.nii.gz Limited estimated T2* 3D map. +t2sv.nii.gz Limited estimated T2* 3D map. The difference between the limited and full maps is that, for voxels affected by dropout where only one echo contains good data, the full map uses the single echo's value while the limited map has a NaN. -s0v.nii.gz Limited S0 3D map. +s0v.nii.gz Limited S0 3D map. The difference between the limited and full maps is that, for voxels affected by dropout where only one echo contains good data, the full map uses the single echo's value while the limited map has a NaN. -ts_OC.nii.gz Optimally combined time series. -dn_ts_OC.nii.gz Denoised optimally combined time series. Recommended +ts_OC.nii.gz Optimally combined time series. +dn_ts_OC.nii.gz Denoised optimally combined time series. Recommended dataset for analysis. -lowk_ts_OC.nii.gz Combined time series from rejected components. -midk_ts_OC.nii.gz Combined time series from "mid-k" rejected components. -hik_ts_OC.nii.gz High-kappa time series. This dataset does not +lowk_ts_OC.nii.gz Combined time series from rejected components. +midk_ts_OC.nii.gz Combined time series from "mid-k" rejected components. +hik_ts_OC.nii.gz High-kappa time series. This dataset does not include thermal noise or low variance components. Not the recommended dataset for analysis. comp_table_pca.txt TEDPCA component table. A tab-delimited file with @@ -37,9 +37,9 @@ meica_mix.1D Mixing matrix (component time series) from ICA mixing matrix and the one above are that components may be sorted differently and signs of time series may be flipped. -betas_OC.nii.gz Full ICA coefficient feature set. -betas_hik_OC.nii.gz High-kappa ICA coefficient feature set -feats_OC2.nii.gz Z-normalized spatial component maps +betas_OC.nii.gz Full ICA coefficient feature set. +betas_hik_OC.nii.gz High-kappa ICA coefficient feature set +feats_OC2.nii.gz Z-normalized spatial component maps comp_table_ica.txt TEDICA component table. A tab-delimited file with summary metrics and inclusion/exclusion information for each component from the ICA decomposition. @@ -52,22 +52,22 @@ If ``verbose`` is set to True: ====================== ===================================================== Filename Content ====================== ===================================================== -t2ss.nii.gz Voxel-wise T2* estimates using ascending numbers +t2ss.nii.gz Voxel-wise T2* estimates using ascending numbers of echoes, starting with 2. -s0vs.nii.gz Voxel-wise S0 estimates using ascending numbers +s0vs.nii.gz Voxel-wise S0 estimates using ascending numbers of echoes, starting with 2. -t2svG.nii.gz Full T2* map/time series. The difference between +t2svG.nii.gz Full T2* map/time series. The difference between the limited and full maps is that, for voxels affected by dropout where only one echo contains good data, the full map uses the single echo's value while the limited map has a NaN. Only used for optimal combination. -s0vG.nii.gz Full S0 map/time series. Only used for optimal +s0vG.nii.gz Full S0 map/time series. Only used for optimal combination. -hik_ts_e[echo].nii.gz High-Kappa time series for echo number ``echo`` -midk_ts_e[echo].nii.gz Mid-Kappa time series for echo number ``echo`` -lowk_ts_e[echo].nii.gz Low-Kappa time series for echo number ``echo`` -dn_ts_e[echo].nii.gz Denoised time series for echo number ``echo`` +hik_ts_e[echo].nii.gz High-Kappa time series for echo number ``echo`` +midk_ts_e[echo].nii.gz Mid-Kappa time series for echo number ``echo`` +lowk_ts_e[echo].nii.gz Low-Kappa time series for echo number ``echo`` +dn_ts_e[echo].nii.gz Denoised time series for echo number ``echo`` ====================== ===================================================== If ``gscontrol`` includes 'gsr': @@ -75,26 +75,26 @@ If ``gscontrol`` includes 'gsr': ====================== ===================================================== Filename Content ====================== ===================================================== -T1gs.nii.gz Spatial global signal +T1gs.nii.gz Spatial global signal glsig.1D Time series of global signal from optimally combined data. -tsoc_orig.nii.gz Optimally combined time series with global signal +tsoc_orig.nii.gz Optimally combined time series with global signal retained. -tsoc_nogs.nii.gz Optimally combined time series with global signal +tsoc_nogs.nii.gz Optimally combined time series with global signal removed. ====================== ===================================================== If ``gscontrol`` includes 't1c': -====================== ===================================================== -Filename Content -====================== ===================================================== -sphis_hik.nii.gz T1-like effect -hik_ts_OC_T1c.nii.gz T1 corrected high-kappa time series by regression -dn_ts_OC_T1c.nii.gz T1 corrected denoised time series -betas_hik_OC_T1c.nii.gz T1-GS corrected high-kappa components -meica_mix_T1c.1D T1-GS corrected mixing matrix -====================== ===================================================== +======================= ===================================================== +Filename Content +======================= ===================================================== +sphis_hik.nii.gz T1-like effect +hik_ts_OC_T1c.nii.gz T1 corrected high-kappa time series by regression +dn_ts_OC_T1c.nii.gz T1 corrected denoised time series +betas_hik_OC_T1c.nii.gz T1-GS corrected high-kappa components +meica_mix_T1c.1D T1-GS corrected mixing matrix +======================= ===================================================== Component tables ---------------- From 8cd1117f0d8f8b412fdd28417fab43926204f731 Mon Sep 17 00:00:00 2001 From: Logan Date: Wed, 6 Nov 2019 15:36:31 -0500 Subject: [PATCH 16/55] rearranging to considerations and recomendations --- docs/multi-echo.rst | 62 +++++++++++++++++++++++++++++---------------- 1 file changed, 40 insertions(+), 22 deletions(-) diff --git a/docs/multi-echo.rst b/docs/multi-echo.rst index bc3053b36..8a46cae19 100644 --- a/docs/multi-echo.rst +++ b/docs/multi-echo.rst @@ -54,15 +54,42 @@ We can use this information to denoise the optimally combined time series. .. _processing pipeline details: https://tedana.readthedocs.io/en/latest/approach.html#optimal-combination .. _Pruim et al. (2015): https://www.sciencedirect.com/science/article/pii/S1053811915001822 -Recommendations on multi-echo use for someone planning a new study ------------------------------------------------------------------- +Considerations for collecting multi-echo data +--------------------------------------------- Multi-echo fMRI acquisition sequences and analysis methods are rapidly maturing. Someone who has access -to a multi-echo fMRI sequence should seriously consider using it. Multiple studies have shown that a +to a multi-echo fMRI sequence should seriously consider using it. The following are a few points to +consider when deciding whether or not to collect multi-echo data + +`There is a cost of collecting multiple echoes` +*********************************************** +The one difference with multi-echo is a slight time cost. +For multi-echo fMRI, the shortest echo time (TE) is essentially free since it is collected in the +gap between the RF pulse and the single-echo acquisition. +The second echo tends to roughly match the single-echo TE. +Additional echoes require more time. +For example, on a 3T MRI, if the T2* weighted TE is 30ms for single echo fMRI, +a multi-echo sequence may have TEs of 15.4, 29.7, and 44.0ms. +In this example, the extra 14ms of acquisition time per RF pulse is the cost of multi-echo fMRI. + +One way to think about this cost is in comparison to single-echo fMRI. +If a multi-echo sequence has identical spatial resolution and acceleration as a single-echo sequence, +then a rough rule of thumb is that the multi-echo sequence will have 10% fewer slices or 10% longer TR. +Instead of compromising on slice coverage or TR, one can increase acceleration. +If one increases acceleration, it is worth doing an empirical comparison to make sure there +isn't a non-trivial loss in SNR or an increase of artifacts. + +`A simple weighted average will increase SNR` +********************************************* +Multiple studies have shown that a weighted average of the echoes to optimize T2* weighting, sometimes called "optimally combined," gives a reliable, modest boost in data quality. The optimal combination of echoes can currently be calculated in several software packages including AFNI, fMRIPrep, and tedana. In tedana, the weighted average can be calculated with `t2smap`_ If no other -acquisition compromises are necessary to acquire multi-echo data, this boost is worthwhile. If other +acquisition compromises are necessary to acquire multi-echo data, this boost is worthwhile. + +`Consider the life of the dataset` +********************************** +If other compromises are necessary, consider the life of the data set. If data is being acquired for a discrete study that will be acquired, analyzed, and published in a year or two, it might not be worth making compromises to acquire multi-echo data. If a data set is expected to be used for future analyses in later @@ -73,7 +100,11 @@ Other multi-echo denoising methods, such as MEICA, the predecessor to tedana, ha much greater data quality improvements, as well as the ability to more accurately separate visually similar signal vs noise, such as scanner based drifts vs slow changes in BOLD signal. These more powerful methods are still being improved, and the algorithms are still changing. Users need to have the time and knowledge to look -at the denoising output from every run to make sure denoising worked as intended. If someone wants a push-button +at the denoising output from every run to make sure denoising worked as intended. + +`Consider the cost of added quality control` +******************************************** +If someone wants a push-button way to use multi-echo data to improve data quality, that doesn't require as deep an inspection of every output, stick with using the weighted average. The developers of tedana look forward to when tedana and other methods have sufficiently stable algorithms, which have been validated on a wide range of data sets, so that we can @@ -90,22 +121,6 @@ fMRI sequences are also relevant. Choose sequence parameters that meet the priorities of a study with regards to spatial resolution, spatial coverage, sample rate, signal-to-noise ratio, signal drop-out, distortion, and artifacts. -The one difference with multi-echo is a slight time cost. -For multi-echo fMRI, the shortest echo time (TE) is essentially free since it is collected in the -gap between the RF pulse and the single-echo acquisition. -The second echo tends to roughly match the single-echo TE. -Additional echoes require more time. -For example, on a 3T MRI, if the T2* weighted TE is 30ms for single echo fMRI, -a multi-echo sequence may have TEs of 15.4, 29.7, and 44.0ms. -In this example, the extra 14ms of acquisition time per RF pulse is the cost of multi-echo fMRI. - -One way to think about this cost is in comparison to single-echo fMRI. -If a multi-echo sequence has identical spatial resolution and acceleration as a single-echo sequence, -then a rough rule of thumb is that the multi-echo sequence will have 10% fewer slices or 10% longer TR. -Instead of compromising on slice coverage or TR, one can increase acceleration. -If one increases acceleration, it is worth doing an empirical comparison to make sure there -isn't a non-trivial loss in SNR or an increase of artifacts. - A minimum of 3 echoes is recommended for running TE-dependent denoising. While there are successful studies that don’t follow this rule, it may be useful to have at least one echo that is earlier and one echo that is later than the @@ -122,7 +137,10 @@ There are multiple ways to balance the slight time cost from the added echoes th resulted in research publications. We suggest new multi-echo fMRI users examine the :ref:`spreadsheet of publications` that use multi-echo fMRI to identify studies with similar acquisition priorities, -and use the parameters from those studies as a starting point. +and use the parameters from those studies as a starting point. More complete recomendations +and guidelines are discussed in the `appendix`_ of Dipasquale et al, 2017. + +.. _appendix: https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0173289 Collecting Multi-echo Data -------------------------- From 7cd37c14fab0c633ab84684e418cda5591ef7b30 Mon Sep 17 00:00:00 2001 From: Logan Date: Wed, 6 Nov 2019 15:52:42 -0500 Subject: [PATCH 17/55] seperating out considerations section --- docs/considerations.rst | 182 ++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 3 +- docs/multi-echo.rst | 182 ---------------------------------------- 3 files changed, 184 insertions(+), 183 deletions(-) create mode 100644 docs/considerations.rst diff --git a/docs/considerations.rst b/docs/considerations.rst new file mode 100644 index 000000000..5211ed893 --- /dev/null +++ b/docs/considerations.rst @@ -0,0 +1,182 @@ +Consideratsion for ME-fMRI +========================== +Multi-echo fMRI acquisition sequences and analysis methods are rapidly maturing. Someone who has access +to a multi-echo fMRI sequence should seriously consider using it. The following are a few points to +consider when deciding whether or not to collect multi-echo data + +`There is a cost of collecting multiple echoes` +*********************************************** +The one difference with multi-echo is a slight time cost. +For multi-echo fMRI, the shortest echo time (TE) is essentially free since it is collected in the +gap between the RF pulse and the single-echo acquisition. +The second echo tends to roughly match the single-echo TE. +Additional echoes require more time. +For example, on a 3T MRI, if the T2* weighted TE is 30ms for single echo fMRI, +a multi-echo sequence may have TEs of 15.4, 29.7, and 44.0ms. +In this example, the extra 14ms of acquisition time per RF pulse is the cost of multi-echo fMRI. + +One way to think about this cost is in comparison to single-echo fMRI. +If a multi-echo sequence has identical spatial resolution and acceleration as a single-echo sequence, +then a rough rule of thumb is that the multi-echo sequence will have 10% fewer slices or 10% longer TR. +Instead of compromising on slice coverage or TR, one can increase acceleration. +If one increases acceleration, it is worth doing an empirical comparison to make sure there +isn't a non-trivial loss in SNR or an increase of artifacts. + +`A simple weighted average will increase SNR` +********************************************* +Multiple studies have shown that a +weighted average of the echoes to optimize T2* weighting, sometimes called "optimally combined," +gives a reliable, modest boost in data quality. The optimal combination of echoes can currently be +calculated in several software packages including AFNI, fMRIPrep, and tedana. In tedana, the weighted +average can be calculated with `t2smap`_ If no other +acquisition compromises are necessary to acquire multi-echo data, this boost is worthwhile. + +`Consider the life of the dataset` +********************************** +If other +compromises are necessary, consider the life of the data set. If data is being acquired for a discrete +study that will be acquired, analyzed, and published in a year or two, it might not be worth making +compromises to acquire multi-echo data. If a data set is expected to be used for future analyses in later +years, it is likely that more powerful approaches to multi-echo denoising will sufficiently mature and add +even more value to a data set. + +Other multi-echo denoising methods, such as MEICA, the predecessor to tedana, have shown the potential for +much greater data quality improvements, as well as the ability to more accurately separate visually similar +signal vs noise, such as scanner based drifts vs slow changes in BOLD signal. These more powerful methods are +still being improved, and the algorithms are still changing. Users need to have the time and knowledge to look +at the denoising output from every run to make sure denoising worked as intended. + +`Consider the cost of added quality control` +******************************************** +If someone wants a push-button +way to use multi-echo data to improve data quality, that doesn't require as deep an inspection of every output, +stick with using the weighted average. The developers of tedana look forward to when tedana and other methods +have sufficiently stable algorithms, which have been validated on a wide range of data sets, so that we can +recommend the wide use of tedana. + +.. _t2smap: https://tedana.readthedocs.io/en/latest/usage.html#run-t2smap + +Acquisition Parameter Recommendations +------------------------------------- +There is no empirically tested best parameter set for multi-echo acquisition. +The guidelines for optimizing parameters are similar to single-echo fMRI. +For multi-echo fMRI, the same factors that may guide priorities for single echo +fMRI sequences are also relevant. +Choose sequence parameters that meet the priorities of a study with regards to spatial resolution, +spatial coverage, sample rate, signal-to-noise ratio, signal drop-out, distortion, and artifacts. + +A minimum of 3 echoes is recommended for running TE-dependent denoising. +While there are successful studies that don’t follow this rule, +it may be useful to have at least one echo that is earlier and one echo that is later than the +TE one would use for single-echo T2* weighted fMRI. + +More than 3 echoes may be useful, because that would allow for more accurate +estimates of BOLD and non-BOLD weighted fluctuations, but more echoes have an +additional time cost, which would result in either less spatiotemporal coverage +or more acceleration. +Where the benefits of more echoes balance out the additional costs is an open research question. + +We are not recommending specific parameter options at this time. +There are multiple ways to balance the slight time cost from the added echoes that have +resulted in research publications. +We suggest new multi-echo fMRI users examine the :ref:`spreadsheet of publications` that use +multi-echo fMRI to identify studies with similar acquisition priorities, +and use the parameters from those studies as a starting point. More complete recomendations +and guidelines are discussed in the `appendix`_ of Dipasquale et al, 2017. + +.. _appendix: https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0173289 + +Collecting Multi-echo Data +-------------------------- +For Siemens users, there are two options for Works In Progress (WIPs) Sequences. +The Center for Magnetic Resonance Research at the University of Minnesota +provides a custom MR sequence that allows users to collect multiple echoes +(termed **Contrasts**). The sequence and documentation can be `found here`_. For details +on obtaining a license follow `this link`_. By default the number of contrasts is 1, +yielding a signal echo sequence. In order to collect multiple echoes, increase number of +Contrasts on the **Sequence Tab, Part 1** on the MR console. + +In addition, the Martinos Center at Harvard also has a MR sequence available, with the +details `available here`_. The number of echoes can be specified on the **Sequence, Special** tab +in this sequence. + +.. _found here: https://www.cmrr.umn.edu/multiband/ +.. _this link: http://license.umn.edu/technologies/cmrr_center-for-magnetic-resonance-research-software-for-siemens-mri-scanners +.. _available here: https://www.nmr.mgh.harvard.edu/software/c2p/sms + +.. note:: + In order to increase the number of contrasts ("echoes") you may need to first increase the TR, shorten the + first TE and/or enable in-plane acceleration. For typically used parameters see the + `parameters and publications page`_ +.. _parameters and publications page: https://tedana.readthedocs.io/en/latest/publications.html + +Resources +--------- + +Journal articles +**************** +* | :ref:`spreadsheet of publications` catalogues papers using multi-echo fMRI, + with information about acquisition parameters. +* | `Multi-echo acquisition`_ + | Posse, NeuroImage 2012 + | Includes an historical overview of multi-echo acquisition and research +* | `Multi-Echo fMRI A Review of Applications in fMRI Denoising and Analysis of BOLD Signals`_ + | Kundu et al, NeuroImage 2017 + | A review of multi-echo denoising with a focus on the MEICA algorithm +* | `Enhanced identification of BOLD-like componenents with MESMS and MEICA`_ + | Olafsson et al, NeuroImage 2015 + | The appendix includes a good explanation of the math underlying MEICA denoising +* | `Comparing resting state fMRI de-noising approaches using multi- and single-echo acqusitions`_ + | Dipasquale et al, PLoS One 2017 + | The appendix includes some recommendations for multi-echo acqusition + +.. _Multi-echo acquisition: https://www.ncbi.nlm.nih.gov/pubmed/22056458 +.. _Multi-Echo fMRI A Review of Applications in fMRI Denoising and Analysis of BOLD Signals: https://www.ncbi.nlm.nih.gov/pubmed/28363836 +.. _Enhanced identification of BOLD-like componenents with MESMS and MEICA: https://www.ncbi.nlm.nih.gov/pubmed/25743045 +.. _Comparing resting state fMRI de-noising approaches using multi- and single-echo acqusitions: https://www.ncbi.nlm.nih.gov/pubmed/28323821 + +Videos +****** +* An `educational session from OHBM 2017`_ by Dr. Prantik Kundu about multi-echo denoising +* A `series of lectures from the OHBM 2017 multi-echo session`_ on multiple facets of multi-echo data analysis +* | Multi-echo fMRI lecture from the `2018 NIH FMRI Summer Course`_ by Javier Gonzalez-Castillo + | `Slides from 2018 NIH FMRI Summer Course`_ + +.. _educational session from OHBM 2017: https://www.pathlms.com/ohbm/courses/5158/sections/7788/video_presentations/75977 +.. _series of lectures from the OHBM 2017 multi-echo session: https://www.pathlms.com/ohbm/courses/5158/sections/7822 +.. _2018 NIH FMRI Summer Course: https://fmrif.nimh.nih.gov/course/fmrif_course/2018/14_Javier_20180713 +.. _Slides from 2018 NIH FMRI Summer Course: https://fmrif.nimh.nih.gov/COURSE/fmrif_course/2018/content/14_Javier_20180713.pdf + +Available multi-echo fMRI sequences for multiple vendors +******************************************************** + +Information on multi-echo sequences from Siemens, GE, and Phillips will be added here. + +Multi-echo preprocessing software +********************************* + +tedana requires data that has already been preprocessed for head motion, alignment, etc. +More details on software packages that include preprocessing options specifically for multi-echo +fMRI data, such as AFNI and fMRIPrep will be added here. + +Other software that uses multi-echo fMRI +**************************************** + +Information and links to other approaches for denoising multi-echo fMRI data will be added here. + +Datasets +******** +A number of multi-echo datasets have been made public so far. +This list is not necessarily up-to-date, so please check out OpenNeuro to potentially find more. + +* `Multi-echo fMRI replication sample of autobiographical memory, prospection and theory of mind reasoning tasks`_ +* `Multi-echo Cambridge`_ +* `Multiband multi-echo imaging of simultaneous oxygenation and flow timeseries for resting state connectivity`_ +* `Valence processing differs across stimulus modalities`_ +* `Cambridge Centre for Ageing Neuroscience (Cam-CAN)`_ + +.. _Multi-echo fMRI replication sample of autobiographical memory, prospection and theory of mind reasoning tasks: https://openneuro.org/datasets/ds000210/ +.. _Multi-echo Cambridge: https://openneuro.org/datasets/ds000258 +.. _Multiband multi-echo imaging of simultaneous oxygenation and flow timeseries for resting state connectivity: https://openneuro.org/datasets/ds000254 +.. _Valence processing differs across stimulus modalities: https://openneuro.org/datasets/ds001491 +.. _Cambridge Centre for Ageing Neuroscience (Cam-CAN): https://camcan-archive.mrc-cbu.cam.ac.uk/dataaccess/ diff --git a/docs/index.rst b/docs/index.rst index ad33fcd2d..7f02eb45e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -141,9 +141,10 @@ tedana is licensed under GNU Lesser General Public License version 2.1. .. toctree:: :maxdepth: 2 :caption: Contents: - + installation multi-echo + considerations publications usage approach diff --git a/docs/multi-echo.rst b/docs/multi-echo.rst index 8a46cae19..395f8fd61 100644 --- a/docs/multi-echo.rst +++ b/docs/multi-echo.rst @@ -54,185 +54,3 @@ We can use this information to denoise the optimally combined time series. .. _processing pipeline details: https://tedana.readthedocs.io/en/latest/approach.html#optimal-combination .. _Pruim et al. (2015): https://www.sciencedirect.com/science/article/pii/S1053811915001822 -Considerations for collecting multi-echo data ---------------------------------------------- -Multi-echo fMRI acquisition sequences and analysis methods are rapidly maturing. Someone who has access -to a multi-echo fMRI sequence should seriously consider using it. The following are a few points to -consider when deciding whether or not to collect multi-echo data - -`There is a cost of collecting multiple echoes` -*********************************************** -The one difference with multi-echo is a slight time cost. -For multi-echo fMRI, the shortest echo time (TE) is essentially free since it is collected in the -gap between the RF pulse and the single-echo acquisition. -The second echo tends to roughly match the single-echo TE. -Additional echoes require more time. -For example, on a 3T MRI, if the T2* weighted TE is 30ms for single echo fMRI, -a multi-echo sequence may have TEs of 15.4, 29.7, and 44.0ms. -In this example, the extra 14ms of acquisition time per RF pulse is the cost of multi-echo fMRI. - -One way to think about this cost is in comparison to single-echo fMRI. -If a multi-echo sequence has identical spatial resolution and acceleration as a single-echo sequence, -then a rough rule of thumb is that the multi-echo sequence will have 10% fewer slices or 10% longer TR. -Instead of compromising on slice coverage or TR, one can increase acceleration. -If one increases acceleration, it is worth doing an empirical comparison to make sure there -isn't a non-trivial loss in SNR or an increase of artifacts. - -`A simple weighted average will increase SNR` -********************************************* -Multiple studies have shown that a -weighted average of the echoes to optimize T2* weighting, sometimes called "optimally combined," -gives a reliable, modest boost in data quality. The optimal combination of echoes can currently be -calculated in several software packages including AFNI, fMRIPrep, and tedana. In tedana, the weighted -average can be calculated with `t2smap`_ If no other -acquisition compromises are necessary to acquire multi-echo data, this boost is worthwhile. - -`Consider the life of the dataset` -********************************** -If other -compromises are necessary, consider the life of the data set. If data is being acquired for a discrete -study that will be acquired, analyzed, and published in a year or two, it might not be worth making -compromises to acquire multi-echo data. If a data set is expected to be used for future analyses in later -years, it is likely that more powerful approaches to multi-echo denoising will sufficiently mature and add -even more value to a data set. - -Other multi-echo denoising methods, such as MEICA, the predecessor to tedana, have shown the potential for -much greater data quality improvements, as well as the ability to more accurately separate visually similar -signal vs noise, such as scanner based drifts vs slow changes in BOLD signal. These more powerful methods are -still being improved, and the algorithms are still changing. Users need to have the time and knowledge to look -at the denoising output from every run to make sure denoising worked as intended. - -`Consider the cost of added quality control` -******************************************** -If someone wants a push-button -way to use multi-echo data to improve data quality, that doesn't require as deep an inspection of every output, -stick with using the weighted average. The developers of tedana look forward to when tedana and other methods -have sufficiently stable algorithms, which have been validated on a wide range of data sets, so that we can -recommend the wide use of tedana. - -.. _t2smap: https://tedana.readthedocs.io/en/latest/usage.html#run-t2smap - -Acquisition Parameter Recommendations -------------------------------------- -There is no empirically tested best parameter set for multi-echo acquisition. -The guidelines for optimizing parameters are similar to single-echo fMRI. -For multi-echo fMRI, the same factors that may guide priorities for single echo -fMRI sequences are also relevant. -Choose sequence parameters that meet the priorities of a study with regards to spatial resolution, -spatial coverage, sample rate, signal-to-noise ratio, signal drop-out, distortion, and artifacts. - -A minimum of 3 echoes is recommended for running TE-dependent denoising. -While there are successful studies that don’t follow this rule, -it may be useful to have at least one echo that is earlier and one echo that is later than the -TE one would use for single-echo T2* weighted fMRI. - -More than 3 echoes may be useful, because that would allow for more accurate -estimates of BOLD and non-BOLD weighted fluctuations, but more echoes have an -additional time cost, which would result in either less spatiotemporal coverage -or more acceleration. -Where the benefits of more echoes balance out the additional costs is an open research question. - -We are not recommending specific parameter options at this time. -There are multiple ways to balance the slight time cost from the added echoes that have -resulted in research publications. -We suggest new multi-echo fMRI users examine the :ref:`spreadsheet of publications` that use -multi-echo fMRI to identify studies with similar acquisition priorities, -and use the parameters from those studies as a starting point. More complete recomendations -and guidelines are discussed in the `appendix`_ of Dipasquale et al, 2017. - -.. _appendix: https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0173289 - -Collecting Multi-echo Data --------------------------- -For Siemens users, there are two options for Works In Progress (WIPs) Sequences. -The Center for Magnetic Resonance Research at the University of Minnesota -provides a custom MR sequence that allows users to collect multiple echoes -(termed **Contrasts**). The sequence and documentation can be `found here`_. For details -on obtaining a license follow `this link`_. By default the number of contrasts is 1, -yielding a signal echo sequence. In order to collect multiple echoes, increase number of -Contrasts on the **Sequence Tab, Part 1** on the MR console. - -In addition, the Martinos Center at Harvard also has a MR sequence available, with the -details `available here`_. The number of echoes can be specified on the **Sequence, Special** tab -in this sequence. - -.. _found here: https://www.cmrr.umn.edu/multiband/ -.. _this link: http://license.umn.edu/technologies/cmrr_center-for-magnetic-resonance-research-software-for-siemens-mri-scanners -.. _available here: https://www.nmr.mgh.harvard.edu/software/c2p/sms - -.. note:: - In order to increase the number of contrasts ("echoes") you may need to first increase the TR, shorten the - first TE and/or enable in-plane acceleration. For typically used parameters see the - `parameters and publications page`_ -.. _parameters and publications page: https://tedana.readthedocs.io/en/latest/publications.html - -Resources ---------- - -Journal articles -**************** -* | :ref:`spreadsheet of publications` catalogues papers using multi-echo fMRI, - with information about acquisition parameters. -* | `Multi-echo acquisition`_ - | Posse, NeuroImage 2012 - | Includes an historical overview of multi-echo acquisition and research -* | `Multi-Echo fMRI A Review of Applications in fMRI Denoising and Analysis of BOLD Signals`_ - | Kundu et al, NeuroImage 2017 - | A review of multi-echo denoising with a focus on the MEICA algorithm -* | `Enhanced identification of BOLD-like componenents with MESMS and MEICA`_ - | Olafsson et al, NeuroImage 2015 - | The appendix includes a good explanation of the math underlying MEICA denoising -* | `Comparing resting state fMRI de-noising approaches using multi- and single-echo acqusitions`_ - | Dipasquale et al, PLoS One 2017 - | The appendix includes some recommendations for multi-echo acqusition - -.. _Multi-echo acquisition: https://www.ncbi.nlm.nih.gov/pubmed/22056458 -.. _Multi-Echo fMRI A Review of Applications in fMRI Denoising and Analysis of BOLD Signals: https://www.ncbi.nlm.nih.gov/pubmed/28363836 -.. _Enhanced identification of BOLD-like componenents with MESMS and MEICA: https://www.ncbi.nlm.nih.gov/pubmed/25743045 -.. _Comparing resting state fMRI de-noising approaches using multi- and single-echo acqusitions: https://www.ncbi.nlm.nih.gov/pubmed/28323821 - -Videos -****** -* An `educational session from OHBM 2017`_ by Dr. Prantik Kundu about multi-echo denoising -* A `series of lectures from the OHBM 2017 multi-echo session`_ on multiple facets of multi-echo data analysis -* | Multi-echo fMRI lecture from the `2018 NIH FMRI Summer Course`_ by Javier Gonzalez-Castillo - | `Slides from 2018 NIH FMRI Summer Course`_ - -.. _educational session from OHBM 2017: https://www.pathlms.com/ohbm/courses/5158/sections/7788/video_presentations/75977 -.. _series of lectures from the OHBM 2017 multi-echo session: https://www.pathlms.com/ohbm/courses/5158/sections/7822 -.. _2018 NIH FMRI Summer Course: https://fmrif.nimh.nih.gov/course/fmrif_course/2018/14_Javier_20180713 -.. _Slides from 2018 NIH FMRI Summer Course: https://fmrif.nimh.nih.gov/COURSE/fmrif_course/2018/content/14_Javier_20180713.pdf - -Available multi-echo fMRI sequences for multiple vendors -******************************************************** - -Information on multi-echo sequences from Siemens, GE, and Phillips will be added here. - -Multi-echo preprocessing software -********************************* - -tedana requires data that has already been preprocessed for head motion, alignment, etc. -More details on software packages that include preprocessing options specifically for multi-echo -fMRI data, such as AFNI and fMRIPrep will be added here. - -Other software that uses multi-echo fMRI -**************************************** - -Information and links to other approaches for denoising multi-echo fMRI data will be added here. - -Datasets -******** -A number of multi-echo datasets have been made public so far. -This list is not necessarily up-to-date, so please check out OpenNeuro to potentially find more. - -* `Multi-echo fMRI replication sample of autobiographical memory, prospection and theory of mind reasoning tasks`_ -* `Multi-echo Cambridge`_ -* `Multiband multi-echo imaging of simultaneous oxygenation and flow timeseries for resting state connectivity`_ -* `Valence processing differs across stimulus modalities`_ -* `Cambridge Centre for Ageing Neuroscience (Cam-CAN)`_ - -.. _Multi-echo fMRI replication sample of autobiographical memory, prospection and theory of mind reasoning tasks: https://openneuro.org/datasets/ds000210/ -.. _Multi-echo Cambridge: https://openneuro.org/datasets/ds000258 -.. _Multiband multi-echo imaging of simultaneous oxygenation and flow timeseries for resting state connectivity: https://openneuro.org/datasets/ds000254 -.. _Valence processing differs across stimulus modalities: https://openneuro.org/datasets/ds001491 -.. _Cambridge Centre for Ageing Neuroscience (Cam-CAN): https://camcan-archive.mrc-cbu.cam.ac.uk/dataaccess/ From ef8d4b7cb1fb5e4fdd2ebe2fc080191d5b8bd282 Mon Sep 17 00:00:00 2001 From: Logan Date: Wed, 6 Nov 2019 15:53:29 -0500 Subject: [PATCH 18/55] technically spelling things correct --- docs/considerations.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/considerations.rst b/docs/considerations.rst index 5211ed893..7bc5f137c 100644 --- a/docs/considerations.rst +++ b/docs/considerations.rst @@ -1,4 +1,4 @@ -Consideratsion for ME-fMRI +Considerations for ME-fMRI ========================== Multi-echo fMRI acquisition sequences and analysis methods are rapidly maturing. Someone who has access to a multi-echo fMRI sequence should seriously consider using it. The following are a few points to From 2efcfa9f2f106811938947c866aa2f51c84afefe Mon Sep 17 00:00:00 2001 From: Logan Date: Wed, 6 Nov 2019 16:18:09 -0500 Subject: [PATCH 19/55] started fixing titles --- docs/considerations.rst | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/docs/considerations.rst b/docs/considerations.rst index 7bc5f137c..4d97afbbd 100644 --- a/docs/considerations.rst +++ b/docs/considerations.rst @@ -1,11 +1,12 @@ +########################## Considerations for ME-fMRI -========================== +########################## Multi-echo fMRI acquisition sequences and analysis methods are rapidly maturing. Someone who has access to a multi-echo fMRI sequence should seriously consider using it. The following are a few points to consider when deciding whether or not to collect multi-echo data -`There is a cost of collecting multiple echoes` -*********************************************** +Possible increase in TR +----------------------- The one difference with multi-echo is a slight time cost. For multi-echo fMRI, the shortest echo time (TE) is essentially free since it is collected in the gap between the RF pulse and the single-echo acquisition. @@ -22,8 +23,8 @@ Instead of compromising on slice coverage or TR, one can increase acceleration. If one increases acceleration, it is worth doing an empirical comparison to make sure there isn't a non-trivial loss in SNR or an increase of artifacts. -`A simple weighted average will increase SNR` -********************************************* +A simple weighted average will increase SNR +------------------------------------------- Multiple studies have shown that a weighted average of the echoes to optimize T2* weighting, sometimes called "optimally combined," gives a reliable, modest boost in data quality. The optimal combination of echoes can currently be @@ -31,8 +32,8 @@ calculated in several software packages including AFNI, fMRIPrep, and tedana. In average can be calculated with `t2smap`_ If no other acquisition compromises are necessary to acquire multi-echo data, this boost is worthwhile. -`Consider the life of the dataset` -********************************** +Consider the life of the dataset +-------------------------------- If other compromises are necessary, consider the life of the data set. If data is being acquired for a discrete study that will be acquired, analyzed, and published in a year or two, it might not be worth making @@ -46,8 +47,8 @@ signal vs noise, such as scanner based drifts vs slow changes in BOLD signal. Th still being improved, and the algorithms are still changing. Users need to have the time and knowledge to look at the denoising output from every run to make sure denoising worked as intended. -`Consider the cost of added quality control` -******************************************** +Consider the cost of added quality control +------------------------------------------ If someone wants a push-button way to use multi-echo data to improve data quality, that doesn't require as deep an inspection of every output, stick with using the weighted average. The developers of tedana look forward to when tedana and other methods @@ -57,7 +58,7 @@ recommend the wide use of tedana. .. _t2smap: https://tedana.readthedocs.io/en/latest/usage.html#run-t2smap Acquisition Parameter Recommendations -------------------------------------- +===================================== There is no empirically tested best parameter set for multi-echo acquisition. The guidelines for optimizing parameters are similar to single-echo fMRI. For multi-echo fMRI, the same factors that may guide priorities for single echo From ee7008ce454628af6b223e852c8aa0db1f24d4aa Mon Sep 17 00:00:00 2001 From: Logan Date: Wed, 6 Nov 2019 16:18:26 -0500 Subject: [PATCH 20/55] addinf figures for what is ME page --- .../physics_kundu_2017_TE_dependence.jpg | Bin 0 -> 53127 bytes docs/multi-echo.rst | 31 +++++++++--------- 2 files changed, 16 insertions(+), 15 deletions(-) create mode 100644 docs/_static/physics_kundu_2017_TE_dependence.jpg diff --git a/docs/_static/physics_kundu_2017_TE_dependence.jpg b/docs/_static/physics_kundu_2017_TE_dependence.jpg new file mode 100644 index 0000000000000000000000000000000000000000..265bbbcc0f46f6112bf442f106b71fe3f6bba5e0 GIT binary patch literal 53127 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 Date: Wed, 6 Nov 2019 16:30:12 -0500 Subject: [PATCH 21/55] title clarification --- docs/usage.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/usage.rst b/docs/usage.rst index a628ee286..0acfc7d2e 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -1,5 +1,5 @@ -Usage -===== +tedana Usage +============ ``tedana`` minimally requires: From ac3557bc6867b2b4986749f4952048b717f2f9b2 Mon Sep 17 00:00:00 2001 From: Logan Date: Thu, 7 Nov 2019 10:21:38 -0500 Subject: [PATCH 22/55] Add information about GE --- docs/considerations.rst | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/docs/considerations.rst b/docs/considerations.rst index 4d97afbbd..cd00a24b6 100644 --- a/docs/considerations.rst +++ b/docs/considerations.rst @@ -89,7 +89,7 @@ and guidelines are discussed in the `appendix`_ of Dipasquale et al, 2017. Collecting Multi-echo Data -------------------------- -For Siemens users, there are two options for Works In Progress (WIPs) Sequences. +**For Siemens** users, there are two options for Works In Progress (WIPs) Sequences. The Center for Magnetic Resonance Research at the University of Minnesota provides a custom MR sequence that allows users to collect multiple echoes (termed **Contrasts**). The sequence and documentation can be `found here`_. For details @@ -101,10 +101,22 @@ In addition, the Martinos Center at Harvard also has a MR sequence available, wi details `available here`_. The number of echoes can be specified on the **Sequence, Special** tab in this sequence. +**For GE users**, there are currently two sharable pulse sequences: + +Multi-echo EPI (MEPI) – Software releases: DV24, MP24 and DV25 (with offline recon) +Hyperband Multi-echo EPI (HyperMEPI) - Software releases: DV26, MP26, DV27, RX27 +(here Hyperband can be deactivated to do simple Multi-echo EPI – online recon) + +Please reach out to the GE Research Operation team or each pulse sequence’s +author to begin the process of obtaining this software. More information can be +found on the `GE Collaboration Portal`_ + +Once logged-in, go to Groups > GE Works-in-Progress you can find the description of the current ATSM (i.e. prototypes) + .. _found here: https://www.cmrr.umn.edu/multiband/ .. _this link: http://license.umn.edu/technologies/cmrr_center-for-magnetic-resonance-research-software-for-siemens-mri-scanners .. _available here: https://www.nmr.mgh.harvard.edu/software/c2p/sms - +.. _GE Collaboration Portal: https://collaborate.mr.gehealthcare.com .. note:: In order to increase the number of contrasts ("echoes") you may need to first increase the TR, shorten the first TE and/or enable in-plane acceleration. For typically used parameters see the From fb30baf3f2449cdd0fba275bda2d31434ab16d70 Mon Sep 17 00:00:00 2001 From: Logan Date: Thu, 7 Nov 2019 10:39:42 -0500 Subject: [PATCH 23/55] adding mutliecho questions to the FAQ --- docs/faq.rst | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/docs/faq.rst b/docs/faq.rst index 0094633d1..73b10b12b 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -1,6 +1,9 @@ FAQ ---- +=== + +tedana +------ ICA has failed to converge. ``````````````````````````` @@ -36,3 +39,20 @@ Anyone interested in using v3.2 may compile and install an earlier release (<=0. .. _NeuroStars: https://neurostars.org .. _fMRIPrep: https://fmriprep.readthedocs.io .. _afni_proc.py: https://afni.nimh.nih.gov/pub/dist/doc/program_help/afni_proc.py.html + +Multi-echo fMRI +--------------- + +Will I encounter SAR limits more often with multi-echo fMRI? +```````````````````````````````````````````````````````````` +While multi-echo does lead to collecting more images during each TR (one per echo), there is still only a single +radiofrequency pulse. For this reason, there is no change in SAR for participants intrinsic to multi-echo +fMRI. + +Can I combine multiband (simultaneous multislice) with multi-echo fMRI? +``````````````````````````````````````````````````````````````````````` +Yes, these techniques are completely seperate. Mutliband fMRI leads to collecting multiple slices within a volume +simultaneouly, while multi-echo fMRI is instead related to collecting multiple unique volumes. These techniques can +be combined to reduce the TR in a multi-echo sequence. + + From cce9f1aaabea86470f772e2e0c752c880a151a1d Mon Sep 17 00:00:00 2001 From: Logan Date: Thu, 7 Nov 2019 13:47:02 -0500 Subject: [PATCH 24/55] initial adding to multiecho --- .../physics_kundu_2017_multiple_echoes.jpg | Bin 0 -> 68305 bytes docs/multi-echo.rst | 8 ++++++++ 2 files changed, 8 insertions(+) create mode 100644 docs/_static/physics_kundu_2017_multiple_echoes.jpg diff --git a/docs/_static/physics_kundu_2017_multiple_echoes.jpg b/docs/_static/physics_kundu_2017_multiple_echoes.jpg new file mode 100644 index 0000000000000000000000000000000000000000..6a1fe3a957f06b57de3c8a51788bedd442dd8e87 GIT binary patch literal 68305 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 C6_)k@ literal 0 HcmV?d00001 diff --git a/docs/multi-echo.rst b/docs/multi-echo.rst index b38619d47..be9f33e26 100644 --- a/docs/multi-echo.rst +++ b/docs/multi-echo.rst @@ -18,8 +18,16 @@ Because the BOLD signal is known to decay at a set rate, collecting multiple echos allows us to assess whether components of the fMRI signal are BOLD- or non-BOLD. +Non-BOLD like components are changes in the static signal. A common example is +movement, in which the voxel (which is at a static location within the scanner) +now contains different tissue or even an area outside of the brain. These changes +in signal, termed :math:`{\Delta}{S_0}` + .. image:: /_static/physics_kundu_2017_TE_dependence.jpg + +.. image:: /_static/physics_kundu_2017_multiple_echoes.jpg + For a comprehensive review, see `Kundu et al. (2017)`_. .. _TEs: http://mriquestions.com/tr-and-te.html From 1da0aab1270c8a9b7155a02be6dfccc738c79eef Mon Sep 17 00:00:00 2001 From: Logan Date: Thu, 7 Nov 2019 14:38:18 -0500 Subject: [PATCH 25/55] multiecho page figures and explanations --- docs/multi-echo.rst | 32 ++++++++++++++++++++++++++------ 1 file changed, 26 insertions(+), 6 deletions(-) diff --git a/docs/multi-echo.rst b/docs/multi-echo.rst index be9f33e26..0c6f1120d 100644 --- a/docs/multi-echo.rst +++ b/docs/multi-echo.rst @@ -18,16 +18,36 @@ Because the BOLD signal is known to decay at a set rate, collecting multiple echos allows us to assess whether components of the fMRI signal are BOLD- or non-BOLD. -Non-BOLD like components are changes in the static signal. A common example is -movement, in which the voxel (which is at a static location within the scanner) -now contains different tissue or even an area outside of the brain. These changes -in signal, termed :math:`{\Delta}{S_0}` +The image below shows the basic relationship between echo times and the image acquired at +3T (top, A) and 7T (bottom, B). Note that the earliest echo time is the brightest, as the +signal has only had a limited amount of time to decay. +In addition, the latter echo times show areas in which is the signal has decayed completely ('drop out') +due to inhomgeneity in the magnetic field. By using the information across multiple +echoes these images can be combined in an optimal manner to take advantage of the signal +in the earlier echoes (see `processing pipeline details`_). -.. image:: /_static/physics_kundu_2017_TE_dependence.jpg +.. image:: /_static/physics_kundu_2017_multiple_echoes.jpg +In order to classify the relationship between the signal and the echo time we can consider a +single voxel at two timepoints (x and y) and the measured signal measured at three different echo times - :math:`S(TE_N)`. -.. image:: /_static/physics_kundu_2017_multiple_echoes.jpg +For the left column, we are observing a change that we term :math:`{\Delta}{S_0}` - that is a change +in the intercept or raw signal intensity. A common example of this is participant movement, +in which the voxel (which is at a static location within the scanner) +now contains different tissue or even an area outside of the brain. + +As we have collected three seperate echoes, we can compare the change in signal at each echo time, :math:`{Delta}{S(TE_N)}. For +:math:`{Delta}{S_0}` we see that this produces a decaying curve. If we compare this to the original signal, as in +:math:`frac{{Delta}{S(TE_N)}{S(TE_N)}} we see that there is no echo time dependence. + +In the right column, we consider changes that are related to brain activity, that is the two brain states here +(x and y) could be a baseline and task activated state. These we term as :math:`{\Delta}{R_2^*}`. Again we can plot the +change in the signal between these two states as a function of echo time, finding that the signal rises and falls. If we compare this +curve to the original signal we find that magnitude of the changes is dependent on the echo time. + +.. image:: /_static/physics_kundu_2017_TE_dependence.jpg +T For a comprehensive review, see `Kundu et al. (2017)`_. .. _TEs: http://mriquestions.com/tr-and-te.html From a4c1b4849aa06e3e89b00c92d47d0a3c2b41d3d6 Mon Sep 17 00:00:00 2001 From: Logan Date: Thu, 7 Nov 2019 14:53:51 -0500 Subject: [PATCH 26/55] pipeline and phsyics updated --- docs/approach.rst | 29 ++++++++++++++++++----------- docs/multi-echo.rst | 1 - 2 files changed, 18 insertions(+), 12 deletions(-) diff --git a/docs/approach.rst b/docs/approach.rst index fc0c19535..5c22c6396 100644 --- a/docs/approach.rst +++ b/docs/approach.rst @@ -133,6 +133,8 @@ For the example voxel, the resulting weights are: :width: 400 px :align: center +THese normalized weights are then used to compute a weighted average that takes advantage +of the higher signal in earlier echoes and the heigher sensitivty at later echoes. The distribution of values for the optimally combined data lands somewhere between the distributions for other echoes. @@ -154,6 +156,17 @@ of the other echoes (which it is). This optimally combined data is written out a We do, however, make it accessible as an alternative combination method in the t2smap workflow. +Denoising +````````` +The next step is an attempt to remove noise from the data. This process can be +broadly seperated into three steps: **decomposition, metric calculation** and +**component selection**. Decomposition reduces the diemnstionality of the +optimally combined data using PCA and then an ICA. Metrics which highlights the +TE-dependence or indepence are derived from these components. Component selection +uses these metrics in order to identify components that should be kept in the data +or discarded. Unwanted components are then removed from the optimally combined data +to produce the denoised data output. + TEDPCA `````` The next step is to dimensionally reduce the data with TE-dependent principal @@ -170,20 +183,14 @@ These components are subjected to component selection, the specifics of which vary according to algorithm. In the simplest approach, ``tedana`` uses Minka’s MLE to estimate the -dimensionality of the data, which disregards low-variance components. +dimensionality of the data, which disregards low-variance components. (the `mle` option in for `--tedpca`). -A more complicated approach involves applying a decision tree to identify and +A more complicated approach involves applying a decision tree (similar to the +decision tree described in the TEDICA section below) to identify and discard PCA components which, in addition to not explaining much variance, are also not significantly TE-dependent (i.e., have low Kappa) or -TE-independent (i.e., have low Rho). - -.. note:: - This process (also performed in TEDICA) can be broadly separated into three - steps: decomposition, metric calculation, and component selection. - Decomposition identifies components in the data. - Metric calculation derives relevant summary statistics for each component. - Component selection uses the summary statistics to identify components that - should be kept or discarded. +TE-independent (i.e., have low Rho). These approaches can be accessed using +either the `kundu` or `kundu_stabilize` options for the `--tedpca` flag. After component selection is performed, the retained components and their associated betas are used to reconstruct the optimally combined data, resulting diff --git a/docs/multi-echo.rst b/docs/multi-echo.rst index 0c6f1120d..3e8e7f3e8 100644 --- a/docs/multi-echo.rst +++ b/docs/multi-echo.rst @@ -47,7 +47,6 @@ curve to the original signal we find that magnitude of the changes is dependent .. image:: /_static/physics_kundu_2017_TE_dependence.jpg -T For a comprehensive review, see `Kundu et al. (2017)`_. .. _TEs: http://mriquestions.com/tr-and-te.html From d819d7a2fad487d5efc6f4c0bc7a6aa738cd2f79 Mon Sep 17 00:00:00 2001 From: Logan Date: Thu, 7 Nov 2019 15:14:58 -0500 Subject: [PATCH 27/55] typo --- docs/approach.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/approach.rst b/docs/approach.rst index 5c22c6396..a66d1b627 100644 --- a/docs/approach.rst +++ b/docs/approach.rst @@ -160,7 +160,7 @@ Denoising ````````` The next step is an attempt to remove noise from the data. This process can be broadly seperated into three steps: **decomposition, metric calculation** and -**component selection**. Decomposition reduces the diemnstionality of the +**component selection**. Decomposition reduces the dimensionality of the optimally combined data using PCA and then an ICA. Metrics which highlights the TE-dependence or indepence are derived from these components. Component selection uses these metrics in order to identify components that should be kept in the data From 56039d4d55e4d3fb531b2a7ed91fd532be2d69ac Mon Sep 17 00:00:00 2001 From: Logan Date: Thu, 7 Nov 2019 15:15:09 -0500 Subject: [PATCH 28/55] fix headings --- docs/considerations.rst | 72 +++++++++++++++++++---------------------- 1 file changed, 34 insertions(+), 38 deletions(-) diff --git a/docs/considerations.rst b/docs/considerations.rst index cd00a24b6..d895ff84d 100644 --- a/docs/considerations.rst +++ b/docs/considerations.rst @@ -6,7 +6,7 @@ to a multi-echo fMRI sequence should seriously consider using it. The following consider when deciding whether or not to collect multi-echo data Possible increase in TR ------------------------ +======================= The one difference with multi-echo is a slight time cost. For multi-echo fMRI, the shortest echo time (TE) is essentially free since it is collected in the gap between the RF pulse and the single-echo acquisition. @@ -24,7 +24,7 @@ If one increases acceleration, it is worth doing an empirical comparison to make isn't a non-trivial loss in SNR or an increase of artifacts. A simple weighted average will increase SNR -------------------------------------------- +=========================================== Multiple studies have shown that a weighted average of the echoes to optimize T2* weighting, sometimes called "optimally combined," gives a reliable, modest boost in data quality. The optimal combination of echoes can currently be @@ -33,7 +33,7 @@ average can be calculated with `t2smap`_ If no other acquisition compromises are necessary to acquire multi-echo data, this boost is worthwhile. Consider the life of the dataset --------------------------------- +================================ If other compromises are necessary, consider the life of the data set. If data is being acquired for a discrete study that will be acquired, analyzed, and published in a year or two, it might not be worth making @@ -48,7 +48,7 @@ still being improved, and the algorithms are still changing. Users need to have at the denoising output from every run to make sure denoising worked as intended. Consider the cost of added quality control ------------------------------------------- +========================================== If someone wants a push-button way to use multi-echo data to improve data quality, that doesn't require as deep an inspection of every output, stick with using the weighted average. The developers of tedana look forward to when tedana and other methods @@ -87,32 +87,6 @@ and guidelines are discussed in the `appendix`_ of Dipasquale et al, 2017. .. _appendix: https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0173289 -Collecting Multi-echo Data --------------------------- -**For Siemens** users, there are two options for Works In Progress (WIPs) Sequences. -The Center for Magnetic Resonance Research at the University of Minnesota -provides a custom MR sequence that allows users to collect multiple echoes -(termed **Contrasts**). The sequence and documentation can be `found here`_. For details -on obtaining a license follow `this link`_. By default the number of contrasts is 1, -yielding a signal echo sequence. In order to collect multiple echoes, increase number of -Contrasts on the **Sequence Tab, Part 1** on the MR console. - -In addition, the Martinos Center at Harvard also has a MR sequence available, with the -details `available here`_. The number of echoes can be specified on the **Sequence, Special** tab -in this sequence. - -**For GE users**, there are currently two sharable pulse sequences: - -Multi-echo EPI (MEPI) – Software releases: DV24, MP24 and DV25 (with offline recon) -Hyperband Multi-echo EPI (HyperMEPI) - Software releases: DV26, MP26, DV27, RX27 -(here Hyperband can be deactivated to do simple Multi-echo EPI – online recon) - -Please reach out to the GE Research Operation team or each pulse sequence’s -author to begin the process of obtaining this software. More information can be -found on the `GE Collaboration Portal`_ - -Once logged-in, go to Groups > GE Works-in-Progress you can find the description of the current ATSM (i.e. prototypes) - .. _found here: https://www.cmrr.umn.edu/multiband/ .. _this link: http://license.umn.edu/technologies/cmrr_center-for-magnetic-resonance-research-software-for-siemens-mri-scanners .. _available here: https://www.nmr.mgh.harvard.edu/software/c2p/sms @@ -124,10 +98,10 @@ Once logged-in, go to Groups > GE Works-in-Progress you can find the description .. _parameters and publications page: https://tedana.readthedocs.io/en/latest/publications.html Resources ---------- +========= Journal articles -**************** +---------------- * | :ref:`spreadsheet of publications` catalogues papers using multi-echo fMRI, with information about acquisition parameters. * | `Multi-echo acquisition`_ @@ -149,7 +123,7 @@ Journal articles .. _Comparing resting state fMRI de-noising approaches using multi- and single-echo acqusitions: https://www.ncbi.nlm.nih.gov/pubmed/28323821 Videos -****** +------ * An `educational session from OHBM 2017`_ by Dr. Prantik Kundu about multi-echo denoising * A `series of lectures from the OHBM 2017 multi-echo session`_ on multiple facets of multi-echo data analysis * | Multi-echo fMRI lecture from the `2018 NIH FMRI Summer Course`_ by Javier Gonzalez-Castillo @@ -161,24 +135,46 @@ Videos .. _Slides from 2018 NIH FMRI Summer Course: https://fmrif.nimh.nih.gov/COURSE/fmrif_course/2018/content/14_Javier_20180713.pdf Available multi-echo fMRI sequences for multiple vendors -******************************************************** +-------------------------------------------------------- -Information on multi-echo sequences from Siemens, GE, and Phillips will be added here. +**For Siemens** users, there are two options for Works In Progress (WIPs) Sequences. +The Center for Magnetic Resonance Research at the University of Minnesota +provides a custom MR sequence that allows users to collect multiple echoes +(termed **Contrasts**). The sequence and documentation can be `found here`_. For details +on obtaining a license follow `this link`_. By default the number of contrasts is 1, +yielding a signal echo sequence. In order to collect multiple echoes, increase number of +Contrasts on the **Sequence Tab, Part 1** on the MR console. + +In addition, the Martinos Center at Harvard also has a MR sequence available, with the +details `available here`_. The number of echoes can be specified on the **Sequence, Special** tab +in this sequence. + +**For GE users**, there are currently two sharable pulse sequences: + +Multi-echo EPI (MEPI) – Software releases: DV24, MP24 and DV25 (with offline recon) +Hyperband Multi-echo EPI (HyperMEPI) - Software releases: DV26, MP26, DV27, RX27 +(here Hyperband can be deactivated to do simple Multi-echo EPI – online recon) + +Please reach out to the GE Research Operation team or each pulse sequence’s +author to begin the process of obtaining this software. More information can be +found on the `GE Collaboration Portal`_ + +Once logged-in, go to Groups > GE Works-in-Progress you can find the description of the current ATSM (i.e. prototypes) Multi-echo preprocessing software -********************************* +--------------------------------- tedana requires data that has already been preprocessed for head motion, alignment, etc. More details on software packages that include preprocessing options specifically for multi-echo fMRI data, such as AFNI and fMRIPrep will be added here. Other software that uses multi-echo fMRI -**************************************** +---------------------------------------- Information and links to other approaches for denoising multi-echo fMRI data will be added here. Datasets -******** +-------- A number of multi-echo datasets have been made public so far. This list is not necessarily up-to-date, so please check out OpenNeuro to potentially find more. From 08a936e77b8ef35f174d3e97042728c73fc119c4 Mon Sep 17 00:00:00 2001 From: Logan Date: Thu, 7 Nov 2019 15:15:26 -0500 Subject: [PATCH 29/55] possibly clean latex? --- docs/multi-echo.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/multi-echo.rst b/docs/multi-echo.rst index 3e8e7f3e8..77ad73491 100644 --- a/docs/multi-echo.rst +++ b/docs/multi-echo.rst @@ -36,9 +36,9 @@ in the intercept or raw signal intensity. A common example of this is participan in which the voxel (which is at a static location within the scanner) now contains different tissue or even an area outside of the brain. -As we have collected three seperate echoes, we can compare the change in signal at each echo time, :math:`{Delta}{S(TE_N)}. For -:math:`{Delta}{S_0}` we see that this produces a decaying curve. If we compare this to the original signal, as in -:math:`frac{{Delta}{S(TE_N)}{S(TE_N)}} we see that there is no echo time dependence. +As we have collected three seperate echoes, we can compare the change in signal at each echo time, :math:`{\Delta}{S(TE_n)}`. For +:math:`{\Delta}{S_0}` we see that this produces a decaying curve. If we compare this to the original signal, as in +:math:`\frac{{\Delta}{S(TE_n)}}{S(TE_n)}` we see that there is no echo time dependence. In the right column, we consider changes that are related to brain activity, that is the two brain states here (x and y) could be a baseline and task activated state. These we term as :math:`{\Delta}{R_2^*}`. Again we can plot the From 81fba41d951241632713693b90a57265ccdc2663 Mon Sep 17 00:00:00 2001 From: Logan Date: Thu, 7 Nov 2019 15:22:03 -0500 Subject: [PATCH 30/55] we have eight echoes --- docs/approach.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/approach.rst b/docs/approach.rst index a66d1b627..66c3e4f38 100644 --- a/docs/approach.rst +++ b/docs/approach.rst @@ -83,7 +83,7 @@ The echo times are also multiplied by -1. A simple line can then be fit to the transformed data with linear regression. For the sake of this introduction, we can assume that the example voxel has -good signal in all five echoes (i.e., the adaptive mask has a value of 5 at +good signal in all eight echoes (i.e., the adaptive mask has a value of 8 at this voxel), so the line is fit to all available data. .. note:: From 811ab6cda95fdb4bdb454f4daa83f42052ad19f1 Mon Sep 17 00:00:00 2001 From: Logan Date: Thu, 7 Nov 2019 15:31:05 -0500 Subject: [PATCH 31/55] more details in approach --- docs/approach.rst | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/approach.rst b/docs/approach.rst index 66c3e4f38..fe852c678 100644 --- a/docs/approach.rst +++ b/docs/approach.rst @@ -210,10 +210,10 @@ the spatially loading of these components on the brain (**betas_OC.nii.gz**). .. image:: /_static/a13_ica_component_timeseries.png Linear regression is used to fit the component time series to each voxel in each -echo from the original, echo-specific data. -This way, low-variance information (originally discarded by TEDPCA) is retained -in the data, but is ignored by the TEDICA process. -This results in echo- and voxel-specific betas for each of the components. +echo from the original, echo-specific data. This results in echo- and voxel-specific +betas for each of the components.The beta values from the linear regression +can be used to determine how the fluctutations (in each component timeseries) change +across the echo times. TE-dependence (:math:`R_2` or :math:`1/T_{2}^*`) and TE-independence (:math:`S_0`) models can then be fit to these betas. @@ -221,6 +221,9 @@ For more information on how these models are estimated, see :ref:`dependence mod These models allow calculation of F-statistics for the :math:`R_2` and :math:`S_0` models (referred to as :math:`\kappa` and :math:`\rho`, respectively). +The grey lines show how beta values (Parameter Estimates) change over time. Refer the the +`physics section`_ :math:`{\Delta}{S_0}` for more information about the :math:`S_0` and :math:`T_2^*` models. + .. image:: /_static/a14_te_dependence_models_component_0.png .. image:: /_static/a14_te_dependence_models_component_1.png @@ -260,3 +263,5 @@ Currently, ``tedana`` implements GSR and T1c-GSR. .. _nilearn.masking.compute_epi_mask: https://nilearn.github.io/modules/generated/nilearn.masking.compute_epi_mask.html .. _Power et al. (2018): http://www.pnas.org/content/early/2018/02/07/1720985115.short .. _Poser et al., 2006: https://onlinelibrary.wiley.com/doi/full/10.1002/mrm.20900 + +.. _physics section: https://tedana.readthedocs.io/en/latest/multi_echo.html \ No newline at end of file From 39b667f891f39808e3530bd6a20505fab21719ee Mon Sep 17 00:00:00 2001 From: Logan Date: Thu, 7 Nov 2019 15:32:25 -0500 Subject: [PATCH 32/55] title change --- docs/approach.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/approach.rst b/docs/approach.rst index fe852c678..54953bada 100644 --- a/docs/approach.rst +++ b/docs/approach.rst @@ -1,5 +1,5 @@ -Processing pipeline details -=========================== +The tedana pipeline +=================== ``tedana`` works by decomposing multi-echo BOLD data via PCA and ICA. The resulting components are then analyzed to determine whether they are From 72137ed4db6f45135012c6b59d70f4f2b5dad3bf Mon Sep 17 00:00:00 2001 From: Logan Date: Thu, 7 Nov 2019 16:06:23 -0500 Subject: [PATCH 33/55] adding software details --- docs/considerations.rst | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/considerations.rst b/docs/considerations.rst index d895ff84d..5b687689e 100644 --- a/docs/considerations.rst +++ b/docs/considerations.rst @@ -165,8 +165,18 @@ Multi-echo preprocessing software --------------------------------- tedana requires data that has already been preprocessed for head motion, alignment, etc. -More details on software packages that include preprocessing options specifically for multi-echo -fMRI data, such as AFNI and fMRIPrep will be added here. + +AFNI can process multi-echo data natively as well as apply tedana denoising through the use of +**afni_proc.py**. To see various implementations, start with Example 12 in the `afni_proc.py help`_ + +.. afni_proc.py: https://afni.nimh.nih.gov/pub/dist/doc/program_help/afni_proc.py.html + +`fmriprep` can also process multi-echo data, but is currently limited to using the optimally combined +timeseries. For more details, see the `fmriprep workflows page`_ + +.. _fmriprep workflows page: https://fmriprep.readthedocs.io/en/stable/workflows.html + +Currently SPM and FSL do not natively support mutli-echo fmri data processing. Other software that uses multi-echo fMRI ---------------------------------------- From 0939c7267a9dc2877a5621856c5c214589981a1a Mon Sep 17 00:00:00 2001 From: Logan Date: Thu, 7 Nov 2019 21:04:33 -0500 Subject: [PATCH 34/55] clean up of multiecho --- docs/multi-echo.rst | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/docs/multi-echo.rst b/docs/multi-echo.rst index 77ad73491..e3ce1069d 100644 --- a/docs/multi-echo.rst +++ b/docs/multi-echo.rst @@ -1,4 +1,4 @@ -What is Multi-echo fMRI +What is multi-echo fMRI ======================= Most echo-planar image (EPI) sequences collect a single brain image following a radio frequency (RF) pulse, at a rate known as the repetition time (TR). @@ -15,8 +15,7 @@ oxygen-level dependent, or `BOLD signal`_, it also contains "noise" (termed non-BOLD signal) caused by things like participant motion and changes in breathing. Because the BOLD signal is known to decay at a set rate, collecting multiple -echos allows us to assess whether components of the fMRI signal are BOLD- or -non-BOLD. +echos allows us to assess non-BOLD. The image below shows the basic relationship between echo times and the image acquired at 3T (top, A) and 7T (bottom, B). Note that the earliest echo time is the brightest, as the @@ -27,9 +26,10 @@ echoes these images can be combined in an optimal manner to take advantage of th in the earlier echoes (see `processing pipeline details`_). .. image:: /_static/physics_kundu_2017_multiple_echoes.jpg +Adapted from `Kundu et al. (2017)`_. In order to classify the relationship between the signal and the echo time we can consider a -single voxel at two timepoints (x and y) and the measured signal measured at three different echo times - :math:`S(TE_N)`. +single voxel at two timepoints (x and y) and the measured signal measured at three different echo times - :math:`S(TE_n)`. For the left column, we are observing a change that we term :math:`{\Delta}{S_0}` - that is a change in the intercept or raw signal intensity. A common example of this is participant movement, @@ -41,13 +41,17 @@ As we have collected three seperate echoes, we can compare the change in signal :math:`\frac{{\Delta}{S(TE_n)}}{S(TE_n)}` we see that there is no echo time dependence. In the right column, we consider changes that are related to brain activity, that is the two brain states here -(x and y) could be a baseline and task activated state. These we term as :math:`{\Delta}{R_2^*}`. Again we can plot the -change in the signal between these two states as a function of echo time, finding that the signal rises and falls. If we compare this -curve to the original signal we find that magnitude of the changes is dependent on the echo time. +(x and y) could be a baseline and task activated state. These we term as :math:`{\Delta}{R_2^*}` which is equivilent +to the inverse of :math:`{T_2^*}`. +Again we can plot the change in the signal between these two states as a function of echo time, +finding that the signal rises and falls. If we compare this curve to the original signal we find +that magnitude of the changes is dependent on the echo time. .. image:: /_static/physics_kundu_2017_TE_dependence.jpg +Adapted from `Kundu et al. (2017)`_. + +For a more comprehensive review of these topics and others, see `Kundu et al. (2017)`_. -For a comprehensive review, see `Kundu et al. (2017)`_. .. _TEs: http://mriquestions.com/tr-and-te.html .. _BOLD signal: http://www.fil.ion.ucl.ac.uk/spm/course/slides10-zurich/Kerstin_BOLD.pdf From 9b16d50485141e8a2b5da196a986d129157ffbad Mon Sep 17 00:00:00 2001 From: Logan Date: Thu, 7 Nov 2019 21:04:41 -0500 Subject: [PATCH 35/55] additional considerations! --- docs/considerations.rst | 29 +++++++++++++++++++++-------- 1 file changed, 21 insertions(+), 8 deletions(-) diff --git a/docs/considerations.rst b/docs/considerations.rst index 5b687689e..fe6b48053 100644 --- a/docs/considerations.rst +++ b/docs/considerations.rst @@ -2,11 +2,14 @@ Considerations for ME-fMRI ########################## Multi-echo fMRI acquisition sequences and analysis methods are rapidly maturing. Someone who has access -to a multi-echo fMRI sequence should seriously consider using it. The following are a few points to -consider when deciding whether or not to collect multi-echo data +to a multi-echo fMRI sequence should seriously consider using it. + +The possible costs and benefits of multi-echo fMRI +================================================== +The following are a few points to consider when deciding whether or not to collect multi-echo data. Possible increase in TR -======================= +----------------------- The one difference with multi-echo is a slight time cost. For multi-echo fMRI, the shortest echo time (TE) is essentially free since it is collected in the gap between the RF pulse and the single-echo acquisition. @@ -23,8 +26,8 @@ Instead of compromising on slice coverage or TR, one can increase acceleration. If one increases acceleration, it is worth doing an empirical comparison to make sure there isn't a non-trivial loss in SNR or an increase of artifacts. -A simple weighted average will increase SNR -=========================================== +Weighted Averaging may lead to an increase in SNR +------------------------------------------------- Multiple studies have shown that a weighted average of the echoes to optimize T2* weighting, sometimes called "optimally combined," gives a reliable, modest boost in data quality. The optimal combination of echoes can currently be @@ -33,7 +36,7 @@ average can be calculated with `t2smap`_ If no other acquisition compromises are necessary to acquire multi-echo data, this boost is worthwhile. Consider the life of the dataset -================================ +-------------------------------- If other compromises are necessary, consider the life of the data set. If data is being acquired for a discrete study that will be acquired, analyzed, and published in a year or two, it might not be worth making @@ -47,14 +50,24 @@ signal vs noise, such as scanner based drifts vs slow changes in BOLD signal. Th still being improved, and the algorithms are still changing. Users need to have the time and knowledge to look at the denoising output from every run to make sure denoising worked as intended. +You may recover signal in areas affected by dropout +--------------------------------------------------- +Typical single echo fMRI uses an echo time that is appropriate for signal across most of the brain. While this is effective +it also leads to drop out in regions with low :math:T_2^* values. This can lead to low or even no signal at all in some areas. +If your research question could benefit from having either +improve signal characteristics in regions such as the orbitofrontal cortex, ventral temporal cortex or +the ventral striatum them multi-echo fMRI may be beneficial. + Consider the cost of added quality control -========================================== +------------------------------------------ If someone wants a push-button way to use multi-echo data to improve data quality, that doesn't require as deep an inspection of every output, stick with using the weighted average. The developers of tedana look forward to when tedana and other methods have sufficiently stable algorithms, which have been validated on a wide range of data sets, so that we can recommend the wide use of tedana. + + .. _t2smap: https://tedana.readthedocs.io/en/latest/usage.html#run-t2smap Acquisition Parameter Recommendations @@ -169,7 +182,7 @@ tedana requires data that has already been preprocessed for head motion, alignme AFNI can process multi-echo data natively as well as apply tedana denoising through the use of **afni_proc.py**. To see various implementations, start with Example 12 in the `afni_proc.py help`_ -.. afni_proc.py: https://afni.nimh.nih.gov/pub/dist/doc/program_help/afni_proc.py.html +.. _afni_proc.py help: https://afni.nimh.nih.gov/pub/dist/doc/program_help/afni_proc.py.html `fmriprep` can also process multi-echo data, but is currently limited to using the optimally combined timeseries. For more details, see the `fmriprep workflows page`_ From 7b242baa9814f548de4873d6243178981e702712 Mon Sep 17 00:00:00 2001 From: Logan Date: Fri, 8 Nov 2019 09:03:14 -0500 Subject: [PATCH 36/55] typo --- docs/considerations.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/considerations.rst b/docs/considerations.rst index fe6b48053..bd125606e 100644 --- a/docs/considerations.rst +++ b/docs/considerations.rst @@ -55,7 +55,7 @@ You may recover signal in areas affected by dropout Typical single echo fMRI uses an echo time that is appropriate for signal across most of the brain. While this is effective it also leads to drop out in regions with low :math:T_2^* values. This can lead to low or even no signal at all in some areas. If your research question could benefit from having either -improve signal characteristics in regions such as the orbitofrontal cortex, ventral temporal cortex or +improved signal characteristics in regions such as the orbitofrontal cortex, ventral temporal cortex or the ventral striatum them multi-echo fMRI may be beneficial. Consider the cost of added quality control From 8407826eadf26c2fe6ceb91f09b4d4da92db5744 Mon Sep 17 00:00:00 2001 From: Logan Date: Fri, 8 Nov 2019 09:10:09 -0500 Subject: [PATCH 37/55] update plots --- docs/publications.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/publications.rst b/docs/publications.rst index c219ff3f7..f06a31563 100644 --- a/docs/publications.rst +++ b/docs/publications.rst @@ -15,8 +15,10 @@ The following plots reflect the average values for studies conducted at 3 Tesla. import matplotlib.pyplot as plt import pandas as pd import numpy as np + # TODO deal with the issue that the plot doesn't regenterate (ie isn't alive) + # Unless the code is updated. metable = pd.read_csv('https://docs.google.com/spreadsheets/d/1WERojJyxFoqcg_tndUm5Kj0H1UfUc9Ban0jFGGfPaBk/export?gid=0&format=csv', - header=0 ) + header=0) TEs = [metable.TE1.mean(), metable.TE2.mean(), metable.TE3.mean(), metable.TE4.mean(), metable.TE5.mean()] TE_labels = ['TE1', 'TE2', 'TE3', 'TE4', 'TE5'] plt.bar([1, 2, 3, 4, 5], TEs) @@ -39,7 +41,7 @@ The following plots reflect the average values for studies conducted at 3 Tesla. y_vox = metable.y.to_numpy() z_vox = metable.z.to_numpy() plt.hist(np.nanmean([x_vox, y_vox, z_vox],0)) - plt.title('Voxel dimensions', fontsize = 18) + plt.title('Voxel Dimensions', fontsize = 18) plt.xlabel('Average Voxel dimension (mm)') plt.ylabel('Count') plt.show() From e19da750de80ddeaa6859fd170f048bc8d837bb5 Mon Sep 17 00:00:00 2001 From: Logan Date: Fri, 8 Nov 2019 09:35:24 -0500 Subject: [PATCH 38/55] due credit in faq --- docs/faq.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/faq.rst b/docs/faq.rst index 73b10b12b..5fbe66766 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -34,6 +34,15 @@ the v3.2 code, with the goal of revisiting it when ``tedana`` is more stable. Anyone interested in using v3.2 may compile and install an earlier release (<=0.0.4) of ``tedana``. +What is the warning about ``duecredit``? +````````````````````````````````````````` +``duecredit`` is a python package that is used, but not required by ``tedana``. These warnings do +not affect any of the processing within the ``tedana``. To avoide this warning, you can install +``duecredit`` with ``pip install duecredit``. For more information about ``duecredit`` and concerns about +the citation and visibility of software or methods, visit the `duecredit`_ github. + +.. _duecredit: https://github.com/duecredit/duecredit + .. _here: https://bitbucket.org/prantikk/me-ica/commits/906bd1f6db7041f88cd0efcac8a74074d673f4f5 .. _NeuroStars: https://neurostars.org From 1fd01787c12df00aa250b6b1d39caef24f5822ba Mon Sep 17 00:00:00 2001 From: Logan Date: Fri, 8 Nov 2019 09:35:37 -0500 Subject: [PATCH 39/55] more details on multi echo, usage --- docs/multi-echo.rst | 19 ++++++++++--------- docs/usage.rst | 18 +++++++++--------- 2 files changed, 19 insertions(+), 18 deletions(-) diff --git a/docs/multi-echo.rst b/docs/multi-echo.rst index e3ce1069d..7dbadadeb 100644 --- a/docs/multi-echo.rst +++ b/docs/multi-echo.rst @@ -31,6 +31,9 @@ Adapted from `Kundu et al. (2017)`_. In order to classify the relationship between the signal and the echo time we can consider a single voxel at two timepoints (x and y) and the measured signal measured at three different echo times - :math:`S(TE_n)`. +.. image:: /_static/physics_kundu_2017_TE_dependence.jpg +Adapted from `Kundu et al. (2017)`_. + For the left column, we are observing a change that we term :math:`{\Delta}{S_0}` - that is a change in the intercept or raw signal intensity. A common example of this is participant movement, in which the voxel (which is at a static location within the scanner) @@ -38,17 +41,15 @@ now contains different tissue or even an area outside of the brain. As we have collected three seperate echoes, we can compare the change in signal at each echo time, :math:`{\Delta}{S(TE_n)}`. For :math:`{\Delta}{S_0}` we see that this produces a decaying curve. If we compare this to the original signal, as in -:math:`\frac{{\Delta}{S(TE_n)}}{S(TE_n)}` we see that there is no echo time dependence. +:math:`\frac{{\Delta}{S(TE_n)}}{S(TE_n)}` we see that there is no echo time dependence, as the final plot is a flat line. -In the right column, we consider changes that are related to brain activity, that is the two brain states here -(x and y) could be a baseline and task activated state. These we term as :math:`{\Delta}{R_2^*}` which is equivilent -to the inverse of :math:`{T_2^*}`. -Again we can plot the change in the signal between these two states as a function of echo time, +In the right column, we consider changes that are related to brain activity. For example, imagine that the two brain states here +(x and y) are a baseline and task activated state respectively. This effect is a change in in :math:`{\Delta}{R_2^*}` which is equivilent +to the inverse of :math:`{T_2^*}`. We typically observe this change in signal amplitude occuring over volumes with +the hemodynamic response, while here we are examining the change in signal over echo times. +Again we can plot the difference in the signal between these two states as a function of echo time, finding that the signal rises and falls. If we compare this curve to the original signal we find -that magnitude of the changes is dependent on the echo time. - -.. image:: /_static/physics_kundu_2017_TE_dependence.jpg -Adapted from `Kundu et al. (2017)`_. +that the magnitude of the changes is dependent on the echo time. For a more comprehensive review of these topics and others, see `Kundu et al. (2017)`_. diff --git a/docs/usage.rst b/docs/usage.rst index 0acfc7d2e..968b29958 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -91,12 +91,12 @@ Instead, we recommend that researchers apply the same transforms to all echoes i That is, that they calculate head motion correction parameters from one echo and apply the resulting transformation to all echoes. -Similarly, any intensity normalization or nuisance regressors should be applied to the data -*after* ``tedana`` calculates the BOLD and non-BOLD weighting of components. - -If this is not considered, resulting intensity gradients (e.g., in the case of scaling) -or alignment parameters (e.g., in the case of motion correction, normalization) -are likely to differ across echos, -and the subsequent calculation of voxelwise T2* values will be distorted. -See the description of ``tedana``'s :doc:`approach <\approach>` for more details -on how T2* values are calculated. +.. note:: + Any intensity normalization or nuisance regressors should be applied to the data + *after* ``tedana`` calculates the BOLD and non-BOLD weighting of components. If this is + not considered, resulting intensity gradients (e.g., in the case of scaling) + or alignment parameters (e.g., in the case of motion correction, normalization) + are likely to differ across echos, + and the subsequent calculation of voxelwise T2* values will be distorted or incorrect. + See the description of ``tedana``'s :doc:`approach <\approach>` for more details + on how T2* values are calculated. From b0ac47da408c8c052aa9198ebf7bbed6c1566718 Mon Sep 17 00:00:00 2001 From: Logan Date: Fri, 8 Nov 2019 09:36:35 -0500 Subject: [PATCH 40/55] tedana does accept BRIK/HEAD --- docs/roadmap.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/roadmap.rst b/docs/roadmap.rst index f1c575d04..fc9bf87f1 100644 --- a/docs/roadmap.rst +++ b/docs/roadmap.rst @@ -156,8 +156,6 @@ such that the ``afni_proc.py`` maintainers are willing to switch to ``tedana`` a method of accessing ME-EPI denoising in AFNI. We will aim to aid in this process by increasing compatibility between ``tedana`` and the ``afni_proc.py`` workflow, eliminating the need for an additional wrapper script. -For example, ``tedana`` could directly accept BRIK/HEAD files, -facilitating interoperability with other AFNI pipelines. |milestone4|_ From 1a88b8545cbf515d5667673482fab07e46e3d127 Mon Sep 17 00:00:00 2001 From: Logan Date: Fri, 8 Nov 2019 10:11:13 -0500 Subject: [PATCH 41/55] someone wanted sentences seperated --- docs/approach.rst | 41 +++++++++++++++++++----------- docs/considerations.rst | 55 ++++++++++++++++++++++++++--------------- docs/faq.rst | 18 ++++++++------ docs/multi-echo.rst | 46 +++++++++++++++++++--------------- docs/publications.rst | 3 ++- docs/usage.rst | 10 +++++--- 6 files changed, 105 insertions(+), 68 deletions(-) diff --git a/docs/approach.rst b/docs/approach.rst index 54953bada..f4cc55d2f 100644 --- a/docs/approach.rst +++ b/docs/approach.rst @@ -62,11 +62,11 @@ value for that voxel in the adaptive mask. Monoexponential decay model fit ``````````````````````````````` The next step is to fit a monoexponential decay model to the data in order to -estimate voxel-wise :math:`T_{2}^*` and :math:`S_0`. :math:`S_0` corresponds -to the total signal in each voxel before decay and can reflect coil sensivity. +estimate voxel-wise :math:`T_{2}^*` and :math:`S_0`. +:math:`S_0` corresponds to the total signal in each voxel before decay and can reflect coil sensivity. :math:`T_{2}^*` corresponds to the rate at which a voxel decays over time, which -is related to signal dropout and BOLD sensitivity. Estimates of the parameters are -saved as **t2sv.nii.gz** and **s0v.nii.gz**. +is related to signal dropout and BOLD sensitivity. +Estimates of the parameters are saved as **t2sv.nii.gz** and **s0v.nii.gz**. While :math:`T_{2}^*` and :math:`S_0` in fact fluctuate over time, estimating them on a volume-by-volume basis with only a small number of echoes is not @@ -141,7 +141,8 @@ between the distributions for other echoes. .. image:: /_static/a09_optimal_combination_value_distributions.png The time series for the optimally combined data also looks like a combination -of the other echoes (which it is). This optimally combined data is written out as **ts_OC.nii.gz** +of the other echoes (which it is). +This optimally combined data is written out as **ts_OC.nii.gz** .. image:: /_static/a10_optimal_combination_timeseries.png @@ -158,13 +159,18 @@ of the other echoes (which it is). This optimally combined data is written out a Denoising ````````` -The next step is an attempt to remove noise from the data. This process can be +The next step is an attempt to remove noise from the data. +This process can be broadly seperated into three steps: **decomposition, metric calculation** and -**component selection**. Decomposition reduces the dimensionality of the -optimally combined data using PCA and then an ICA. Metrics which highlights the -TE-dependence or indepence are derived from these components. Component selection +**component selection**. +Decomposition reduces the dimensionality of the +optimally combined data using PCA and then an ICA. +Metrics which highlights the +TE-dependence or indepence are derived from these components. +Component selection uses these metrics in order to identify components that should be kept in the data -or discarded. Unwanted components are then removed from the optimally combined data +or discarded. +Unwanted components are then removed from the optimally combined data to produce the denoised data output. TEDPCA @@ -189,7 +195,8 @@ A more complicated approach involves applying a decision tree (similar to the decision tree described in the TEDICA section below) to identify and discard PCA components which, in addition to not explaining much variance, are also not significantly TE-dependent (i.e., have low Kappa) or -TE-independent (i.e., have low Rho). These approaches can be accessed using +TE-independent (i.e., have low Rho). +These approaches can be accessed using either the `kundu` or `kundu_stabilize` options for the `--tedpca` flag. After component selection is performed, the retained components and their @@ -203,15 +210,18 @@ TEDICA Next, ``tedana`` applies TE-dependent independent components analysis (ICA) in order to identify and remove TE-independent (i.e., non-BOLD noise) components. The dimensionally reduced optimally combined data are first subjected to ICA in -order to fit a mixing matrix to the whitened data. This generates a number if +order to fit a mixing matrix to the whitened data. +This generates a number if independent timeseries (saved as **meica_mix.1D**), as well as beta maps which show the spatially loading of these components on the brain (**betas_OC.nii.gz**). .. image:: /_static/a13_ica_component_timeseries.png Linear regression is used to fit the component time series to each voxel in each -echo from the original, echo-specific data. This results in echo- and voxel-specific -betas for each of the components.The beta values from the linear regression +echo from the original, echo-specific data. +This results in echo- and voxel-specific +betas for each of the components. +The beta values from the linear regression can be used to determine how the fluctutations (in each component timeseries) change across the echo times. @@ -232,7 +242,8 @@ The grey lines show how beta values (Parameter Estimates) change over time. Refe A decision tree is applied to :math:`\kappa`, :math:`\rho`, and other metrics in order to classify ICA components as TE-dependent (BOLD signal), TE-independent -(non-BOLD noise), or neither (to be ignored). These classifications are saved in +(non-BOLD noise), or neither (to be ignored). +These classifications are saved in `comp_table_ica.txt`. The actual decision tree is dependent on the component selection algorithm employed. ``tedana`` includes two options: `kundu_v2_5` (which uses hardcoded thresholds diff --git a/docs/considerations.rst b/docs/considerations.rst index bd125606e..7579e91bb 100644 --- a/docs/considerations.rst +++ b/docs/considerations.rst @@ -1,8 +1,8 @@ ########################## Considerations for ME-fMRI ########################## -Multi-echo fMRI acquisition sequences and analysis methods are rapidly maturing. Someone who has access -to a multi-echo fMRI sequence should seriously consider using it. +Multi-echo fMRI acquisition sequences and analysis methods are rapidly maturing. +Someone who has access to a multi-echo fMRI sequence should seriously consider using it. The possible costs and benefits of multi-echo fMRI ================================================== @@ -30,30 +30,37 @@ Weighted Averaging may lead to an increase in SNR ------------------------------------------------- Multiple studies have shown that a weighted average of the echoes to optimize T2* weighting, sometimes called "optimally combined," -gives a reliable, modest boost in data quality. The optimal combination of echoes can currently be -calculated in several software packages including AFNI, fMRIPrep, and tedana. In tedana, the weighted +gives a reliable, modest boost in data quality. +The optimal combination of echoes can currently be calculated in several software packages including AFNI, +fMRIPrep, and tedana. In tedana, the weighted average can be calculated with `t2smap`_ If no other acquisition compromises are necessary to acquire multi-echo data, this boost is worthwhile. Consider the life of the dataset -------------------------------- If other -compromises are necessary, consider the life of the data set. If data is being acquired for a discrete +compromises are necessary, consider the life of the data set. +If data is being acquired for a discrete study that will be acquired, analyzed, and published in a year or two, it might not be worth making -compromises to acquire multi-echo data. If a data set is expected to be used for future analyses in later +compromises to acquire multi-echo data. +If a data set is expected to be used for future analyses in later years, it is likely that more powerful approaches to multi-echo denoising will sufficiently mature and add even more value to a data set. Other multi-echo denoising methods, such as MEICA, the predecessor to tedana, have shown the potential for much greater data quality improvements, as well as the ability to more accurately separate visually similar -signal vs noise, such as scanner based drifts vs slow changes in BOLD signal. These more powerful methods are -still being improved, and the algorithms are still changing. Users need to have the time and knowledge to look +signal vs noise, such as scanner based drifts vs slow changes in BOLD signal. +These more powerful methods are +still being improved, and the algorithms are still changing. +Users need to have the time and knowledge to look at the denoising output from every run to make sure denoising worked as intended. You may recover signal in areas affected by dropout --------------------------------------------------- -Typical single echo fMRI uses an echo time that is appropriate for signal across most of the brain. While this is effective -it also leads to drop out in regions with low :math:T_2^* values. This can lead to low or even no signal at all in some areas. +Typical single echo fMRI uses an echo time that is appropriate for signal across most of the brain. +While this is effective +it also leads to drop out in regions with low :math:T_2^* values. +This can lead to low or even no signal at all in some areas. If your research question could benefit from having either improved signal characteristics in regions such as the orbitofrontal cortex, ventral temporal cortex or the ventral striatum them multi-echo fMRI may be beneficial. @@ -62,7 +69,8 @@ Consider the cost of added quality control ------------------------------------------ If someone wants a push-button way to use multi-echo data to improve data quality, that doesn't require as deep an inspection of every output, -stick with using the weighted average. The developers of tedana look forward to when tedana and other methods +stick with using the weighted average. +The developers of tedana look forward to when tedana and other methods have sufficiently stable algorithms, which have been validated on a wide range of data sets, so that we can recommend the wide use of tedana. @@ -95,7 +103,8 @@ There are multiple ways to balance the slight time cost from the added echoes th resulted in research publications. We suggest new multi-echo fMRI users examine the :ref:`spreadsheet of publications` that use multi-echo fMRI to identify studies with similar acquisition priorities, -and use the parameters from those studies as a starting point. More complete recomendations +and use the parameters from those studies as a starting point. +More complete recomendations and guidelines are discussed in the `appendix`_ of Dipasquale et al, 2017. .. _appendix: https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0173289 @@ -106,8 +115,8 @@ and guidelines are discussed in the `appendix`_ of Dipasquale et al, 2017. .. _GE Collaboration Portal: https://collaborate.mr.gehealthcare.com .. note:: In order to increase the number of contrasts ("echoes") you may need to first increase the TR, shorten the - first TE and/or enable in-plane acceleration. For typically used parameters see the - `parameters and publications page`_ + first TE and/or enable in-plane acceleration. + For typically used parameters see the `parameters and publications page`_ .. _parameters and publications page: https://tedana.readthedocs.io/en/latest/publications.html Resources @@ -153,13 +162,17 @@ Available multi-echo fMRI sequences for multiple vendors **For Siemens** users, there are two options for Works In Progress (WIPs) Sequences. The Center for Magnetic Resonance Research at the University of Minnesota provides a custom MR sequence that allows users to collect multiple echoes -(termed **Contrasts**). The sequence and documentation can be `found here`_. For details -on obtaining a license follow `this link`_. By default the number of contrasts is 1, -yielding a signal echo sequence. In order to collect multiple echoes, increase number of +(termed **Contrasts**). +The sequence and documentation can be `found here`_. For details +on obtaining a license follow `this link`_. +By default the number of contrasts is 1, +yielding a signal echo sequence. + In order to collect multiple echoes, increase number of Contrasts on the **Sequence Tab, Part 1** on the MR console. In addition, the Martinos Center at Harvard also has a MR sequence available, with the -details `available here`_. The number of echoes can be specified on the **Sequence, Special** tab +details `available here`_. +The number of echoes can be specified on the **Sequence, Special** tab in this sequence. **For GE users**, there are currently two sharable pulse sequences: @@ -169,7 +182,8 @@ Hyperband Multi-echo EPI (HyperMEPI) - Software releases: DV26, MP26, DV27, RX27 (here Hyperband can be deactivated to do simple Multi-echo EPI – online recon) Please reach out to the GE Research Operation team or each pulse sequence’s -author to begin the process of obtaining this software. More information can be +author to begin the process of obtaining this software. +More information can be found on the `GE Collaboration Portal`_ Once logged-in, go to Groups > GE Works-in-Progress you can find the description of the current ATSM (i.e. prototypes) @@ -185,7 +199,8 @@ AFNI can process multi-echo data natively as well as apply tedana denoising thro .. _afni_proc.py help: https://afni.nimh.nih.gov/pub/dist/doc/program_help/afni_proc.py.html `fmriprep` can also process multi-echo data, but is currently limited to using the optimally combined -timeseries. For more details, see the `fmriprep workflows page`_ +timeseries. +For more details, see the `fmriprep workflows page`_ .. _fmriprep workflows page: https://fmriprep.readthedocs.io/en/stable/workflows.html diff --git a/docs/faq.rst b/docs/faq.rst index 5fbe66766..24caef0bc 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -36,9 +36,10 @@ Anyone interested in using v3.2 may compile and install an earlier release (<=0. What is the warning about ``duecredit``? ````````````````````````````````````````` -``duecredit`` is a python package that is used, but not required by ``tedana``. These warnings do -not affect any of the processing within the ``tedana``. To avoide this warning, you can install -``duecredit`` with ``pip install duecredit``. For more information about ``duecredit`` and concerns about +``duecredit`` is a python package that is used, but not required by ``tedana``. +These warnings do not affect any of the processing within the ``tedana``. +To avoide this warning, you can install ``duecredit`` with ``pip install duecredit``. +For more information about ``duecredit`` and concerns about the citation and visibility of software or methods, visit the `duecredit`_ github. .. _duecredit: https://github.com/duecredit/duecredit @@ -55,13 +56,14 @@ Multi-echo fMRI Will I encounter SAR limits more often with multi-echo fMRI? ```````````````````````````````````````````````````````````` While multi-echo does lead to collecting more images during each TR (one per echo), there is still only a single -radiofrequency pulse. For this reason, there is no change in SAR for participants intrinsic to multi-echo -fMRI. +radiofrequency pulse. +For this reason, there is no change in SAR for participants intrinsic to multi-echo fMRI. Can I combine multiband (simultaneous multislice) with multi-echo fMRI? ``````````````````````````````````````````````````````````````````````` -Yes, these techniques are completely seperate. Mutliband fMRI leads to collecting multiple slices within a volume -simultaneouly, while multi-echo fMRI is instead related to collecting multiple unique volumes. These techniques can -be combined to reduce the TR in a multi-echo sequence. +Yes, these techniques are completely seperate. +Mutliband fMRI leads to collecting multiple slices within a volume simultaneouly, while multi-echo +fMRI is instead related to collecting multiple unique volumes. +These techniques can be combined to reduce the TR in a multi-echo sequence. diff --git a/docs/multi-echo.rst b/docs/multi-echo.rst index 7dbadadeb..23c329734 100644 --- a/docs/multi-echo.rst +++ b/docs/multi-echo.rst @@ -2,9 +2,9 @@ What is multi-echo fMRI ======================= Most echo-planar image (EPI) sequences collect a single brain image following a radio frequency (RF) pulse, at a rate known as the repetition time (TR). -This typical approach is known as single-echo fMRI. In contrast, multi-echo (ME) -fMRI refers to collecting data at multiple echo times, resulting in -multiple volumes with varying levels of contrast acquired per RF pulse. +This typical approach is known as single-echo fMRI. +In contrast, multi-echo (ME) fMRI refers to collecting data at multiple echo times, +resulting in multiple volumes with varying levels of contrast acquired per RF pulse. The physics of multi-echo fMRI ------------------------------ @@ -21,8 +21,9 @@ The image below shows the basic relationship between echo times and the image ac 3T (top, A) and 7T (bottom, B). Note that the earliest echo time is the brightest, as the signal has only had a limited amount of time to decay. In addition, the latter echo times show areas in which is the signal has decayed completely ('drop out') -due to inhomgeneity in the magnetic field. By using the information across multiple -echoes these images can be combined in an optimal manner to take advantage of the signal +due to inhomgeneity in the magnetic field. +By using the information across multiple echoes these images can be combined in +an optimal manner to take advantage of the signal in the earlier echoes (see `processing pipeline details`_). .. image:: /_static/physics_kundu_2017_multiple_echoes.jpg @@ -35,20 +36,24 @@ single voxel at two timepoints (x and y) and the measured signal measured at thr Adapted from `Kundu et al. (2017)`_. For the left column, we are observing a change that we term :math:`{\Delta}{S_0}` - that is a change -in the intercept or raw signal intensity. A common example of this is participant movement, -in which the voxel (which is at a static location within the scanner) -now contains different tissue or even an area outside of the brain. - -As we have collected three seperate echoes, we can compare the change in signal at each echo time, :math:`{\Delta}{S(TE_n)}`. For -:math:`{\Delta}{S_0}` we see that this produces a decaying curve. If we compare this to the original signal, as in -:math:`\frac{{\Delta}{S(TE_n)}}{S(TE_n)}` we see that there is no echo time dependence, as the final plot is a flat line. - -In the right column, we consider changes that are related to brain activity. For example, imagine that the two brain states here -(x and y) are a baseline and task activated state respectively. This effect is a change in in :math:`{\Delta}{R_2^*}` which is equivilent -to the inverse of :math:`{T_2^*}`. We typically observe this change in signal amplitude occuring over volumes with +in the intercept or raw signal intensity. +A common example of this is participant movement, in which the voxel (which is at a static +location within the scanner) now contains different tissue or even an area outside of the brain. + +As we have collected three seperate echoes, we can compare the change in signal at each echo time, :math:`{\Delta}{S(TE_n)}`. +For :math:`{\Delta}{S_0}` we see that this produces a decaying curve. +If we compare this to the original signal, as in :math:`\frac{{\Delta}{S(TE_n)}}{S(TE_n)}` +we see that there is no echo time dependence, as the final plot is a flat line. + +In the right column, we consider changes that are related to brain activity. +For example, imagine that the two brain states here (x and y) are a baseline and task activated state respectively. +This effect is a change in in :math:`{\Delta}{R_2^*}` which is equivilent +to the inverse of :math:`{T_2^*}`. +We typically observe this change in signal amplitude occuring over volumes with the hemodynamic response, while here we are examining the change in signal over echo times. Again we can plot the difference in the signal between these two states as a function of echo time, -finding that the signal rises and falls. If we compare this curve to the original signal we find +finding that the signal rises and falls. +If we compare this curve to the original signal we find that the magnitude of the changes is dependent on the echo time. For a more comprehensive review of these topics and others, see `Kundu et al. (2017)`_. @@ -75,9 +80,10 @@ Optimally combined data exhibits higher SNR and improves statistical power of an traditionally affected by drop-out. **Denoise the data based on information contained in the echoes**: Collecting multi-echo data allows -access to unique denoising methods. ICA-based denoising methods like ICA-AROMA (`Pruim et al. (2015)`_) -have been shown to significantly improve the quality of cleaned signal. These methods, however, have comparably -limited information, as they are designed to work with single-echo EPI. +access to unique denoising methods. +ICA-based denoising methods like ICA-AROMA (`Pruim et al. (2015)`_) +have been shown to significantly improve the quality of cleaned signal. +These methods, however, have comparably limited information, as they are designed to work with single-echo EPI. ``tedana`` is an ICA-based denoising pipeline built especially for multi-echo data. Collecting multi-echo EPI allows us to leverage all of the information available for single-echo datasets, diff --git a/docs/publications.rst b/docs/publications.rst index f06a31563..6bfab4943 100644 --- a/docs/publications.rst +++ b/docs/publications.rst @@ -4,7 +4,8 @@ ME-fMRI Parameters & Publications ================================= The following page highlights a selection of parameters collected from published papers that have -used multi-echo fMRI. The subsequent spreadsheet is an on-going effort to track all of these publication. +used multi-echo fMRI. +The subsequent spreadsheet is an on-going effort to track all of these publication. This is a volunteer led effort so, if you know of a excluded publication, whether or not it is yours, please add it. diff --git a/docs/usage.rst b/docs/usage.rst index 968b29958..c82541300 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -34,9 +34,11 @@ https://tedana.readthedocs.io/en/latest/outputs.html .. note:: The ``--mask`` argument is not intended for use with very conservative region-of-interest - analyses. One of the ways by which components are assessed as BOLD or non-BOLD is their + analyses. + One of the ways by which components are assessed as BOLD or non-BOLD is their spatial pattern, so overly conservative masks will invalidate several steps in the tedana - workflow. To examine regions-of-interest with multi-echo data, apply masks after TE + workflow. + To examine regions-of-interest with multi-echo data, apply masks after TE Dependent ANAlysis. Run t2smap @@ -93,8 +95,8 @@ and apply the resulting transformation to all echoes. .. note:: Any intensity normalization or nuisance regressors should be applied to the data - *after* ``tedana`` calculates the BOLD and non-BOLD weighting of components. If this is - not considered, resulting intensity gradients (e.g., in the case of scaling) + *after* ``tedana`` calculates the BOLD and non-BOLD weighting of components. + If this is not considered, resulting intensity gradients (e.g., in the case of scaling) or alignment parameters (e.g., in the case of motion correction, normalization) are likely to differ across echos, and the subsequent calculation of voxelwise T2* values will be distorted or incorrect. From d4c82d837008b73bcaca057cb0856b7908f25707 Mon Sep 17 00:00:00 2001 From: Logan Date: Fri, 8 Nov 2019 10:57:23 -0500 Subject: [PATCH 42/55] life by a thousand little edits --- docs/approach.rst | 20 +++++++++++++++----- docs/considerations.rst | 18 ++++++++++++++---- docs/faq.rst | 9 +++++++-- docs/multi-echo.rst | 2 ++ 4 files changed, 38 insertions(+), 11 deletions(-) diff --git a/docs/approach.rst b/docs/approach.rst index f4cc55d2f..825ad4374 100644 --- a/docs/approach.rst +++ b/docs/approach.rst @@ -1,7 +1,8 @@ The tedana pipeline =================== -``tedana`` works by decomposing multi-echo BOLD data via PCA and ICA. +``tedana`` works by decomposing multi-echo BOLD data via priniciple component analysis (PCA) +and independent component analyses (ICA). The resulting components are then analyzed to determine whether they are TE-dependent or -independent. TE-dependent components are classified as BOLD, while TE-independent components @@ -79,6 +80,12 @@ transforms the data by default. The BOLD data are transformed as :math:`log(|S|+1)`, where :math:`S` is the BOLD signal. The echo times are also multiplied by -1. +.. note:: + It is now possible to do a nonlinear monoexponential fit to the orignal, untransformed + data values by specifiying ``--fittype curvefit``. + This method is slightly more computationally demanding but may obtain more + accurate fits. + .. image:: /_static/a04_echo_log_value_distributions.png A simple line can then be fit to the transformed data with linear regression. @@ -189,15 +196,17 @@ These components are subjected to component selection, the specifics of which vary according to algorithm. In the simplest approach, ``tedana`` uses Minka’s MLE to estimate the -dimensionality of the data, which disregards low-variance components. (the `mle` option in for `--tedpca`). +dimensionality of the data, which disregards low-variance components (the `mle` option in for `--tedpca`). A more complicated approach involves applying a decision tree (similar to the decision tree described in the TEDICA section below) to identify and discard PCA components which, in addition to not explaining much variance, are also not significantly TE-dependent (i.e., have low Kappa) or TE-independent (i.e., have low Rho). -These approaches can be accessed using -either the `kundu` or `kundu_stabilize` options for the `--tedpca` flag. +These approaches can be accessed using either the `kundu` or `kundu_stabilize` +options for the `--tedpca` flag. +For a more thorough explanation of this approach, consider the supplemental information +in `Kundu et al (2013)`_ After component selection is performed, the retained components and their associated betas are used to reconstruct the optimally combined data, resulting @@ -275,4 +284,5 @@ Currently, ``tedana`` implements GSR and T1c-GSR. .. _Power et al. (2018): http://www.pnas.org/content/early/2018/02/07/1720985115.short .. _Poser et al., 2006: https://onlinelibrary.wiley.com/doi/full/10.1002/mrm.20900 -.. _physics section: https://tedana.readthedocs.io/en/latest/multi_echo.html \ No newline at end of file +.. _physics section: https://tedana.readthedocs.io/en/latest/multi_echo.html +.. _Kundu et al (2013): https://www.ncbi.nlm.nih.gov/pubmed/24038744 \ No newline at end of file diff --git a/docs/considerations.rst b/docs/considerations.rst index 7579e91bb..dacf813f5 100644 --- a/docs/considerations.rst +++ b/docs/considerations.rst @@ -67,16 +67,19 @@ the ventral striatum them multi-echo fMRI may be beneficial. Consider the cost of added quality control ------------------------------------------ +The developers of ``tedana`` strongly support always examining data for quality concerns, whether +or not multi-echo fMRI is used. If someone wants a push-button way to use multi-echo data to improve data quality, that doesn't require as deep an inspection of every output, stick with using the weighted average. The developers of tedana look forward to when tedana and other methods have sufficiently stable algorithms, which have been validated on a wide range of data sets, so that we can recommend the wide use of tedana. - - +``tedana`` currently allows the use of a ``--png`` flag when called, in order to produce basic diagnostic images, +`see outputs`_ for more information on these outputs. .. _t2smap: https://tedana.readthedocs.io/en/latest/usage.html#run-t2smap +.. _see outputs: https://tedana.readthedocs.io/en/latest/outputs.html Acquisition Parameter Recommendations ===================================== @@ -87,11 +90,18 @@ fMRI sequences are also relevant. Choose sequence parameters that meet the priorities of a study with regards to spatial resolution, spatial coverage, sample rate, signal-to-noise ratio, signal drop-out, distortion, and artifacts. -A minimum of 3 echoes is recommended for running TE-dependent denoising. +A minimum of 3 echoes is required for running the current implementation fo TE-dependent denoising in +``tedana``. While there are successful studies that don’t follow this rule, it may be useful to have at least one echo that is earlier and one echo that is later than the TE one would use for single-echo T2* weighted fMRI. +.. note:: + This is in contrast to the **dual echo** denoising method which uses a very early (~5ms) + first echo in order to clean data. For more information on this method, see `Bright and Murphy`_ (2013). + +.. _Bright and Murphy: https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3518782/ + More than 3 echoes may be useful, because that would allow for more accurate estimates of BOLD and non-BOLD weighted fluctuations, but more echoes have an additional time cost, which would result in either less spatiotemporal coverage @@ -167,7 +177,7 @@ The sequence and documentation can be `found here`_. For details on obtaining a license follow `this link`_. By default the number of contrasts is 1, yielding a signal echo sequence. - In order to collect multiple echoes, increase number of +In order to collect multiple echoes, increase number of Contrasts on the **Sequence Tab, Part 1** on the MR console. In addition, the Martinos Center at Harvard also has a MR sequence available, with the diff --git a/docs/faq.rst b/docs/faq.rst index 24caef0bc..44ba1a563 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -53,12 +53,17 @@ the citation and visibility of software or methods, visit the `duecredit`_ githu Multi-echo fMRI --------------- -Will I encounter SAR limits more often with multi-echo fMRI? -```````````````````````````````````````````````````````````` +Will I encounter participant heating limits more often with multi-echo fMRI? +```````````````````````````````````````````````````````````````````````````` +One of the more important considerations in MR imaging is limits assocaited with the `specific absorbtion rate`_ (SAR). +This is related to how much radio frequency (RF) energy can be used in imaging over time, in order to avoid adding +to much heat to the participant. While multi-echo does lead to collecting more images during each TR (one per echo), there is still only a single radiofrequency pulse. For this reason, there is no change in SAR for participants intrinsic to multi-echo fMRI. +.. _specific absorbtion rate: https://www.mr-tip.com/serv1.php?type=db1&dbs=Specific%20Absorption%20Rate + Can I combine multiband (simultaneous multislice) with multi-echo fMRI? ``````````````````````````````````````````````````````````````````````` Yes, these techniques are completely seperate. diff --git a/docs/multi-echo.rst b/docs/multi-echo.rst index 23c329734..58725899f 100644 --- a/docs/multi-echo.rst +++ b/docs/multi-echo.rst @@ -27,12 +27,14 @@ an optimal manner to take advantage of the signal in the earlier echoes (see `processing pipeline details`_). .. image:: /_static/physics_kundu_2017_multiple_echoes.jpg + Adapted from `Kundu et al. (2017)`_. In order to classify the relationship between the signal and the echo time we can consider a single voxel at two timepoints (x and y) and the measured signal measured at three different echo times - :math:`S(TE_n)`. .. image:: /_static/physics_kundu_2017_TE_dependence.jpg + Adapted from `Kundu et al. (2017)`_. For the left column, we are observing a change that we term :math:`{\Delta}{S_0}` - that is a change From 93befb15f4505f0a18c6c1dccb27462cfccbe041 Mon Sep 17 00:00:00 2001 From: Logan Date: Fri, 8 Nov 2019 11:00:15 -0500 Subject: [PATCH 43/55] GrAmMaRs --- docs/publications.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/publications.rst b/docs/publications.rst index 6bfab4943..ece4b3c84 100644 --- a/docs/publications.rst +++ b/docs/publications.rst @@ -6,7 +6,7 @@ ME-fMRI Parameters & Publications The following page highlights a selection of parameters collected from published papers that have used multi-echo fMRI. The subsequent spreadsheet is an on-going effort to track all of these publication. -This is a volunteer led effort so, if you know of a excluded publication, whether or not it is yours, +This is a volunteer-led effort so, if you know of a excluded publication, whether or not it is yours, please add it. The following plots reflect the average values for studies conducted at 3 Tesla. From 916729b10f831b37f0040a03df4a904e3972963f Mon Sep 17 00:00:00 2001 From: Logan Date: Fri, 8 Nov 2019 12:24:41 -0500 Subject: [PATCH 44/55] other software! --- docs/considerations.rst | 32 ++++++++++++++++++++++++++++++-- 1 file changed, 30 insertions(+), 2 deletions(-) diff --git a/docs/considerations.rst b/docs/considerations.rst index dacf813f5..71254bc94 100644 --- a/docs/considerations.rst +++ b/docs/considerations.rst @@ -217,9 +217,37 @@ For more details, see the `fmriprep workflows page`_ Currently SPM and FSL do not natively support mutli-echo fmri data processing. Other software that uses multi-echo fMRI ----------------------------------------- +======================================== + +``tedana`` represents only one approach to processing multiecho data. +Currently there are a number of methods that can take advantage of or use the information contain in multi-echo data. +These include: + +`3dMEPFM`_: A multi-echo implemntation of 'paradigm free mapping', that is detection of neural events in the absense of +a prespecified model. +By leveraging the information present in multiecho data, changes in relaxation time can be directly esimated and +more events can be detected. For more information, see the `following paper`_. + +.. _3dMEPFM: https://afni.nimh.nih.gov/pub/dist/doc/program_help/3dMEPFM.html +.. _following paper: https://www.sciencedirect.com/science/article/pii/S105381191930669X + +`Bayesian approach to denoising`_: An alternative approach to seperating out BOLD and non-BOLD signals within a Bayesian +framework is currently under development. + +.. _Bayesian approach to denoising: https://ww5.aievolution.com/hbm1901/index.cfm?do=abs.viewAbs&abs=5026 + +`Multi-echo Group ICA`_: Current approches to ICA just use a single run of data in order to perform denoising. An alternative +approach is to use information from multiple subjects or multiple runs from a single subject in order to improve the +classification of BOLD and non-BOLD components. + +.. _Multi-echo Group ICA: https://ww5.aievolution.com/hbm1901/index.cfm?do=abs.viewAbs&abs=1286 + +`Dual Echo Denoising`_: If the first echo can be collected early enough, there are currently methods that take advantage of the +very limited BOLD weighting at these early echo times. + +.. _Dual Echo Denoising: https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3518782/ + -Information and links to other approaches for denoising multi-echo fMRI data will be added here. Datasets -------- From 709a16631236fe3f99bc78f4297337d2bfd8ffd4 Mon Sep 17 00:00:00 2001 From: Logan Date: Fri, 8 Nov 2019 12:58:42 -0500 Subject: [PATCH 45/55] links to api in approach --- docs/approach.rst | 32 ++++++++++++++++++++++++++++++-- 1 file changed, 30 insertions(+), 2 deletions(-) diff --git a/docs/approach.rst b/docs/approach.rst index 825ad4374..9d1467372 100644 --- a/docs/approach.rst +++ b/docs/approach.rst @@ -2,7 +2,7 @@ The tedana pipeline =================== ``tedana`` works by decomposing multi-echo BOLD data via priniciple component analysis (PCA) -and independent component analyses (ICA). +and independent component analysis (ICA). The resulting components are then analyzed to determine whether they are TE-dependent or -independent. TE-dependent components are classified as BOLD, while TE-independent components @@ -46,6 +46,10 @@ When :math:`T_{2}^*` and :math:`S_{0}` are calculated below, each voxel's values are only calculated from the first :math:`n` echoes, where :math:`n` is the value for that voxel in the adaptive mask. +`Adaptive mask code`_ + +.. _Adaptive mask code: https://tedana.readthedocs.io/en/latest/generated/tedana.utils.make_adaptive_mask.html#tedana.utils.make_adaptive_mask + .. note:: ``tedana`` allows users to provide their own mask. The adaptive mask will be computed on this explicit mask, and may reduce @@ -80,6 +84,11 @@ transforms the data by default. The BOLD data are transformed as :math:`log(|S|+1)`, where :math:`S` is the BOLD signal. The echo times are also multiplied by -1. +`Decay model fit code`_ + +.. _Decay model fit code: https://tedana.readthedocs.io/en/latest/generated/tedana.decay.fit_decay.html#tedana.decay.fit_decay + + .. note:: It is now possible to do a nonlinear monoexponential fit to the orignal, untransformed data values by specifiying ``--fittype curvefit``. @@ -151,6 +160,11 @@ The time series for the optimally combined data also looks like a combination of the other echoes (which it is). This optimally combined data is written out as **ts_OC.nii.gz** +`Optimal combination code`_ + +.. _Optimal combination code: https://tedana.readthedocs.io/en/latest/generated/tedana.combine.make_optcom.html#tedana.combine.make_optcom + + .. image:: /_static/a10_optimal_combination_timeseries.png .. note:: @@ -214,6 +228,11 @@ in a dimensionally reduced version of the dataset which is then used in the `TED .. image:: /_static/a12_pca_reduced_data.png +`TEDPCA code`_ + +.. _TEDPCA code: https://tedana.readthedocs.io/en/latest/generated/tedana.decomposition.tedpca.html#tedana.decomposition.tedpca + + TEDICA `````` Next, ``tedana`` applies TE-dependent independent components analysis (ICA) in @@ -260,7 +279,12 @@ applied to each of the metrics) and `kundu_v3_2` (which trains a classifier to select components). Components that are classified as noise are projected out of the optimally combined data, -yielding a denoised timeseries, which is saved as `dn_ts_OC.nii.gz`. +yielding a denoised timeseries, which is saved as `dn_ts_OC.nii.gz`. + +`TEDICA code`_ + +.. _TEDICA code: https://tedana.readthedocs.io/en/latest/generated/tedana.decomposition.tedica.html#tedana.decomposition.tedica + .. image:: /_static/a15_denoised_data_timeseries.png @@ -278,6 +302,10 @@ regression (GSR), T1c-GSR, anatomical CompCor, Go Decomposition (GODEC), and robust PCA. Currently, ``tedana`` implements GSR and T1c-GSR. +`Global signal control code`_ + +.. _Global signal control code: https://tedana.readthedocs.io/en/latest/generated/tedana.gscontrol.gscontrol_mmix.html#tedana.gscontrol.gscontrol_mmix + .. image:: /_static/a16_t1c_denoised_data_timeseries.png .. _nilearn.masking.compute_epi_mask: https://nilearn.github.io/modules/generated/nilearn.masking.compute_epi_mask.html From e28447a2ac67055b36a457526e48692253748681 Mon Sep 17 00:00:00 2001 From: Logan Date: Fri, 8 Nov 2019 13:42:40 -0500 Subject: [PATCH 46/55] white space? --- docs/faq.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/faq.rst b/docs/faq.rst index 44ba1a563..0ec4b38cc 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -70,5 +70,3 @@ Yes, these techniques are completely seperate. Mutliband fMRI leads to collecting multiple slices within a volume simultaneouly, while multi-echo fMRI is instead related to collecting multiple unique volumes. These techniques can be combined to reduce the TR in a multi-echo sequence. - - From 9634b717900863f00816947df6096768a8dfddbb Mon Sep 17 00:00:00 2001 From: Logan Dowdle Date: Fri, 8 Nov 2019 15:23:51 -0500 Subject: [PATCH 47/55] Update docs/faq.rst Co-Authored-By: Elizabeth DuPre --- docs/faq.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/faq.rst b/docs/faq.rst index 0ec4b38cc..3b15f7d68 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -66,7 +66,7 @@ For this reason, there is no change in SAR for participants intrinsic to multi-e Can I combine multiband (simultaneous multislice) with multi-echo fMRI? ``````````````````````````````````````````````````````````````````````` -Yes, these techniques are completely seperate. +Yes, these techniques are complementary. Mutliband fMRI leads to collecting multiple slices within a volume simultaneouly, while multi-echo fMRI is instead related to collecting multiple unique volumes. These techniques can be combined to reduce the TR in a multi-echo sequence. From 85a5f06b4f64114b606f6851dd4042a72143fd39 Mon Sep 17 00:00:00 2001 From: Logan Date: Fri, 8 Nov 2019 15:28:52 -0500 Subject: [PATCH 48/55] MRI scanners != BBQ --- docs/faq.rst | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/docs/faq.rst b/docs/faq.rst index 0ec4b38cc..a7fd217e9 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -53,14 +53,11 @@ the citation and visibility of software or methods, visit the `duecredit`_ githu Multi-echo fMRI --------------- -Will I encounter participant heating limits more often with multi-echo fMRI? -```````````````````````````````````````````````````````````````````````````` -One of the more important considerations in MR imaging is limits assocaited with the `specific absorbtion rate`_ (SAR). -This is related to how much radio frequency (RF) energy can be used in imaging over time, in order to avoid adding -to much heat to the participant. +Does multi-echo fMRI require more radio frequency pulses? +````````````````````````````````````````````````````````` While multi-echo does lead to collecting more images during each TR (one per echo), there is still only a single -radiofrequency pulse. -For this reason, there is no change in SAR for participants intrinsic to multi-echo fMRI. +radiofrequency pulse per TR. This means that there is no change in the `specific absorbtion rate`_ (SAR) limits +for the participant. .. _specific absorbtion rate: https://www.mr-tip.com/serv1.php?type=db1&dbs=Specific%20Absorption%20Rate From 563e64303577ce84bb231fe1ea4d9fc7ba427528 Mon Sep 17 00:00:00 2001 From: Logan Dowdle Date: Fri, 8 Nov 2019 15:32:43 -0500 Subject: [PATCH 49/55] Update docs/approach.rst Co-Authored-By: Elizabeth DuPre --- docs/approach.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/approach.rst b/docs/approach.rst index 9d1467372..02e0dc090 100644 --- a/docs/approach.rst +++ b/docs/approach.rst @@ -149,7 +149,7 @@ For the example voxel, the resulting weights are: :width: 400 px :align: center -THese normalized weights are then used to compute a weighted average that takes advantage +These normalized weights are then used to compute a weighted average that takes advantage of the higher signal in earlier echoes and the heigher sensitivty at later echoes. The distribution of values for the optimally combined data lands somewhere between the distributions for other echoes. @@ -313,4 +313,4 @@ Currently, ``tedana`` implements GSR and T1c-GSR. .. _Poser et al., 2006: https://onlinelibrary.wiley.com/doi/full/10.1002/mrm.20900 .. _physics section: https://tedana.readthedocs.io/en/latest/multi_echo.html -.. _Kundu et al (2013): https://www.ncbi.nlm.nih.gov/pubmed/24038744 \ No newline at end of file +.. _Kundu et al (2013): https://www.ncbi.nlm.nih.gov/pubmed/24038744 From 07829672bfd2e44037c55aeee7293d9686b9a2c5 Mon Sep 17 00:00:00 2001 From: Logan Dowdle Date: Fri, 8 Nov 2019 15:33:30 -0500 Subject: [PATCH 50/55] Update docs/approach.rst Co-Authored-By: Elizabeth DuPre --- docs/approach.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/approach.rst b/docs/approach.rst index 02e0dc090..b50b19321 100644 --- a/docs/approach.rst +++ b/docs/approach.rst @@ -90,7 +90,7 @@ The echo times are also multiplied by -1. .. note:: - It is now possible to do a nonlinear monoexponential fit to the orignal, untransformed + It is now possible to do a nonlinear monoexponential fit to the original, untransformed data values by specifiying ``--fittype curvefit``. This method is slightly more computationally demanding but may obtain more accurate fits. From cad87a997e67e63746f695f27a8d342e793a78fe Mon Sep 17 00:00:00 2001 From: Logan Dowdle Date: Fri, 8 Nov 2019 15:37:16 -0500 Subject: [PATCH 51/55] Apply suggestions from code review, thanks a million Co-Authored-By: Elizabeth DuPre --- docs/approach.rst | 10 +++++----- docs/considerations.rst | 4 ++-- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/approach.rst b/docs/approach.rst index b50b19321..0256b7283 100644 --- a/docs/approach.rst +++ b/docs/approach.rst @@ -182,10 +182,10 @@ Denoising ````````` The next step is an attempt to remove noise from the data. This process can be -broadly seperated into three steps: **decomposition, metric calculation** and +broadly seperated into three steps: **decomposition**, **metric calculation** and **component selection**. Decomposition reduces the dimensionality of the -optimally combined data using PCA and then an ICA. +optimally combined data using `Principal Components Analysis (PCA)`_ and then an `Independent Components Analysis (ICA)`_. Metrics which highlights the TE-dependence or indepence are derived from these components. Component selection @@ -239,14 +239,14 @@ Next, ``tedana`` applies TE-dependent independent components analysis (ICA) in order to identify and remove TE-independent (i.e., non-BOLD noise) components. The dimensionally reduced optimally combined data are first subjected to ICA in order to fit a mixing matrix to the whitened data. -This generates a number if +This generates a number of independent timeseries (saved as **meica_mix.1D**), as well as beta maps which show -the spatially loading of these components on the brain (**betas_OC.nii.gz**). +the spatial loading of these components on the brain (**betas_OC.nii.gz**). .. image:: /_static/a13_ica_component_timeseries.png Linear regression is used to fit the component time series to each voxel in each -echo from the original, echo-specific data. +of the original, echo-specific data. This results in echo- and voxel-specific betas for each of the components. The beta values from the linear regression diff --git a/docs/considerations.rst b/docs/considerations.rst index 71254bc94..facc278c3 100644 --- a/docs/considerations.rst +++ b/docs/considerations.rst @@ -50,8 +50,8 @@ even more value to a data set. Other multi-echo denoising methods, such as MEICA, the predecessor to tedana, have shown the potential for much greater data quality improvements, as well as the ability to more accurately separate visually similar signal vs noise, such as scanner based drifts vs slow changes in BOLD signal. -These more powerful methods are -still being improved, and the algorithms are still changing. +More powerful methods are +still being improved, and associated algorithms are still being actively developed. Users need to have the time and knowledge to look at the denoising output from every run to make sure denoising worked as intended. From 6977bd5e44098bfef8fde6ed616095deafbb3cec Mon Sep 17 00:00:00 2001 From: Logan Date: Fri, 8 Nov 2019 15:42:31 -0500 Subject: [PATCH 52/55] echo cleanup, and kundu 3 banish --- docs/approach.rst | 5 ++--- docs/considerations.rst | 3 +-- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/approach.rst b/docs/approach.rst index 0256b7283..650796a9a 100644 --- a/docs/approach.rst +++ b/docs/approach.rst @@ -274,9 +274,8 @@ classify ICA components as TE-dependent (BOLD signal), TE-independent These classifications are saved in `comp_table_ica.txt`. The actual decision tree is dependent on the component selection algorithm employed. -``tedana`` includes two options: `kundu_v2_5` (which uses hardcoded thresholds -applied to each of the metrics) and `kundu_v3_2` (which trains a classifier to -select components). +``tedana`` includes the option `kundu` (which uses hardcoded thresholds +applied to each of the metrics). Components that are classified as noise are projected out of the optimally combined data, yielding a denoised timeseries, which is saved as `dn_ts_OC.nii.gz`. diff --git a/docs/considerations.rst b/docs/considerations.rst index facc278c3..0b256c986 100644 --- a/docs/considerations.rst +++ b/docs/considerations.rst @@ -92,8 +92,7 @@ spatial coverage, sample rate, signal-to-noise ratio, signal drop-out, distortio A minimum of 3 echoes is required for running the current implementation fo TE-dependent denoising in ``tedana``. -While there are successful studies that don’t follow this rule, -it may be useful to have at least one echo that is earlier and one echo that is later than the +It may be useful to have at least one echo that is earlier and one echo that is later than the TE one would use for single-echo T2* weighted fMRI. .. note:: From d7e45984823147bbbddb88a503f4ae1db3d15380 Mon Sep 17 00:00:00 2001 From: Logan Date: Fri, 8 Nov 2019 15:46:24 -0500 Subject: [PATCH 53/55] noted png default --- docs/considerations.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/considerations.rst b/docs/considerations.rst index 0b256c986..42af16814 100644 --- a/docs/considerations.rst +++ b/docs/considerations.rst @@ -75,7 +75,7 @@ stick with using the weighted average. The developers of tedana look forward to when tedana and other methods have sufficiently stable algorithms, which have been validated on a wide range of data sets, so that we can recommend the wide use of tedana. -``tedana`` currently allows the use of a ``--png`` flag when called, in order to produce basic diagnostic images, +``tedana`` currently produces basic diagnostic images by default, `see outputs`_ for more information on these outputs. .. _t2smap: https://tedana.readthedocs.io/en/latest/usage.html#run-t2smap From 90718ed09c08876aa3462f5e423d8a0aae133986 Mon Sep 17 00:00:00 2001 From: Logan Date: Fri, 8 Nov 2019 15:50:24 -0500 Subject: [PATCH 54/55] completely changed the QC section --- docs/considerations.rst | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/docs/considerations.rst b/docs/considerations.rst index 42af16814..a1df8e5c9 100644 --- a/docs/considerations.rst +++ b/docs/considerations.rst @@ -68,15 +68,11 @@ the ventral striatum them multi-echo fMRI may be beneficial. Consider the cost of added quality control ------------------------------------------ The developers of ``tedana`` strongly support always examining data for quality concerns, whether -or not multi-echo fMRI is used. -If someone wants a push-button -way to use multi-echo data to improve data quality, that doesn't require as deep an inspection of every output, -stick with using the weighted average. -The developers of tedana look forward to when tedana and other methods -have sufficiently stable algorithms, which have been validated on a wide range of data sets, so that we can -recommend the wide use of tedana. -``tedana`` currently produces basic diagnostic images by default, -`see outputs`_ for more information on these outputs. +or not multi-echo fMRI is used. +Multi-echo data and denoising are no exception. +For this purpose, ``tedana`` currently produces basic diagnostic images by default, which can be +inspected in order to determine the quality of denoising. +`See outputs`_ for more information on these outputs. .. _t2smap: https://tedana.readthedocs.io/en/latest/usage.html#run-t2smap .. _see outputs: https://tedana.readthedocs.io/en/latest/outputs.html From 33e4675dd417c9c574db94780445d6b7e446586f Mon Sep 17 00:00:00 2001 From: Logan Dowdle Date: Fri, 8 Nov 2019 16:21:25 -0500 Subject: [PATCH 55/55] pls wrk Co-Authored-By: Elizabeth DuPre --- docs/considerations.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/considerations.rst b/docs/considerations.rst index a1df8e5c9..b4c4c11f8 100644 --- a/docs/considerations.rst +++ b/docs/considerations.rst @@ -132,8 +132,8 @@ Journal articles * | :ref:`spreadsheet of publications` catalogues papers using multi-echo fMRI, with information about acquisition parameters. * | `Multi-echo acquisition`_ - | Posse, NeuroImage 2012 - | Includes an historical overview of multi-echo acquisition and research + | Posse, NeuroImage 2012 + | Includes an historical overview of multi-echo acquisition and research * | `Multi-Echo fMRI A Review of Applications in fMRI Denoising and Analysis of BOLD Signals`_ | Kundu et al, NeuroImage 2017 | A review of multi-echo denoising with a focus on the MEICA algorithm