Using tedana¶
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.
Running 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 ...] [--out-dir PATH]
[--mask FILE] [--fittype {loglin,curvefit}] [--combmode {t2s}]
[--tedpca TEDPCA] [--seed INT] [--maxit INT] [--maxrestart INT]
[--tedort] [--gscontrol {mir,gsr} [{mir,gsr} ...]]
[--no-reports] [--png-cmap PNG_CMAP] [--verbose] [--lowmem]
[--n-threads N_THREADS] [--debug] [-v] [--t2smap FILE]
[--mix FILE] [--ctab FILE] [--manacc INT [INT ...]]
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¶
- --out-dir
Output directory.
Default: “.”
- --mask
Binary mask of voxels to include in TE Dependent ANAlysis. Must be in the same space as data. If an explicit mask is not provided, then Nilearn’s compute_epi_mask function will be used to derive a mask from the first echo’s data.
- --fittype
Possible choices: loglin, curvefit
Desired T2*/S0 fitting method. “loglin” means that a linear model is fit to the log of the data. “curvefit” means that a more computationally demanding monoexponential model is fit to the raw data. Default is “loglin”.
Default: “loglin”
- --combmode
Possible choices: t2s
Combination scheme for TEs: t2s (Posse 1999, default)
Default: “t2s”
- --tedpca
Method with which to select components in TEDPCA. PCA decomposition with the mdl, kic and aic options is based on a Moving Average (stationary Gaussian) process and are ordered from most to least aggressive. Users may also provide a float from 0 to 1, in which case components will be selected based on the cumulative variance explained. Default=’mdl’.
Default: mdl
- --seed
Value used for random initialization of ICA algorithm. Set to an integer value for reproducible ICA results. Set to -1 for varying results across ICA calls. Default=42.
Default: 42
- --maxit
Maximum number of iterations for ICA.
Default: 500
- --maxrestart
Maximum number of attempts for ICA. If ICA fails to converge, the fixed seed will be updated and ICA will be run again. If convergence is achieved before maxrestart attempts, ICA will finish early.
Default: 10
- --tedort
Orthogonalize rejected components w.r.t. accepted components prior to denoising.
Default: False
- --gscontrol
Possible choices: mir, gsr
Perform additional denoising to remove spatially diffuse noise. Default is None. This argument can be single value or a space delimited list
- --no-reports
Creates a figures folder with static component maps, timecourse plots and other diagnostic images and displays these in an interactive reporting framework
Default: False
- --png-cmap
Colormap for figures
Default: “coolwarm”
- --verbose
Generate intermediate and additional files.
Default: False
- --lowmem
Enables low-memory processing, including the use of IncrementalPCA. May increase workflow duration.
Default: False
- --n-threads
Number of threads to use. Used by threadpoolctl to set the parameter outside of the workflow function. Higher numbers of threads tend to slow down performance on typical datasets. Default is 1.
Default: 1
- --debug
Logs in the terminal will have increased verbosity, and will also be written into a .tsv file in the output directory.
Default: False
- -v, --version
show program’s version number and exit
Arguments for Rerunning the Workflow¶
- --t2smap
Precalculated T2* map in the same space as the input 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
List of manually accepted components.
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.
Running 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 ...] [--out-dir PATH]
[--mask FILE] [--fittype {loglin,curvefit}] [--fitmode {all,ts}]
[--combmode {t2s,paid}] [--n-threads N_THREADS]
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¶
- --out-dir
Output directory.
Default: “.”
- --mask
Binary mask of voxels to include in TE Dependent ANAlysis. Must be in the same space as data.
- --fittype
Possible choices: loglin, curvefit
Desired Fitting Method”loglin” means that a linear model is fit to the log of the data, default”curvefit” means that a more computationallydemanding monoexponential model is fitto the raw data
Default: “loglin”
- --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, paid
Combination scheme for TEs: t2s (Posse 1999, default), paid (Poser)
Default: “t2s”
- --n-threads
Number of threads to use. Used by threadpoolctl to set the parameter outside of the workflow function. Higher numbers of threads tend to slow down performance on typical datasets. Default is 1.
Default: 1
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.
Note
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 or incorrect.
See the description of tedana
’s approach for more details
on how T2* values are calculated.