---

Overview

Augmentrum is a modular Python framework designed to help researchers with limited in-vivo MRS data create diverse, physically consistent datasets through flexible augmentation. It supports k-space resampling, coil and average sampling, signal-level perturbations, and synthetic artifact generation, expanding both synthetic and in-vivo data in a realistic and controlled manner.

Built for data-driven MRS applications, Augmentrum streamlines the integration of data augmentation into existing workflows. It operates on the NIfTI-MRS standard, making it compatible with any acquisition format. Simply load your data as NIfTI (using spec2nii if needed) and apply either predefined augmentation settings or build a custom pipeline by combining modules. Each augmentation can be parameterized or used with default ranges to populate a dense and diverse dataset environment.

From MRSI reconstruction and acquisition variability to spectral perturbations and artifact synthesis, Augmentrum handles it all in a modular, flexible, and easy-to-use structure. Dataloaders allow on-the-fly augmentation for deep learning backends such as PyTorch, TensorFlow, Keras, and JAX, enabling robust training beyond static datasets.

Note: Augmentrum is currently in alpha development. It is an active research framework and may undergo changes as modules and interfaces evolve.

---

Features

• Modular augmentation across time, frequency, and k-space domains
• Physically valid transformations for realistic variability
• Native NIfTI-MRS I/O and metadata tracking
• Customizable pipelines with user-defined parameters
• On-the-fly augmentation for machine learning workflows

---

Installation

pip install augmentrum

or from source:

git clone https://github.com/julianmer/Augmentrum.git
cd Augmentrum
pip install -e .

---

Quick Start

from augmentrum import Augmentrum

data   # list of NIfTI-MRS files
water   # list of corresponding water reference files (optional)

# initialize Augmentrum with data and optional water references
augmenter = Augmentrum(
    data=data, 
    water=water, 
    
    # custom pipeline example
    pipeline = [
        'coil_sampling',
        'average_sampling',
        'processing',
        'line_broadening',
        'baseline',
        'noise',
    ],
    
    # general settings
    batch_size=16,
    backend='pytorch',  # or 'tensorflow', 'keras', 'jax', 'numpy'
)

# get a dataloader for PyTorch with on-the-fly augmentation
train_data = augmenter.dataloader()

Supervised Pairs: Taps and outputs

Any pipeline stage can be named with a 'tap:<name>' marker and yielded by the dataloaders through the outputs spec — an arbitrarily nested tuple of stage tokens ('data' / 'water' for the pipeline end, '<tap>' / '<tap>.water' for a tapped stage). The classic (data, water) pair stays the default.

augmenter = Augmentrum(
    data=data,
    pipeline=['coil_sampling', 'macromolecules', 'tap:clean', 'undersampling'],
    outputs=(('data', 'water'), ('clean', 'clean.water')),
    backend='pytorch',
)

# supervised reconstruction pairs: input fully augmented, target frozen at the tap
for (x, x_water), (y, y_water) in augmenter.dataloader():
    train_step(x, y)

Per-Step Parameters, Seeds and Subject-Wise Splits

A keyword argument reaches every module whose constructor names it, so lb_hz=(0, 5) would move LineBroadening and Apodization (you get a warning). A pipeline entry can carry its own kwargs, which reach that step only and override the globals there; a kwarg no module accepts raises with the closest valid names instead of being ignored.

augmenter = Augmentrum(
    data=data,
    groups=subject_ids,                     # one id per item: a subject never straddles splits
    split_fractions={'val': 0.1, 'test': 0.1},
    pipeline=[
        'coil_sampling',
        {'noise': {'sigma_frac': (0.0, 0.02)}},
        {'line_broadening': {'lb_hz': (0.0, 5.0)}},
        ('apodization', {'mode': 'exponential', 'lb_hz': 2.0}),
        'baseline_bspline',                 # registry alias fixing mode='bspline'
    ],
    n_coils=(1, 8),                         # integer-typed ranges are inclusive
    seed=1,                                 # fixes the split, subject draws, ranges and modules
)
augmenter.split_groups['val']               # the subject ids held out for validation

