Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[DOC] Add information about using tedana with fMRIPrep v21.0.0 #847

Merged
merged 6 commits into from
Jul 6, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
.DS_Store
docs/generated/
.pytest_cache/

Expand Down
4 changes: 2 additions & 2 deletions docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -161,14 +161,14 @@ def setup(app):

# The following is used by sphinx.ext.linkcode to provide links to github
linkcode_resolve = make_linkcode_resolve(
"tedana", "https://github.com/me-ica/" "tedana/blob/{revision}/" "{package}/{path}#L{lineno}"
"tedana", "https://github.com/me-ica/tedana/blob/{revision}/{package}/{path}#L{lineno}"
)

# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {
"python": ("https://docs.python.org/3/", None),
"numpy": ("https://numpy.org/doc/stable/", None),
"scipy": ("https://docs.scipy.org/doc/scipy/reference/", None),
"scipy": ("https://docs.scipy.org/doc/scipy/", None),
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was getting the following when I built the docs locally:

intersphinx inventory has moved: https://docs.scipy.org/doc/scipy/reference/objects.inv -> https://docs.scipy.org/doc/scipy/objects.inv

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems like either now work, so I'm fine with this as-is !

"matplotlib": ("https://matplotlib.org/", None),
"nibabel": ("https://nipy.org/nibabel/", None),
"pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
Expand Down
42 changes: 33 additions & 9 deletions docs/faq.rst
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,26 @@ FAQ
[tedana] How do I use tedana with fMRIPrepped data?
***************************************************

`fMRIPrep`_ outputs the preprocessed, optimally-combined fMRI data, rather than echo-wise data.
fMRIPrep versions >= 21.0.0
===========================

Starting with version 21.0.0, `fMRIPrep`_ added the ``--me-output-echos`` argument,
which outputs individual echoes after slice timing, motion correction, and distortion correction have been performed.
These preprocessed echoes can be denoised with tedana,
after which warps written out by fMRIPrep can be applied to transform the denoised data to standard space.

As the fMRIPrep outputs become more formalized,
it is possible to write functions that can select the appropriate derivative files and run tedana on them.
Below is one example of such a function.

.. raw:: html

<script src="https://gist.github.com/jbdenniso/73ec8281229d584721563a41aba410cf.js"></script>

fMRIPrep versions < 21.0.0
==========================

Prior to version 21.0.0, `fMRIPrep`_ outputted the preprocessed, optimally-combined fMRI data, rather than echo-wise data.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Technically, it could also output preprocessed, individual echos using the --echo-idx option. It might be worth bringing this up only in that previously, folks might have thought they could use those echos in tedana (which we tried to discourage).

This means that you cannot use the standard fMRIPrep outputs with tedana for multi-echo denoising.

However, as long as you still have access to fMRIPrep's working directory,
Expand All @@ -24,18 +43,23 @@ Unfortunately, fMRIPrep's working directory structure is not stable across versi
so writing code to grab the relevant files from the working directory is a bit of a moving target.
Nevertheless, we have some code (thanks to Julio Peraza) that works for version 20.2.1.

.. warning::
We will try to keep the following gist up-to-date, but there is no guarantee that it will work for a given version.
Use it with caution!

If you do find that the gist isn't working for an fMRIPrep version >= 20.2.1,
please comment on `Issue #717 <https://github.com/ME-ICA/tedana/issues/717>`_ (even if it's closed)
and we will take a look at the problem.

Comment on lines -27 to -34
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Given that fMRIPrep added an option to output individual echoes, we don't really need to keep the gist up to date.

.. raw:: html

<script src="https://gist.github.com/tsalo/83828e0c1e9009f3cbd82caed888afba.js"></script>

Warping scanner-space fMRIPrep outputs to standard space
========================================================

Here is a basic approach to normalizing scanner-space tedana-denoised data created from fMRIPrep outputs,
using ANTS's antsApplyTransforms tool.
The actual filenames of fMRIPrep derivatives depend on the filenames in the BIDS dataset
(e.g., the name of the task, run numbers, etc.),
but in this example we chose to use the simple example of "sub-01" and "task-rest".
The standard space template in this example is "MNI152NLin2009cAsym", but will depend on fMRIPrep settings in practice.

.. raw:: html

<script src="https://gist.github.com/tsalo/f9f38e9aba901e99ddb720465bb5222b.js"></script>

************************************
[tedana] ICA has failed to converge.
Expand Down