Metadata-Version: 2.4
Name: nmrmetaproc
Version: 1.0.1
Summary: NMR Metabolomics Spectral Processor - raw Bruker FID to analysis-ready CSV
Author-email: Folorunsho Bright Omage <omagefolorunsho@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/omagebright/nmrmetaproc
Project-URL: Repository, https://github.com/omagebright/nmrmetaproc
Keywords: NMR,metabolomics,spectral processing,chemometrics,Bruker
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: nmrglue>=0.9
Requires-Dist: numpy>=1.21
Requires-Dist: scipy>=1.7
Requires-Dist: pandas>=1.3
Requires-Dist: tqdm>=4.60
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Dynamic: license-file

﻿# nmrmetaproc

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19194107.svg)](https://doi.org/10.5281/zenodo.19194107)

**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](https://orcid.org/0000-0002-9750-5034)
**Email:** omagefolorunsho@gmail.com

---

## 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

```bash
pip install nmrmetaproc
```

Or from source:

```bash
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

[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/omagebright/nmrmetaproc/blob/main/examples/colab_demo_real_data.ipynb)

**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 →**](https://colab.research.google.com/github/omagebright/nmrmetaproc/blob/main/examples/colab_demo_real_data.ipynb)

## Command-Line Usage

### Full Processing Pipeline

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

```bash
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

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

### Inspect Available Samples

```bash
nmrmetaproc info /path/to/data
```

---

## Python API

```python
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

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

---

## License

MIT License. See [LICENSE](LICENSE) for details.


