nmrmetaproc 1.0.0__tar.gz

nmrmetaproc-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Folorunsho Bright Omage
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nmrmetaproc-1.0.0/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: nmrmetaproc
+Version: 1.0.0
+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.XXXXXXX.svg)](https://doi.org/10.5281/zenodo.XXXXXXX)
+
+**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).
+
+**Author:** Folorunsho Bright Omage, Ph.D.
+**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://github.com/omagebright/nmrmetaproc.git
+cd nmrmetaproc
+pip install -e .
+```
+
+**Dependencies:** `nmrglue`, `numpy`, `scipy`, `pandas`, `tqdm`
+
+---
+
+## 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. (2026). nmrmetaproc: NMR Metabolomics Spectral Processor (Version 1.0.0).
+Zenodo. https://doi.org/10.5281/zenodo.XXXXXXX
+```
+
+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://github.com/omagebright/nmrmetaproc.git
+cd nmrmetaproc
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

nmrmetaproc-1.0.0/README.md

@@ -0,0 +1,175 @@
+# 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.XXXXXXX.svg)](https://doi.org/10.5281/zenodo.XXXXXXX)
+
+**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).
+
+**Author:** Folorunsho Bright Omage, Ph.D.
+**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://github.com/omagebright/nmrmetaproc.git
+cd nmrmetaproc
+pip install -e .
+```
+
+**Dependencies:** `nmrglue`, `numpy`, `scipy`, `pandas`, `tqdm`
+
+---
+
+## 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. (2026). nmrmetaproc: NMR Metabolomics Spectral Processor (Version 1.0.0).
+Zenodo. https://doi.org/10.5281/zenodo.XXXXXXX
+```
+
+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://github.com/omagebright/nmrmetaproc.git
+cd nmrmetaproc
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

nmrmetaproc-1.0.0/nmrmetaproc/__init__.py

@@ -0,0 +1,32 @@
+# Silence scipy.optimize.fmin convergence output used internally by nmrglue
+import scipy.optimize as _scipy_opt
+_scipy_opt_fmin_orig = _scipy_opt.fmin
+def _fmin_silent(fn, x0, *args, **kwargs):
+    kwargs.setdefault("disp", False)
+    return _scipy_opt_fmin_orig(fn, x0, *args, **kwargs)
+_scipy_opt.fmin = _fmin_silent
+del _scipy_opt  # clean up namespace
+
+"""
+nmrmetaproc: NMR Metabolomics Spectral Processor
+=================================================
+A Python package for processing raw Bruker NMR FID files into
+analysis-ready spectral matrices for metabolomics studies.
+
+Author: Folorunsho Bright Omage
+ORCID: https://orcid.org/0000-0002-9750-5034
+Email: omagefolorunsho@gmail.com
+License: MIT
+"""
+
+from nmrmetaproc.version import __version__, __author__, __email__, __orcid__
+from nmrmetaproc.processor import NMRProcessor, ProcessingResults
+
+__all__ = [
+    "__version__",
+    "__author__",
+    "__email__",
+    "__orcid__",
+    "NMRProcessor",
+    "ProcessingResults",
+]

nmrmetaproc-1.0.0/nmrmetaproc/__main__.py

@@ -0,0 +1,5 @@
+"""Entry point for `python -m nmrmetaproc`."""
+from nmrmetaproc.cli import main
+
+if __name__ == "__main__":
+    main()

nmrmetaproc-1.0.0/nmrmetaproc/alignment.py

