Usage¶
tedana minimally requires:
- Acquired echo times (in milliseconds)
- Functional datasets equal to the number of acquired echoes
But you can supply many other options, viewable with tedana -h or
t2smap -h.
For most use cases, we recommend that users call tedana from within existing fMRI preprocessing
pipelines such as fMRIPrep or afni_proc.py.
fMRIPrep currently supports Optimal combination through tedana, but not the full multi-echo
denoising pipeline, although there are plans underway to integrate it.
Users can also construct their own preprocessing pipelines from which to call tedana;
for recommendations on doing so, see our general guidelines for
Constructing ME-EPI pipelines.
Run tedana¶
This is the full tedana workflow, which runs multi-echo ICA and outputs multi-echo denoised data along with many other derivatives. To see which files are generated by this workflow, check out the outputs page: https://tedana.readthedocs.io/en/latest/outputs.html
usage: tedana [-h] -d FILE [FILE ...] -e TE [TE ...] [--mask FILE]
[--mix FILE] [--ctab FILE] [--manacc MANACC] [--sourceTEs STE]
[--combmode {t2s,ste}] [--verbose] [--tedort]
[--gscontrol {t1c,gsr} [{t1c,gsr} ...]] [--wvpca]
[--tedpca {mle,kundu,kundu-stabilize}] [--out-dir OUT_DIR]
[--seed FIXED_SEED]
required arguments¶
| -d | Multi-echo dataset for analysis. May be a single file with spatially concatenated data or a set of echo-specific files, in the same order as the TEs are listed in the -e argument. |
| -e | Echo times (in ms). E.g., 15.0 39.0 63.0 |
Named Arguments¶
| --mask | Binary mask of voxels to include in TE Dependent ANAlysis. Must be in the same space as data. |
| --mix | File containing mixing matrix. If not provided, ME-PCA & ME-ICA is done. |
| --ctab | File containing a component table from which to extract pre-computed classifications. |
| --manacc | Comma separated list of manually accepted components |
| --sourceTEs | Source TEs for models. E.g., 0 for all, -1 for opt. com., and 1,2 for just TEs 1 and 2. Default=-1. Default: -1 |
| --combmode | Possible choices: t2s, ste Combination scheme for TEs: t2s (Posse 1999, default), ste (Poser) Default: “t2s” |
| --verbose | Generate intermediate and additional files. Default: False |
| --tedort | Orthogonalize rejected components w.r.t. accepted components prior to denoising. Default: False |
| --gscontrol | Possible choices: t1c, gsr Perform additional denoising to remove spatially diffuse noise. Default is None. This argument can be single value or a space delimited list |
| --wvpca | Perform PCA on wavelet-transformed data Default: False |
| --tedpca | Possible choices: mle, kundu, kundu-stabilize Method with which to select components in TEDPCA Default: “mle” |
| --out-dir | Output directory. Default: “.” |
| --seed | Value passed to repr(mdp.numx_rand.seed()) Set to an integer value for reproducible ICA results; otherwise, set to -1 for varying results across calls. Default: 42 |
Note
The --mask argument is not intended for use with very conservative region-of-interest
analyses. One of the ways by which components are assessed as BOLD or non-BOLD is their
spatial pattern, so overly conservative masks will invalidate several steps in the tedana
workflow. To examine regions-of-interest with multi-echo data, apply masks after TE
Dependent ANAlysis.
Run t2smap¶
This workflow uses multi-echo data to optimally combine data across echoes and
to estimate T2* and S0 maps or time series.
To see which files are generated by this workflow, check out the workflow
documentation: tedana.workflows.t2smap_workflow().
usage: t2smap [-h] -d FILE [FILE ...] -e TE [TE ...] [--mask FILE]
[--fitmode {all,ts}] [--combmode {t2s,ste}] [--label LABEL]
required arguments¶
| -d | Multi-echo dataset for analysis. May be a single file with spatially concatenated data or a set of echo-specific files, in the same order as the TEs are listed in the -e argument. |
| -e | Echo times (in ms). E.g., 15.0 39.0 63.0 |
Named Arguments¶
| --mask | Binary mask of voxels to include in TE Dependent ANAlysis. Must be in the same space as data. |
| --fitmode | Possible choices: all, ts Monoexponential model fitting scheme. “all” means that the model is fit, per voxel, across all timepoints. “ts” means that the model is fit, per voxel and per timepoint. Default: “all” |
| --combmode | Possible choices: t2s, ste Combination scheme for TEs: t2s (Posse 1999, default), ste (Poser) Default: “t2s” |
| --label | Label for output directory. |
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.
Users can also construct their own preprocessing pipeline for ME-EPI data from which to call tedana.
There are several general principles to keep in mind when constructing ME-EPI processing pipelines.
In general, we recommend
1. Perform slice timing correction and motion correction before tedana¶
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.
2. Perform distortion correction, spatial normalization, smoothing, and any rescaling or filtering after tedana¶
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 recommend 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 approach for more details
on how T2* values are calculated.
Support and communication¶
All bugs, concerns and enhancement requests for this software can be submitted here: https://github.com/ME-ICA/tedana/issues.
If you would like to ask a question about usage or tedana’s outputs, please submit a question to NeuroStars with the multi-echo tag.
All previous tedana-related questions are available under the multi-echo tag.
We will also attempt to archive certain common questions and associate answers in the Frequently Asked Questions (FAQ) section below.
FAQ¶
ICA has failed to converge.¶
The TEDICA step may fail to converge if TEDPCA is either too strict (i.e., there are too few components) or too lenient (there are too many).
In our experience, this may happen when preprocessing has not been applied to the data, or when improper steps have been applied to the data (e.g., distortion correction, rescaling, nuisance regression). If you are confident that your data have been preprocessed correctly prior to applying tedana, and you encounter this problem, please submit a question to NeuroStars.
I think that some BOLD ICA components have been misclassified as noise.¶
tedana allows users to manually specify accepted components when calling the pipeline.
You can use the --manacc argument to specify the indices of components to accept.
Why isn’t v3.2 of the component selection algorithm supported in tedana?¶
There is a lot of solid logic behind the updated version of the TEDICA component
selection algorithm, first added to the original ME-ICA codebase here by Dr. Prantik Kundu.
However, we (the tedana developers) have encountered certain difficulties
with this method (e.g., misclassified components) and the method itself has yet
to be validated in any papers, posters, etc., which is why we have chosen to archive
the v3.2 code, with the goal of revisiting it when tedana is more stable.
Anyone interested in using v3.2 may compile and install an earlier release (<=0.0.4) of tedana.