Without groups, a user-defined SubjectID header-extension field is used when every item carries one. seed makes the whole run replay — including num_workers > 0 DataLoaders, where each worker is reseeded from it — and augmenter.reseed(k) restarts every stream; 'fixed' mode draws its ranges once per split and keeps them across dataloader() calls.

---

Module Reference & Backend Support

Every module is called as module(nifti_plus, water). When a backend is not natively supported, the base class automatically routes the call through the NIfTI-list path and returns the result in the original backend format — no manual conversion needed.

Module	Modes / Methods	NIfTI	NumPy	PyTorch	TensorFlow	JAX	Keras
AmplitudeScaling	uniform, normal	✓	✓	✓	✓	✓	✓
Apodization	exponential, gaussian, hamming, truncate	✓	✓†	✓†	✓†	✓†	✓†
ArtificialPeaks	Lorentzian, Gaussian, Voigt	✓	✓	✓	✓	✓	✓
AverageSampler	random, consecutive, strided, deterministic	✓	✓	✓	✓	✓	✓
BaselineAugmentation	random_walk, bspline, polynomial	✓	✓	✓	✓	✓	✓
CoilSampler	draw random, reweight, grow from CSMs	✓	✓	✓	✓	✓	✓
EddyCurrent	synthetic, water (call-time reference or source library)	✓	✓	✓	✓	✓	✓
EditCombiner	diff, sum along DIM_EDIT	~	✓	✓	✓	✓	✓
FrequencyShift	shift_hz	✓	✓	✓	✓	✓	✓
Noise	sigma, sigma_frac, snr, snr_db	✓	✓	✓	✓	✓	✓
KspaceUndersampling	cartesian, gridded, nufft, dual trajectory	~	✓	✓	✓	✓	✓
LineBroadening	lorentzian, gaussian, voigt	✓	✓	✓	✓	✓	✓
Macromolecules	parametrized, measured, supplied	~	✓	✓	✓	✓	✓
RawProcessor	coil combination, registration, ECC, ...	✓	✓‡	✓‡	✓‡	✓‡	✓‡
PhaseShift	zero_order, first_order	✓	✓	✓	✓	✓	✓
ResidualWater	lobes, turco (7-Lorentzian WaterFit)	✓	✓	✓	✓	✓	✓
SpatialAugmentations	2-D / 3-D affine, flip, zoom, shear	✓	✓	✓	✓	✓	✓
SpuriousEchoes	echo, replica, hybrid	✓	✓	✓	✓	✓	✓
Tap	marker: snapshot a stage for outputs	✓	✓	✓	✓	✓	✓
TransientSynthesizer	correlated drift, respiration, motion events	~	✓	✓	✓	✓	✓
ZeroFill	pad FID to target length	✓	✓†	✓†	✓†	✓†	✓†

✓ native — data tensor stays in the target framework throughout.
~ automatic — the base class routes the call through the NIfTI-list path; the result is returned in the original backend format. Functional, but not natively differentiable.
— not supported / not applicable.

Modes that differ in backend support get a row each, named Module[mode].

† Apodization[truncate] and ZeroFill both change N_PTS. Because target_pts / n_pts is a module-level scalar, the same length is applied uniformly to every batch member — the output is still a uniform tensor.

‡ RawProcessor[remove_outliers] on tensor backends zeroes outlier transients instead of dropping them — a batched tensor cannot go ragged.

---

Contact

For questions, issues, or collaborations:

• GitHub Issues: github.com/julianmer/Augmentrum/issues
• Email: jlamaste@gmail.com, j.p.merkofer@tue.nl, kci2104@columbia.edu

---

Citation

J. T. LaMaster, J. P. Merkofer, K. C. Igwe, "Augmentrum: A Data Augmentation Package for MR Spectroscopy", International Society for Magnetic Resonance in Medicine (ISMRM), Abstract #05685, Cape Town, South Africa, 2026.

---