@@ -0,0 +1,137 @@
+"""
+Spectral alignment algorithms.
+
+Two strategies are available:
+    1. Reference-peak alignment: shift each spectrum so a chosen reference
+       peak (e.g. TSP) aligns exactly. Fast and interpretable.
+    2. Icoshift-style correlation-optimized shifting: maximise cross-
+       correlation with a reference (or mean) spectrum over a defined
+       shifting window. More robust for complex metabolite regions.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import List, Optional, Tuple
+
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+# Maximum shift window (in number of bins) for icoshift-style alignment
+DEFAULT_MAX_SHIFT: int = 50
+
+
+# ---------------------------------------------------------------------------
+# Reference-peak alignment
+# ---------------------------------------------------------------------------
+
+def align_to_reference_peak(
+    spectra: np.ndarray,
+    ppm_axis: np.ndarray,
+    ref_ppm: float,
+    search_width: float = 0.1,
+) -> Tuple[np.ndarray, List[int]]:
+    """Shift each spectrum so the tallest peak near *ref_ppm* lands exactly there.
+
+    Parameters
+    ----------
+    spectra:
+        2-D array (n_samples x n_points).
+    ppm_axis:
+        1-D ppm axis.
+    ref_ppm:
+        Target chemical shift for the reference peak.
+    search_width:
+        Half-width of the search window in ppm.
+
+    Returns
+    -------
+    aligned:
+        Shifted spectra (same shape as input).
+    shifts:
+        Integer shift applied to each spectrum (in data-point units).
+    """
+    from nmrmetaproc.utils import ppm_range_to_slice, ppm_to_index
+
+    lo = ref_ppm - search_width
+    hi = ref_ppm + search_width
+    start, stop = ppm_range_to_slice(ppm_axis, lo, hi)
+    target_idx = ppm_to_index(ppm_axis, ref_ppm)
+
+    aligned = np.zeros_like(spectra)
+    shifts: List[int] = []
+
+    for i, sp in enumerate(spectra):
+        region = sp[start:stop]
+        if region.size == 0:
+            aligned[i] = sp
+            shifts.append(0)
+            continue
+        peak_local = int(np.argmax(region))
+        peak_global = start + peak_local
+        shift = target_idx - peak_global
+        aligned[i] = np.roll(sp, shift)
+        shifts.append(int(shift))
+
+    return aligned, shifts
+
+
+# ---------------------------------------------------------------------------
+# Icoshift-style cross-correlation alignment
+# ---------------------------------------------------------------------------
+
+def icoshift_align(
+    spectra: np.ndarray,
+    reference: Optional[np.ndarray] = None,
+    max_shift: int = DEFAULT_MAX_SHIFT,
+) -> Tuple[np.ndarray, List[int]]:
+    """Correlation-optimized spectral alignment inspired by icoshift.
+
+    Aligns each spectrum to *reference* (or the column-mean if None) by
+    finding the integer shift that maximises normalised cross-correlation,
+    within a window of [-max_shift, +max_shift] data points.
+
+    Parameters
+    ----------
+    spectra:
+        2-D array (n_samples x n_points).
+    reference:
+        Target spectrum.  If None, the column-mean is used.
+    max_shift:
+        Maximum allowed shift in data points.
+
+    Returns
+    -------
+    aligned:
+        Aligned spectra.
+    shifts:
+        Integer shift applied to each spectrum.
+    """
+    if reference is None:
+        reference = np.mean(spectra, axis=0)
+
+    ref_norm = _normalise_for_xcorr(reference)
+    aligned = np.zeros_like(spectra)
+    shifts: List[int] = []
+
+    for i, sp in enumerate(spectra):
+        sp_norm = _normalise_for_xcorr(sp)
+        xcorr = np.correlate(sp_norm, ref_norm, mode="full")
+        n = len(sp)
+        lags = np.arange(-(n - 1), n)
+
+        # Restrict to allowed window
+        mask = np.abs(lags) <= max_shift
+        best_lag = lags[mask][int(np.argmax(xcorr[mask]))]
+        aligned[i] = np.roll(sp, -int(best_lag))
+        shifts.append(int(-best_lag))
+
+    return aligned, shifts
+
+
+def _normalise_for_xcorr(arr: np.ndarray) -> np.ndarray:
+    """Zero-mean, unit-norm normalisation."""
+    a = arr - arr.mean()
+    norm = np.linalg.norm(a)
+    return a / norm if norm > 0 else a