Using tedana from the command line

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, ica_reclassify -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. In the meantime, if you plan to use fMRIPrep and tedana together, please see [tedana] How do I use tedana with fMRIPrepped data?.

Users can also construct their own preprocessing pipelines from which to call tedana; for recommendations on doing so, see our general guidelines for Processing multi-echo fMRI.

Running the tedana workflow

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] [--prefix PREFIX] [--convention {orig,bids}]
              [--masktype {dropout,decay,none} [{dropout,decay,none} ...]]
              [--fittype {loglin,curvefit}] [--combmode {t2s}]
              [--tedpca TEDPCA] [--tree TREE] [--external EXTERNAL_REGRESSORS]
              [--ica-method {robustica,fastica}] [--seed INT]
              [--n-robust-runs [5-500]] [--maxit INT] [--maxrestart INT]
              [--tedort] [--gscontrol {mir,gsr} [{mir,gsr} ...]]
              [--no-reports] [--png-cmap PNG_CMAP] [--verbose] [--lowmem]
              [--n-threads N_THREADS] [--debug] [--t2smap FILE] [--mix FILE]
              [--overwrite] [-v]

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.

--prefix

Prefix for filenames generated.

Default: ''

--convention

Possible choices: orig, bids

Filenaming convention. bids will use the latest BIDS derivatives version.

Default: 'bids'

--masktype

Possible choices: dropout, decay, none

Method(s) by which to define the adaptive mask.

Default: ['dropout']

--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: 'loglin'

--combmode

Possible choices: t2s

Combination scheme for TEs: t2s (Posse 1999)

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. ‘kundu’ or ‘kundu-stabilize’ are selection methods that were distributed with MEICA. Users may also provide a float from 0 to 1, in which case components will be selected based on the cumulative variance explained or an integer greater than 1 in which case the specificed number of components will be selected.

Default: aic

--tree

Decision tree to use. You may use a packaged tree (tedana_orig, meica, minimal) or supply a JSON file which matches the decision tree file specification. Minimal still being tested with more details in docs

Default: 'tedana_orig'

--external

File containing external regressors to compare to ICA component be used in the decision tree. For example, to identify components fit head motion time series. The file must be a TSV file with the same number of rows as the number of volumes in the input data. Column labels and statistical tests are defined with external_labels.

--ica-method, --ica_method

Possible choices: robustica, fastica

The applied ICA method. fastica runs FastICA from sklearn once with the seed value. robustica will run FastICA n_robust_runs times and uses clustering methods to overcome the randomness of the FastICA algorithm. robustica will be slower.

Default: fastica

--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. This applies to both fastica and robustica methods.

Default: 42

--n-robust-runs, --n_robust_runs

The number of times robustica will run. This is only effective when ica_method is set to robustica.

Default: 30

--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. This argument can be single value or a space delimited list.

Default: ''

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

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

--overwrite, -f

Force overwriting of files.

Default: False

-v, --version

show program’s version number and exit

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 the ica_reclassify workflow

ica_reclassify takes the output of tedana and can be used to manually reclassify components, re-save denoised classifications following the new classifications, and log the changes in all relevant output files. The output files are the same as for tedana: https://tedana.readthedocs.io/en/latest/outputs.html

usage: ica_reclassify [-h] [--manacc MANUAL_ACCEPT [MANUAL_ACCEPT ...]]
                      [--manrej MANUAL_REJECT [MANUAL_REJECT ...]]
                      [--config CONFIG] [--out-dir PATH] [--prefix PREFIX]
                      [--convention {orig,bids}] [--tedort] [--mir]
                      [--no-reports] [--png-cmap PNG_CMAP] [--debug]
                      [--overwrite] [-v]
                      registry

Required Arguments

registry: File registry from a previous tedana run

Named Arguments

--manacc

Component indices to accept (zero-indexed).Supply as a comma-delimited list with no spaces, as a csv file, or as a text file with an allowed delimiter (’t’, ‘n’, ‘ ‘, ‘,’).

Default: []

--manrej

Component indices to reject (zero-indexed).Supply as a comma-delimited list with no spaces, as a csv file, or as a text file with an allowed delimiter (’t’, ‘n’, ‘ ‘, ‘,’).

Default: []

--config

File naming configuration.

Default: 'auto'

--out-dir

Output directory.

Default: '.'

--prefix

Prefix for filenames generated.

Default: ''

--convention

Possible choices: orig, bids

Filenaming convention. bids will use the latest BIDS derivatives version.

Default: 'bids'

--tedort

Orthogonalize rejected components w.r.t. accepted components prior to denoising.

Default: False

--mir

Run minimum image regression.

Default: False

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

--debug

Logs in the terminal will have increased verbosity, and will also be written into a .tsv file in the output directory.

Default: False

--overwrite, -f

Force overwriting of files.

Default: False

-v, --version

show program’s version number and exit

Running the t2smap workflow

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] [--prefix PREFIX] [--convention {orig,bids}]
              [--masktype {dropout,decay,none} [{dropout,decay,none} ...]]
              [--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.

--prefix

Prefix for filenames generated.

Default: ''

--convention

Possible choices: orig, bids

Filenaming convention. bids will use the latest BIDS derivatives version.

Default: 'bids'

--masktype

Possible choices: dropout, decay, none

Method(s) by which to define the adaptive mask.

Default: ['dropout']

--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: '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), 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: 1