MT Saturation - qmrust

Config name: model: mt_sat BIDS suffix; MTS Method family; Semi-quantitative MT Acquired volumes; 3 Fit granularity; voxelwise

Derives the MT saturation parameter from three spoiled gradient-echo volumes — MT-weighted, PD-weighted and T1-weighted. Unlike MTR, MTsat removes the leading-order dependence on T1 and on transmit-field inhomogeneity, making it far more comparable across sites; supplying a B1 map applies the residual correction. T1 (and optionally MTR) fall out of the same three volumes.

Signal model¶

\delta = \left(\frac{A\,\alpha_\mathrm{MT}}{S_\mathrm{MT}} - 1\right)\frac{\mathrm{TR}_\mathrm{MT}}{T_1} - \frac{\alpha_\mathrm{MT}^{2}}{2}

(1)

Symbol	Quantity	Unit
`A`	Apparent signal amplitude	—
`T1`	Longitudinal relaxation time	s
`MTSAT`	MT saturation	%

What the model reads¶

A fixed set of 3 role-labeled volumes. Order does not matter — each volume is matched to its role by its BIDS filename entities.

Role	Entities
`MTw`	`flip-1`, `mt-on`
`PDw`	`flip-1`, `mt-off`
`T1w`	`flip-2`, `mt-off`

Where the protocol comes from¶

In a BIDS dataset these values are resolved for you:

Protocol parameter	Source	Key	Resolved
`FlipAngle`	sidecar field	`FlipAngle`	per volume
`RepetitionTimeExcitation`	sidecar field	`RepetitionTimeExcitation`	per volume

Inputs¶

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

Auxiliary maps¶

Input	Required	BIDS suffix	CLI flag
`B1map`	optional	`TB1map`	`--b1map`

Outputs¶

Map	BIDS suffix	Unit	Fit bounds	Fitted
`MTSAT`	`MTsat`	%	unbounded … unbounded	free
`T1`	`T1map`	s	unbounded … unbounded	free
`MTR`	`MTRmap`	%	—	—

Figure 2:Fitted maps for one example subject.

Usage¶

BIDS

Without BIDS

Simulation

Browser

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

model: mt_sat

# BIDS input: each MTS role's FlipAngle and RepetitionTimeExcitation come from
# its JSON sidecar (via the model's protocol_schema), so the per-role
# acquisition is NOT declared here.

# Options (always used; not BIDS metadata).
# B1 correction is applied only when a B1 map (TB1map) is present in the dataset.
b1_correction_factor: 0.4
export_mtr: true

# BIDS mask selection. Left blank: this example dataset ships no mask, and
# naming one here would claim otherwise. Blank means "whatever mask is
# present", so a dataset of your own that has one is masked by it.
mask:
  desc: ""

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

Fitted maps are written as BIDS derivatives:

out/derivatives/qmrust/sub-01/anat/
  sub-01_MTsat.nii.gz
  sub-01_MTsat.json
  sub-01_T1map.nii.gz
  sub-01_T1map.json
  sub-01_MTRmap.nii.gz
  sub-01_MTRmap.json

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

model: mt_sat

# Non-BIDS / bidsify protocol source: per-weighting nominal flip angle (deg)
# and repetition time (s). bidsify writes these into the MTS sidecars
# (FlipAngle / RepetitionTimeExcitation); a non-BIDS fit reads them directly.
mtw: { flip_angle: 6, repetition_time: 0.028 }
pdw: { flip_angle: 6, repetition_time: 0.028 }
t1w: { flip_angle: 20, repetition_time: 0.018 }

# Options (always used; not BIDS metadata).
# B1 correction is applied only when a B1 map (TB1map) is supplied.
b1_correction_factor: 0.4
export_mtr: true

# Non-BIDS input is a named set: one <role>.nii.gz per role under --nii-dir
# (MTw.nii.gz, PDw.nii.gz, T1w.nii.gz); mask via --mask/--nii-mask. Example:
#
#   qmrust bidsify --model mt_sat --nii-dir <dir> \
#     --config recipes/non-bids/mt_sat_config.yaml --subject 01 --out ds

qmrust fit --data data.nii.gz --mask mask.nii.gz \
  --config recipes/non-bids/mt_sat_config.yaml \
  --b1map <file> \
  --output-dir out

See Fitting without BIDS.

model: mt_sat

# Simulation: the acquisition comes from this file. Per-weighting nominal flip
# angle (deg) and repetition time (s), as the MTS sidecars carry them.
mtw: { flip_angle: 6, repetition_time: 0.028 }
pdw: { flip_angle: 6, repetition_time: 0.028 }
t1w: { flip_angle: 20, repetition_time: 0.018 }

b1_correction_factor: 0.4
export_mtr: true

# Ground truth: white matter at 3 T. A is the apparent signal amplitude; MTSAT
# is in percent, near 5% in white matter and 2% in grey.
sim:
  params: { A: 1000.0, T1: 1.0, MTSAT: 3.0 }
  noise: { type: rician, snr: 100.0 }
  seed: 0
  trials: 100
  sweep: { param: MTSAT, start: 1.0, stop: 8.0, steps: 10 }
  distributions:
    T1: { mean: 1.0, std: 0.15 }
    MTSAT: { mean: 3.0, std: 0.5 }

qmrust sim signal       --config recipes/sim/mt_sat_sim.yaml --output signal.json
qmrust sim single-voxel --config recipes/sim/mt_sat_sim.yaml --output sv.json
qmrust sim sensitivity  --config recipes/sim/mt_sat_sim.yaml --output sens.json
qmrust sim montecarlo   --config recipes/sim/mt_sat_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.

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: mt_sat
mtw:
  flip_angle: 6.0
  repetition_time: 0.028
pdw:
  flip_angle: 6.0
  repetition_time: 0.028
t1w:
  flip_angle: 20.0
  repetition_time: 0.018
b1_correction_factor: 0.4
export_mtr: true
b1_correction: null

References¶

Helms et al. (2008)

References¶

Helms, G., Dathe, H., Kallenberg, K., & Dechent, P. (2008). High-resolution maps of magnetization transfer with inherent correction for RF inhomogeneity and T1 relaxation obtained from 3D FLASH MRI. Magnetic Resonance in Medicine, 60(6), 1396–1407.