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]
[--prefix PREFIX] [--convention {orig,bids}] [--no-reports]
[--png-cmap PNG_CMAP] [--verbose] [--overwrite] [--mask FILE]
[--masktype {dropout,decay,none} [{dropout,decay,none} ...]]
[--dummy-scans INT] [--fittype {loglin,curvefit}]
[--combmode {t2s}] [--t2smap FILE] [--tedpca TEDPCA]
[--tree TREE] [--external FILE]
[--ica-method {robustica,fastica}] [--seed INT]
[--n-robust-runs [5-500]] [--maxit INT] [--maxrestart INT]
[--mix FILE] [--n-independent-echos INT] [--tedort]
[--gscontrol {mir,gsr} [{mir,gsr} ...]] [--lowmem]
[--n-threads INT] [--debug] [-v]
Named Arguments
- -v, --version
show program’s version number and exit
Required Arguments
- -d
Multi-echo dataset for analysis. A set of echo-specific files in ascending order. The TEs of the data should match the TEs listed in the -e argument.
- -e
Ascending echo times in seconds (per BIDS convention). E.g., 0.015 0.039 0.063. Millisecond values (e.g., 15.0 39.0 63.0) are still accepted but deprecated.
Output Control
- --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'- --no-reports
Disables creation of a figures folder with static component maps, timecourse plots, and other diagnostic images. Also disables the generation of a dynamic report.
Default:
False- --png-cmap
Colormap for figures.
Default:
'coolwarm'- --verbose
Generate intermediate and additional files.
Default:
False- --overwrite, -f
Force overwriting of files.
Default:
False
Temporal and Spatial Masking
- --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. Providing a mask is recommended.
- --masktype
Possible choices: dropout, decay, none
Method(s) by which to define the adaptive mask. The adaptive mask starts with the mask from ‘–mask’, when provided. It identifies voxels that have good data in all vs a subset of echoes. “dropout” removes voxels with much lower voxels than other voxels within each echo. “decay” removes voxels where the raw signal does not decay across echoes. Users can specify one, both, or neither of the models.
Default:
['dropout']- --dummy-scans
Number of dummy scans to remove from the beginning of the data.
Default:
0
Decay Model Fitting and Optimal Combination
- --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'- --t2smap
Precalculated T2* map in the same space as the input data. Values should be in seconds (per BIDS convention). Maps in milliseconds are auto-detected and handled with a warning.
Component Selection
- --tedpca
Method by which to select number of components in TEDPCA. This can be one of the following: String (“mdl”, “kic”, “aic”, “kundu”, or “kundu-stabilize”); floating-point value in the range (0.0, 1.0); positive integer value. PCA decomposition with the mdl, kic and aic options are based on a Moving Average (stationary Gaussian) process, and are ordered from most to least aggressive. “kundu” or “kundu-stabilize” are legacy selection methods that were distributed with MEICA. Floating-point inputs select components based on the cumulative variance explained. Integer inputs select the specified number of components. Default: “aic”.
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- --mix
File containing mixing matrix. If not provided, ME-PCA & ME-ICA is done.
- --n-independent-echos
Number of independent echoes to use in goodness of fit metrics (fstat). Primarily used for EPTI acquisitions, which have dependency across echoes. If not provided, number of echoes will be used.
Additional Denoising Options
- --tedort
Orthogonalize rejected components w.r.t. accepted components prior to denoising. This is a conservative option where shared variance between accepted and rejected components will be retained in the denoised data.
Default:
False- --gscontrol
Possible choices: mir, gsr
Perform additional denoising to remove spatially diffuse noise. “gsr” regresses out the global signal of all voxels in the mask. “mir” is Minimum Image Regression with the goal of reducing T1-like effects. The positive and negative effects of using these options are unclear. This argument can be a single value or a space-delimited list.
Default:
''
Performance Control
- --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
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 INT [INT ...]] [--manrej INT [INT ...]]
[--tagacc TAG [TAG ...]] [--tagrej TAG [TAG ...]]
[--config CONFIG] [--out-dir PATH] [--prefix PREFIX]
[--convention {orig,bids}] [--no-reports]
[--png-cmap PNG_CMAP] [--verbose] [-f]
[--dummy-scans INT] [--tedort]
[--gscontrol {gsr,mir} [{gsr,mir} ...]]
[--n-threads INT] [--debug] [-v]
FILE
Named Arguments
- -v, --version
show program’s version number and exit
Required Arguments
- FILE
File registry from a previous tedana run.
Component Selection
- --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:
[]- --tagacc
Classification tag(s) to add to accepted components. Will be applied to all listed accepted components, even if they were already accepted. Supply a single tag or a comma-delimited list.
Default:
[]- --tagrej
Classification tag(s) to add to rejected components. Will be applied to all listed rejected components, even if they were already rejected. Supply a single tag or a comma-delimited list.
Default:
[]
Output Control
- --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'- --no-reports
Disables creation of a figures folder with static component maps, timecourse plots, and other diagnostic images. Also disables the generation of a dynamic report.
Default:
False- --png-cmap
Colormap for figures.
Default:
'coolwarm'- --verbose
Generate intermediate and additional files.
Default:
False- -f, --overwrite
Force overwriting of files.
Default:
False
Temporal and Spatial Masking
- --dummy-scans
Number of dummy scans to remove from the beginning of the data.
Default:
0
Additional Denoising Options
- --tedort
Orthogonalize rejected components w.r.t. accepted components prior to denoising. This is a conservative option where shared variance between accepted and rejected components will be retained in the denoised data.
Default:
False- --gscontrol
Possible choices: gsr, mir
Perform additional denoising to remove spatially diffuse noise. “gsr” regresses out the global signal of all voxels in the mask. “mir” is Minimum Image Regression with the goal of reducing T1-like effects. The positive and negative effects of using these options are unclear. This argument can be a single value or a space-delimited list.
Default:
''
Performance Control
- --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
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]
[--prefix PREFIX] [--convention {orig,bids}] [--verbose]
[--overwrite] [--mask FILE]
[--masktype {dropout,decay,none} [{dropout,decay,none} ...]]
[--dummy-scans INT] [--exclude EXCLUDE]
[--fittype {loglin,curvefit}] [--fitmode {all,ts}]
[--combmode {t2s,paid}] [--n-independent-echos INT]
[--n-threads INT] [--debug] [-v]
Named Arguments
- -v, --version
show program’s version number and exit
Required Arguments
- -d
Multi-echo dataset for analysis. A set of echo-specific files in ascending order. The TEs of the data should match the TEs listed in the -e argument.
- -e
Ascending echo times in seconds (per BIDS convention). E.g., 0.015 0.039 0.063. Millisecond values (e.g., 15.0 39.0 63.0) are still accepted but deprecated.
Output Control
- --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'- --verbose
Generate intermediate and additional files.
Default:
False- --overwrite, -f
Force overwriting of files.
Default:
False
Temporal and Spatial Masking
- --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. Providing a mask is recommended.
- --masktype
Possible choices: dropout, decay, none
Method(s) by which to define the adaptive mask. The adaptive mask starts with the mask from ‘–mask’, when provided. It identifies voxels that have good data in all vs a subset of echoes. “dropout” removes voxels with much lower voxels than other voxels within each echo. “decay” removes voxels where the raw signal does not decay across echoes. Users can specify one, both, or neither of the models.
Default:
['dropout']- --dummy-scans
Number of dummy scans to remove from the beginning of the data.
Default:
0- --exclude
Volume indices to exclude from adaptive mask generation and T2* and S0 estimation, but which will be retained in the optimally combined data. Can be individual indices (e.g., ‘0,5,10’), ranges (e.g., ‘5:10’), or a mix of the two (e.g., ‘0,5:10,15’). Indices are 0-based. As in Python lists, ranges are start-inclusive and end-exclusive (for example, ‘0:5’ includes the first [0] through fifth [4] timepoints). Default is to not exclude any volumes.
Decay Model Fitting and Optimal Combination
- --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'
Component Selection
- --n-independent-echos
Number of independent echoes to use in goodness of fit metrics (fstat). Primarily used for EPTI acquisitions, which have dependency across echoes. If not provided, number of echoes will be used.
Performance Control
- --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