Programs · tedana
t2smap
- Original
- tedana 26.0.3
- Command line
larmorx tedana t2smap- Python
lx.tedana.t2smap- Ports
- replica
larmorx-gplGNU GPL version 3 experimental - clean room
larmorxApache-2.0 experimental
- replica
- Evidence
- every comparison with tedana
- Source
- made from docs/api/tedana-t2smap.md and the code
What it does
t2smap estimates the T2* and S0 of multi-echo fMRI voxel by voxel and combines the echoes into
one series.
Command line
larmorx tedana 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]Everything after larmorx tedana t2smap is the original’s command line: the arguments of tedana 26.0.3’s t2smap, as tedana takes them. LARMORX’s own options stand between larmorx and the family tedana, so they never meet the original’s (below):
larmorx
[--n-threads N]
[--implementation auto|replica|clean-room]
[--upstream-defects fix|reproduce]
tedana t2smap ...From the next release. In 0.1.0rc1, set the variables instead: OMP_NUM_THREADS, LARMORX_IMPLEMENTATION (original for the clean room) and LARMORX_UPSTREAM_DEFECTS.
Python
lx.tedana.t2smap(
echoes: Any,
echo_times: Sequence[float],
*,
mask: Any = None,
masktype: MaskType | Sequence[MaskType] = "dropout",
fittype: FitType = "loglin",
fitmode: FitMode = "all",
combmode: CombMode = "t2s",
dummy_scans: int = 0,
exclude: str | Sequence[int] | None = None,
n_independent_echos: int | None = None,
convention: Convention = "bids",
prefix: str = "",
verbose: bool = False,
debug: bool = False,
quiet: bool = False,
out_dir: str | os.PathLike[str] | None = None,
overwrite: bool = False,
libraries: Libraries = "newest",
implementation: ImplementationName = "auto",
upstream_defects: UpstreamDefectsName = "fix",
n_threads: int = 1,
) -> T2smapResultWhere MaskType is one of "dropout", "decay", "none"; FitType is one of "loglin", "curvefit"; FitMode is one of "all", "ts"; CombMode is one of "t2s", "paid"; Convention is one of "bids", "orig"; Libraries is one of "newest", "shared"; ImplementationName is one of "auto", "replica", "clean-room", "original" (0.1.0rc1’s spelling of "clean-room"); UpstreamDefectsName is one of "fix", "reproduce".
tedana’s t2smap: the T2* and S0 maps of the multi-echo series echoes (one image per echo, in ascending order of echo_times, -d; or one path of a z-concatenated file, the echoes stacked along the third axis, which tedana deprecates) and their optimal combination.
import larmorx as lx
# fMRIPrep's call: three echoes, their times (seconds, or ms as fMRIPrep passes them), a mask
res = lx.tedana.t2smap(
["echo-1_bold.nii.gz", "echo-2_bold.nii.gz", "echo-3_bold.nii.gz"],
[0.014, 0.02996, 0.04592],
mask="brainmask_dilated.nii.gz",
fittype="curvefit",
)
res.t2star # lx.Image, the full T2* map in seconds (fMRIPrep's)
res.optcom # lx.Image, the optimally combined series (fMRIPrep's)
res.adaptive_mask # int32: the number of good echoes per voxel
res.fit_failures # uint8: the voxels whose curve fit failed (they keep the log-linear estimate)
res.confounds["rmse_mean"] # the fit's error per volume
# tedana's defaults (log-linear fit), the files kept, tedana's original names
res = lx.tedana.t2smap(echoes, tes, mask=mask, out_dir="derivatives/t2smap", convention="orig")larmorx tedana t2smap -d echo-1.nii.gz echo-2.nii.gz echo-3.nii.gz -e 14.0 29.96 45.92 \
--mask mask.nii.gz --fittype curvefit --out-dir t2smap
larmorx --implementation clean-room --n-threads 8 tedana t2smap -d echo-1.nii.gz \
echo-2.nii.gz echo-3.nii.gz -e 14.0 29.96 45.92 --mask mask.nii.gz --out-dir t2smap-crInputs are paths or in-memory images (an lx.Image, a nibabel image, an (array, affine) pair),
written as NIfTI-1 in their own data type to the call’s temporary directory. The files are written
to a temporary directory and read back, unless out_dir is given (then they stay there, and
tedana refuses to overwrite an existing one unless overwrite=True). The result is a
T2smapResult: t2star, s0, t2star_limited, s0_limited, optcom, adaptive_mask,
rmse (images carrying implementation), confounds (the table’s columns as float64 arrays,
NaN for tedana’s n/a), fit_failures, t2star_variance, s0_variance,
t2star_s0_covariance (or None), dataset_description, files (tedana’s registry: each
file’s name by its description), out_dir, log (tedana’s log, its standard error without
larmorx’s notice lines) and implementation (the larmorx-gpl replica, or the clean room:
Implementation(kind="clean-room", package="larmorx", ...)). A run of the replica that fails
raises ReplicaError (a RuntimeError) with tedana’s messages and exit status; one of the clean
room a RuntimeError with the same messages.
Its result, T2smapResult, holds what t2smap wrote, read back.
| Field | Type | What it holds |
|---|---|---|
t2star |
Image |
The full T2* map in seconds (T2starmap): every voxel of the mask, from the echoes the adaptive mask keeps (at least two). fMRIPrep’s T2* map. |
s0 |
Image |
The full S0 map (S0map). |
t2star_limited |
Image |
The limited maps (desc-limited_T2starmap, desc-limited_S0map): 0 where fewer than two echoes have good signal; the T2* map’s outliers capped (above ten times its 99.5th percentile). |
s0_limited |
Image |
The limited maps (desc-limited_T2starmap, desc-limited_S0map): 0 where fewer than two echoes have good signal; the T2* map’s outliers capped (above ten times its 99.5th percentile). |
optcom |
Image |
The optimally combined series (desc-optcom_bold), every volume (the excluded ones too, not the dummy scans). fMRIPrep’s combined BOLD series. |
adaptive_mask |
Image |
The adaptive mask (desc-adaptiveGoodSignal_mask, int32): per voxel the number of echoes with good signal, 0 outside the mask. |
rmse |
Image |
The fit’s root-mean-square error per voxel (desc-rmse_statmap). |
confounds |
dict[str, np.ndarray] |
The fit’s error per volume (desc-confounds_timeseries.tsv): its columns (rmse_mean, rmse_std, rmse_min, rmse_percentile02 … rmse_max) as float64 arrays, NaN where tedana writes n/a. |
fit_failures |
Image | None |
With fittype="curvefit": the voxels whose monoexponential fit failed (uint8; they keep the log-linear estimate), else None. |
t2star_variance |
Image | None |
With fittype="curvefit" and verbose=True: the fit’s variances and covariance, else None. |
s0_variance |
Image | None |
With fittype="curvefit" and verbose=True: the fit’s variances and covariance, else None. |
t2star_s0_covariance |
Image | None |
With fittype="curvefit" and verbose=True: the fit’s variances and covariance, else None. |
dataset_description |
dict[str, Any] |
dataset_description.json. |
files |
dict[str, str] |
tedana’s output registry: each file’s name (relative to out_dir) by tedana’s description ("t2star img", "combined img", …). |
out_dir |
str | None |
Where the files are, when out_dir was given (else they were removed after reading). |
log |
str |
tedana’s log (its standard error, without larmorx’s notice lines). |
implementation |
_replica.Implementation |
What computed them (Implementation: the larmorx-gpl replica, or larmorx’s clean room). |
Options
Each row joins an option of the original’s command line with the Python argument that does the same. The rows are checked against the code at every test run: the options t2smap accepts (crates/larmorx-tedana/src/cli.rs) and the arguments of lx.tedana.t2smap (python/larmorx/tedana/t2smap.py), whose defaults and descriptions are taken from it. Under each option, in grey, tedana’s own help for it.
t2smap |
Python (lx.tedana.t2smap(...)) |
What |
|---|---|---|
-d FILE [FILE ...] |
echoes (first argument) |
the echoes’ series, in ascending order of echo time; one file is a z-concatenated series (the echoes stacked along the third axis: tedana warns that it is deprecated, issue 1313). NIfTI-1 and -2 (.nii, .nii.gz, pairs), ANALYZE and MGH; other formats nibabel reads (AFNI, MINC, PAR/REC) are refused with a clear message (a documented gap)tedana: “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 TE [TE ...] |
echo_times (second argument) |
the echo times: seconds when all are below 1 (converted to ms, an INFO line), milliseconds when all are at least 1 (tedana’s deprecation warning); otherwise tedana’s ValueErrortedana: “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.” |
--out-dir PATH |
out_dir=None |
the output directory (created, one level); by default the wrapper’s temporary directorytedana: “Output directory.” |
--prefix PREFIX |
prefix="" |
a prefix of every file name (_ appended unless it ends with one)tedana: “Prefix for filenames generated.” |
--convention {orig,bids} |
convention="bids" |
the files’ names: BIDS derivatives 1.5.0, or tedana’s original ones (the API page’s “Outputs”)tedana: “Filenaming convention. “bids” will use the latest BIDS derivatives version.” |
--verbose |
verbose=False |
with curvefit: also the fit’s variance and covariance mapstedana: “Generate intermediate and additional files.” |
--overwrite, -f |
overwrite=False |
overwrite existing files (else an existing output stops the run: RuntimeError)tedana: “Force overwriting of files.” |
--mask FILE |
mask=None |
the analysis mask (its voxels above 0); without one, nilearn’s compute_epi_mask of the first echo (a warning: tedana recommends a mask)tedana: “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 {dropout,decay,none} ... |
masktype="dropout" (one or several) |
the adaptive mask’s methods: dropout (an echo whose mean signal is below a third of a reference voxel’s), decay (signal that stops decaying), nonetedana: “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.” |
--dummy-scans INT |
dummy_scans=0 |
volumes removed from the start (also from the combined series)tedana: “Number of dummy scans to remove from the beginning of the data.” |
--exclude EXCLUDE |
exclude=None (tedana’s text, "0,5:10,15", or volume indices) |
volumes left out of the adaptive mask and the fit, kept in the combination (0-based, ranges end-exclusive; not with --fitmode ts)tedana: “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.” |
--fittype {loglin,curvefit} |
fittype="loglin" |
the fit: log-linear least squares, or the monoexponential curve fit (fMRIPrep’s)tedana: “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.” |
--fitmode {all,ts} |
fitmode="all" |
one fit per voxel over all volumes, or one per voxel and volume (4D maps)tedana: “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.” |
--combmode {t2s,paid} |
combmode="t2s" |
the combination’s weights: TE · exp(-TE / T2*), or PAID’s temporal SNRtedana: “Combination scheme for TEs: “t2s” (Posse 1999), “paid” (Poser)” |
--n-independent-echos INT |
n_independent_echos=None |
the number of independent echoes (EPTI): only tedana’s warnings changetedana: “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.” |
--n-threads INT |
n_threads=1 (0: all logical CPUs, passed as -1) |
threads; tedana’s limit for its BLAS and its curve-fit processes. On the command line, when it is not given, larmorx’s own --n-threads before the family applies (larmorx --n-threads 4 tedana t2smap ...; else OMP_NUM_THREADS, else every logical CPU), not tedana’s default of 1. The replica’s results never depend on it (it gives tedana’s one-thread results; tedana’s own log-linear maps change with BLAS threads in a few voxels’ last bits), nor the clean room’s (the same files at any count)tedana: “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.” |
--debug |
debug=False |
the log at DEBUG level (the help’s TSV log file is never written: tedana’s, kept)tedana: “Logs in the terminal will have increased verbosity, and will also be written into a TSV file in the output directory.” |
--quiet (hidden) |
quiet=False |
the log at WARNING level |
-h, --help |
- | the usage (argparse’s, exit 0)tedana: “show this help message and exit” |
-v, --version |
- | t2smap v26.0.3 (exit 0)tedana: “show program’s version number and exit” |
LARMORX_UPSTREAM_DEFECTS |
upstream_defects="fix" |
"reproduce" gives tedana’s files: bit for bit by the replica (its defects and its maths), and by the clean room with tedana’s defects exactly and its fitted numbers within the spec’s thresholds (§17.3; exactly at TED-46’s voxels) |
LARMORX_TEDANA_LIBRARIES |
libraries="newest" |
the numpy and SciPy whose arithmetic is reproduced: newest (numpy 2.5.4, SciPy 1.18.1) or shared (numpy 2.3.5, SciPy 1.15.3); the curve fit’s last bits differ between them |
LARMORX’s own options
From the next release. In 0.1.0rc1, set the variables instead: OMP_NUM_THREADS, LARMORX_IMPLEMENTATION (original for the clean room) and LARMORX_UPSTREAM_DEFECTS.
They stand between larmorx and tedana on the command line (larmorx --n-threads 4 tedana t2smap ...) and are arguments of lx.tedana.t2smap. Each one given wins over its environment variable, which keeps working.
| Command line, then Python | What it does |
|---|---|
--n-threads Nn_threads=1 |
Default: every logical CPU on the command line (0), 1 in Python. The variable OMP_NUM_THREADS in 0.1.0rc1. |
--implementation auto|replica|clean-roomimplementation="auto" |
The variable LARMORX_IMPLEMENTATION in 0.1.0rc1. |
--upstream-defects fix|reproduceupstream_defects="fix" |
The variable LARMORX_UPSTREAM_DEFECTS in 0.1.0rc1. |
Examples
The tests run every example below (validation/tests/test_reference.py), each section in a new folder where these inputs are made first: echo-1.nii.gz (the first echo of a synthetic multi-echo series: 8 heads of 40 × 48 × 40 voxels of 4 mm), echo-2.nii.gz (the second echo: the first times 0.6), echo-3.nii.gz (the third echo: the first times 0.36), mask.nii.gz (the synthetic head’s brain as a mask (1 inside, 0 outside)). The command lines run as python -m larmorx.
import larmorx as lx
# Three echoes 15 ms apart and a mask: the T2* map and the combined series.
res = lx.tedana.t2smap(
["echo-1.nii.gz", "echo-2.nii.gz", "echo-3.nii.gz"], [0.015, 0.030, 0.045], mask="mask.nii.gz"
)
res.t2star.shape # -> (40, 48, 40)
res.optcom.shape # -> (40, 48, 40, 8)larmorx tedana t2smap -d echo-1.nii.gz echo-2.nii.gz echo-3.nii.gz -e 15 30 45 --mask mask.nii.gz --out-dir t2smap
larmorx tedana t2smap -d echo-1.nii.gz echo-2.nii.gz echo-3.nii.gz -e 15 30 45 --mask mask.nii.gz --fittype curvefit --convention orig --out-dir t2smap-curvefitPorts
t2smap has two ports: a replica and a clean room.
| Port | Package | Licence | Status | Records |
|---|---|---|---|---|
| replica | larmorx-gpl |
GNU GPL version 3 | experimental | tedana-t2smap-replica |
| clean room | larmorx |
Apache-2.0 | experimental | tedana-t2smap-original |
The replica: status experimental, against tedana 26.0.3 (its record,
tedana-t2smap-replica, 2026-11-12, in both library environments):
102 cases, 62 bit-identical (every output file, header, log line and Python warning, the chain of
tracebacks, the exit status and the last error line), 40 rejected by both alike, 0 failures:
fMRIPrep’s four multi-echo calls, every option and path, ANALYZE and MGH inputs and the failure
cases of every defect.
The clean room: status experimental, against tedana 26.0.3 in reproduce and the replica’s
default by default (its record, 2026-11-12, the full
tier): 125 cases, 124 pass, 1 expected divergence (a chaotic curve-fit regime: SciPy’s own
floating-point warnings inside its steps), 0 failures, by the spec’s thresholds (§17.3): every
option, the readers, TED-46’s saturated voxels, thread invariance at 1, 4 and 8 threads, and
fMRIPrep’s six multi-echo calls.
tedana is licensed under the GNU LGPL version 2.1, so t2smap has two ports
(licensing):
- the replica (2026-11-08),
larmorx-gpl tedana t2smap(packagelarmorx-gpl, under the GNU GPL version 3 only: tedana’s LGPL-2.1 converted under its section 3; its provenance incrates-gpl/larmorx-gpl-tedana/PROVENANCE.md), bit-exact, run as a separate program; - the clean room,
crates/larmorx-tedanain the main package (Apache-2.0, written fromspecs/t2smap.mdby implementers who never read tedana’s source or the replica’s code, 2026-11-11; PROVENANCE), built for speed: the log-linear fit per voxel in closed form, its own trust-region curve fit on the per-echo means, deterministic threads (the same files at any--n-threads), every option, message, exit status and defect of the spec; run in this process bylx.tedana.t2smapandlarmorx tedana t2smapsince 2026-11-12 (its own binding,larmorx._core.tedana_t2smap_cleanroom(args, env, cwd): tedana’s arguments, an environment table, the directory;(exit status, standard output, standard error), serves the validation tools). Itsreproducegives tedana’s defects exactly and its fitted numbers within the spec’s thresholds (§17.3), not bit for bit: the replica is the exact one (but at TED-46’s voxels of equal observations, whose values are tedana’s rounding noise: therereproducecomputes them with the main package’s exact ports of numpy’slstsqand SciPy’scurve_fit, since 2026-11-12).
implementation="auto" (the default) runs the replica when larmorx-gpl is installed (pip install larmorx-gpl, or pip install "larmorx[all]"), else the clean room; "replica" runs the
replica or raises ReplicaNotFoundError with that command; "clean-room" ("original",
0.1.0rc1’s spelling, still works, with a DeprecationWarning) runs the clean room. The command
line does the same (--implementation before the family, or LARMORX_IMPLEMENTATION; replica
without the program exits 127 with the command that installs it): larmorx --implementation clean-room tedana t2smap -d ... -e .... The program is found through LARMORX_GPL_BIN, then the
Python environment’s scripts directory, then PATH.
Evidence
How each of t2smap’s ports was measured against tedana, case by case: its evidence.
More in the repository
The API page docs/api/tedana-t2smap.md holds what t2smap shares with the page’s other programs: