MT Ratio - qmrust

Config name: model: mt_ratio BIDS suffix; MTR Method family; Semi-quantitative MT Acquired volumes; 2 Fit granularity; voxelwise

Computes the magnetization transfer ratio from two images: one acquired with an off-resonance saturation pulse and one without. MTR is a semi-quantitative percentage that reflects the pool of macromolecule-bound protons, but it depends on the saturation pulse and sequence timing, so values are not comparable across protocols.

Signal model¶

\mathrm{MTR} = 100 \times \frac{S_\mathrm{off} - S_\mathrm{on}}{S_\mathrm{off}}

(1)

Symbol	Quantity	Unit
`MTR`	Magnetization transfer ratio	%

What the model reads¶

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

Role	Entities
`MTon`	`mt-on`
`MToff`	`mt-off`

Inputs¶

Figure 1:The 2 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
`MTR`	`MTRmap`	%	unbounded … unbounded	free

Figure 3:Fitted maps for one example subject.

Usage¶

BIDS

Without BIDS

Simulation

Browser

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

model: mt_ratio

# MTR = 100 * (MToff - MTon) / MToff. No acquisition protocol and no fit
# options: the MTon/MToff volumes are resolved from the BIDS MTR named set
# (mt-on / mt-off) by the grouping manifest. Example:
#
#   qmrust fit --bids-dir <dataset> \
#     --config recipes/bids/mt_ratio_config.yaml --output-dir out

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

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

Fitted maps are written as BIDS derivatives:

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

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

model: mt_ratio

# MTR = 100 * (MToff - MTon) / MToff. There is no acquisition protocol and no
# fit options, so this config carries nothing but the model name.
#
# Two uses:
#   - bidsify a qMRLab named set (one <role>.mat per role — MTon.mat, MToff.mat
#     — plus Mask.mat) from --mat-dir; this config is the --config input:
#
#       qmrust bidsify --model mt_ratio --mat-dir <dir> \
#         --config recipes/non-bids/mt_ratio_config.yaml --subject 01 --out ds
#
#   - fit a stacked 4D NIfTI whose two volumes are [mt-on, mt-off], with the
#     mask via --mask:
#
#       qmrust fit --data mton_mtoff.nii.gz --mask Mask.mat \
#         --config recipes/non-bids/mt_ratio_config.yaml --output-dir out_mtr

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

See Fitting without BIDS.

model: mt_ratio

# Simulation: MTR = 100 * (MToff - MTon) / MToff. There is no acquisition
# protocol and no fit options, so the model name and the sim block are the
# whole recipe.
#
# Ground truth: white matter at 3 T, MTR in percent.
sim:
  params: { MTR: 40.0 }
  noise: { type: rician, snr: 100.0 }
  seed: 0
  trials: 100
  sweep: { param: MTR, start: 5.0, stop: 60.0, steps: 10 }
  distributions:
    MTR: { mean: 40.0, std: 5.0 }

qmrust sim signal       --config recipes/sim/mt_ratio_sim.yaml --output signal.json
qmrust sim single-voxel --config recipes/sim/mt_ratio_sim.yaml --output sv.json
qmrust sim sensitivity  --config recipes/sim/mt_ratio_sim.yaml --output sens.json
qmrust sim montecarlo   --config recipes/sim/mt_ratio_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:Measured values for one voxel beside the model’s forward prediction at the fitted parameters.

Implementation¶

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

References¶

Wolff & Balaban (1989)

References¶

Wolff, S. D., & Balaban, R. S. (1989). Magnetization transfer contrast (MTC) and tissue water proton relaxation in vivo. Magnetic Resonance in Medicine, 10(1), 135–144.