Multi-echo background documentation edits (#351)

* Adding ME us recommendations to multi-echo.rst

* Small changes to ME us recommendations in multi-echo.rst

* Update docs/multi-echo.rst

Co-Authored-By: Joshua Teves <[email protected]>

* Update multi-echo.rst

Small text edits to correctly spell fMRIPrep and add a link to the weighted average function in tedana.

* Update docs/multi-echo.rst

Co-Authored-By: Joshua Teves <[email protected]>

* Update multi-echo.rst

Fixing link to t2smap

* Merge remote-tracking branch 'upstream/master'

# Conflicts:
#	docs/multi-echo.rst

* Reformated refs in publications.rst

Several references were added to the main text and I split off the
spreadsheet of publications into its own page rather than just linking
to a google doc.

* Additional fixes to documentation

More fixed how publication table looks and corrected a few ‘make html’
warnings for readthedocs

docs/api.rst

@@ -81,7 +81,7 @@ API
 
 
 :mod:`tedana.metrics`: Computing TE-dependence metrics
-----------------------------------------------------
+--------------------------------------------------------
 
 .. automodule:: tedana.metrics
    :no-members:
@@ -96,7 +96,7 @@ API
 
    :template: module.rst
 
-   tedana.metrics.fit
+   tedana.metrics.kundu_fit
 
 .. currentmodule:: tedana
 

docs/index.rst

@@ -142,6 +142,7 @@ tedana is licensed under GNU Lesser General Public License version 2.1.
 
    installation
    multi-echo
+   publications
    usage
    approach
    outputs

docs/make.bat

@@ -1,36 +1,36 @@
-@ECHO OFF
-
-pushd %~dp0
-
-REM Command file for Sphinx documentation
-
-if "%SPHINXBUILD%" == "" (
-	set SPHINXBUILD=python -msphinx
-)
-set SOURCEDIR=.
-set BUILDDIR=_build
-set SPHINXPROJ=meica
-
-if "%1" == "" goto help
-
-%SPHINXBUILD% >NUL 2>NUL
-if errorlevel 9009 (
-	echo.
-	echo.The Sphinx module was not found. Make sure you have Sphinx installed,
-	echo.then set the SPHINXBUILD environment variable to point to the full
-	echo.path of the 'sphinx-build' executable. Alternatively you may add the
-	echo.Sphinx directory to PATH.
-	echo.
-	echo.If you don't have Sphinx installed, grab it from
-	echo.http://sphinx-doc.org/
-	exit /b 1
-)
-
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
-goto end
-
-:help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
-
-:end
-popd
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=python -msphinx
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+set SPHINXPROJ=meica
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The Sphinx module was not found. Make sure you have Sphinx installed,
+	echo.then set the SPHINXBUILD environment variable to point to the full
+	echo.path of the 'sphinx-build' executable. Alternatively you may add the
+	echo.Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
+popd

docs/multi-echo.rst

@@ -120,30 +120,46 @@ Where the benefits of more echoes balance out the additional costs is an open re
 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
+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.
 
-.. _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
+* | :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
 ********************************************************

docs/outputs.rst

@@ -158,7 +158,7 @@ Images are created and placed within the output directory, in a folder labeled
 These reports consist of three main types of images.
 
 Component Images
-````````````
+````````````````
 .. image:: /_static/example_good_component.png
   :align: center
 
@@ -195,13 +195,13 @@ Tip: Look for your fundamental task frequencies here!
 
 Above, you can review a component that was rejected.
 In this case, the subject moved each time the task was performed - which
-affected single slices of the fMRI volume. 
+affected single slices of the fMRI volume.
 This scan used multiband imaging (collecting multiple slices at once), so
 the motion artifact occurs in more than once slice.
 
 
 Kappa vs Rho Scatter Plot
-````````````
+`````````````````````````
 .. image:: /_static/example_Kappa_vs_Rho_Scatter.png
   :align: center
 
@@ -212,7 +212,7 @@ This can be useful for getting a big picture view of your data or for comparing
 denoising performance with various fMRI sequences.
 
 Double Pie Chart
-````````````
+````````````````
 .. image:: /_static/example_Component_Overview.png
   :align: center
 
@@ -222,6 +222,5 @@ ring.
 If a low amount of variance is explained, this will be shown as a gap in the
 ring.
 
-Tip: Sometimes large variance is due to singular components, which can be easily
-seen here.
-
+Tip: Sometimes large variance is due to singular components, which can be
+easily seen here.

docs/publications.rst

@@ -0,0 +1,16 @@
+.. _spreadsheet of publications:
+
+Multi-echo fMRI Publications
+============================
+
+The following spreadsheet is an on-going effort to track all publications that
+use multi-echo fMRI. This is a volunteer led effort so, if you know of an
+excluded publication, whether or not it is yours, please add it.
+
+You can view and suggest additions to this spreadsheet `here`_
+
+.. raw:: html
+
+    <iframe style="position: absolute; height: 60%; width: 60%; border: none" src="https://docs.google.com/spreadsheets/d/e/2PACX-1vS0nEVp27NpwdzPunvMLflyKzcZbCo4k2qPk5zxEiaoJTD_IY1OGbWICizogAEZlTyL7d_7aDA92uwf/pubhtml?widget=true&amp;headers=false"></iframe>
+
+.. _here: https://docs.google.com/spreadsheets/d/1WERojJyxFoqcg_tndUm5Kj0H1UfUc9Ban0jFGGfPaBk/edit#gid=0