From b8b458a777e5e736766dce59a8400fb6d6c93d7d Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Mon, 17 Feb 2020 08:45:49 -0500 Subject: [PATCH 01/11] Fix typos. --- docs/approach.rst | 76 +++++++++++------------ docs/considerations.rst | 130 ++++++++++++++++++++-------------------- docs/multi-echo.rst | 77 ++++++++++++------------ 3 files changed, 141 insertions(+), 142 deletions(-) diff --git a/docs/approach.rst b/docs/approach.rst index 650796a9a..05d888ce8 100644 --- a/docs/approach.rst +++ b/docs/approach.rst @@ -1,7 +1,7 @@ The tedana pipeline =================== -``tedana`` works by decomposing multi-echo BOLD data via priniciple component analysis (PCA) +``tedana`` works by decomposing multi-echo BOLD data via principal component analysis (PCA) and independent component analysis (ICA). The resulting components are then analyzed to determine whether they are TE-dependent or -independent. @@ -67,11 +67,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 @@ -90,10 +90,10 @@ The echo times are also multiplied by -1. .. note:: - It is now possible to do a nonlinear monoexponential fit to the original, untransformed - data values by specifiying ``--fittype curvefit``. + 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. + accurate fits. .. image:: /_static/a04_echo_log_value_distributions.png @@ -150,14 +150,14 @@ For the example voxel, the resulting weights are: :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. +of the higher signal in earlier echoes and the higher sensitivity at later echoes. The distribution of values for the optimally combined data lands somewhere 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** `Optimal combination code`_ @@ -180,19 +180,19 @@ This optimally combined data is written out as **ts_OC.nii.gz** 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 dimensionality of the -optimally combined data using `Principal Components Analysis (PCA)`_ and then an `Independent Components Analysis (ICA)`_. +The next step is an attempt to remove noise from the data. +This process can be +broadly separated into three steps: **decomposition**, **metric calculation** and +**component selection**. +Decomposition reduces the dimensionality of the +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 +TE-dependence or independence 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. +or discarded. +Unwanted components are then removed from the optimally combined data +to produce the denoised data output. TEDPCA `````` @@ -216,11 +216,11 @@ 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. -For a more thorough explanation of this approach, consider the supplemental information -in `Kundu et al (2013)`_ +TE-independent (i.e., have low Rho). +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 @@ -238,20 +238,20 @@ 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 of -independent timeseries (saved as **meica_mix.1D**), as well as beta maps which show -the spatial loading of these components on the brain (**betas_OC.nii.gz**). +order to fit a mixing matrix to the whitened data. +This generates a number of +independent timeseries (saved as **meica_mix.1D**), as well as beta maps which show +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 -of the original, echo-specific data. -This results in echo- and voxel-specific +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 -can be used to determine how the fluctutations (in each component timeseries) change -across the echo times. +The beta values from the linear regression +can be used to determine how the fluctuations (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. @@ -270,14 +270,14 @@ 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 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, +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`. `TEDICA code`_ diff --git a/docs/considerations.rst b/docs/considerations.rst index b4c4c11f8..c95956f71 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 ================================================== @@ -26,53 +26,53 @@ 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. -Weighted Averaging may lead to an increase in 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 calculated in several software packages including AFNI, +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. +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. +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. +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. +signal vs noise, such as scanner based drifts vs slow changes in BOLD signal. More powerful methods are -still being improved, and associated algorithms are still being actively developed. +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. +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. +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. +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. +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 ------------------------------------------ The developers of ``tedana`` strongly support always examining data for quality concerns, whether or not multi-echo fMRI is used. -Multi-echo data and denoising are no exception. +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. +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 @@ -87,7 +87,7 @@ Choose sequence parameters that meet the priorities of a study with regards to s spatial coverage, sample rate, signal-to-noise ratio, signal drop-out, distortion, and artifacts. A minimum of 3 echoes is required for running the current implementation fo TE-dependent denoising in -``tedana``. +``tedana``. 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. @@ -108,8 +108,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 recommendations 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 @@ -118,9 +118,9 @@ and guidelines are discussed in the `appendix`_ of Dipasquale et al, 2017. .. _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. +.. 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 @@ -137,17 +137,17 @@ Journal articles * | `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`_ +* | `Enhanced identification of BOLD-like components 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`_ +* | `Comparing resting state fMRI de-noising approaches using multi- and single-echo acquisitions`_ | Dipasquale et al, PLoS One 2017 - | The appendix includes some recommendations for multi-echo acqusition + | The appendix includes some recommendations for multi-echo acquisition .. _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 +.. _Enhanced identification of BOLD-like components with MESMS and MEICA: https://www.ncbi.nlm.nih.gov/pubmed/25743045 +.. _Comparing resting state fMRI de-noising approaches using multi- and single-echo acquisitions: https://www.ncbi.nlm.nih.gov/pubmed/28323821 Videos ------ @@ -164,32 +164,32 @@ Videos 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 -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 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 single-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 +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`_ +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) @@ -198,47 +198,47 @@ Multi-echo preprocessing software tedana requires data that has already been preprocessed for head motion, alignment, etc. -AFNI can process multi-echo data natively as well as apply tedana denoising through the use of +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 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. +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. +Currently SPM and FSL do not natively support multi-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. +``tedana`` represents only one approach to processing multi-echo 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`_: A multi-echo implementation of 'paradigm free mapping', that is detection of neural events in the absence of +a prespecified model. +By leveraging the information present in multi-echo data, changes in relaxation time can be directly estimated 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`_: An alternative approach to separating 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. +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`_: 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/ diff --git a/docs/multi-echo.rst b/docs/multi-echo.rst index 58725899f..8d3664fc6 100644 --- a/docs/multi-echo.rst +++ b/docs/multi-echo.rst @@ -1,9 +1,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, +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 @@ -18,44 +18,44 @@ Because the BOLD signal is known to decay at a set rate, collecting multiple 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 -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 +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 inhomogeneity 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 - + 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)`. +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) 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 +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 separate 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 equivalent +to the inverse of :math:`{T_2^*}`. +We typically observe this change in signal amplitude occurring 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 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)`_. @@ -72,8 +72,8 @@ Among these are the different levels of analysis ME-EPI enables. Specifically, by collecting multi-echo data, researchers are able to: **Compare results across different echoes**: 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 -and compared to one another. +Because multi-echo is composed of multiple single-echo time series, each of these can be analyzed separately +and compared to one another. **Combine the results by weighted averaging**: Rather than analyzing single-echo time series separately, we can combine them into an "optimally combined time series". @@ -81,17 +81,16 @@ 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. -**Denoise the data based on information contained in the echoes**: Collecting multi-echo data allows -access to unique denoising methods. +**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. +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 +``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, as well as additional information only available when looking at signal decay across multiple TEs. 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 - From cd4bbbc89e11458676bfde8c60b36cf7400c9b29 Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Mon, 17 Feb 2020 09:18:40 -0500 Subject: [PATCH 02/11] Miscellaneous doc cleanup. --- docs/approach.rst | 25 +++++----- docs/considerations.rst | 106 ++++++++++++++++++++-------------------- docs/faq.rst | 24 ++++----- docs/multi-echo.rst | 4 +- docs/outputs.rst | 2 +- 5 files changed, 79 insertions(+), 82 deletions(-) diff --git a/docs/approach.rst b/docs/approach.rst index 05d888ce8..a431a6eec 100644 --- a/docs/approach.rst +++ b/docs/approach.rst @@ -13,8 +13,8 @@ and decompose the resulting data into components that can be classified as BOLD or non-BOLD. This is performed in a series of steps, including: -* Principal components analysis -* Independent components analysis +* Principal component analysis +* Independent component analysis * Component classification .. image:: /_static/tedana-workflow.png @@ -181,23 +181,20 @@ This optimally combined data is written out as **ts_OC.nii.gz** Denoising ````````` The next step is an attempt to remove noise from the data. -This process can be -broadly separated into three steps: **decomposition**, **metric calculation** and -**component selection**. -Decomposition reduces the dimensionality of the -optimally combined data using `Principal Components Analysis (PCA)`_ and then an `Independent Components Analysis (ICA)`_. -Metrics which highlights the -TE-dependence or independence are derived from these components. -Component selection -uses these metrics in order to identify components that should be kept in the data -or discarded. +This process can be broadly separated into three steps: **decomposition**, +**metric calculation** and **component selection**. +Decomposition reduces the dimensionality of the optimally combined data using +`principal component analysis (PCA)`_ and then an `independent component analysis (ICA)`_. +Metrics which highlights the TE-dependence or independence 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 -components analysis (PCA). +component 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 @@ -235,7 +232,7 @@ in a dimensionally reduced version of the dataset which is then used in the `TED TEDICA `````` -Next, ``tedana`` applies TE-dependent independent components analysis (ICA) in +Next, ``tedana`` applies TE-dependent independent component 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. diff --git a/docs/considerations.rst b/docs/considerations.rst index c95956f71..51515e4ab 100644 --- a/docs/considerations.rst +++ b/docs/considerations.rst @@ -4,8 +4,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. -The possible costs and benefits of multi-echo fMRI -================================================== +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 @@ -26,7 +26,7 @@ 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. -Weighted Averaging may lead to an increase in 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," @@ -77,7 +77,7 @@ inspected in order to determine the quality of denoising. .. _t2smap: https://tedana.readthedocs.io/en/latest/usage.html#run-t2smap .. _see outputs: https://tedana.readthedocs.io/en/latest/outputs.html -Acquisition Parameter Recommendations +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. @@ -114,10 +114,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 -.. _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. @@ -161,37 +157,44 @@ Videos .. _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 --------------------------------------------------------- +Available multi-echo fMRI sequences +----------------------------------- +Siemens +``````` **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 single-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. +* | 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 single-echo sequence. + | In order to collect multiple echoes, increase number of Contrasts on the + | **Sequence Tab, Part 1** on the MR console. +* | 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 + +GE +`` **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) +* 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`_ +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) +Once logged in, go to Groups > GE Works-in-Progress you can find the description +of the current ATSM (i.e. prototypes). + +.. _GE Collaboration Portal: https://collaborate.mr.gehealthcare.com Multi-echo preprocessing software --------------------------------- @@ -205,7 +208,7 @@ AFNI can process multi-echo data natively as well as apply tedana denoising thro `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`_ +For more details, see the `fmriprep workflows page`_. .. _fmriprep workflows page: https://fmriprep.readthedocs.io/en/stable/workflows.html @@ -215,39 +218,36 @@ Other software that uses multi-echo fMRI ======================================== ``tedana`` represents only one approach to processing multi-echo data. -Currently there are a number of methods that can take advantage of or use the information contain in multi-echo 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 implementation of 'paradigm free mapping', that is detection of neural events in the absence of -a prespecified model. -By leveraging the information present in multi-echo data, changes in relaxation time can be directly estimated and -more events can be detected. For more information, see the `following paper`_. +* | `3dMEPFM`_: A multi-echo implementation of 'paradigm free mapping', that is + | detection of neural events in the absence of a prespecified model. By + | leveraging the information present in multi-echo data, changes in relaxation + | time can be directly estimated and more events can be detected. + | For more information, see the `following paper`_. +* | `Bayesian approach to denoising`_: An alternative approach to separating out + | BOLD and non-BOLD signals within a Bayesian framework is currently under + | development. +* | `Multi-echo Group ICA`_: Current approaches 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. +* | `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. .. _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 separating 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/ - - 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. +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`_ diff --git a/docs/faq.rst b/docs/faq.rst index ff80b6154..7ace84e2f 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -36,11 +36,11 @@ 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 -the citation and visibility of software or methods, visit the `duecredit`_ github. +``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 avoid 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 repository. .. _duecredit: https://github.com/duecredit/duecredit @@ -56,14 +56,14 @@ Multi-echo fMRI 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 per TR. This means that there is no change in the `specific absorbtion rate`_ (SAR) limits -for the participant. +radiofrequency pulse per TR. This means that there is no change in the `specific absorption rate`_ (SAR) limits +for the participant. -.. _specific absorbtion rate: https://www.mr-tip.com/serv1.php?type=db1&dbs=Specific%20Absorption%20Rate +.. _specific absorption 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 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. +Yes, these techniques are complementary. +Multiband fMRI leads to collecting multiple slices within a volume simultaneously, 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 8d3664fc6..f7154e00c 100644 --- a/docs/multi-echo.rst +++ b/docs/multi-echo.rst @@ -1,5 +1,5 @@ -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). This typical approach is known as single-echo fMRI. diff --git a/docs/outputs.rst b/docs/outputs.rst index bddc75aa2..a5cb872c7 100644 --- a/docs/outputs.rst +++ b/docs/outputs.rst @@ -1,5 +1,5 @@ Outputs of tedana -=========================== +================= tedana derivatives ------------------ From 058674520eb63e57ded58045921cce78966364b4 Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Mon, 17 Feb 2020 09:19:31 -0500 Subject: [PATCH 03/11] Fix PCA/ICA links (closes #480). --- docs/approach.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/approach.rst b/docs/approach.rst index a431a6eec..dda538f31 100644 --- a/docs/approach.rst +++ b/docs/approach.rst @@ -191,6 +191,10 @@ should be kept in the data or discarded. Unwanted components are then removed from the optimally combined data to produce the denoised data output. +.. _principal component analysis (PCA): https://en.wikipedia.org/wiki/Principal_component_analysis +.. _independent component Analysis (ICA): https://en.wikipedia.org/wiki/Independent_component_analysis + + TEDPCA `````` The next step is to dimensionally reduce the data with TE-dependent principal From 360c37742f598f3e302e992a7d1bf3819ac6db01 Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Mon, 17 Feb 2020 09:19:46 -0500 Subject: [PATCH 04/11] Remove outdated output from table. --- docs/outputs.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/outputs.rst b/docs/outputs.rst index a5cb872c7..cd586d0bc 100644 --- a/docs/outputs.rst +++ b/docs/outputs.rst @@ -61,9 +61,6 @@ ica_components.nii.gz Component weight maps from ICA decomposition. 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. report.txt A summary report for the workflow with relevant citations. ====================== ===================================================== From 4932ce3a7b5d5ce06a06eec16db5481caeb63a0c Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Tue, 18 Feb 2020 08:03:49 -0500 Subject: [PATCH 05/11] Move acquisition-related sections to one page. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Also, move considerations into multi-echo page, move resources from considerations into new “resources” page, and move publications into new “acquisition” page. --- docs/acquisition.rst | 141 +++++++++++++++++++++ docs/considerations.rst | 262 ---------------------------------------- docs/index.rst | 6 +- docs/multi-echo.rst | 80 +++++++++++- docs/publications.rst | 56 --------- docs/resources.rst | 102 ++++++++++++++++ 6 files changed, 325 insertions(+), 322 deletions(-) create mode 100644 docs/acquisition.rst delete mode 100644 docs/considerations.rst delete mode 100644 docs/publications.rst create mode 100644 docs/resources.rst diff --git a/docs/acquisition.rst b/docs/acquisition.rst new file mode 100644 index 000000000..fae238897 --- /dev/null +++ b/docs/acquisition.rst @@ -0,0 +1,141 @@ +Acquiring multi-echo data +========================= + +Available multi-echo fMRI sequences +----------------------------------- + +Siemens +``````` +**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 single-echo sequence. + | In order to collect multiple echoes, increase number of Contrasts on the + | **Sequence Tab, Part 1** on the MR console. +* | 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 + +GE +`` +**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). + +.. _GE Collaboration Portal: https://collaborate.mr.gehealthcare.com + +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 required for running the current implementation fo TE-dependent denoising in +``tedana``. +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 +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 recommendations +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 + +.. 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 + +.. _spreadsheet of publications: + +ME-fMRI parameters and 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. + +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 + # 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) + 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', 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 + + + +.. _here: https://docs.google.com/spreadsheets/d/1WERojJyxFoqcg_tndUm5Kj0H1UfUc9Ban0jFGGfPaBk/edit#gid=0 diff --git a/docs/considerations.rst b/docs/considerations.rst deleted file mode 100644 index 51515e4ab..000000000 --- a/docs/considerations.rst +++ /dev/null @@ -1,262 +0,0 @@ -########################## -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. - -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. -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. - -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 -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. -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. - -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 -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 ------------------------------------------- -The developers of ``tedana`` strongly support always examining data for quality concerns, whether -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 - -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 required for running the current implementation fo TE-dependent denoising in -``tedana``. -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 -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 recommendations -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 - -.. 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 components 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 acquisitions`_ - | Dipasquale et al, PLoS One 2017 - | The appendix includes some recommendations for multi-echo acquisition - -.. _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 components with MESMS and MEICA: https://www.ncbi.nlm.nih.gov/pubmed/25743045 -.. _Comparing resting state fMRI de-noising approaches using multi- and single-echo acquisitions: 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 ------------------------------------ - -Siemens -``````` -**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 single-echo sequence. - | In order to collect multiple echoes, increase number of Contrasts on the - | **Sequence Tab, Part 1** on the MR console. -* | 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 - -GE -`` -**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). - -.. _GE Collaboration Portal: https://collaborate.mr.gehealthcare.com - -Multi-echo preprocessing software ---------------------------------- - -tedana requires data that has already been preprocessed for head motion, alignment, etc. - -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 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`_. - -.. _fmriprep workflows page: https://fmriprep.readthedocs.io/en/stable/workflows.html - -Currently SPM and FSL do not natively support multi-echo fmri data processing. - -Other software that uses multi-echo fMRI -======================================== - -``tedana`` represents only one approach to processing multi-echo 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 implementation of 'paradigm free mapping', that is - | detection of neural events in the absence of a prespecified model. By - | leveraging the information present in multi-echo data, changes in relaxation - | time can be directly estimated and more events can be detected. - | For more information, see the `following paper`_. -* | `Bayesian approach to denoising`_: An alternative approach to separating out - | BOLD and non-BOLD signals within a Bayesian framework is currently under - | development. -* | `Multi-echo Group ICA`_: Current approaches 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. -* | `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. - -.. _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: https://ww5.aievolution.com/hbm1901/index.cfm?do=abs.viewAbs&abs=5026 -.. _Multi-echo Group ICA: https://ww5.aievolution.com/hbm1901/index.cfm?do=abs.viewAbs&abs=1286 -.. _Dual Echo Denoising: https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3518782/ - -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 2cf2bc8cd..edc3b2e41 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -141,11 +141,11 @@ tedana is licensed under GNU Lesser General Public License version 2.1. .. toctree:: :maxdepth: 2 :caption: Contents: - + installation multi-echo - considerations - publications + acquisition + resources usage approach outputs diff --git a/docs/multi-echo.rst b/docs/multi-echo.rst index f7154e00c..169e0beaa 100644 --- a/docs/multi-echo.rst +++ b/docs/multi-echo.rst @@ -60,11 +60,11 @@ 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)`_. - .. _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://www.sciencedirect.com/science/article/pii/S1053811917302410?via%3Dihub + Why use multi-echo? ------------------- There are many potential reasons an investigator would be interested in using multi-echo EPI (ME-EPI). @@ -94,3 +94,81 @@ 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 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. + +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. +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. + +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 +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. +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. + +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 +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 +`````````````````````````````````````````` +The developers of ``tedana`` strongly support always examining data for quality concerns, whether +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 diff --git a/docs/publications.rst b/docs/publications.rst deleted file mode 100644 index ece4b3c84..000000000 --- a/docs/publications.rst +++ /dev/null @@ -1,56 +0,0 @@ -.. _spreadsheet of publications: - -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. - -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 - # 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) - 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', 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 - - - -.. _here: https://docs.google.com/spreadsheets/d/1WERojJyxFoqcg_tndUm5Kj0H1UfUc9Ban0jFGGfPaBk/edit#gid=0 \ No newline at end of file diff --git a/docs/resources.rst b/docs/resources.rst new file mode 100644 index 000000000..c0eded7ae --- /dev/null +++ b/docs/resources.rst @@ -0,0 +1,102 @@ +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 components 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 acquisitions`_ + | Dipasquale et al, PLoS One 2017 + | The appendix includes some recommendations for multi-echo acquisition + +.. _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 components with MESMS and MEICA: https://www.ncbi.nlm.nih.gov/pubmed/25743045 +.. _Comparing resting state fMRI de-noising approaches using multi- and single-echo acquisitions: 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 + + +Multi-echo preprocessing software +--------------------------------- + +tedana requires data that has already been preprocessed for head motion, alignment, etc. + +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 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`_. + +.. _fmriprep workflows page: https://fmriprep.readthedocs.io/en/stable/workflows.html + +Currently SPM and FSL do not natively support multi-echo fmri data processing. + +Other software that uses multi-echo fMRI +---------------------------------------- + +``tedana`` represents only one approach to processing multi-echo 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 implementation of 'paradigm free mapping', that is + | detection of neural events in the absence of a prespecified model. By + | leveraging the information present in multi-echo data, changes in relaxation + | time can be directly estimated and more events can be detected. + | For more information, see the `following paper`_. +* | `Bayesian approach to denoising`_: An alternative approach to separating out + | BOLD and non-BOLD signals within a Bayesian framework is currently under + | development. +* | `Multi-echo Group ICA`_: Current approaches 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. +* | `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. + +.. _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: https://ww5.aievolution.com/hbm1901/index.cfm?do=abs.viewAbs&abs=5026 +.. _Multi-echo Group ICA: https://ww5.aievolution.com/hbm1901/index.cfm?do=abs.viewAbs&abs=1286 +.. _Dual Echo Denoising: https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3518782/ + +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 c9fc7942dedd499752669f7a228f674754d54175 Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Tue, 18 Feb 2020 08:49:05 -0500 Subject: [PATCH 06/11] Add info about quantitative T2* mapping (closes #464). --- docs/acquisition.rst | 23 +++++++++++++++++++++-- docs/resources.rst | 7 ++++++- 2 files changed, 27 insertions(+), 3 deletions(-) diff --git a/docs/acquisition.rst b/docs/acquisition.rst index fae238897..278c5aa1f 100644 --- a/docs/acquisition.rst +++ b/docs/acquisition.rst @@ -40,9 +40,28 @@ of the current ATSM (i.e. prototypes). .. _GE Collaboration Portal: https://collaborate.mr.gehealthcare.com +Other available multi-echo MRI sequences +---------------------------------------- + +In addition to ME-fMRI, many other MR sequences benefit from acquiring multiple +echoes, including T1-weighted imaging (MEMPRAGE) and susceptibility weighted imaging. +While most of these kinds of sequences fall outside the purview of this documentation, +we do want to document sequences for quantitative T2* mapping. +Estimation of T2* and S0 from ME-fMRI data is inherently noisy, given the +relatively low spatial resolution of EPI data and the limited number of echoes +that can be acquired while maintaining reasonable temporal resolution. +As such, ``tedana`` allows users to provide a T2* map as input to the workflow, +which means that it may be beneficial to acquire a quantitative T2* map if you +are also acquiring ME-fMRI data. + +Quantitative T2* mapping can be done with a multi-echo GRE sequence, such as a +multi-echo FLASH stock sequence, with a large number of echoes (e.g., 12). +When acquiring such a scan, it is best to reconstruct both magnitude and phase data. + + Acquisition parameter recommendations ------------------------------------- -There is no empirically tested best parameter set for multi-echo acquisition. +There is no empirically tested best parameter set for multi-echo fMRI 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. @@ -88,7 +107,7 @@ and guidelines are discussed in the `appendix`_ of Dipasquale et al, 2017. ME-fMRI parameters and publications ----------------------------------- -The following page highlights a selection of parameters collected from published papers that have +The following section 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, diff --git a/docs/resources.rst b/docs/resources.rst index c0eded7ae..e6210395d 100644 --- a/docs/resources.rst +++ b/docs/resources.rst @@ -59,7 +59,7 @@ Other software that uses multi-echo fMRI ``tedana`` represents only one approach to processing multi-echo data. Currently there are a number of methods that can take advantage of or use the -information contain in multi-echo data. +information contained in multi-echo data. These include: * | `3dMEPFM`_: A multi-echo implementation of 'paradigm free mapping', that is @@ -77,12 +77,17 @@ These include: * | `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. +* | `qMRLab`_: This is a MATLAB software package for quantitative magnetic + | resonance imaging. While it does not support ME-fMRI, it does include methods + | for estimating T2*/S0 from high-resolution, complex-valued multi-echo GRE + | data with correction for background field gradients. .. _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: https://ww5.aievolution.com/hbm1901/index.cfm?do=abs.viewAbs&abs=5026 .. _Multi-echo Group ICA: https://ww5.aievolution.com/hbm1901/index.cfm?do=abs.viewAbs&abs=1286 .. _Dual Echo Denoising: https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3518782/ +.. _qMRLab: https://github.com/qMRLab/qMRLab Datasets -------- From 1180ccbdf9929a8c896ccae93e2988a1aa94809e Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Thu, 20 Feb 2020 08:28:46 -0500 Subject: [PATCH 07/11] Add link to ME-fMRI sequences OSF project. --- docs/acquisition.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/acquisition.rst b/docs/acquisition.rst index 278c5aa1f..55374144d 100644 --- a/docs/acquisition.rst +++ b/docs/acquisition.rst @@ -4,6 +4,13 @@ Acquiring multi-echo data Available multi-echo fMRI sequences ----------------------------------- +We have attempted to compile some basic multi-echo fMRI protocols in an `OSF project`_. +These protocols should not be considered "canonical". +If you would like to use one of them, please customize it for your own purposes +and make sure to pilot it before using it in a study. + +.. _OSF project: https://osf.io/ebkrp/ + Siemens ``````` **For Siemens** users, there are two options for Works In Progress (WIPs) Sequences. From 4397d776b7491bd172a997abce5261aa62f281fe Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Thu, 20 Feb 2020 09:14:29 -0500 Subject: [PATCH 08/11] Address review. --- docs/acquisition.rst | 29 ++++++++++++----------------- docs/conf.py | 6 ++++-- docs/developing.rst | 5 +++-- docs/index.rst | 6 ++++++ docs/resources.rst | 39 +++++++++++++++++++++++++-------------- docs/usage.rst | 18 +++++++++--------- 6 files changed, 59 insertions(+), 44 deletions(-) diff --git a/docs/acquisition.rst b/docs/acquisition.rst index 55374144d..7fa99a451 100644 --- a/docs/acquisition.rst +++ b/docs/acquisition.rst @@ -30,6 +30,7 @@ Siemens .. _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 `` **For GE users**, there are currently two sharable pulse sequences: @@ -47,9 +48,9 @@ of the current ATSM (i.e. prototypes). .. _GE Collaboration Portal: https://collaborate.mr.gehealthcare.com + Other available multi-echo MRI sequences ---------------------------------------- - In addition to ME-fMRI, many other MR sequences benefit from acquiring multiple echoes, including T1-weighted imaging (MEMPRAGE) and susceptibility weighted imaging. While most of these kinds of sequences fall outside the purview of this documentation, @@ -61,6 +62,11 @@ As such, ``tedana`` allows users to provide a T2* map as input to the workflow, which means that it may be beneficial to acquire a quantitative T2* map if you are also acquiring ME-fMRI data. +.. warning:: + While tedana allows the input of a T2* map from any source, and a more + accurate T2* map should lead to better results, this hasn't been + systematically evaluated yet. + Quantitative T2* mapping can be done with a multi-echo GRE sequence, such as a multi-echo FLASH stock sequence, with a large number of echoes (e.g., 12). When acquiring such a scan, it is best to reconstruct both magnitude and phase data. @@ -106,19 +112,16 @@ and guidelines are discussed in the `appendix`_ of Dipasquale et al, 2017. .. 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 + For typically used parameters see the **ME-fMRI parameters** section below. -.. _spreadsheet of publications: -ME-fMRI parameters and publications ------------------------------------ +.. _common multi-echo parameters: +ME-fMRI parameters +------------------ The following section 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. +You can see the spreadsheet of publications at :ref:`spreadsheet of publications`. The following plots reflect the average values for studies conducted at 3 Tesla. @@ -157,11 +160,3 @@ The following plots reflect the average values for studies conducted at 3 Tesla. plt.xlabel('Average Voxel dimension (mm)') plt.ylabel('Count') plt.show() - -You can view and suggest additions to this spreadsheet `here`_ - -.. raw:: html - - - -.. _here: https://docs.google.com/spreadsheets/d/1WERojJyxFoqcg_tndUm5Kj0H1UfUc9Ban0jFGGfPaBk/edit#gid=0 diff --git a/docs/conf.py b/docs/conf.py index aa4eb12eb..081fd9e78 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -114,8 +114,10 @@ # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. -# -# html_theme_options = {} + +html_theme_options = { + 'includehidden': False, +} # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, diff --git a/docs/developing.rst b/docs/developing.rst index 32900cbb4..1cb47cc46 100644 --- a/docs/developing.rst +++ b/docs/developing.rst @@ -69,7 +69,7 @@ To write the test function you can follow the model of our `five echo set`_, whi actual output. (4) If you need to upload new data, you will need to contact the maintainers and ask them to either add -it to `OSF`_ or give you permission to add it. +it to the `tedana OSF project`_ or give you permission to add it. (5) Once you've tested your integration test locally and it is working, you will need to add it to the CircleCI config and the ``Makefile``. @@ -138,7 +138,7 @@ We should see that our unit test is successful via .. code-block:: bash pytest $TEDANADIR/tedana/tests/test_io.py -k test_say_hello - + If not, we should continue editing the function until it passes our test. Let's suppose that suddenly, you realize that what would be even more useful is a function that takes an argument, ``place``, so that the output filename is actually ``hello_PLACE``, with @@ -208,6 +208,7 @@ We should then do the following cleanup with our git repository: and we're good to go! +.. _`tedana OSF project`: https://osf.io/bpe8h/ .. _git: https://git-scm.com/ .. _`git pro`: https://git-scm.com/book/en/v2 .. _repository: https://github.com/ME-ICA/tedana diff --git a/docs/index.rst b/docs/index.rst index edc3b2e41..ab15727a9 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -156,6 +156,12 @@ tedana is licensed under GNU Lesser General Public License version 2.1. roadmap api +.. toctree:: + :hidden: + :name: hiddentoc + + dependence_metrics + Indices and tables ------------------ diff --git a/docs/resources.rst b/docs/resources.rst index e6210395d..3879374c4 100644 --- a/docs/resources.rst +++ b/docs/resources.rst @@ -1,22 +1,22 @@ Resources ========= -Journal articles ----------------- +Journal articles describing multi-echo methods +---------------------------------------------- * | :ref:`spreadsheet of publications` catalogues papers using multi-echo fMRI, - with information about acquisition parameters. + | 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 + | Kundu et al, NeuroImage 2017 + | A review of multi-echo denoising with a focus on the MEICA algorithm * | `Enhanced identification of BOLD-like components with MESMS and MEICA`_ - | Olafsson et al, NeuroImage 2015 - | The appendix includes a good explanation of the math underlying MEICA denoising + | 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 acquisitions`_ - | Dipasquale et al, PLoS One 2017 - | The appendix includes some recommendations for multi-echo acquisition + | Dipasquale et al, PLoS One 2017 + | The appendix includes some recommendations for multi-echo acquisition .. _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 @@ -35,10 +35,8 @@ Videos .. _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 - Multi-echo preprocessing software --------------------------------- - tedana requires data that has already been preprocessed for head motion, alignment, etc. AFNI can process multi-echo data natively as well as apply tedana denoising through the use of @@ -56,7 +54,6 @@ Currently SPM and FSL do not natively support multi-echo fmri data processing. Other software that uses multi-echo fMRI ---------------------------------------- - ``tedana`` represents only one approach to processing multi-echo data. Currently there are a number of methods that can take advantage of or use the information contained in multi-echo data. @@ -105,3 +102,17 @@ This list is not necessarily up to date, so please check out OpenNeuro to potent .. _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/ + +.. _spreadsheet of publications: + +Publications using multi-echo fMRI +---------------------------------- +You can view and suggest additions to this spreadsheet `here`_ +This is a volunteer-led effort so, if you know of a excluded publication, whether or not it is yours, +please add it. + +.. raw:: html + + + +.. _here: https://docs.google.com/spreadsheets/d/1WERojJyxFoqcg_tndUm5Kj0H1UfUc9Ban0jFGGfPaBk/edit#gid=0 diff --git a/docs/usage.rst b/docs/usage.rst index c82541300..8ce67dfc3 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -1,4 +1,4 @@ -tedana Usage +Using tedana ============ ``tedana`` minimally requires: @@ -20,8 +20,8 @@ for recommendations on doing so, see our general guidelines for .. _fMRIPrep: https://fmriprep.readthedocs.io .. _afni_proc.py: https://afni.nimh.nih.gov/pub/dist/doc/program_help/afni_proc.py.html -Run tedana ----------- +Running tedana +-------------- This is the full tedana workflow, which runs multi-echo ICA and outputs multi-echo denoised data along with many other derivatives. To see which files are generated by this workflow, check out the outputs page: @@ -34,15 +34,15 @@ https://tedana.readthedocs.io/en/latest/outputs.html .. note:: The ``--mask`` argument is not intended for use with very conservative region-of-interest - analyses. + 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. + workflow. To examine regions-of-interest with multi-echo data, apply masks after TE Dependent ANAlysis. -Run t2smap ----------- +Running t2smap +-------------- This workflow uses multi-echo data to optimally combine data across echoes and to estimate T2* and S0 maps or time series. To see which files are generated by this workflow, check out the workflow @@ -93,9 +93,9 @@ 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. -.. note:: +.. note:: Any intensity normalization or nuisance regressors should be applied to the data - *after* ``tedana`` calculates the BOLD and non-BOLD weighting of components. + *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, From 5bfd6ba0bb4782a88883fac5526cf52ee50777a3 Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Thu, 20 Feb 2020 09:19:55 -0500 Subject: [PATCH 09/11] Add @handwerkerd's recommendation for the protocols. --- docs/acquisition.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/acquisition.rst b/docs/acquisition.rst index 7fa99a451..6522f46e9 100644 --- a/docs/acquisition.rst +++ b/docs/acquisition.rst @@ -5,9 +5,12 @@ Available multi-echo fMRI sequences ----------------------------------- We have attempted to compile some basic multi-echo fMRI protocols in an `OSF project`_. -These protocols should not be considered "canonical". +The parameter choices in these protocols run and seem reasonable, but they have +not been optimized for a specific situation. +They are a good starting point for someone designing a study, but should not be +considered canonical. If you would like to use one of them, please customize it for your own purposes -and make sure to pilot it before using it in a study. +and make sure to run pilot scans to test your choices. .. _OSF project: https://osf.io/ebkrp/ From 491e1fbca651d6f1866ebdd5ebfef920bce8a929 Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Thu, 20 Feb 2020 12:42:48 -0500 Subject: [PATCH 10/11] Add @handwerkerd's text about T2* mapping. --- docs/acquisition.rst | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/docs/acquisition.rst b/docs/acquisition.rst index 6522f46e9..0f33eea8b 100644 --- a/docs/acquisition.rst +++ b/docs/acquisition.rst @@ -3,7 +3,6 @@ Acquiring multi-echo data Available multi-echo fMRI sequences ----------------------------------- - We have attempted to compile some basic multi-echo fMRI protocols in an `OSF project`_. The parameter choices in these protocols run and seem reasonable, but they have not been optimized for a specific situation. @@ -54,25 +53,29 @@ of the current ATSM (i.e. prototypes). Other available multi-echo MRI sequences ---------------------------------------- -In addition to ME-fMRI, many other MR sequences benefit from acquiring multiple +In addition to ME-fMRI, other MR sequences benefit from acquiring multiple echoes, including T1-weighted imaging (MEMPRAGE) and susceptibility weighted imaging. While most of these kinds of sequences fall outside the purview of this documentation, -we do want to document sequences for quantitative T2* mapping. -Estimation of T2* and S0 from ME-fMRI data is inherently noisy, given the -relatively low spatial resolution of EPI data and the limited number of echoes -that can be acquired while maintaining reasonable temporal resolution. -As such, ``tedana`` allows users to provide a T2* map as input to the workflow, -which means that it may be beneficial to acquire a quantitative T2* map if you -are also acquiring ME-fMRI data. +quantitative T2* mapping is relevant since a baseline T2* map is used in several +processing steps including :ref:`optimal combination`. +While the T2* map estimated directly from fMRI time series is noisy, no current +study quantifies the benefit to optimal combination or tedana denoising if a +higher quality T2* map is used. +Some benefit is likely, so, if a T2* map is independently calculated, it can be +used as an input to many functions in the tedana workflow. .. warning:: While tedana allows the input of a T2* map from any source, and a more accurate T2* map should lead to better results, this hasn't been systematically evaluated yet. -Quantitative T2* mapping can be done with a multi-echo GRE sequence, such as a -multi-echo FLASH stock sequence, with a large number of echoes (e.g., 12). -When acquiring such a scan, it is best to reconstruct both magnitude and phase data. +There are many ways to calculate T2* maps, with some using multi-echo acquisitions. +We are not presenting an expansive review of this literature here, +but Cohen-Adad et al. (2012) and Ruuth et al. (2019) are good places to start +learning more about this topic. + +.. _Cohen-Adad et al. (2012): https://doi.org/10.1016/j.neuroimage.2012.01.053 +.. _Ruuth et al. (2019): https://doi.org/10.1016/j.ejro.2018.12.006 Acquisition parameter recommendations From 943136285b19c5fac2a26c7d9872f126d13e101b Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Thu, 20 Feb 2020 16:28:35 -0500 Subject: [PATCH 11/11] Fix links. --- docs/acquisition.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/acquisition.rst b/docs/acquisition.rst index 0f33eea8b..ac4344cce 100644 --- a/docs/acquisition.rst +++ b/docs/acquisition.rst @@ -71,7 +71,7 @@ used as an input to many functions in the tedana workflow. There are many ways to calculate T2* maps, with some using multi-echo acquisitions. We are not presenting an expansive review of this literature here, -but Cohen-Adad et al. (2012) and Ruuth et al. (2019) are good places to start +but `Cohen-Adad et al. (2012)`_ and `Ruuth et al. (2019)`_ are good places to start learning more about this topic. .. _Cohen-Adad et al. (2012): https://doi.org/10.1016/j.neuroimage.2012.01.053