Usage

tedana minimally requires:

  1. acquired echo times (in milliseconds), and
  2. 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.. 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] [--kdaw KDAW]
              [--rdaw RDAW] [--conv CONV] [--sourceTEs STE]
              [--combmode {t2s,ste}] [--cost {logcosh,cube,exp}]
              [--denoiseTEs] [--strict] [--no_gscontrol] [--stabilize]
              [--filecsdata] [--wvpca] [--label LABEL] [--seed FIXED_SEED]

Named 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
--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
--kdaw

Dimensionality augmentation weight (Kappa). Default=10. -1 for low-dimensional ICA

Default: 10.0

--rdaw

Dimensionality augmentation weight (Rho). Default=1. -1 for low-dimensional ICA

Default: 1.0

--conv

Convergence limit. Default 2.5e-5

Default: 2.5e-5

--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”

--cost

Possible choices: logcosh, cube, exp

Cost func. for ICA: logcosh (default), cube, exp

Default: “logcosh”

--denoiseTEs

Denoise each TE dataset separately.

Default: False

--strict

Ignore low-variance ambiguous components

Default: False

--no_gscontrol

Disable global signal regression.

Default: True

--stabilize

Stabilize convergence by reducing dimensionality, for low quality data

Default: False

--filecsdata

Save component selection data

Default: False

--wvpca

Perform PCA on wavelet-transformed data

Default: False

--label Label for output directory.
--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]

Named 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
--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. Performing slice timing correction and motion correction before tedana, and

2. Performing distortion correction, spatial normalization, smoothing, and any rescaling or filtering after tedana.

Other suggestions follow below.

3. 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.

4. 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.