nmrmetaproc 1.0.1

NMR Metabolomics Spectral Processor - raw Bruker FID to analysis-ready CSV

nmrmetaproc

NMR Metabolomics Spectral Processor

nmrmetaproc converts raw Bruker NMR FID files into clean, analysis-ready spectral matrices (CSV format) suitable for PCA, PLS-DA, pathway analysis, and other downstream metabolomics workflows. It implements a rigorous, reproducible processing pipeline with automatic phase correction, chemical-shift referencing, robust baseline correction, spectral alignment, and Probabilistic Quotient Normalization (PQN).

Authors: Folorunsho Bright Omage, Toyin Bright Omage, Ljubica Tasic ORCID: 0000-0002-9750-5034 Email: [e-mail]

---

Features

• Reads raw Bruker FID files (fid + acqus) directly, no conversion needed
• Full processing pipeline in correct order:
  1. Exponential apodization (line broadening)
  2. Zero-filling
  3. Fast Fourier Transform
  4. Automatic phase correction (ACME algorithm, no fixed phase values)
  5. Chemical-shift referencing to TSP (0.00 ppm, auto-detected)
  6. Asymmetric least-squares (ALS) baseline correction
  7. Negative-value handling with per-sample logging
  8. Water region exclusion (4.5-5.0 ppm)
  9. Spectral alignment (icoshift-style cross-correlation or reference-peak)
  10. Configurable region exclusion
  11. Uniform binning
  12. PQN normalization (default), or total area, TSP reference, none
• Per-sample quality control: SNR, TSP linewidth, water suppression score
• Clean CSV outputs ready for MetaboAnalyst, R, MATLAB
• Works on Windows, macOS, and Linux

---

Installation

pip install nmrmetaproc

Or from source:

git clone https://doi.org/10.5281/zenodo.19194107.git
cd nmrmetaproc
pip install -e .

Dependencies: nmrglue, numpy, scipy, pandas, tqdm

---

---

🚀 Try it Now - Interactive Demo

Try nmrmetaproc instantly with real de-identified clinical NMR data from a thrombosis study! The interactive Google Colab notebook demonstrates the complete workflow from raw Bruker FID files to publication-quality figures and statistical analysis.

Demo features:

• Process 6 real NMR samples (3 Control + 3 Thrombosis)
• 600 MHz Bruker AVANCE III data
• Quality control visualization
• Group comparison plots
• Principal component analysis
• Zero installation required - runs in your browser!

Launch Demo →

Command-Line Usage

Full Processing Pipeline

nmrmetaproc process /path/to/bruker/data --output ./results

nmrmetaproc process /path/to/data \
    --output ./results \
    --lb 0.5 \
    --bin-width 0.005 \
    --normalization pqn \
    --snr-threshold 10 \
    --exclude-regions "4.5-5.0,0.0-0.5"

QC Scan Only

nmrmetaproc qc /path/to/data --output ./qc_results

Inspect Available Samples

nmrmetaproc info /path/to/data

---

Python API

from nmrmetaproc import NMRProcessor

processor = NMRProcessor(
    lb=0.3,
    bin_width=0.01,
    normalization="pqn",
    ppm_range=(0.5, 9.5),
    snr_threshold=10.0,
    linewidth_threshold=2.5,
    align="icoshift",
)

results = processor.process("/path/to/bruker/data")

print(results.spectral_matrix)   # rows=samples, columns=ppm bins
print(results.qc_report)         # SNR, linewidth, pass/fail per sample

results.save("./output")

---

Output Files

File	Description
spectral_matrix.csv	Rows = samples (passed QC), columns = ppm bin centres
qc_report.csv	SNR, linewidth (Hz), water suppression score, pass/fail per sample
acquisition_parameters.csv	SW, SFO1, TD, NS, RG, pulse program, temperature per sample
processing_log.txt	Full processing log with all parameters and per-sample status

---

Data Format

Each sample must be in its own directory containing:

• fid - binary FID data (interleaved real/imaginary int32)
• acqus - acquisition parameter file

data_root/
|-- sample_001/
|   |-- fid
|   `-- acqus
`-- sample_002/
    |-- fid
    `-- acqus

Nested layouts are also supported and discovered automatically.

---

Citing

If you use nmrmetaproc in your research, please cite:

Omage, F. B., Omage, T. B., & Tasic, L. (2026). nmrmetaproc: NMR Metabolomics Spectral Processor (Version 1.0.0).
Zenodo. https://doi.org/10.5281/zenodo.19194107

The PQN normalization method:

Dieterle, F., Ross, A., Schlotterbeck, G., & Senn, H. (2006). Probabilistic quotient normalization as robust method to account for dilution of complex biological mixtures. Analytical Chemistry, 78(13), 4281-4290. https://doi.org/10.1021/ac051632c

---

Development

git clone https://doi.org/10.5281/zenodo.19194107.git
cd nmrmetaproc
pip install -e ".[dev]"
pytest tests/ -v

---

License

MIT License. See LICENSE for details.