nmrmetaproc 1.0.0__py3-none-any.whl

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/__main__.py

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

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

nmrmetaproc/cli.py

@@ -0,0 +1,199 @@
+"""
+Command-line interface for nmrmetaproc.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+import warnings
+warnings.filterwarnings("ignore", category=RuntimeWarning, module="scipy")
+warnings.filterwarnings("ignore", category=RuntimeWarning, module="nmrglue")
+
+from nmrmetaproc import __version__, __author__, __orcid__
+from nmrmetaproc.io import find_sample_dirs
+
+
+def _parse_regions(regions_str: str) -> List[Tuple[float, float]]:
+    """Parse comma-separated ppm range string like '4.5-5.0,0.0-0.5'."""
+    result = []
+    for part in regions_str.split(","):
+        part = part.strip()
+        if not part:
+            continue
+        try:
+            lo_str, hi_str = part.split("-", 1)
+            result.append((float(lo_str), float(hi_str)))
+        except ValueError:
+            print(f"  Warning: could not parse region '{part}', skipping.", file=sys.stderr)
+    return result
+
+
+def cmd_process(args: argparse.Namespace) -> int:
+    """Run the full processing pipeline."""
+    from nmrmetaproc.processor import NMRProcessor
+
+    extra_regions = []
+    if args.exclude_regions:
+        extra_regions = _parse_regions(args.exclude_regions)
+
+    processor = NMRProcessor(
+        lb=args.lb,
+        bin_width=args.bin_width,
+        normalization=args.normalization,
+        ppm_range=(args.ppm_min, args.ppm_max),
+        exclude_regions_extra=extra_regions if extra_regions else None,
+        snr_threshold=args.snr_threshold,
+        linewidth_threshold=args.linewidth_threshold,
+        align=args.align,
+    )
+
+    results = processor.process(args.data_dir)
+
+    output_dir = Path(args.output)
+    results.save(output_dir)
+
+    print(f"\nOutput:")
+    if not results.spectral_matrix.empty:
+        nr, nc = results.spectral_matrix.shape
+        print(f"  ? {output_dir}/spectral_matrix.csv ({nr} samples × {nc} bins)")
+    print(f"  ? {output_dir}/qc_report.csv")
+    print(f"  ? {output_dir}/acquisition_parameters.csv")
+    print(f"  ? {output_dir}/processing_log.txt")
+
+    return 0 if results.n_passed > 0 else 1
+
+
+def cmd_qc(args: argparse.Namespace) -> int:
+    """Quick QC-only scan (no full processing)."""
+    from nmrmetaproc.io import read_fid
+    from nmrmetaproc.processing import (
+        apodize_exponential, auto_phase, baseline_als,
+        build_ppm_axis, fourier_transform, zero_fill,
+    )
+    from nmrmetaproc.qc import evaluate_sample
+    import pandas as pd
+
+    data_dir = Path(args.data_dir)
+    output_dir = Path(args.output)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    sample_dirs = find_sample_dirs(data_dir)
+    if not sample_dirs:
+        print("No valid FID directories found.")
+        return 1
+
+    print(f"nmrmetaproc v{__version__} — QC scan")
+    print(f"Found {len(sample_dirs)} samples\n")
+
+    rows = []
+    for sdir in sample_dirs:
+        sid = sdir.name
+        try:
+            fid, params = read_fid(sdir)
+            sw_hz = float(params.get("SW_h", params.get("SW", 20.0) * float(params.get("SFO1", 600.0))))
+            fid = apodize_exponential(fid, lb=0.3, sw=sw_hz)
+            fid = zero_fill(fid)
+            spec = fourier_transform(fid)
+            ppm = build_ppm_axis(params, len(spec))
+            spec_r = auto_phase(spec)
+            spec_r = baseline_als(spec_r)
+            qc = evaluate_sample(spec_r, ppm, sid, sw_hz)
+            status = "PASS" if qc.passed else "FAIL"
+            warn = "; ".join(qc.warnings)
+            print(f"  {sid:<30s} {status}  SNR={qc.snr:.1f}  LW={qc.linewidth_hz:.2f}Hz  {warn}")
+            rows.append({
+                "sample_id": sid,
+                "snr": qc.snr,
+                "linewidth_hz": qc.linewidth_hz,
+                "water_suppression_score": qc.water_suppression_score,
+                "passed": qc.passed,
+                "warnings": warn,
+            })
+        except Exception as exc:
+            print(f"  {sid:<30s} ERROR: {exc}")
+            rows.append({"sample_id": sid, "passed": False, "warnings": str(exc)})
+
+    pd.DataFrame(rows).to_csv(output_dir / "qc_report.csv", index=False)
+    print(f"\nQC report saved to {output_dir}/qc_report.csv")
+    return 0
+
+
+def cmd_info(args: argparse.Namespace) -> int:
+    """Show available samples."""
+    data_dir = Path(args.data_dir)
+    sample_dirs = find_sample_dirs(data_dir)
+
+    print(f"nmrmetaproc v{__version__} — Data Info")
+    print(f"Root: {data_dir}\n")
+
+    if not sample_dirs:
+        print("No valid FID directories found.")
+        return 1
+
+    print(f"Found {len(sample_dirs)} samples:")
+    for sdir in sample_dirs:
+        size = (sdir / "fid").stat().st_size
+        print(f"  {sdir.name:<40s}  FID size: {size:>10,} bytes")
+
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="nmrmetaproc",
+        description=(
+            f"nmrmetaproc v{__version__} — NMR Metabolomics Spectral Processor\n"
+            f"Author: {__author__} (ORCID: {__orcid__})"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+
+    sub = parser.add_subparsers(dest="command", metavar="COMMAND")
+    sub.required = True
+
+    # --- process ---
+    p_proc = sub.add_parser("process", help="Full spectral processing pipeline")
+    p_proc.add_argument("data_dir", metavar="DATA_DIR", help="Root directory with Bruker FID data")
+    p_proc.add_argument("--output", "-o", default="./results", metavar="DIR", help="Output directory (default: ./results)")
+    p_proc.add_argument("--lb", type=float, default=0.3, metavar="HZ", help="Line broadening in Hz (default: 0.3)")
+    p_proc.add_argument("--bin-width", type=float, default=0.01, metavar="PPM", dest="bin_width", help="Bin width in ppm (default: 0.01)")
+    p_proc.add_argument("--normalization", choices=["pqn", "total", "tsp", "none"], default="pqn", help="Normalisation method (default: pqn)")
+    p_proc.add_argument("--ppm-min", type=float, default=0.5, dest="ppm_min", help="Lower ppm limit (default: 0.5)")
+    p_proc.add_argument("--ppm-max", type=float, default=9.5, dest="ppm_max", help="Upper ppm limit (default: 9.5)")
+    p_proc.add_argument("--snr-threshold", type=float, default=10.0, dest="snr_threshold", help="Minimum SNR to pass QC (default: 10)")
+    p_proc.add_argument("--linewidth-threshold", type=float, default=2.5, dest="linewidth_threshold", help="Max TSP linewidth Hz to pass QC (default: 2.5)")
+    p_proc.add_argument("--exclude-regions", metavar="RANGES", dest="exclude_regions", help="Additional ppm regions to exclude, e.g. '4.5-5.0,0.0-0.5'")
+    p_proc.add_argument("--align", choices=["icoshift", "reference", "none"], default="icoshift", help="Spectral alignment method (default: icoshift)")
+    p_proc.set_defaults(func=cmd_process)
+
+    # --- qc ---
+    p_qc = sub.add_parser("qc", help="QC scan only (no full processing)")
+    p_qc.add_argument("data_dir", metavar="DATA_DIR")
+    p_qc.add_argument("--output", "-o", default="./qc_results", metavar="DIR")
+    p_qc.set_defaults(func=cmd_qc)
+
+    # --- info ---
+    p_info = sub.add_parser("info", help="List available samples")
+    p_info.add_argument("data_dir", metavar="DATA_DIR")
+    p_info.set_defaults(func=cmd_info)
+
+    return parser
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+
+    if hasattr(args, "align") and args.align == "none":
+        args.align = None
+
+    sys.exit(args.func(args))
+
+
+if __name__ == "__main__":
+    main()

nmrmetaproc/io.py

@@ -0,0 +1,185 @@
+"""
+I/O module: reading Bruker FID data and writing output files.
+"""
+
+from __future__ import annotations
+
+import logging
+import struct
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+import numpy as np
+import pandas as pd
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Bruker FID reader
+# ---------------------------------------------------------------------------
+
+def find_sample_dirs(root: Path) -> List[Path]:
+    """Walk *root* and return directories that contain both ``fid`` and ``acqus``.
+
+    Bruker raw data typically lives in numbered experiment directories
+    (e.g. ``sample01/1/``, ``sample01/10/``).  We accept any layout as long
+    as both files are present.
+    """
+    hits: List[Path] = []
+    for p in sorted(root.rglob("fid")):
+        if (p.parent / "acqus").exists():
+            hits.append(p.parent)
+    return hits
+
+
+def read_acqus(acqus_path: Path) -> Dict[str, Any]:
+    """Parse a Bruker ``acqus`` parameter file.
+
+    Returns a flat dict with parameter names (without leading ``$``) as keys.
+    Multiline arrays are stored as lists.
+    """
+    params: Dict[str, Any] = {}
+    current_key: Optional[str] = None
+    array_buf: List[str] = []
+
+    with open(acqus_path, "r", encoding="latin-1") as fh:
+        for raw_line in fh:
+            line = raw_line.strip()
+            if not line or line.startswith("$$"):
+                continue
+
+            if line.startswith("##$"):
+                # flush previous array if any
+                if current_key and array_buf:
+                    params[current_key] = _parse_value(" ".join(array_buf))
+                    array_buf = []
+                # parse new key
+                rest = line[3:]
+                if "=" in rest:
+                    key, val = rest.split("=", 1)
+                    current_key = key.strip()
+                    val = val.strip()
+                    if val.startswith("("):
+                        # array opener - may continue on next lines
+                        array_buf = [val]
+                    else:
+                        params[current_key] = _parse_value(val)
+                        current_key = None
+            elif current_key:
+                array_buf.append(line)
+
+    # flush any trailing array
+    if current_key and array_buf:
+        params[current_key] = _parse_value(" ".join(array_buf))
+
+    return params
+
+
+def _parse_value(val: str) -> Any:
+    """Try to cast a string value to int, float, or leave as str."""
+    val = val.strip()
+    try:
+        return int(val)
+    except ValueError:
+        pass
+    try:
+        return float(val)
+    except ValueError:
+        pass
+    # strip angle-bracket strings like <PROTON>
+    if val.startswith("<") and val.endswith(">"):
+        return val[1:-1]
+    return val
+
+
+def read_fid(sample_dir: Path) -> Tuple[np.ndarray, Dict[str, Any]]:
+    """Read a Bruker FID file and return the complex time-domain signal.
+
+    Parameters
+    ----------
+    sample_dir:
+        Directory containing ``fid`` and ``acqus``.
+
+    Returns
+    -------
+    fid_data:
+        Complex 1-D numpy array (time-domain FID).
+    params:
+        Parsed acquisition parameters from ``acqus``.
+
+    Raises
+    ------
+    FileNotFoundError
+        If expected files are missing.
+    ValueError
+        If byte order or data type cannot be determined.
+    """
+    fid_path = sample_dir / "fid"
+    acqus_path = sample_dir / "acqus"
+
+    if not fid_path.exists():
+        raise FileNotFoundError(f"fid not found: {fid_path}")
+    if not acqus_path.exists():
+        raise FileNotFoundError(f"acqus not found: {acqus_path}")
+
+    params = read_acqus(acqus_path)
+
+    # Determine byte order
+    dtypa = params.get("DTYPA", 0)  # 0=int32, 2=float64
+    bytorda = params.get("BYTORDA", 0)  # 0=little, 1=big
+
+    if bytorda == 0:
+        endian = "<"
+    else:
+        endian = ">"
+
+    if dtypa == 2:
+        dtype = np.dtype(f"{endian}f8")  # float64
+    else:
+        dtype = np.dtype(f"{endian}i4")  # int32
+
+    raw = np.frombuffer(fid_path.read_bytes(), dtype=dtype).astype(np.float64)
+
+    # Interleaved real/imag
+    if len(raw) % 2 != 0:
+        raw = raw[:-1]
+    fid = raw[0::2] + 1j * raw[1::2]
+
+    return fid, params
+
+
+# ---------------------------------------------------------------------------
+# Output writers
+# ---------------------------------------------------------------------------
+
+def save_results(
+    output_dir: Path,
+    spectral_matrix: pd.DataFrame,
+    qc_report: pd.DataFrame,
+    acq_params: pd.DataFrame,
+    log_text: str,
+) -> None:
+    """Write all output files to *output_dir*.
+
+    Parameters
+    ----------
+    output_dir:
+        Destination directory (created if absent).
+    spectral_matrix:
+        Rows = samples, columns = ppm bins.
+    qc_report:
+        One row per sample with QC metrics.
+    acq_params:
+        Acquisition parameters table.
+    log_text:
+        Full processing log as a single string.
+    """
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    spectral_matrix.to_csv(output_dir / "spectral_matrix.csv")
+    qc_report.to_csv(output_dir / "qc_report.csv", index=False)
+    acq_params.to_csv(output_dir / "acquisition_parameters.csv", index=False)
+
+    log_path = output_dir / "processing_log.txt"
+    log_path.write_text(log_text, encoding="utf-8")

nmrmetaproc/normalization.py

@@ -0,0 +1,123 @@
+"""
+Normalization strategies for NMR spectral matrices.
+
+Supported methods:
+    pqn   — Probabilistic Quotient Normalization (Dieterle et al. 2006)
+    total — Total-area (sum) normalization
+    tsp   — TSP-peak reference normalization
+    none  — No normalization (return as-is)
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Literal, Optional
+
+import numpy as np
+import pandas as pd
+
+logger = logging.getLogger(__name__)
+
+NormMethod = Literal["pqn", "total", "tsp", "none"]
+
+
+def normalize(
+    matrix: np.ndarray,
+    method: NormMethod = "pqn",
+    tsp_bin_index: Optional[int] = None,
+) -> np.ndarray:
+    """Normalise a spectral matrix.
+
+    Parameters
+    ----------
+    matrix:
+        2-D array (n_samples x n_bins).  All values should be >= 0.
+    method:
+        Normalisation method ('pqn', 'total', 'tsp', 'none').
+    tsp_bin_index:
+        Column index of the TSP reference peak bin (required for method='tsp').
+
+    Returns
+    -------
+    np.ndarray
+        Normalised matrix (same shape).
+
+    Raises
+    ------
+    ValueError
+        If method is unknown or tsp_bin_index is missing when method='tsp'.
+    """
+    if method == "none":
+        return matrix.copy()
+    if method == "total":
+        return _total_area(matrix)
+    if method == "pqn":
+        return _pqn(matrix)
+    if method == "tsp":
+        if tsp_bin_index is None:
+            raise ValueError("tsp_bin_index must be provided for method='tsp'")
+        return _tsp_reference(matrix, tsp_bin_index)
+    raise ValueError(f"Unknown normalisation method: {method!r}")
+
+
+def _total_area(matrix: np.ndarray) -> np.ndarray:
+    """Divide each sample by its total spectral area."""
+    totals = matrix.sum(axis=1, keepdims=True)
+    totals[totals == 0] = 1.0  # avoid divide-by-zero for empty spectra
+    return matrix / totals
+
+
+def _pqn(matrix: np.ndarray) -> np.ndarray:
+    """Probabilistic Quotient Normalization (PQN).
+
+    Algorithm (Dieterle et al. 2006, Anal. Chem.):
+        1. Total-area normalize all spectra.
+        2. Compute a reference spectrum (column-wise median).
+        3. For each sample, compute quotients (sample / reference) for all bins
+           where the reference > 0.
+        4. The normalisation factor is the median of those quotients.
+        5. Divide the original (not total-area) spectrum by that factor.
+
+    Parameters
+    ----------
+    matrix:
+        2-D array (n_samples x n_bins), values >= 0.
+
+    Returns
+    -------
+    np.ndarray
+        PQN-normalised matrix.
+    """
+    # Step 1: total-area normalise for reference construction only
+    ta = _total_area(matrix)
+
+    # Step 2: reference spectrum
+    reference = np.median(ta, axis=0)
+
+    # Steps 3-5: compute PQN factor per sample
+    normed = np.zeros_like(matrix)
+    nonzero_ref = reference > 0
+
+    for i, sample in enumerate(ta):
+        if not nonzero_ref.any():
+            normed[i] = matrix[i]
+            continue
+        quotients = sample[nonzero_ref] / reference[nonzero_ref]
+        pqn_factor = float(np.median(quotients))
+        if pqn_factor <= 0:
+            logger.warning(
+                "Sample %d: PQN factor <= 0 (%.4g), skipping normalisation.", i, pqn_factor
+            )
+            normed[i] = matrix[i]
+        else:
+            # Divide the original (un-normalised) sample by the PQN factor
+            normed[i] = matrix[i] / pqn_factor
+
+    return normed
+
+
+def _tsp_reference(matrix: np.ndarray, tsp_bin_index: int) -> np.ndarray:
+    """Normalise each sample to the intensity of the TSP reference peak."""
+    tsp_intensities = matrix[:, tsp_bin_index].copy()
+    tsp_intensities[tsp_intensities == 0] = 1.0
+    return matrix / tsp_intensities[:, np.newaxis]