Programs · tedana

t2smap

Original
tedana 26.0.3
Command line
larmorx tedana t2smap
Python
lx.tedana.t2smap
Ports
  • replica larmorx-gpl GNU GPL version 3 experimental
  • clean room larmorx Apache-2.0 experimental
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

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

text
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

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,
) -> T2smapResult

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

python
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")
bash
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-cr

Inputs 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 N
n_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-room
implementation="auto"
The variable LARMORX_IMPLEMENTATION in 0.1.0rc1.
--upstream-defects fix|reproduce
upstream_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.

python
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)
bash
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-curvefit

Ports

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 (package larmorx-gpl, under the GNU GPL version 3 only: tedana’s LGPL-2.1 converted under its section 3; its provenance in crates-gpl/larmorx-gpl-tedana/PROVENANCE.md), bit-exact, run as a separate program;
  • the clean room, crates/larmorx-tedana in the main package (Apache-2.0, written from specs/t2smap.md by 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 by lx.tedana.t2smap and larmorx tedana t2smap since 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). Its reproduce gives 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: there reproduce computes them with the main package’s exact ports of numpy’s lstsq and SciPy’s curve_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: