Monoexp T2 - qmrust

Config name: model: mono_t2 BIDS suffix; MESE Method family; T2 Relaxometry Acquired volumes; 30 Fit granularity; voxelwise

Fits the transverse relaxation time T2 from a multi-echo spin-echo series as a mono-exponential decay with a free amplitude. The fit runs either as a log-linear least-squares solve or as a bounded non-linear exponential fit, optionally dropping the first echo — commonly contaminated by stimulated-echo effects — or adding a constant offset term to absorb noise-floor bias.

Signal model¶

S(\mathrm{TE}) = M_0\,\exp\!\left(-\mathrm{TE}/T_2\right)

(1)

Symbol	Quantity	Unit
`T2`	Transverse relaxation time	s
`M0`	Signal amplitude at TE = 0 (arbitrary units)	—

What the model reads¶

A series of 30 volumes indexed by EchoTime. Volumes are matched to these identities by value, so reordering the acquisition yields an identical fit.

#	EchoTime
1	0.0128
2	0.0256
3	0.0384
4	0.0512
5	0.064
6	0.0768
7	0.0896
8	0.1024
9	0.1152
10	0.128
11	0.1408
12	0.1536
13	0.1664
14	0.1792
15	0.192
16	0.2048
17	0.2176
18	0.2304
19	0.2432
20	0.256
21	0.2688
22	0.2816
23	0.2944
24	0.3072
25	0.32
26	0.3328
27	0.3456
28	0.3584
29	0.3712
30	0.384

Where the protocol comes from¶

In a BIDS dataset these values are resolved for you:

Protocol parameter	Source	Key	Resolved
`EchoTime`	sidecar field	`EchoTime`	per volume

Inputs¶

Figure 1:The 30 acquired volumes, each labeled with the identity the model reads it by.

Figure 2:Auxiliary maps and the mask applied to this fit.

Outputs¶

Map	BIDS suffix	Unit	Fit bounds	Fitted
`T2`	`T2map`	s	0.001 … 0.3	free
`M0`	`M0map`	—	1 … 10000	free

Figure 3:Fitted maps for one example subject.

Usage¶

BIDS

Without BIDS

Simulation

Browser

The acquisition comes from the sidecars, so recipes/bids/mono_t2_config.yaml carries only algorithm options:

model: mono_t2

# BIDS input: EchoTime is read from the JSON sidecars via the model's
# protocol_schema(), so the echo-time list is NOT declared here.

# Algorithm options (always used; not BIDS metadata).
fit_type: exponential
drop_first_echo: false
offset_term: false

# BIDS mask selection — disambiguates which mask in the dataset to apply.
mask:
  desc: brain

qmrust fit --bids-dir ds-mydata \
  --config recipes/bids/mono_t2_config.yaml --output-dir out

Fitted maps are written as BIDS derivatives:

out/derivatives/qmrust/sub-01/anat/
  sub-01_T2map.nii.gz
  sub-01_T2map.json
  sub-01_M0map.nii.gz
  sub-01_M0map.json

No sidecars, so recipes/non-bids/mono_t2_config.yaml declares the acquisition itself:

model: mono_t2

# non-BIDS: protocol from this file; mask via --mask/--nii-mask.
# All times are in seconds (BIDS/SI). qMRLab mono_t2 default protocol:
# 30 spin echoes, 12.8 ms spacing (12.8..384 ms).
echo_times:
- 0.0128
- 0.0256
- 0.0384
- 0.0512
- 0.064
- 0.0768
- 0.0896
- 0.1024
- 0.1152
- 0.128
- 0.1408
- 0.1536
- 0.1664
- 0.1792
- 0.192
- 0.2048
- 0.2176
- 0.2304
- 0.2432
- 0.256
- 0.2688
- 0.2816
- 0.2944
- 0.3072
- 0.32
- 0.3328
- 0.3456
- 0.3584
- 0.3712
- 0.384

# Algorithm options (always used; not BIDS metadata).
fit_type: exponential
drop_first_echo: false
offset_term: false

qmrust fit --data data.nii.gz --mask mask.nii.gz \
  --config recipes/non-bids/mono_t2_config.yaml \
  --output-dir out

See Fitting without BIDS.

model: mono_t2

# Simulation: the acquisition comes from this file. All times are in seconds
# (BIDS/SI). qMRLab mono_t2 default protocol: 30 spin echoes, 12.8 ms spacing.
echo_times:
- 0.0128
- 0.0256
- 0.0384
- 0.0512
- 0.064
- 0.0768
- 0.0896
- 0.1024
- 0.1152
- 0.128
- 0.1408
- 0.1536
- 0.1664
- 0.1792
- 0.192
- 0.2048
- 0.2176
- 0.2304
- 0.2432
- 0.256
- 0.2688
- 0.2816
- 0.2944
- 0.3072
- 0.32
- 0.3328
- 0.3456
- 0.3584
- 0.3712
- 0.384

fit_type: exponential
drop_first_echo: false
offset_term: false

# Ground truth: white matter at 3 T, T2 near 50 ms.
sim:
  params: { T2: 0.05, M0: 1000.0 }
  noise: { type: rician, snr: 100.0 }
  seed: 0
  trials: 100
  sweep: { param: T2, start: 0.01, stop: 0.2, steps: 10 }
  distributions:
    T2: { mean: 0.05, std: 0.01 }

qmrust sim signal       --config recipes/sim/mono_t2_sim.yaml --output signal.json
qmrust sim single-voxel --config recipes/sim/mono_t2_sim.yaml --output sv.json
qmrust sim sensitivity  --config recipes/sim/mono_t2_sim.yaml --output sens.json
qmrust sim montecarlo   --config recipes/sim/mono_t2_sim.yaml --output mc.json

See Simulation.

The same core, compiled to WebAssembly:

import init, { fit_volume } from './pkg/qmrust_wasm.js';
await init();
const maps = fit_volume(configYaml, data, [nx, ny, nz, nt],
                        JSON.stringify(volumeIds), mask, '{}');

Try it on real data in the playground, or read Browser & wasm.

Figure 4:One voxel’s measured data with the model’s forward signal at the fitted parameters. The curve is computed by the same Rust code that does the fitting.

Implementation¶

model.rs — the Model implementation: measurement contract, protocol schema, BIDS outputs.
fit.rs — the numerical fit.
config.rs — configuration and validation.

Every default materialized, as qmrust dump-config prints it.

model: mono_t2
echo_times:
- 0.0128
- 0.0256
- 0.0384
- 0.0512
- 0.064
- 0.0768
- 0.0896
- 0.1024
- 0.1152
- 0.128
- 0.1408
- 0.1536
- 0.1664
- 0.1792
- 0.192
- 0.2048
- 0.2176
- 0.2304
- 0.2432
- 0.256
- 0.2688
- 0.2816
- 0.2944
- 0.3072
- 0.32
- 0.3328
- 0.3456
- 0.3584
- 0.3712
- 0.384
fit_type: exponential
drop_first_echo: false
offset_term: false

References¶

Milford et al. (2015)

References¶

Milford, D., Rosbach, N., Bendszus, M., & Heiland, S. (2015). Mono-exponential fitting in T2-relaxometry: relevance of offset and first echo. PLOS ONE, 10(12), e0145255.