diff --git a/.gitignore b/.gitignore index af64fb138..41e4de67c 100644 --- a/.gitignore +++ b/.gitignore @@ -104,4 +104,4 @@ ENV/ .mypy_cache/ # vscode -.vscode +.vscode \ No newline at end of file diff --git a/docs/_static/physics_kundu_2017_TE_dependence.jpg b/docs/_static/physics_kundu_2017_TE_dependence.jpg new file mode 100644 index 000000000..265bbbcc0 Binary files /dev/null and b/docs/_static/physics_kundu_2017_TE_dependence.jpg differ diff --git a/docs/_static/physics_kundu_2017_multiple_echoes.jpg b/docs/_static/physics_kundu_2017_multiple_echoes.jpg new file mode 100644 index 000000000..6a1fe3a95 Binary files /dev/null and b/docs/_static/physics_kundu_2017_multiple_echoes.jpg differ diff --git a/docs/approach.rst b/docs/approach.rst index 7ac9803ec..650796a9a 100644 --- a/docs/approach.rst +++ b/docs/approach.rst @@ -1,7 +1,8 @@ -Processing pipeline details -=========================== +The tedana pipeline +=================== -``tedana`` works by decomposing multi-echo BOLD data via PCA and ICA. +``tedana`` works by decomposing multi-echo BOLD data via priniciple component analysis (PCA) +and independent component analysis (ICA). The resulting components are then analyzed to determine whether they are TE-dependent or -independent. TE-dependent components are classified as BOLD, while TE-independent components @@ -23,7 +24,7 @@ Multi-echo data ``````````````` Here are the echo-specific time series for a single voxel in an example -resting-state scan with 5 echoes. +resting-state scan with 8 echoes. .. image:: /_static/a01_echo_timeseries.png @@ -45,6 +46,10 @@ When :math:`T_{2}^*` and :math:`S_{0}` are calculated below, each voxel's values are only calculated from the first :math:`n` echoes, where :math:`n` is the value for that voxel in the adaptive mask. +`Adaptive mask code`_ + +.. _Adaptive mask code: https://tedana.readthedocs.io/en/latest/generated/tedana.utils.make_adaptive_mask.html#tedana.utils.make_adaptive_mask + .. note:: ``tedana`` allows users to provide their own mask. The adaptive mask will be computed on this explicit mask, and may reduce @@ -62,7 +67,12 @@ value for that voxel in the adaptive mask. Monoexponential decay model fit ``````````````````````````````` The next step is to fit a monoexponential decay model to the data in order to -estimate voxel-wise :math:`T_{2}^*` and :math:`S_0`. +estimate voxel-wise :math:`T_{2}^*` and :math:`S_0`. +:math:`S_0` corresponds to the total signal in each voxel before decay and can reflect coil sensivity. +:math:`T_{2}^*` corresponds to the rate at which a voxel decays over time, which +is related to signal dropout and BOLD sensitivity. +Estimates of the parameters are saved as **t2sv.nii.gz** and **s0v.nii.gz**. + While :math:`T_{2}^*` and :math:`S_0` in fact fluctuate over time, estimating them on a volume-by-volume basis with only a small number of echoes is not feasible (i.e., the estimates would be extremely noisy). @@ -70,15 +80,26 @@ As such, we estimate average :math:`T_{2}^*` and :math:`S_0` maps and use those throughout the workflow. In order to make it easier to fit the decay model to the data, ``tedana`` -transforms the data. +transforms the data by default. The BOLD data are transformed as :math:`log(|S|+1)`, where :math:`S` is the BOLD signal. The echo times are also multiplied by -1. +`Decay model fit code`_ + +.. _Decay model fit code: https://tedana.readthedocs.io/en/latest/generated/tedana.decay.fit_decay.html#tedana.decay.fit_decay + + +.. note:: + It is now possible to do a nonlinear monoexponential fit to the original, untransformed + data values by specifiying ``--fittype curvefit``. + This method is slightly more computationally demanding but may obtain more + accurate fits. + .. image:: /_static/a04_echo_log_value_distributions.png A simple line can then be fit to the transformed data with linear regression. For the sake of this introduction, we can assume that the example voxel has -good signal in all five echoes (i.e., the adaptive mask has a value of 5 at +good signal in all eight echoes (i.e., the adaptive mask has a value of 8 at this voxel), so the line is fit to all available data. .. note:: @@ -128,13 +149,21 @@ For the example voxel, the resulting weights are: :width: 400 px :align: center +These normalized weights are then used to compute a weighted average that takes advantage +of the higher signal in earlier echoes and the heigher sensitivty at later echoes. The distribution of values for the optimally combined data lands somewhere between the distributions for other echoes. .. 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`_ + +.. _Optimal combination code: https://tedana.readthedocs.io/en/latest/generated/tedana.combine.make_optcom.html#tedana.combine.make_optcom + .. image:: /_static/a10_optimal_combination_timeseries.png @@ -149,6 +178,22 @@ of the other echoes (which it is). We do, however, make it accessible as an alternative combination method in the t2smap workflow. +Denoising +````````` +The next step is an attempt to remove noise from the data. +This process can be +broadly seperated into three steps: **decomposition**, **metric calculation** and +**component selection**. +Decomposition reduces the 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 +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 @@ -156,7 +201,7 @@ components analysis (PCA). The goal of this step is to make it easier for the later ICA decomposition to converge. Dimensionality reduction is a common step prior to ICA. TEDPCA applies PCA to the optimally combined data in order to decompose it into component maps and -time series. +time series (saved as **mepca_mix.1D**). Here we can see time series for some example components (we don't really care about the maps): .. image:: /_static/a11_pca_component_timeseries.png @@ -165,48 +210,58 @@ These components are subjected to component selection, the specifics of which vary according to algorithm. In the simplest approach, ``tedana`` uses Minka’s MLE to estimate the -dimensionality of the data, which disregards low-variance components. +dimensionality of the data, which disregards low-variance components (the `mle` option in for `--tedpca`). -A more complicated approach involves applying a decision tree to identify and +A more complicated approach involves applying a decision tree (similar to the +decision tree described in the TEDICA section below) to identify and discard PCA components which, in addition to not explaining much variance, are also not significantly TE-dependent (i.e., have low Kappa) or -TE-independent (i.e., have low Rho). - -.. note:: - This process (also performed in TEDICA) can be broadly separated into three - steps: decomposition, metric calculation, and component selection. - Decomposition identifies components in the data. - Metric calculation derives relevant summary statistics for each component. - Component selection uses the summary statistics to identify components that - should be kept or discarded. +TE-independent (i.e., have low Rho). +These approaches can be accessed using either the `kundu` or `kundu_stabilize` +options for the `--tedpca` flag. +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 -in a dimensionally reduced version of the dataset. +in a dimensionally reduced version of the dataset which is then used in the `TEDICA` step. .. image:: /_static/a12_pca_reduced_data.png +`TEDPCA code`_ + +.. _TEDPCA code: https://tedana.readthedocs.io/en/latest/generated/tedana.decomposition.tedpca.html#tedana.decomposition.tedpca + + TEDICA `````` Next, ``tedana`` applies TE-dependent independent components analysis (ICA) in order to identify and remove TE-independent (i.e., non-BOLD noise) components. The dimensionally reduced optimally combined data are first subjected to ICA in -order to fit a mixing matrix to the whitened data. +order to fit a mixing matrix to the whitened data. +This generates a number 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 -echo from the original, echo-specific data. -This way, low-variance information (originally discarded by TEDPCA) is retained -in the data, but is ignored by the TEDICA process. -This results in echo- and voxel-specific betas for each of the components. - -TE-dependence (:math:`R_2`) and TE-independence (:math:`S_0`) models can then +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. + +TE-dependence (:math:`R_2` or :math:`1/T_{2}^*`) and TE-independence (:math:`S_0`) models can then be fit to these betas. For more information on how these models are estimated, see :ref:`dependence models`. These models allow calculation of F-statistics for the :math:`R_2` and :math:`S_0` models (referred to as :math:`\kappa` and :math:`\rho`, respectively). +The grey lines show how beta values (Parameter Estimates) change over time. Refer the the +`physics section`_ :math:`{\Delta}{S_0}` for more information about the :math:`S_0` and :math:`T_2^*` models. + .. image:: /_static/a14_te_dependence_models_component_0.png .. image:: /_static/a14_te_dependence_models_component_1.png @@ -215,11 +270,20 @@ models (referred to as :math:`\kappa` and :math:`\rho`, respectively). A decision tree is applied to :math:`\kappa`, :math:`\rho`, and other metrics in order to classify ICA components as TE-dependent (BOLD signal), TE-independent -(non-BOLD noise), or neither (to be ignored). +(non-BOLD noise), or neither (to be ignored). +These classifications are saved in +`comp_table_ica.txt`. The actual decision tree is dependent on the component selection algorithm employed. -``tedana`` includes two options: `kundu_v2_5` (which uses hardcoded thresholds -applied to each of the metrics) and `kundu_v3_2` (which trains a classifier to -select components). +``tedana`` includes the option `kundu` (which uses hardcoded thresholds +applied to each of the metrics). + +Components that are classified as noise are projected out of the optimally combined data, +yielding a denoised timeseries, which is saved as `dn_ts_OC.nii.gz`. + +`TEDICA code`_ + +.. _TEDICA code: https://tedana.readthedocs.io/en/latest/generated/tedana.decomposition.tedica.html#tedana.decomposition.tedica + .. image:: /_static/a15_denoised_data_timeseries.png @@ -237,8 +301,15 @@ regression (GSR), T1c-GSR, anatomical CompCor, Go Decomposition (GODEC), and robust PCA. Currently, ``tedana`` implements GSR and T1c-GSR. +`Global signal control code`_ + +.. _Global signal control code: https://tedana.readthedocs.io/en/latest/generated/tedana.gscontrol.gscontrol_mmix.html#tedana.gscontrol.gscontrol_mmix + .. image:: /_static/a16_t1c_denoised_data_timeseries.png .. _nilearn.masking.compute_epi_mask: https://nilearn.github.io/modules/generated/nilearn.masking.compute_epi_mask.html .. _Power et al. (2018): http://www.pnas.org/content/early/2018/02/07/1720985115.short .. _Poser et al., 2006: https://onlinelibrary.wiley.com/doi/full/10.1002/mrm.20900 + +.. _physics section: https://tedana.readthedocs.io/en/latest/multi_echo.html +.. _Kundu et al (2013): https://www.ncbi.nlm.nih.gov/pubmed/24038744 diff --git a/docs/conf.py b/docs/conf.py index 97650cd0f..aa4eb12eb 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -48,7 +48,8 @@ 'sphinx.ext.todo', 'numpydoc', 'sphinx.ext.ifconfig', - 'sphinx.ext.linkcode'] + 'sphinx.ext.linkcode', + 'matplotlib.sphinxext.plot_directive'] import sphinx from distutils.version import LooseVersion diff --git a/docs/considerations.rst b/docs/considerations.rst new file mode 100644 index 000000000..b4c4c11f8 --- /dev/null +++ b/docs/considerations.rst @@ -0,0 +1,262 @@ +########################## +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 +================================================== +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 recomendations +and guidelines are discussed in the `appendix`_ of Dipasquale et al, 2017. + +.. _appendix: https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0173289 + +.. _found here: https://www.cmrr.umn.edu/multiband/ +.. _this link: http://license.umn.edu/technologies/cmrr_center-for-magnetic-resonance-research-software-for-siemens-mri-scanners +.. _available here: https://www.nmr.mgh.harvard.edu/software/c2p/sms +.. _GE Collaboration Portal: https://collaborate.mr.gehealthcare.com +.. note:: + In order to increase the number of contrasts ("echoes") you may need to first increase the TR, shorten the + first TE and/or enable in-plane acceleration. + For typically used parameters see the `parameters and publications page`_ +.. _parameters and publications page: https://tedana.readthedocs.io/en/latest/publications.html + +Resources +========= + +Journal articles +---------------- +* | :ref:`spreadsheet of publications` catalogues papers using multi-echo fMRI, + with information about acquisition parameters. +* | `Multi-echo acquisition`_ + | Posse, NeuroImage 2012 + | Includes an historical overview of multi-echo acquisition and research +* | `Multi-Echo fMRI A Review of Applications in fMRI Denoising and Analysis of BOLD Signals`_ + | Kundu et al, NeuroImage 2017 + | A review of multi-echo denoising with a focus on the MEICA algorithm +* | `Enhanced identification of BOLD-like componenents with MESMS and MEICA`_ + | Olafsson et al, NeuroImage 2015 + | The appendix includes a good explanation of the math underlying MEICA denoising +* | `Comparing resting state fMRI de-noising approaches using multi- and single-echo acqusitions`_ + | Dipasquale et al, PLoS One 2017 + | The appendix includes some recommendations for multi-echo acqusition + +.. _Multi-echo acquisition: https://www.ncbi.nlm.nih.gov/pubmed/22056458 +.. _Multi-Echo fMRI A Review of Applications in fMRI Denoising and Analysis of BOLD Signals: https://www.ncbi.nlm.nih.gov/pubmed/28363836 +.. _Enhanced identification of BOLD-like componenents with MESMS and MEICA: https://www.ncbi.nlm.nih.gov/pubmed/25743045 +.. _Comparing resting state fMRI de-noising approaches using multi- and single-echo acqusitions: https://www.ncbi.nlm.nih.gov/pubmed/28323821 + +Videos +------ +* An `educational session from OHBM 2017`_ by Dr. Prantik Kundu about multi-echo denoising +* A `series of lectures from the OHBM 2017 multi-echo session`_ on multiple facets of multi-echo data analysis +* | Multi-echo fMRI lecture from the `2018 NIH FMRI Summer Course`_ by Javier Gonzalez-Castillo + | `Slides from 2018 NIH FMRI Summer Course`_ + +.. _educational session from OHBM 2017: https://www.pathlms.com/ohbm/courses/5158/sections/7788/video_presentations/75977 +.. _series of lectures from the OHBM 2017 multi-echo session: https://www.pathlms.com/ohbm/courses/5158/sections/7822 +.. _2018 NIH FMRI Summer Course: https://fmrif.nimh.nih.gov/course/fmrif_course/2018/14_Javier_20180713 +.. _Slides from 2018 NIH FMRI Summer Course: https://fmrif.nimh.nih.gov/COURSE/fmrif_course/2018/content/14_Javier_20180713.pdf + +Available multi-echo fMRI sequences for multiple vendors +-------------------------------------------------------- + +**For Siemens** users, there are two options for Works In Progress (WIPs) Sequences. +The Center for Magnetic Resonance Research at the University of Minnesota +provides a custom MR sequence that allows users to collect multiple echoes +(termed **Contrasts**). +The sequence and documentation can be `found here`_. For details +on obtaining a license follow `this link`_. +By default the number of contrasts is 1, +yielding a signal echo sequence. +In order to collect multiple echoes, increase number of +Contrasts on the **Sequence Tab, Part 1** on the MR console. + +In addition, the Martinos Center at Harvard also has a MR sequence available, with the +details `available here`_. +The number of echoes can be specified on the **Sequence, Special** tab +in this sequence. + +**For GE users**, there are currently two sharable pulse sequences: + +Multi-echo EPI (MEPI) – Software releases: DV24, MP24 and DV25 (with offline recon) +Hyperband Multi-echo EPI (HyperMEPI) - Software releases: DV26, MP26, DV27, RX27 +(here Hyperband can be deactivated to do simple Multi-echo EPI – online recon) + +Please reach out to the GE Research Operation team or each pulse sequence’s +author to begin the process of obtaining this software. +More information can be +found on the `GE Collaboration Portal`_ + +Once logged-in, go to Groups > GE Works-in-Progress you can find the description of the current ATSM (i.e. prototypes) + +Multi-echo preprocessing software +--------------------------------- + +tedana requires data that has already been preprocessed for head motion, alignment, etc. + +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 mutli-echo fmri data processing. + +Other software that uses multi-echo fMRI +======================================== + +``tedana`` represents only one approach to processing multiecho data. +Currently there are a number of methods that can take advantage of or use the information contain in multi-echo data. +These include: + +`3dMEPFM`_: A multi-echo implemntation of 'paradigm free mapping', that is detection of neural events in the absense of +a prespecified model. +By leveraging the information present in multiecho data, changes in relaxation time can be directly esimated and +more events can be detected. For more information, see the `following paper`_. + +.. _3dMEPFM: https://afni.nimh.nih.gov/pub/dist/doc/program_help/3dMEPFM.html +.. _following paper: https://www.sciencedirect.com/science/article/pii/S105381191930669X + +`Bayesian approach to denoising`_: An alternative approach to seperating out BOLD and non-BOLD signals within a Bayesian +framework is currently under development. + +.. _Bayesian approach to denoising: https://ww5.aievolution.com/hbm1901/index.cfm?do=abs.viewAbs&abs=5026 + +`Multi-echo Group ICA`_: Current approches to ICA just use a single run of data in order to perform denoising. An alternative +approach is to use information from multiple subjects or multiple runs from a single subject in order to improve the +classification of BOLD and non-BOLD components. + +.. _Multi-echo Group ICA: https://ww5.aievolution.com/hbm1901/index.cfm?do=abs.viewAbs&abs=1286 + +`Dual Echo Denoising`_: If the first echo can be collected early enough, there are currently methods that take advantage of the +very limited BOLD weighting at these early echo times. + +.. _Dual Echo Denoising: https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3518782/ + + + +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/faq.rst b/docs/faq.rst index 0094633d1..ff80b6154 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -1,6 +1,9 @@ FAQ ---- +=== + +tedana +------ ICA has failed to converge. ``````````````````````````` @@ -31,8 +34,36 @@ the v3.2 code, with the goal of revisiting it when ``tedana`` is more stable. Anyone interested in using v3.2 may compile and install an earlier release (<=0.0.4) of ``tedana``. +What is the warning about ``duecredit``? +````````````````````````````````````````` +``duecredit`` is a python package that is used, but not required by ``tedana``. +These warnings do not affect any of the processing within the ``tedana``. +To avoide this warning, you can install ``duecredit`` with ``pip install duecredit``. +For more information about ``duecredit`` and concerns about +the citation and visibility of software or methods, visit the `duecredit`_ github. + +.. _duecredit: https://github.com/duecredit/duecredit + .. _here: https://bitbucket.org/prantikk/me-ica/commits/906bd1f6db7041f88cd0efcac8a74074d673f4f5 .. _NeuroStars: https://neurostars.org .. _fMRIPrep: https://fmriprep.readthedocs.io .. _afni_proc.py: https://afni.nimh.nih.gov/pub/dist/doc/program_help/afni_proc.py.html + +Multi-echo fMRI +--------------- + +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. + +.. _specific absorbtion rate: https://www.mr-tip.com/serv1.php?type=db1&dbs=Specific%20Absorption%20Rate + +Can I combine multiband (simultaneous multislice) with multi-echo fMRI? +``````````````````````````````````````````````````````````````````````` +Yes, these techniques are 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. diff --git a/docs/index.rst b/docs/index.rst index ad33fcd2d..7f02eb45e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -141,9 +141,10 @@ tedana is licensed under GNU Lesser General Public License version 2.1. .. toctree:: :maxdepth: 2 :caption: Contents: - + installation multi-echo + considerations publications usage approach diff --git a/docs/multi-echo.rst b/docs/multi-echo.rst index d760385f3..58725899f 100644 --- a/docs/multi-echo.rst +++ b/docs/multi-echo.rst @@ -1,196 +1,97 @@ -Multi-echo fMRI -=============== -In most echo-planar image (EPI) fMRI sequences, only one brain image is acquired -at each repetition time, at the rate of radio frequency (RF). In contrast, in -multi-echo (ME) fMRI, data are acquired for multiple echo times, resulting in -multiple volumes with varying levels of contrast acquired per RF. +What is multi-echo fMRI +======================= +Most echo-planar image (EPI) sequences collect a single brain image following +a radio frequency (RF) pulse, at a rate known as the repetition time (TR). +This typical approach is known as single-echo fMRI. +In contrast, multi-echo (ME) fMRI refers to collecting data at multiple echo times, +resulting in multiple volumes with varying levels of contrast acquired per RF pulse. The physics of multi-echo fMRI ------------------------------ -Multi-echo fMRI data is obtained by acquiring multiple TEs (commonly called -`echo times`_) for each MRI volume -during data collection. +Multi-echo fMRI data is obtained by acquiring multiple echo times (commonly called +`TEs`_) for each MRI volume during data collection. While fMRI signal contains important neural information (termed the blood oxygen-level dependent, or `BOLD signal`_, it also contains "noise" (termed non-BOLD signal) caused by things like participant motion and changes in breathing. Because the BOLD signal is known to decay at a set rate, collecting multiple -echos allows us to assess whether components of the fMRI signal are BOLD- or -non-BOLD. -For a comprehensive review, see `Kundu et al. (2017)`_. - -.. _echo times: http://mriquestions.com/tr-and-te.html +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 +in the earlier echoes (see `processing pipeline details`_). + +.. image:: /_static/physics_kundu_2017_multiple_echoes.jpg + +Adapted from `Kundu et al. (2017)`_. + +In order to classify the relationship between the signal and the echo time we can consider a +single voxel at two timepoints (x and y) and the measured signal measured at three different echo times - :math:`S(TE_n)`. + +.. image:: /_static/physics_kundu_2017_TE_dependence.jpg + +Adapted from `Kundu et al. (2017)`_. + +For the left column, we are observing a change that we term :math:`{\Delta}{S_0}` - that is a change +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 +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://paperpile.com/shared/eH3PPu +.. _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). Among these are the different levels of analysis ME-EPI enables. -Specifically, by collecting multi-echo data, researchers are able to compare results for -(1) single-echo, (2) optimally combined, and (3) denoised data. -Each of these levels of analysis have their own advantages. +Specifically, by collecting multi-echo data, researchers are able to: -For single-echo: currently, field standards are largely set using single-echo EPI. -Because multi-echo is composed of multiple single-echo time series, each of these can be analyzed separately. -This allows researchers to benchmark their results. +**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. -For optimally combined: Rather than analyzing single-echo time series separately, -we can combine them into a "optimally combined time series". +**Combine the results by weighted averaging**: Rather than analyzing single-echo time series separately, +we can combine them into an "optimally combined time series". For more information on this combination, see `processing pipeline details`_. Optimally combined data exhibits higher SNR and improves statistical power of analyses in regions traditionally affected by drop-out. -For denoised: Collecting multi-echo data allows access to unique denoising metrics. -``tedana`` is one ICA-based denoising pipeline built on this information. -Other ICA-based denoising methods like ICA-AROMA (`Pruim et al. (2015)`_) -have been shown to significantly improve the quality of cleaned signal. - +**Denoise the data based on information contained in the echoes**: Collecting multi-echo data allows +access to unique denoising methods. +ICA-based denoising methods like ICA-AROMA (`Pruim et al. (2015)`_) +have been shown to significantly improve the quality of cleaned signal. These methods, however, have comparably limited information, as they are designed to work with single-echo EPI. -Collecting multi-echo EPI allows us to leverage all of the information available for single-echo datasets, + +``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 -Recommendations on multi-echo use for someone planning a new study ------------------------------------------------------------------- -Multi-echo fMRI acquisition sequences and analysis methods are rapidly maturing. Someone who has access -to a multi-echo fMRI sequence should seriously consider using it. Multiple studies have shown that a -weighted average of the echoes to optimize T2* weighting, sometimes called "optimally combined," -gives a reliable, modest boost in data quality. The optimal combination of echoes can currently be -calculated in several software packages including AFNI, fMRIPrep, and tedana. In tedana, the weighted -average can be calculated with `t2smap`_ If no other -acquisition compromises are necessary to acquire multi-echo data, this boost is worthwhile. If other -compromises are necessary, consider the life of the data set. If data is being acquired for a discrete -study that will be acquired, analyzed, and published in a year or two, it might not be worth making -compromises to acquire multi-echo data. If a data set is expected to be used for future analyses in later -years, it is likely that more powerful approaches to multi-echo denoising will sufficiently mature and add -even more value to a data set. - -Other multi-echo denoising methods, such as MEICA, the predecessor to tedana, have shown the potential for -much greater data quality improvements, as well as the ability to more accurately separate visually similar -signal vs noise, such as scanner based drifts vs slow changes in BOLD signal. These more powerful methods are -still being improved, and the algorithms are still changing. Users need to have the time and knowledge to look -at the denoising output from every run to make sure denoising worked as intended. If someone wants a push-button -way to use multi-echo data to improve data quality, that doesn't require as deep an inspection of every output, -stick with using the weighted average. The developers of tedana look forward to when tedana and other methods -have sufficiently stable algorithms, which have been validated on a wide range of data sets, so that we can -recommend the wide use of tedana. - -.. _t2smap: https://tedana.readthedocs.io/en/latest/usage.html#run-t2smap - -Acquisition Parameter Recommendations -------------------------------------- -There is no empirically tested best parameter set for multi-echo acquisition. -The guidelines for optimizing parameters are similar to single-echo fMRI. -For multi-echo fMRI, the same factors that may guide priorities for single echo -fMRI sequences are also relevant. -Choose sequence parameters that meet the priorities of a study with regards to spatial resolution, -spatial coverage, sample rate, signal-to-noise ratio, signal drop-out, distortion, and artifacts. - -The one difference with multi-echo is a slight time cost. -For multi-echo fMRI, the shortest echo time (TE) is essentially free since it is collected in the -gap between the RF pulse and the single-echo acquisition. -The second echo tends to roughly match the single-echo TE. -Additional echoes require more time. -For example, on a 3T MRI, if the T2* weighted TE is 30ms for single echo fMRI, -a multi-echo sequence may have TEs of 15.4, 29.7, and 44.0ms. -In this example, the extra 14ms of acquisition time per RF pulse is the cost of multi-echo fMRI. - -One way to think about this cost is in comparison to single-echo fMRI. -If a multi-echo sequence has identical spatial resolution and acceleration as a single-echo sequence, -then a rough rule of thumb is that the multi-echo sequence will have 10% fewer slices or 10% longer TR. -Instead of compromising on slice coverage or TR, one can increase acceleration. -If one increases acceleration, it is worth doing an empirical comparison to make sure there -isn't a non-trivial loss in SNR or an increase of artifacts. - -A minimum of 3 echoes is recommended for running TE-dependent denoising. -While there are successful studies that don’t follow this rule, -it may be useful to have at least one echo that is earlier and one echo that is later than the -TE one would use for single-echo T2* weighted fMRI. - -More than 3 echoes may be useful, because that would allow for more accurate -estimates of BOLD and non-BOLD weighted fluctuations, but more echoes have an -additional time cost, which would result in either less spatiotemporal coverage -or more acceleration. -Where the benefits of more echoes balance out the additional costs is an open research question. - -We are not recommending specific parameter options at this time. -There are multiple ways to balance the slight time cost from the added echoes that have -resulted in research publications. -We suggest new multi-echo fMRI users examine the :ref:`spreadsheet of publications` that use -multi-echo fMRI to identify studies with similar acquisition priorities, -and use the parameters from those studies as a starting point. - -Resources ---------- - -Journal articles -**************** -* | :ref:`spreadsheet of publications` catalogues papers using multi-echo fMRI, - with information about acquisition parameters. -* | `Multi-echo acquisition`_ - | Posse, NeuroImage 2012 - | Includes an historical overview of multi-echo acquisition and research -* | `Multi-Echo fMRI A Review of Applications in fMRI Denoising and Analysis of BOLD Signals`_ - | Kundu et al, NeuroImage 2017 - | A review of multi-echo denoising with a focus on the MEICA algorithm -* | `Enhanced identification of BOLD-like componenents with MESMS and MEICA`_ - | Olafsson et al, NeuroImage 2015 - | The appendix includes a good explanation of the math underlying MEICA denoising -* | `Comparing resting state fMRI de-noising approaches using multi- and single-echo acqusitions`_ - | Dipasquale et al, PLoS One 2017 - | The appendix includes some recommendations for multi-echo acqusition - -.. _Multi-echo acquisition: https://www.ncbi.nlm.nih.gov/pubmed/22056458 -.. _Multi-Echo fMRI A Review of Applications in fMRI Denoising and Analysis of BOLD Signals: https://www.ncbi.nlm.nih.gov/pubmed/28363836 -.. _Enhanced identification of BOLD-like componenents with MESMS and MEICA: https://www.ncbi.nlm.nih.gov/pubmed/25743045 -.. _Comparing resting state fMRI de-noising approaches using multi- and single-echo acqusitions: https://www.ncbi.nlm.nih.gov/pubmed/28323821 - -Videos -****** -* An `educational session from OHBM 2017`_ by Dr. Prantik Kundu about multi-echo denoising -* A `series of lectures from the OHBM 2017 multi-echo session`_ on multiple facets of multi-echo data analysis -* | Multi-echo fMRI lecture from the `2018 NIH FMRI Summer Course`_ by Javier Gonzalez-Castillo - | `Slides from 2018 NIH FMRI Summer Course`_ - -.. _educational session from OHBM 2017: https://www.pathlms.com/ohbm/courses/5158/sections/7788/video_presentations/75977 -.. _series of lectures from the OHBM 2017 multi-echo session: https://www.pathlms.com/ohbm/courses/5158/sections/7822 -.. _2018 NIH FMRI Summer Course: https://fmrif.nimh.nih.gov/course/fmrif_course/2018/14_Javier_20180713 -.. _Slides from 2018 NIH FMRI Summer Course: https://fmrif.nimh.nih.gov/COURSE/fmrif_course/2018/content/14_Javier_20180713.pdf - -Available multi-echo fMRI sequences for multiple vendors -******************************************************** - -Information on multi-echo sequences from Siemens, GE, and Phillips will be added here. - -Multi-echo preprocessing software -********************************* - -tedana requires data that has already been preprocessed for head motion, alignment, etc. -More details on software packages that include preprocessing options specifically for multi-echo -fMRI data, such as AFNI and fMRIPrep will be added here. - -Other software that uses multi-echo fMRI -**************************************** - -Information and links to other approaches for denoising multi-echo fMRI data will be added here. - -Datasets -******** -A number of multi-echo datasets have been made public so far. -This list is not necessarily up-to-date, so please check out OpenNeuro to potentially find more. - -* `Multi-echo fMRI replication sample of autobiographical memory, prospection and theory of mind reasoning tasks`_ -* `Multi-echo Cambridge`_ -* `Multiband multi-echo imaging of simultaneous oxygenation and flow timeseries for resting state connectivity`_ -* `Valence processing differs across stimulus modalities`_ -* `Cambridge Centre for Ageing Neuroscience (Cam-CAN)`_ - -.. _Multi-echo fMRI replication sample of autobiographical memory, prospection and theory of mind reasoning tasks: https://openneuro.org/datasets/ds000210/ -.. _Multi-echo Cambridge: https://openneuro.org/datasets/ds000258 -.. _Multiband multi-echo imaging of simultaneous oxygenation and flow timeseries for resting state connectivity: https://openneuro.org/datasets/ds000254 -.. _Valence processing differs across stimulus modalities: https://openneuro.org/datasets/ds001491 -.. _Cambridge Centre for Ageing Neuroscience (Cam-CAN): https://camcan-archive.mrc-cbu.cam.ac.uk/dataaccess/ diff --git a/docs/outputs.rst b/docs/outputs.rst index a0c7c0d1b..d8422137a 100644 --- a/docs/outputs.rst +++ b/docs/outputs.rst @@ -7,24 +7,24 @@ tedana derivatives ====================== ===================================================== Filename Content ====================== ===================================================== -t2sv.nii Limited estimated T2* 3D map. +t2sv.nii.gz Limited estimated T2* 3D map. The difference between the limited and full maps is that, for voxels affected by dropout where only one echo contains good data, the full map uses the single echo's value while the limited map has a NaN. -s0v.nii Limited S0 3D map. +s0v.nii.gz Limited S0 3D map. The difference between the limited and full maps is that, for voxels affected by dropout where only one echo contains good data, the full map uses the single echo's value while the limited map has a NaN. -ts_OC.nii Optimally combined time series. -dn_ts_OC.nii Denoised optimally combined time series. Recommended +ts_OC.nii.gz Optimally combined time series. +dn_ts_OC.nii.gz Denoised optimally combined time series. Recommended dataset for analysis. -lowk_ts_OC.nii Combined time series from rejected components. -midk_ts_OC.nii Combined time series from "mid-k" rejected components. -hik_ts_OC.nii High-kappa time series. This dataset does not +lowk_ts_OC.nii.gz Combined time series from rejected components. +midk_ts_OC.nii.gz Combined time series from "mid-k" rejected components. +hik_ts_OC.nii.gz High-kappa time series. This dataset does not include thermal noise or low variance components. Not the recommended dataset for analysis. comp_table_pca.txt TEDPCA component table. A tab-delimited file with @@ -37,9 +37,9 @@ meica_mix.1D Mixing matrix (component time series) from ICA mixing matrix and the one above are that components may be sorted differently and signs of time series may be flipped. -betas_OC.nii Full ICA coefficient feature set. -betas_hik_OC.nii High-kappa ICA coefficient feature set -feats_OC2.nii Z-normalized spatial component maps +betas_OC.nii.gz Full ICA coefficient feature set. +betas_hik_OC.nii.gz High-kappa ICA coefficient feature set +feats_OC2.nii.gz Z-normalized spatial component maps comp_table_ica.txt TEDICA component table. A tab-delimited file with summary metrics and inclusion/exclusion information for each component from the ICA decomposition. @@ -52,22 +52,22 @@ If ``verbose`` is set to True: ====================== ===================================================== Filename Content ====================== ===================================================== -t2ss.nii Voxel-wise T2* estimates using ascending numbers +t2ss.nii.gz Voxel-wise T2* estimates using ascending numbers of echoes, starting with 2. -s0vs.nii Voxel-wise S0 estimates using ascending numbers +s0vs.nii.gz Voxel-wise S0 estimates using ascending numbers of echoes, starting with 2. -t2svG.nii Full T2* map/time series. The difference between +t2svG.nii.gz Full T2* map/time series. The difference between the limited and full maps is that, for voxels affected by dropout where only one echo contains good data, the full map uses the single echo's value while the limited map has a NaN. Only used for optimal combination. -s0vG.nii Full S0 map/time series. Only used for optimal +s0vG.nii.gz Full S0 map/time series. Only used for optimal combination. -hik_ts_e[echo].nii High-Kappa time series for echo number ``echo`` -midk_ts_e[echo].nii Mid-Kappa time series for echo number ``echo`` -lowk_ts_e[echo].nii Low-Kappa time series for echo number ``echo`` -dn_ts_e[echo].nii Denoised time series for echo number ``echo`` +hik_ts_e[echo].nii.gz High-Kappa time series for echo number ``echo`` +midk_ts_e[echo].nii.gz Mid-Kappa time series for echo number ``echo`` +lowk_ts_e[echo].nii.gz Low-Kappa time series for echo number ``echo`` +dn_ts_e[echo].nii.gz Denoised time series for echo number ``echo`` ====================== ===================================================== If ``gscontrol`` includes 'gsr': @@ -75,26 +75,26 @@ If ``gscontrol`` includes 'gsr': ====================== ===================================================== Filename Content ====================== ===================================================== -T1gs.nii Spatial global signal +T1gs.nii.gz Spatial global signal glsig.1D Time series of global signal from optimally combined data. -tsoc_orig.nii Optimally combined time series with global signal +tsoc_orig.nii.gz Optimally combined time series with global signal retained. -tsoc_nogs.nii Optimally combined time series with global signal +tsoc_nogs.nii.gz Optimally combined time series with global signal removed. ====================== ===================================================== If ``gscontrol`` includes 't1c': -====================== ===================================================== -Filename Content -====================== ===================================================== -sphis_hik.nii T1-like effect -hik_ts_OC_T1c.nii T1 corrected high-kappa time series by regression -dn_ts_OC_T1c.nii T1 corrected denoised time series -betas_hik_OC_T1c.nii T1-GS corrected high-kappa components -meica_mix_T1c.1D T1-GS corrected mixing matrix -====================== ===================================================== +======================= ===================================================== +Filename Content +======================= ===================================================== +sphis_hik.nii.gz T1-like effect +hik_ts_OC_T1c.nii.gz T1 corrected high-kappa time series by regression +dn_ts_OC_T1c.nii.gz T1 corrected denoised time series +betas_hik_OC_T1c.nii.gz T1-GS corrected high-kappa components +meica_mix_T1c.1D T1-GS corrected mixing matrix +======================= ===================================================== Component tables ---------------- diff --git a/docs/publications.rst b/docs/publications.rst index 1cf208257..ece4b3c84 100644 --- a/docs/publications.rst +++ b/docs/publications.rst @@ -1,11 +1,51 @@ .. _spreadsheet of publications: -Multi-echo fMRI Publications -============================ +ME-fMRI Parameters & Publications +================================= -The following spreadsheet is an on-going effort to track all publications that -use multi-echo fMRI. This is a volunteer led effort so, if you know of an -excluded publication, whether or not it is yours, please add it. +The 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`_ diff --git a/docs/roadmap.rst b/docs/roadmap.rst index f1c575d04..fc9bf87f1 100644 --- a/docs/roadmap.rst +++ b/docs/roadmap.rst @@ -156,8 +156,6 @@ such that the ``afni_proc.py`` maintainers are willing to switch to ``tedana`` a method of accessing ME-EPI denoising in AFNI. We will aim to aid in this process by increasing compatibility between ``tedana`` and the ``afni_proc.py`` workflow, eliminating the need for an additional wrapper script. -For example, ``tedana`` could directly accept BRIK/HEAD files, -facilitating interoperability with other AFNI pipelines. |milestone4|_ diff --git a/docs/usage.rst b/docs/usage.rst index a628ee286..c82541300 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -1,5 +1,5 @@ -Usage -===== +tedana Usage +============ ``tedana`` minimally requires: @@ -34,9 +34,11 @@ https://tedana.readthedocs.io/en/latest/outputs.html .. note:: The ``--mask`` argument is not intended for use with very conservative region-of-interest - analyses. One of the ways by which components are assessed as BOLD or non-BOLD is their + analyses. + One of the ways by which components are assessed as BOLD or non-BOLD is their spatial pattern, so overly conservative masks will invalidate several steps in the tedana - workflow. To examine regions-of-interest with multi-echo data, apply masks after TE + workflow. + To examine regions-of-interest with multi-echo data, apply masks after TE Dependent ANAlysis. Run t2smap @@ -91,12 +93,12 @@ Instead, we recommend that researchers apply the same transforms to all echoes i That is, that they calculate head motion correction parameters from one echo and apply the resulting transformation to all echoes. -Similarly, any intensity normalization or nuisance regressors should be applied to the data -*after* ``tedana`` calculates the BOLD and non-BOLD weighting of components. - -If this is not considered, resulting intensity gradients (e.g., in the case of scaling) -or alignment parameters (e.g., in the case of motion correction, normalization) -are likely to differ across echos, -and the subsequent calculation of voxelwise T2* values will be distorted. -See the description of ``tedana``'s :doc:`approach <\approach>` for more details -on how T2* values are calculated. +.. note:: + Any intensity normalization or nuisance regressors should be applied to the data + *after* ``tedana`` calculates the BOLD and non-BOLD weighting of components. + If this is not considered, resulting intensity gradients (e.g., in the case of scaling) + or alignment parameters (e.g., in the case of motion correction, normalization) + are likely to differ across echos, + and the subsequent calculation of voxelwise T2* values will be distorted or incorrect. + See the description of ``tedana``'s :doc:`approach <\approach>` for more details + on how T2* values are calculated.