From 5644dc4bd80ac929cc7568b614f9fbaa061e0b91 Mon Sep 17 00:00:00 2001 From: Daniel Handwerker Date: Thu, 20 Jun 2019 22:21:04 -0400 Subject: [PATCH 1/9] Adding ME us recommendations to multi-echo.rst --- docs/multi-echo.rst | 48 +++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 44 insertions(+), 4 deletions(-) diff --git a/docs/multi-echo.rst b/docs/multi-echo.rst index 42075a223..8e6229283 100644 --- a/docs/multi-echo.rst +++ b/docs/multi-echo.rst @@ -1,9 +1,9 @@ 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. +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. The physics of multi-echo fMRI ------------------------------ @@ -54,6 +54,30 @@ 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, FMRI_PREP, and tedana. If no other acquisition +need to be compromised 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 very 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 everything worked. 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 that has been validated on a wide range data data sets that we can recommended +the push-button use of tedana. + Acquisition Parameter Recommendations ------------------------------------- There is no empirically tested best parameter set for multi-echo acquisition. @@ -118,6 +142,22 @@ Videos .. _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 +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 FMRI_PREP 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 ******** From a6b536f6ee3ca4a75276afe699fb9216db66a4d7 Mon Sep 17 00:00:00 2001 From: Daniel Handwerker Date: Thu, 20 Jun 2019 22:27:48 -0400 Subject: [PATCH 2/9] Small changes to ME us recommendations in multi-echo.rst --- docs/multi-echo.rst | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/multi-echo.rst b/docs/multi-echo.rst index 8e6229283..6519c4117 100644 --- a/docs/multi-echo.rst +++ b/docs/multi-echo.rst @@ -58,25 +58,25 @@ 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," +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, FMRI_PREP, and tedana. If no other acquisition -need to be compromised 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 very likely that more powerful approaches to multi-echo denoising will sufficiently mature and add +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 everything worked. 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 that has been validated on a wide range data data sets that we can recommended -the push-button use of tedana. +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 data data sets, so that we can +recommended the wide use of tedana. Acquisition Parameter Recommendations ------------------------------------- @@ -152,7 +152,7 @@ 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 FMRI_PREP will be added here. +fMRI data, such as AFNI and FMRI_PREP will be added here. Other software that uses multi-echo fMRI **************************************** From fa6c3daa92bee6bd84aed794564555322f95aaaf Mon Sep 17 00:00:00 2001 From: handwerkerd <7406227+handwerkerd@users.noreply.github.com> Date: Fri, 21 Jun 2019 11:38:29 -0400 Subject: [PATCH 3/9] Update docs/multi-echo.rst Co-Authored-By: Joshua Teves --- docs/multi-echo.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/multi-echo.rst b/docs/multi-echo.rst index 6519c4117..4c901e726 100644 --- a/docs/multi-echo.rst +++ b/docs/multi-echo.rst @@ -60,7 +60,7 @@ Multi-echo fMRI acquisition sequences and analysis methods are rapidly maturing. 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, FMRI_PREP, and tedana. If no other acquisition +calculated in several software packages including AFNI, fMRIPrep, and tedana. 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 From ac3a0415cc236c35c1682dbc15a931b248fed80f Mon Sep 17 00:00:00 2001 From: handwerkerd <7406227+handwerkerd@users.noreply.github.com> Date: Fri, 21 Jun 2019 11:44:14 -0400 Subject: [PATCH 4/9] Update multi-echo.rst Small text edits to correctly spell fMRIPrep and add a link to the weighted average function in tedana. --- docs/multi-echo.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/multi-echo.rst b/docs/multi-echo.rst index 4c901e726..679ef3693 100644 --- a/docs/multi-echo.rst +++ b/docs/multi-echo.rst @@ -60,12 +60,13 @@ Multi-echo fMRI acquisition sequences and analysis methods are rapidly maturing. 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. 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 +calculated in several software packages including AFNI, fMRIPrep, and tedana. In tedana, the weighted +average can be calculated with https://tedana.readthedocs.io/en/latest/usage.html#run-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 @@ -152,7 +153,7 @@ 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 FMRI_PREP will be added here. +fMRI data, such as AFNI and fMRIPrep will be added here. Other software that uses multi-echo fMRI **************************************** From 0368e5172a3d9cf77d232a9b6b3a60318f3596a5 Mon Sep 17 00:00:00 2001 From: handwerkerd <7406227+handwerkerd@users.noreply.github.com> Date: Fri, 21 Jun 2019 11:54:49 -0400 Subject: [PATCH 5/9] Update docs/multi-echo.rst Co-Authored-By: Joshua Teves --- docs/multi-echo.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/multi-echo.rst b/docs/multi-echo.rst index 679ef3693..f1fdb1b2a 100644 --- a/docs/multi-echo.rst +++ b/docs/multi-echo.rst @@ -61,7 +61,7 @@ to a multi-echo fMRI sequence should seriously consider using it. Multiple studi 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 https://tedana.readthedocs.io/en/latest/usage.html#run-t2smap If no other +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 From c9c0c5108b7a4333e803968bd76679c153649b90 Mon Sep 17 00:00:00 2001 From: handwerkerd <7406227+handwerkerd@users.noreply.github.com> Date: Fri, 21 Jun 2019 13:31:54 -0400 Subject: [PATCH 6/9] Update multi-echo.rst Fixing link to t2smap --- docs/multi-echo.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/multi-echo.rst b/docs/multi-echo.rst index f1fdb1b2a..36d48181d 100644 --- a/docs/multi-echo.rst +++ b/docs/multi-echo.rst @@ -61,7 +61,7 @@ to a multi-echo fMRI sequence should seriously consider using it. Multiple studi 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 +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 @@ -79,6 +79,8 @@ stick with using the weighted average. The developers of tedana look forward to have sufficiently stable algorithms, which have been validated on a wide range data data sets, so that we can recommended 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. From 189cd87533cee47c1503ec9b5700d24c044ba44e Mon Sep 17 00:00:00 2001 From: handwerkerd <7406227+handwerkerd@users.noreply.github.com> Date: Mon, 1 Jul 2019 16:47:52 -0400 Subject: [PATCH 7/9] Merge remote-tracking branch 'upstream/master' # Conflicts: # docs/multi-echo.rst --- README.md | 45 +++++++++++------------- docs/index.rst | 4 +++ docs/make.bat | 72 +++++++++++++++++++------------------- docs/multi-echo.rst | 4 +-- tedana/workflows/tedana.py | 11 ++++++ 5 files changed, 74 insertions(+), 62 deletions(-) diff --git a/README.md b/README.md index 35eeae56d..267a20c6f 100644 --- a/README.md +++ b/README.md @@ -13,30 +13,29 @@ multi-echo functional magnetic resonance imaging (fMRI) data. [![Documentation Status](https://readthedocs.org/projects/tedana/badge/?version=latest)](http://tedana.readthedocs.io/en/latest/?badge=latest) [![Codecov](https://codecov.io/gh/me-ica/tedana/branch/master/graph/badge.svg)](https://codecov.io/gh/me-ica/tedana) [![Join the chat at https://gitter.im/ME-ICA/tedana](https://badges.gitter.im/ME-ICA/tedana.svg)](https://gitter.im/ME-ICA/tedana?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) -[![All Contributors](https://img.shields.io/badge/all_contributors-10-orange.svg?style=flat-square)](#contributors) +[![Join our tinyletter mailing list](https://img.shields.io/badge/receive-our%20newsletter%20❤%EF%B8%8F-blueviolet.svg)](https://tinyletter.com/tedana-devs) +[![All Contributors](https://img.shields.io/badge/all_contributors-10-orange.svg)](#contributors) ## About ``tedana`` originally came about as a part of the [ME-ICA](https://github.com/me-ica/me-ica) pipeline. -The ME-ICA pipeline originally performed both pre-processing and TE-dependent -analysis of multi-echo fMRI data; however, ``tedana`` now assumes that you're -working with data which has been previously preprocessed. +The ME-ICA pipeline originally performed both pre-processing and TE-dependent analysis of multi-echo fMRI data; however, ``tedana`` now assumes that you're working with data which has been previously preprocessed. ![http://tedana.readthedocs.io/](https://user-images.githubusercontent.com/7406227/40031156-57b7cbb8-57bc-11e8-8c51-5b29f2e86a48.png) -More information and documentation can be found at https://tedana.readthedocs.io/. +More information and documentation can be found at https://tedana.readthedocs.io. ## Installation You'll need to set up a working development environment to use `tedana`. To set up a local environment, you will need Python >=3.5 and the following packages will need to be installed: -[numpy](http://www.numpy.org/) -[scipy](https://www.scipy.org/) -[scikit-learn](http://scikit-learn.org/stable/) -[nilearn](https://nilearn.github.io/) -[nibabel>=2.1.0](http://nipy.org/nibabel/) +* [numpy](http://www.numpy.org/) +* [scipy](https://www.scipy.org/) +* [scikit-learn](http://scikit-learn.org/stable/) +* [nilearn](https://nilearn.github.io/) +* [nibabel>=2.1.0](http://nipy.org/nibabel/) You can then install `tedana` with @@ -45,6 +44,7 @@ pip install tedana ``` ### Creating a miniconda environment for use with `tedana` + In using `tedana`, you can optionally configure [a conda environment](https://conda.io/docs/user-guide/tasks/manage-environments.html). We recommend using [miniconda3](https://conda.io/miniconda.html). @@ -58,7 +58,7 @@ pip install tedana ``` `tedana` will then be available in your path. -This will also allow any previously existing tedana installations to remain untouched. +This will also allow any previously existing `tedana` installations to remain untouched. To exit this conda environment, use @@ -66,10 +66,8 @@ To exit this conda environment, use conda deactivate ``` -NOTE: Conda < 4.6 users will need to use the soon-to-be-deprecated option -`source` rather than `conda` for the activation and deactivation steps. -You can read more about managing conda environments and this discrepancy here: -[here](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html) +NOTE: Conda < 4.6 users will need to use the soon-to-be-deprecated option `source` rather than `conda` for the activation and deactivation steps. +You can read more about managing conda environments and this discrepancy [here](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html). ## Getting involved @@ -79,15 +77,14 @@ To get started, check out [our contributing guidelines](https://github.com/ME-IC Want to learn more about our plans for developing ``tedana``? Have a question, comment, or suggestion? Open or comment on one of [our issues](https://github.com/ME-ICA/tedana/issues)! -If you're not sure where to begin, -feel free to pop into [Gitter](https://gitter.im/ME-ICA/tedana) and -introduce yourself! We will be happy to help you find somewhere to get -started. - -We ask that all contributors to ``tedana`` across all project-related -spaces (including but not limited to: GitHub, Gitter, and project emails), -adhere to our -[code of conduct](https://github.com/ME-ICA/tedana/blob/master/CODE_OF_CONDUCT.md). + +If you're not sure where to begin, feel free to pop into [Gitter](https://gitter.im/ME-ICA/tedana) and introduce yourself! +We will be happy to help you find somewhere to get started. + +If you don't want to get lots of notifications, we send out newsletters approximately once per month though our TinyLetter mailing list. +You can view the [previous newsletters](https://tinyletter.com/tedana-devs/archive) and/or sign up to receive future ones at [https://tinyletter.com/tedana-devs](https://tinyletter.com/tedana-devs). + +We ask that all contributors to ``tedana`` across all project-related spaces (including but not limited to: GitHub, Gitter, and project emails), adhere to our [code of conduct](https://github.com/ME-ICA/tedana/blob/master/CODE_OF_CONDUCT.md). ## Contributors diff --git a/docs/index.rst b/docs/index.rst index 7903a6de4..67734175d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -40,6 +40,10 @@ multi-echo functional magnetic resonance imaging (fMRI) data. :target: https://gitter.im/ME-ICA/tedana :alt: Join the chat +.. image:: https://img.shields.io/badge/receive-our%20newsletter%20❤%EF%B8%8F-blueviolet.svg + :target: https://tinyletter.com/tedana-devs + :alt: Join our tinyletter mailing list + About ----- diff --git a/docs/make.bat b/docs/make.bat index 9e3a58643..3fe374051 100644 --- a/docs/make.bat +++ b/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 diff --git a/docs/multi-echo.rst b/docs/multi-echo.rst index 36d48181d..7d1c3c785 100644 --- a/docs/multi-echo.rst +++ b/docs/multi-echo.rst @@ -76,8 +76,8 @@ still being improved, and the algorithms are still changing. Users need to have at the denoising output from every run to make sure denoising worked as intended. 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 data data sets, so that we can -recommended the wide use of tedana. +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 diff --git a/tedana/workflows/tedana.py b/tedana/workflows/tedana.py index 421fd6c20..ec0aa5cca 100644 --- a/tedana/workflows/tedana.py +++ b/tedana/workflows/tedana.py @@ -311,6 +311,17 @@ def tedana_workflow(data, tes, mask=None, mixm=None, ctab=None, manacc=None, n_samp, n_echos, n_vols = catd.shape LGR.debug('Resulting data shape: {}'.format(catd.shape)) + # check if TR is 0 + img_t_r = ref_img.header.get_zooms()[-1] + if img_t_r == 0 and png: + raise IOError('Dataset has a TR of 0. This indicates incorrect' + ' header information. To correct this, we recommend' + ' using this snippet:' + '\n' + 'https://gist.github.com/jbteves/032c87aeb080dd8de8861cb151bff5d6' + '\n' + 'to correct your TR to the value it should be.') + if mixm is not None and op.isfile(mixm): mixm = op.abspath(mixm) # Allow users to re-run on same folder From 5b51d75dc45d4dd2a73f5cec5f1a16b43f74aaf5 Mon Sep 17 00:00:00 2001 From: handwerkerd <7406227+handwerkerd@users.noreply.github.com> Date: Tue, 2 Jul 2019 14:50:31 -0400 Subject: [PATCH 8/9] 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. --- docs/index.rst | 1 + docs/multi-echo.rst | 31 +++++++++++++++++++++++-------- docs/publications.rst | 16 ++++++++++++++++ 3 files changed, 40 insertions(+), 8 deletions(-) create mode 100644 docs/publications.rst diff --git a/docs/index.rst b/docs/index.rst index 67734175d..e85a769a9 100644 --- a/docs/index.rst +++ b/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 diff --git a/docs/multi-echo.rst b/docs/multi-echo.rst index 7d1c3c785..daef28238 100644 --- a/docs/multi-echo.rst +++ b/docs/multi-echo.rst @@ -120,30 +120,45 @@ 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 +* | A :ref:`spreadsheet of publications` cataloguing 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 ******************************************************** diff --git a/docs/publications.rst b/docs/publications.rst new file mode 100644 index 000000000..faa15f0f6 --- /dev/null +++ b/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 edit this spreadsheet `here`_ + +.. raw:: html + + + +.. _here: https://docs.google.com/spreadsheets/d/1WERojJyxFoqcg_tndUm5Kj0H1UfUc9Ban0jFGGfPaBk/edit#gid=0 \ No newline at end of file From 1d25f0537584d73475ce34842235e29ac1ab757d Mon Sep 17 00:00:00 2001 From: handwerkerd <7406227+handwerkerd@users.noreply.github.com> Date: Tue, 2 Jul 2019 16:19:55 -0400 Subject: [PATCH 9/9] Additional fixes to documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit More fixed how publication table looks and corrected a few ‘make html’ warnings for readthedocs --- docs/api.rst | 4 ++-- docs/multi-echo.rst | 3 ++- docs/outputs.rst | 13 ++++++------- docs/publications.rst | 4 ++-- 4 files changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index c3d839eb3..291999107 100644 --- a/docs/api.rst +++ b/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 diff --git a/docs/multi-echo.rst b/docs/multi-echo.rst index daef28238..d760385f3 100644 --- a/docs/multi-echo.rst +++ b/docs/multi-echo.rst @@ -129,7 +129,8 @@ Resources Journal articles **************** -* | A :ref:`spreadsheet of publications` cataloguing papers using multi-echo fMRI, with information about acquisition parameters. +* | :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 diff --git a/docs/outputs.rst b/docs/outputs.rst index 5826a52a5..3f3a88f1e 100644 --- a/docs/outputs.rst +++ b/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. diff --git a/docs/publications.rst b/docs/publications.rst index faa15f0f6..1cf208257 100644 --- a/docs/publications.rst +++ b/docs/publications.rst @@ -7,10 +7,10 @@ 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 edit this spreadsheet `here`_ +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