From 4807ac8701e579623276b39b4d6cb234318a22a6 Mon Sep 17 00:00:00 2001 From: Elizabeth DuPre Date: Mon, 5 Nov 2018 15:28:20 -0500 Subject: [PATCH] [DOC] Finish general recommendations --- docs/index.rst | 11 ++++----- docs/pipelines.rst | 24 ------------------- docs/usage.rst | 57 ++++++++++++++++++++++++++++++++++++++++++++-- 3 files changed, 59 insertions(+), 33 deletions(-) delete mode 100644 docs/pipelines.rst diff --git a/docs/index.rst b/docs/index.rst index c523af10c..1e7450965 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -43,19 +43,16 @@ multi-echo functional magnetic resonance imaging (fMRI) data. About ----- +.. image:: https://user-images.githubusercontent.com/7406227/40031156-57b7cbb8-57bc-11e8-8c51-5b29f2e86a48.png + :target: http://tedana.readthedocs.io/ + ``tedana`` originally came about as a part of the `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. -If you're in need of a preprocessing pipeline, we recommend -`fmriprep`_, which has been tested -for compatibility with multi-echo fMRI data and ``tedana``. - -.. image:: https://user-images.githubusercontent.com/7406227/40031156-57b7cbb8-57bc-11e8-8c51-5b29f2e86a48.png - :target: http://tedana.readthedocs.io/ .. _ME-ICA: https://github.com/me-ica/me-ica -.. _fmriprep: https://github.com/poldracklab/fmriprep/ + Citations --------- diff --git a/docs/pipelines.rst b/docs/pipelines.rst deleted file mode 100644 index a46f347c9..000000000 --- a/docs/pipelines.rst +++ /dev/null @@ -1,24 +0,0 @@ -ME-EPI preprocessing -==================== - -tedana must be called in the context of a larger ME-EPI preprocessing pipeline. -Two common pipelines which support ME-EPI processing include `fMRIPrep`_ and `afni_proc.py`_. - -.. _fMRIPrep: https://fmriprep.readthedocs.io -.. _afni_proc.py: https://afni.nimh.nih.gov/pub/dist/doc/program_help/afni_proc.py.html - -Users can also construct their own preprocessing pipeline for ME-EPI data from which to call tedana. -Any constructed pipeline must include the following steps: - -#. Slice time correction ------------------------- - -Similarly to single-echo EPI data, slice time correction allows use to assume that voxels across -slices represent roughly simultaneous events. -This must be done before multi-echo denoising because slice timing differences might cause problems -with the echo-dependent estimates. - -The slice time is generally defined as the excitation pulse time for each slice. -For single-echo EPI data, that excitation time would be the same regardless of the echo time, -and the same is true when one is collecting multiple echoes after a single excitation pulse. -Therefore, we suggest using the same slice timing for all echoes. diff --git a/docs/usage.rst b/docs/usage.rst index e02b3608e..848de21a9 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -12,8 +12,8 @@ But you can supply many other options, viewable with ``tedana -h`` or For most use cases, we recommend that users call tedana from within existing fMRI preprocessing pipelines such as `fMRIPrep`_ or `afni_proc.py`_.. Users can also construct their own preprocessing pipelines from which to call tedana; -for more information on doing so, see the documentation on -:doc:`ME-EPI preprocessing pipelines `. +for recommendations on doing so, see our general guidelines for +:ref:`_constructing ME-EPI pipelines`. .. _fMRIPrep: https://fmriprep.readthedocs.io .. _afni_proc.py: https://afni.nimh.nih.gov/pub/dist/doc/program_help/afni_proc.py.html @@ -48,3 +48,56 @@ documentation: :py:func:`tedana.workflows.t2smap_workflow`. :ref: tedana.workflows.t2smap._get_parser :prog: t2smap :func: _get_parser + + +.. _constructing ME-EPI pipelines: + +Constructing ME-EPI pipelines +----------------------------- + +``tedana`` must be called in the context of a larger ME-EPI preprocessing pipeline. +Two common pipelines which support ME-EPI processing include `fMRIPrep`_ and `afni_proc.py`_. + +.. _fMRIPrep: https://fmriprep.readthedocs.io +.. _afni_proc.py: https://afni.nimh.nih.gov/pub/dist/doc/program_help/afni_proc.py.html + +Users can also construct their own preprocessing pipeline for ME-EPI data from which to call ``tedana``. +There are several general principles to consider when constructing ME-EPI processing pipelines +for use with ``tedana``: + +#. Calculating slice time correction for ME-EPI +``````````````````````````````````````````````` + +Similarly to single-echo EPI data, slice time correction allows us to assume that voxels across +slices represent roughly simultaneous events. +If the TR is slow enough to necessitate slice-timing (i.e., TR >= 1 sec., as a rule of thumb), then +slice-timing correction should be done before ``tedana``. +This is because slice timing differences may impact echo-dependent estimates. + +The slice time is generally defined as the excitation pulse time for each slice. +For single-echo EPI data, that excitation time would be the same regardless of the echo time, +and the same is true when one is collecting multiple echoes after a single excitation pulse. +Therefore, we suggest using the same slice timing for all echoes in an ME-EPI series. + +#. Avoid applying individual transformations to each echo +````````````````````````````````````````````````````````` + +When preparing ME-EPI data for multi-echo denoising as in ``tedana``, it is important +not to do anything that mean shifts the data or otherwise separately +scales the voxelwise values at each echo. + +For example, head-motion correction parameters should *not* be calculated and applied at an +individual echo level. +Instead, we reccommend that researchers apply the same transforms to all echoes in an ME-EPI series. +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.