nmrmetaproc 1.0.16

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]
Provenance: Zenodo DOI, CITATION.cff, AUTHORS.md, NOTICE, PROVENANCE.md

---

Features

• Reads raw Bruker FID files (fid/*.fid + acqus/acqu) directly, no conversion needed
• Automatically discovers valid Bruker spectra under a parent directory and splits mixed data into scientifically comparable batches by cohort and pulse program
• Applies pulse-program-specific and sample-context-aware processing presets for supported Bruker 1D 1H experiments (noesygppr1d, cpmgpr1d, zg30, ledbpgppr2s1d)
• 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. Solvent/context region exclusion, for example aqueous water or residual CHCl3
  9. Spectral alignment (whole-spectrum correlation shift 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, reference-peak linewidth, solvent-region score, pass/fail, and warnings
• Clean CSV outputs ready for MetaboAnalyst, R, MATLAB
• Works on Windows, macOS, and Linux

---

Download

Pre-built desktop applications for Windows, macOS, and Linux are published to the Releases page:

Platform	File	How to use
Windows 10 / 11 (x64)	nmrmetaproc-gui-windows-x64.zip	Unzip and run nmrmetaproc-gui.exe
macOS 12+ (Apple Silicon + Intel)	nmrmetaproc-gui-macos.dmg	Open the DMG, drag nmrmetaproc.app to Applications
Linux (glibc 2.31+, x86_64)	nmrmetaproc-gui-linux-x86_64.AppImage	chmod +x the file and double-click

These bundles contain Python, all dependencies, and the GUI app. You do not need to install Python separately to use them.

If you prefer Python integration (CLI + scriptable API), install from PyPI instead -- see Installation below.

First-launch notes

The desktop bundles are unsigned -- we do not yet hold an Apple Developer ID or a Windows EV code-signing certificate, so the operating system shows a warning the first time you open the app. The app itself is the same code published on PyPI; you are bypassing OS-level signature checks, not malware checks.

macOS (Gatekeeper) -- if you see "Apple could not verify nmrmetaproc is free of malware" with no Open button, do one of the following after dragging the .app to /Applications:

• Terminal one-liner (fastest):

  xattr -dr com.apple.quarantine /Applications/nmrmetaproc.app
  

  Then launch normally.

• GUI path: click Done on the dialog (do not click Move to Bin), then open System Settings -> Privacy & Security, scroll to the Security section, click Open Anyway next to the "nmrmetaproc was blocked" line, and re-launch the app.

Windows (SmartScreen) -- on first launch you may see "Windows protected your PC". Click More info, then Run anyway.

Linux (AppImage permissions) -- the file needs the executable bit set:

chmod +x nmrmetaproc-gui-linux-x86_64.AppImage

If your distro complains about FUSE, install libfuse2 (Ubuntu: sudo apt install libfuse2).

---

Installation

pip install nmrmetaproc

Or from source:

git clone https://github.com/omagebright/nmrmetaproc.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

Point nmrmetaproc at the parent Bruker directory. By default it discovers all valid spectra, separates incompatible cohorts and pulse programs into independent batches, applies the registered pulse-program presets, and writes one analysis-ready matrix per batch.

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

Batch output layout:

results/
|-- batch_manifest.csv
|-- FIDs_Toyin__zg30/
|   |-- spectral_matrix.csv
|   |-- qc_report.csv
|   |-- acquisition_parameters.csv
|   `-- processing.log
`-- FIDs_Julia__cpmgpr1d/
    |-- spectral_matrix.csv
    |-- qc_report.csv
    |-- acquisition_parameters.csv
    `-- processing.log

Use --single-matrix only when the input directory is already one homogeneous cohort and pulse program:

nmrmetaproc process /path/to/one_batch --output ./results --single-matrix

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="correlation",
)

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. PQN/total-area normalized; not scaled
spectral_matrix_labeled.csv	Optional. Labelled feature matrix (only when peak-label export is enabled). Solvent/reference labels marked as solvent are excluded
spectral_matrix_analysis_ready.csv	Optional. Low-information bins removed, robust per-bin outlier screen, robust feature scaling already applied (median-centred, MAD-scaled), so do not autoscale again in MetaboAnalyst/sklearn. Robust steps are skipped for cohorts with < 8 samples
analysis_ready_report.csv	Optional. Audit table for the raw-bin analysis-ready matrix
spectral_matrix_labeled_analysis_ready.csv	Optional. ML/chemometrics-ready version of the labelled matrix, written when both label export and analysis-ready export are enabled
analysis_ready_labeled_report.csv	Optional. Audit table for the labelled analysis-ready matrix
qc_report.csv	SNR, linewidth (Hz), residual-region score and label, pass/fail per sample
acquisition_parameters.csv	Bruker metadata, inferred context/solvent, pulse program, and effective per-sample processing settings
processing.log	Full processing log with all parameters and per-sample status

---

Data Format

Each sample must be in its own directory containing:

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

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

Nested layouts are also supported and discovered automatically.

---

Citing and Provenance

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.16).
Zenodo. https://doi.org/10.5281/zenodo.19194107

The canonical public provenance records are the GitHub repository, annotated release tags, GitHub Releases, CITATION.cff, AUTHORS.md, NOTICE, PROVENANCE.md, and the Zenodo DOI. The MIT License permits reuse and redistribution only with the required copyright and permission notices retained. Scientific use should preserve authorship and cite the software DOI.

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://github.com/omagebright/nmrmetaproc.git
cd nmrmetaproc
pip install -e ".[dev]"
pytest tests/ -v

---

License

MIT License. See LICENSE for details. Redistribution and derivative work must retain the copyright and permission notices. See NOTICE and PROVENANCE.md for authorship and citation records.