Merge pull request #4 from ME-ICA/master

update fork
ME-ICA · May 24, 2019 · f81f57d · f81f57d
2 parents cdbcef1 + 0c0d704
commit f81f57d
Show file tree

Hide file tree

Showing 25 changed files with 823 additions and 591 deletions.
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -200,7 +200,9 @@ jobs:
             cd /tmp/data/five-echo/
             tedana -d p06.SBJ01_S09_Task11_e[1,2,3,4,5].sm.nii.gz \
                 -e 15.4 29.7 44.0 58.3 72.6 --verbose \
-                --out-dir /tmp/data/five-echo/TED.five-echo/
+                --out-dir /tmp/data/five-echo/TED.five-echo \
+                --debug
+
       - run:
           name: Checking outputs
           command: |

diff --git a/.circleci/tedana_outputs_verbose.txt b/.circleci/tedana_outputs_verbose.txt
@@ -40,5 +40,6 @@ s0vs.nii
 t2ss.nii
 t2sv.nii
 t2svG.nii
+tedana_run.txt
 ts_OC.nii
 ts_OC_whitened.nii
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -94,6 +94,11 @@ The current list of labels are [here][link_labels] and include:
 
     If you feel that you can contribute to one of these issues, we especially encourage you to do so!
 
+* [![Paused](https://img.shields.io/badge/-paused-%23ddcc5f.svg)][link_paused] *These issues should not be worked on until the resolution of other issues or Pull Requests.*
+
+    These are issues that are paused pending resolution of a related issue or Pull Request.
+    Please do not open any Pull Requests to resolve these issues.
+
 * [![Bugs](https://img.shields.io/badge/-bugs-fc2929.svg)][link_bugs] *These issues point to problems in the project.*
 
     If you find new a bug, please give as much detail as possible in your issue, including steps to recreate the error.
@@ -223,6 +228,7 @@ You're awesome. :wave::smiley:
 [link_stale-bot]: https://github.com/probot/stale
 
 [link_labels]: https://github.com/ME-ICA/tedana/labels
+[link_paused]: https://github.com/ME-ICA/tedana/labels/paused
 [link_bugs]: https://github.com/ME-ICA/tedana/labels/bug
 [link_helpwanted]: https://github.com/ME-ICA/tedana/labels/help%20wanted
 [link_enhancement]: https://github.com/ME-ICA/tedana/labels/enhancement

diff --git a/docs/api.rst b/docs/api.rst
@@ -20,22 +20,37 @@ API
 .. _calibration_ref:
 
 
-:mod:`tedana.model`: Modeling TE-dependence
---------------------------------------------------
+:mod:`tedana.decay`: Modeling signal decay across echoes
+--------------------------------------------------------
 
-.. automodule:: tedana.model
+.. automodule:: tedana.decay
    :no-members:
    :no-inherited-members:
 
-.. autosummary:: tedana.model
-   :toctree: generated/
+.. autosummary:: tedana.decay
    :template: function.rst
+   :toctree: generated/
+
+   tedana.decay.fit_decay
+   tedana.decay.fit_decay_ts
 
-   tedana.model.fitmodels_direct
+.. currentmodule:: tedana
 
-   :template: module.rst
+.. _calibration_ref:
 
-   tedana.model.fit
+
+:mod:`tedana.combine`: Combining time series across echoes
+----------------------------------------------------------
+
+.. automodule:: tedana.combine
+   :no-members:
+   :no-inherited-members:
+
+.. autosummary:: tedana.combine
+   :toctree: generated/
+   :template: function.rst
+
+   tedana.combine.make_optcom
 
 .. currentmodule:: tedana
 
@@ -65,67 +80,65 @@ API
 .. _calibration_ref:
 
 
-:mod:`tedana.combine`: Combine time series
---------------------------------------------------
+:mod:`tedana.model`: Computing TE-dependence metrics
+----------------------------------------------------
 
-.. automodule:: tedana.combine
+.. automodule:: tedana.model
    :no-members:
    :no-inherited-members:
 
-.. autosummary:: tedana.combine
+.. autosummary:: tedana.model
    :toctree: generated/
    :template: function.rst
 
-   tedana.combine.make_optcom
+   tedana.model.dependence_metrics
+   tedana.model.kundu_metrics
 
    :template: module.rst
 
-   tedana.combine
+   tedana.model.fit
 
 .. currentmodule:: tedana
 
 .. _calibration_ref:
 
 
-:mod:`tedana.decay`: Signal decay
+:mod:`tedana.selection`: Component selection
 --------------------------------------------------
 
-.. automodule:: tedana.decay
+.. automodule:: tedana.selection
    :no-members:
    :no-inherited-members:
 
-.. autosummary:: tedana.decay
+.. autosummary:: tedana.selection
    :toctree: generated/
    :template: function.rst
 
-   tedana.decay.fit_decay
-   tedana.decay.fit_decay_ts
+   tedana.selection.manual_selection
+   tedana.selection.kundu_selection_v2
 
    :template: module.rst
 
-   tedana.decay
+   tedana.selection._utils
 
 .. currentmodule:: tedana
 
 .. _calibration_ref:
 
 
-:mod:`tedana.selection`: Component selection
+:mod:`tedana.gscontrol`: Global signal control
 --------------------------------------------------
 
-.. automodule:: tedana.selection
+.. automodule:: tedana.gscontrol
    :no-members:
    :no-inherited-members:
 
-.. autosummary:: tedana.selection
+.. autosummary:: tedana.gscontrol
    :toctree: generated/
    :template: function.rst
 
-   tedana.selection.selcomps
-
-   :template: module.rst
-
-   tedana.selection._utils
+   tedana.gscontrol.gscontrol_raw
+   tedana.gscontrol.gscontrol_mmix
 
 .. currentmodule:: tedana
 
@@ -146,17 +159,32 @@ API
 
    tedana.io.split_ts
    tedana.io.filewrite
-   tedana.io.gscontrol_mmix
    tedana.io.load_data
    tedana.io.new_nii_like
    tedana.io.write_split_ts
    tedana.io.writefeats
    tedana.io.writeresults
    tedana.io.writeresults_echoes
 
-   :template: module.rst
+.. currentmodule:: tedana
+
+.. _calibration_ref:
+
 
-   tedana.io
+:mod:`tedana.stats`: Statistical functions
+--------------------------------------------------
+
+.. automodule:: tedana.stats
+   :no-members:
+   :no-inherited-members:
+
+.. autosummary:: tedana.stats
+   :toctree: generated/
+   :template: function.rst
+
+   tedana.stats.get_coeffs
+   tedana.stats.computefeats2
+   tedana.stats.getfbounds
 
 .. currentmodule:: tedana
 
@@ -177,15 +205,10 @@ API
 
    tedana.utils.andb
    tedana.utils.dice
-   tedana.utils.getfbounds
    tedana.utils.load_image
    tedana.utils.make_adaptive_mask
    tedana.utils.unmask
 
-   :template: module.rst
-
-   tedana.utils
-
 .. currentmodule:: tedana
 
 .. _calibration_ref:
diff --git a/docs/conf.py b/docs/conf.py
@@ -68,7 +68,7 @@
 
 # General information about the project.
 project = 'tedana'
-copyright = '2017-2018, tedana developers'
+copyright = '2017-2019, tedana developers'
 author = 'tedana developers'
 
 # The version info for the project you're documenting, acts as replacement for

diff --git a/docs/multi-echo.rst b/docs/multi-echo.rst
@@ -23,89 +23,112 @@ For a comprehensive review, see `Kundu et al. (2017)`_.
 
 Why use multi-echo?
 -------------------
-ME-EPI exhibits higher SNR and improves statistical power of analyses.
-
-Resources
----------
-
-Journal articles
-****************
-* A `review`_ on multi-echo fMRI and its applications
-* A `spreadsheet`_ cataloguing papers using multi-echo fMRI, with information about acquisition parameters.
-
-.. _review: https://www.ncbi.nlm.nih.gov/pubmed/28363836
-.. _spreadsheet: https://docs.google.com/spreadsheets/d/1WERojJyxFoqcg_tndUm5Kj0H1UfUc9Ban0jFGGfPaBk/edit#gid=0
-
-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
-
-.. _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
-
-Sequences
-*********
-* Multi-echo sequences: who has them and how to get them.
+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.
+
+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.
+
+For optimally combined: Rather than analyzing single-echo time series separately,
+we can combine them into a "optimally combined time series".
+For more information on this combination, see :ref:`approach`.
+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.
+
+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,
+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.
+
+.. _Pruim et al., 2015: https://www.sciencedirect.com/science/article/pii/S1053811915001822
 
 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 sequence 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.
+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
+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 radio frequency (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.
+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
+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
+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.
+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 `spreadsheet`_ of journal articles that use multi-echo fMRI to identify
-studies with similar acquisition priorities, and use the parameters from those
-studies as a starting point.
+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 `spreadsheet`_ of journal articles that use
+multi-echo fMRI to identify studies with similar acquisition priorities,
+and use the parameters from those studies as a starting point.
 
 .. _spreadsheet: https://docs.google.com/spreadsheets/d/1WERojJyxFoqcg_tndUm5Kj0H1UfUc9Ban0jFGGfPaBk/edit#gid=0
 
+Resources
+---------
+
+Journal articles
+****************
+* A `review`_ on multi-echo fMRI and its applications
+* A `spreadsheet`_ cataloguing papers using multi-echo fMRI, with information about acquisition parameters.
+
+.. _review: https://www.ncbi.nlm.nih.gov/pubmed/28363836
+.. _spreadsheet: https://docs.google.com/spreadsheets/d/1WERojJyxFoqcg_tndUm5Kj0H1UfUc9Ban0jFGGfPaBk/edit#gid=0
+
+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
+
+.. _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
+
+
 Datasets
 ********
-A small 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.
+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/