rt-anchor 0.1.0__tar.gz

rt_anchor-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bowen Yang
+
+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.

rt_anchor-0.1.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: rt-anchor
+Version: 0.1.0
+Summary: Standard-panel retention-index (iRT) calibration for LC-MS lipidomics feature tables (MS-DIAL / MZmine / MassCube / LipidScreener)
+Author: Bowen Yang
+License-Expression: MIT
+Keywords: retention index,iRT,retention time,calibration,lipidomics,metabolomics,LC-MS,mass spectrometry,MS-DIAL,MZmine,MassCube,LipidScreener
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Requires-Dist: pandas>=1.3
+Requires-Dist: scipy>=1.7
+Requires-Dist: matplotlib>=3.5
+Requires-Dist: plotly>=5.0
+Provides-Extra: excel
+Requires-Dist: openpyxl>=3.0; extra == "excel"
+Provides-Extra: report
+Requires-Dist: matplotlib>=3.5; extra == "report"
+Requires-Dist: plotly>=5.0; extra == "report"
+Provides-Extra: structures
+Requires-Dist: rdkit>=2022.9; extra == "structures"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: openpyxl>=3.0; extra == "test"
+Dynamic: license-file
+
+# rt-anchor
+
+Standard-panel **retention-index (iRT) calibration** for LC-MS lipidomics.
+
+## Purpose
+
+Convert the retention time of every feature in an LC-MS table into a
+dimensionless, portable **retention index (RI/iRT)** anchored on a spiked
+standard panel — so retention is comparable across injections, batches, and
+instruments. A monotone warp is fitted from the standards and applied to all
+features; nothing in the original table is dropped, calibration only appends
+columns.
+
+## Download
+
+```bash
+pip install rt-anchor
+pip install "rt-anchor[report,structures]"   # + HTML/PDF report and structure hover
+```
+
+## Input
+
+Required:
+
+| Input | What |
+|-------|------|
+| **Sample feature table** | The table to calibrate. MS-DIAL / MZmine / MassCube / LipidScreener — auto-detected. Must have an **m/z** and a **retention-time** column. |
+| **Standards run** | A run of the standard panel (same formats) — builds the native anchor template. **Required.** |
+| **Polarity** | `positive` or `negative`. |
+
+Optional: per-injection files (per-sample tier + repeatability QC), a custom
+standard manifest / reference baseline, and the matching parameters
+(`mz_tol_ppm`, `rt_window_min`, `min_anchors`, `extrapolate`).
+
+```python
+from rt_anchor import calibrate, write_results
+res = calibrate("samples.txt", polarity="positive", standards_table="standards.txt")
+write_results(res, "out/run1")
+```
+```bash
+rt-anchor calibrate --samples samples.txt --standards standards.txt --polarity positive --out out/run1
+```
+
+## Output
+
+- **`*_calibrated.csv`** — the original table + appended columns: `RI` (iRT-style
+  index), `RI_uncertainty`, `RI_reliability` (high/medium/low/none), `RI_spread`,
+  `n_contributing`, `is_extrapolated`, `calibration_scope`, `warp_source`.
+- **`*_model.json`** — the fitted warp, anchors, and QC metrics.
+- **`*_anchors.csv`**, **`*_log.txt`** — anchors used and a run log.
+- **`*_report.html`** + **`*_report.pdf`** — an interactive + static report
+  (detection, calibration warp, repeatability). On by default; `--no-report` to skip.
+
+## License
+
+MIT

rt_anchor-0.1.0/README.md

@@ -0,0 +1,56 @@
+# rt-anchor
+
+Standard-panel **retention-index (iRT) calibration** for LC-MS lipidomics.
+
+## Purpose
+
+Convert the retention time of every feature in an LC-MS table into a
+dimensionless, portable **retention index (RI/iRT)** anchored on a spiked
+standard panel — so retention is comparable across injections, batches, and
+instruments. A monotone warp is fitted from the standards and applied to all
+features; nothing in the original table is dropped, calibration only appends
+columns.
+
+## Download
+
+```bash
+pip install rt-anchor
+pip install "rt-anchor[report,structures]"   # + HTML/PDF report and structure hover
+```
+
+## Input
+
+Required:
+
+| Input | What |
+|-------|------|
+| **Sample feature table** | The table to calibrate. MS-DIAL / MZmine / MassCube / LipidScreener — auto-detected. Must have an **m/z** and a **retention-time** column. |
+| **Standards run** | A run of the standard panel (same formats) — builds the native anchor template. **Required.** |
+| **Polarity** | `positive` or `negative`. |
+
+Optional: per-injection files (per-sample tier + repeatability QC), a custom
+standard manifest / reference baseline, and the matching parameters
+(`mz_tol_ppm`, `rt_window_min`, `min_anchors`, `extrapolate`).
+
+```python
+from rt_anchor import calibrate, write_results
+res = calibrate("samples.txt", polarity="positive", standards_table="standards.txt")
+write_results(res, "out/run1")
+```
+```bash
+rt-anchor calibrate --samples samples.txt --standards standards.txt --polarity positive --out out/run1
+```
+
+## Output
+
+- **`*_calibrated.csv`** — the original table + appended columns: `RI` (iRT-style
+  index), `RI_uncertainty`, `RI_reliability` (high/medium/low/none), `RI_spread`,
+  `n_contributing`, `is_extrapolated`, `calibration_scope`, `warp_source`.
+- **`*_model.json`** — the fitted warp, anchors, and QC metrics.
+- **`*_anchors.csv`**, **`*_log.txt`** — anchors used and a run log.
+- **`*_report.html`** + **`*_report.pdf`** — an interactive + static report
+  (detection, calibration warp, repeatability). On by default; `--no-report` to skip.
+
+## License
+
+MIT

rt_anchor-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rt-anchor"
+version = "0.1.0"
+description = "Standard-panel retention-index (iRT) calibration for LC-MS lipidomics feature tables (MS-DIAL / MZmine / MassCube / LipidScreener)"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Bowen Yang" }]
+keywords = [
+    "retention index", "iRT", "retention time", "calibration",
+    "lipidomics", "metabolomics", "LC-MS", "mass spectrometry",
+    "MS-DIAL", "MZmine", "MassCube", "LipidScreener",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "Topic :: Scientific/Engineering :: Chemistry",
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "numpy>=1.21",
+    "pandas>=1.3",
+    "scipy>=1.7",
+    "matplotlib>=3.5",
+    "plotly>=5.0",
+]
+
+[project.optional-dependencies]
+excel = ["openpyxl>=3.0"]
+report = ["matplotlib>=3.5", "plotly>=5.0"]
+structures = ["rdkit>=2022.9"]   # optional: molecular-structure hover for the default panel
+test = ["pytest>=7.0", "openpyxl>=3.0"]
+
+[project.scripts]
+rt-anchor = "rt_anchor.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+rt_anchor = ["py.typed"]

rt_anchor-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

rt_anchor-0.1.0/src/rt_anchor/__init__.py

@@ -0,0 +1,45 @@
+"""rt_anchor — standard-panel retention-index (iRT) calibration for LC-MS lipidomics.
+
+Unifies feature tables from MS-DIAL, MZmine, MassCube and LipidScreener, then
+warps retention time onto a dimensionless iRT scale anchored by a spiked lipid
+standard panel. Outputs are CSV / JSON / log (no visualisation).
+
+Quick start
+-----------
+>>> from rt_anchor import calibrate, write_results
+>>> res = calibrate("samples.txt", polarity="positive", standards_table="std.txt")
+>>> write_results(res, "out/run1")
+"""
+
+from __future__ import annotations
+
+from .calibrate import MonotoneWarp, apply_warp, fit_warp
+from .config import CalibrationConfig
+from .errors import (
+    AnchorIdentificationError,
+    CalibrationError,
+    ColumnResolutionError,
+    ConfigError,
+    InputFormatError,
+    PanelError,
+    RtAnchorError,
+    RTUnitError,
+)
+from .helpers import describe_input, setup_logger, which_format, write_results
+from .identify import build_native_template, identify_anchors
+from .io import FeatureTable, detect_format, load_feature_table
+from .panel import DEFAULT_MANIFEST, Panel, build_panel, load_manifest_csv, load_reference_csv
+from .pipeline import CalibrationResult, calibrate
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "calibrate", "CalibrationResult", "CalibrationConfig",
+    "load_feature_table", "detect_format", "FeatureTable",
+    "build_panel", "Panel", "DEFAULT_MANIFEST", "load_manifest_csv", "load_reference_csv",
+    "build_native_template", "identify_anchors",
+    "fit_warp", "apply_warp", "MonotoneWarp",
+    "describe_input", "which_format", "write_results", "setup_logger",
+    "RtAnchorError", "InputFormatError", "ColumnResolutionError", "RTUnitError",
+    "PanelError", "AnchorIdentificationError", "CalibrationError", "ConfigError",
+]

rt_anchor-0.1.0/src/rt_anchor/calibrate.py

@@ -0,0 +1,149 @@
+"""The calibration itself: a monotone RT->iRT warp plus numeric uncertainty.
+
+* :class:`MonotoneWarp` — shape-preserving monotone interpolation (PCHIP) with
+  ``extrapolate=False`` so features beyond the anchor span become NaN (never a
+  fabricated value). Leave-one-anchor-out residuals give the honest in-domain
+  interpolation error.
+* :func:`apply_warp` — turn a warp + a config into per-feature ``RI``,
+  ``RI_uncertainty``, ``RI_reliability`` and ``is_extrapolated``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, List, Optional
+
+import numpy as np
+import pandas as pd
+from scipy.interpolate import PchipInterpolator
+
+from .config import CalibrationConfig
+from .errors import CalibrationError
+
+
+@dataclass
+class MonotoneWarp:
+    rt: np.ndarray          # anchor observed RT (minutes), strictly increasing
+    irt: np.ndarray         # anchor iRT values
+    _pchip: PchipInterpolator
+    loo_resid: np.ndarray   # per-anchor leave-one-out residual (iRT units)
+
+    @property
+    def rt_min(self) -> float:
+        return float(self.rt[0])
+
+    @property
+    def rt_max(self) -> float:
+        return float(self.rt[-1])
+
+    def predict(self, rt_min: np.ndarray, extrapolate: bool = False,
+                max_extrap_min: float = 1.0) -> np.ndarray:
+        rt_min = np.asarray(rt_min, dtype=float)
+        out = self._pchip(rt_min)  # NaN outside [rt_min, rt_max] (extrapolate=False)
+        if extrapolate:
+            below = rt_min < self.rt_min
+            above = rt_min > self.rt_max
+            # linear terminal-slope extrapolation, capped
+            if below.any():
+                s = (self.irt[1] - self.irt[0]) / (self.rt[1] - self.rt[0])
+                d = np.clip(self.rt_min - rt_min[below], 0, max_extrap_min)
+                out[below] = self.irt[0] - s * d
+            if above.any():
+                s = (self.irt[-1] - self.irt[-2]) / (self.rt[-1] - self.rt[-2])
+                d = np.clip(rt_min[above] - self.rt_max, 0, max_extrap_min)
+                out[above] = self.irt[-1] + s * d
+        return out
+
+
+def fit_warp(anchor_rt_min: np.ndarray, anchor_irt: np.ndarray,
+             config: CalibrationConfig) -> MonotoneWarp:
+    rt = np.asarray(anchor_rt_min, dtype=float)
+    irt = np.asarray(anchor_irt, dtype=float)
+    order = np.argsort(rt)
+    rt, irt = rt[order], irt[order]
+
+    # strict-increase guard (PCHIP requires strictly increasing x)
+    keep = np.concatenate([[True], np.diff(rt) > config.tie_epsilon_min])
+    rt, irt = rt[keep], irt[keep]
+    if rt.size < max(2, config.min_anchors_hard):
+        raise CalibrationError(
+            f"Only {rt.size} usable anchors after the monotonicity guard "
+            f"(need >= {max(2, config.min_anchors_hard)}). Loosen mz_tol_ppm / RT "
+            f"window, provide a standard-panel run, or check the polarity."
+        )
+    if not np.all(np.diff(irt) > 0):
+        raise CalibrationError("Anchor iRT values are not strictly increasing — reference baseline is inconsistent.")
+
+    pchip = PchipInterpolator(rt, irt, extrapolate=False)
+    loo = _loo_residuals(rt, irt)
+    return MonotoneWarp(rt=rt, irt=irt, _pchip=pchip, loo_resid=loo)
+
+
+def _loo_residuals(rt: np.ndarray, irt: np.ndarray) -> np.ndarray:
+    """Leave-one-anchor-out residual (iRT) at each anchor; NaN for the two ends
+    (holding out an endpoint is extrapolation, not interpolation)."""
+    n = rt.size
+    res = np.full(n, np.nan)
+    for i in range(1, n - 1):  # interior only
+        m = np.ones(n, bool); m[i] = False
+        f = PchipInterpolator(rt[m], irt[m], extrapolate=True)
+        res[i] = float(f(rt[i]) - irt[i])
+    return res
+
+
+def apply_warp(rt_min: np.ndarray, warp: MonotoneWarp, config: CalibrationConfig,
+               scope: str, warp_source: str = "self") -> pd.DataFrame:
+    """Compute RI + uncertainty for an array of feature RTs (minutes)."""
+    rt_min = np.asarray(rt_min, dtype=float)
+    ri = warp.predict(rt_min, extrapolate=config.extrapolate,
+                      max_extrap_min=config.max_extrapolation_min)
+    in_span = (rt_min >= warp.rt_min) & (rt_min <= warp.rt_max)
+    is_extrap = ~in_span & np.isfinite(rt_min)
+
+    sigma = _sigma_ri(rt_min, warp, config)
+    conf = _reliability(sigma, is_extrap, config)
+
+    # keep sigma / confidence consistent with RI: an uncalibrated feature (RI NaN,
+    # e.g. beyond the anchor span with extrapolate=False) gets sigma NaN + 'none'.
+    uncal = ~np.isfinite(ri)
+    sigma[uncal] = np.nan
+    conf[uncal] = "none"
+
+    return pd.DataFrame({
+        "RI": ri,
+        "RI_uncertainty": sigma,
+        "RI_reliability": conf,
+        "is_extrapolated": is_extrap,
+        "calibration_scope": scope,
+        "warp_source": warp_source,
+    })
+
+
+def _sigma_ri(rt_min: np.ndarray, warp: MonotoneWarp, config: CalibrationConfig) -> np.ndarray:
+    slope = config.slope_irt_per_min()
+    # interior LOO residual as a function of RT (|resid|, iRT units)
+    interior = np.isfinite(warp.loo_resid)
+    if interior.any():
+        loo_interp = np.interp(rt_min, warp.rt[interior], np.abs(warp.loo_resid[interior]),
+                               left=np.abs(warp.loo_resid[interior][0]),
+                               right=np.abs(warp.loo_resid[interior][-1]))
+        sigma_scale = float(np.nanmedian(np.abs(warp.loo_resid[interior])))
+    else:
+        loo_interp = np.zeros_like(rt_min)
+        sigma_scale = 0.0
+    # nearest-anchor gap term (minutes -> iRT)
+    nearest_gap = np.min(np.abs(rt_min[:, None] - warp.rt[None, :]), axis=1)
+    gap_term = slope * config.sigma_gap_factor * nearest_gap
+    sigma_local = np.maximum(loo_interp, gap_term)
+    sigma = np.sqrt(sigma_local ** 2 + sigma_scale ** 2)
+    sigma[~np.isfinite(rt_min)] = np.nan
+    return sigma
+
+
+def _reliability(sigma: np.ndarray, is_extrap: np.ndarray, config: CalibrationConfig) -> np.ndarray:
+    conf = np.full(sigma.shape, "medium", dtype=object)
+    conf[sigma < config.conf_high_irt] = "high"
+    conf[sigma > config.conf_low_irt] = "low"
+    conf[is_extrap] = "low"
+    conf[~np.isfinite(sigma)] = "none"
+    return conf

rt_anchor-0.1.0/src/rt_anchor/cli.py

@@ -0,0 +1,137 @@
+"""Command-line interface.
+
+    rt-anchor describe  <table>
+    rt-anchor calibrate --samples <table> --standards <run> --polarity positive [options] --out <prefix>
+
+Outputs are CSV / JSON / log only (no plots).
+"""
+
+from __future__ import annotations
+
+import argparse
+import glob
+import json
+import os
+import sys
+from typing import List, Optional
+
+from .config import CalibrationConfig
+from .errors import RtAnchorError
+from .helpers import describe_input, setup_logger, write_results
+from .panel import load_manifest_csv, load_reference_csv
+from .pipeline import calibrate
+
+
+def _collect_single_files(spec: Optional[str]) -> Optional[List[str]]:
+    if not spec:
+        return None
+    if os.path.isdir(spec):
+        files = sorted(glob.glob(os.path.join(spec, "*.txt")) +
+                       glob.glob(os.path.join(spec, "*.csv")))
+    else:
+        files = sorted(glob.glob(spec))
+    return files or None
+
+
+def _build_config(args) -> CalibrationConfig:
+    if args.config:
+        with open(args.config) as fh:
+            cfg = CalibrationConfig.from_dict(json.load(fh))
+    else:
+        cfg = CalibrationConfig()        # sensible defaults; tune with the flags below
+    if args.mz_tol_ppm is not None:
+        cfg.mz_tol_ppm = args.mz_tol_ppm
+    if args.rt_window is not None:
+        cfg.rt_window_min = args.rt_window
+    if args.min_anchors is not None:
+        cfg.min_anchors = args.min_anchors
+    if args.extrapolate:
+        cfg.extrapolate = True
+    return cfg
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    p = argparse.ArgumentParser(prog="rt-anchor", description="Standard-panel iRT calibration for LC-MS lipidomics.")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    d = sub.add_parser("describe", help="Detect format + summarise a table (no calibration).")
+    d.add_argument("table")
+    d.add_argument("--format", dest="source_format", default=None)
+    d.add_argument("--polarity", default=None)
+
+    c = sub.add_parser("calibrate", help="Calibrate a feature table to iRT.")
+    c.add_argument("--samples", required=True, help="Feature table to calibrate.")
+    c.add_argument("--standards", required=True,
+                   help="Standard-panel run (required; builds the native anchor template).")
+    c.add_argument("--polarity", required=True, choices=["positive", "negative", "pos", "neg"])
+    c.add_argument("--single-files", default=None,
+                   help="Dir or glob of per-injection tables -> per-sample tier.")
+    c.add_argument("--format", dest="source_format", default=None,
+                   help="Force input format (masscube/lipidscreener/msdial/mzmine).")
+    c.add_argument("--rt-unit", dest="rt_unit", default=None, choices=["min", "sec"])
+    c.add_argument("--manifest", default=None, help="Custom standard manifest CSV (Mode B).")
+    c.add_argument("--reference", default=None, help="Custom reference-baseline CSV.")
+    c.add_argument("--config", default=None,
+                   help="JSON config file (base; the --mz-tol-ppm/--rt-window/--min-anchors flags override individual fields).")
+    # matching / robustness parameters (replace any notion of an 'instrument type')
+    c.add_argument("--mz-tol-ppm", dest="mz_tol_ppm", type=float, default=None,
+                   help="m/z match tolerance in ppm (default 15).")
+    c.add_argument("--rt-window", dest="rt_window", type=float, default=None,
+                   help="RT search window around the native anchor RT, minutes (default 0.5).")
+    c.add_argument("--min-anchors", dest="min_anchors", type=int, default=None,
+                   help="Minimum anchors for a confident warp (default 6).")
+    c.add_argument("--extrapolate", action="store_true",
+                   help="Assign RI beyond the anchor span (capped); default off -> NaN beyond span.")
+    c.add_argument("--no-report", action="store_true", help="Skip the HTML/PDF report (data only).")
+    c.add_argument("--tic-style", default="clean", choices=["clean", "realistic", "both"],
+                   help="Reconstructed-TIC style in the report (default clean; realistic adds simulated noise).")
+    c.add_argument("--report-format", default="html,pdf",
+                   help="Comma list of report formats: html,pdf.")
+    c.add_argument("--out", required=True, help="Output path prefix.")
+
+    args = p.parse_args(argv)
+
+    if args.cmd == "describe":
+        try:
+            print(json.dumps(describe_input(args.table, source_format=args.source_format,
+                                            polarity=args.polarity), indent=2, default=str))
+            return 0
+        except RtAnchorError as e:
+            print(f"ERROR: {e}", file=sys.stderr)
+            return 2
+        except Exception as e:  # e.g. FileNotFoundError -> clean message, no traceback
+            print(f"ERROR: {type(e).__name__}: {e}", file=sys.stderr)
+            return 3
+
+    # calibrate
+    log = setup_logger()
+    try:
+        cfg = _build_config(args)
+        manifest = load_manifest_csv(args.manifest) if args.manifest else None
+        reference = load_reference_csv(args.reference) if args.reference else None
+        single = _collect_single_files(args.single_files)
+        if single:
+            log.info(f"per-sample tier: {len(single)} injection tables")
+        result = calibrate(
+            sample_table=args.samples, polarity=args.polarity,
+            standards_table=args.standards, single_files=single,
+            config=cfg, manifest=manifest, reference=reference,
+            source_format=args.source_format, rt_unit=args.rt_unit,
+        )
+        for line in result.log:
+            log.info(line)
+        fmts = tuple(f.strip() for f in args.report_format.split(",") if f.strip())
+        paths = write_results(result, args.out, report=not args.no_report,
+                              tic_style=args.tic_style, report_formats=fmts)
+        log.info(f"wrote: {json.dumps(paths)}")
+        return 0
+    except RtAnchorError as e:
+        log.error(str(e))
+        return 2
+    except Exception as e:  # unexpected -> surface with type
+        log.error(f"{type(e).__name__}: {e}")
+        return 3
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

rt_anchor-0.1.0/src/rt_anchor/config.py

@@ -0,0 +1,86 @@
+"""Configuration for the calibration.
+
+Defaults are tuned for **QTOF** data (the common case for this project):
+wider m/z tolerance and RT windows than an Orbitrap would need. Every value is
+override-able (constructor kwargs, ``CalibrationConfig.qtof()`` /
+``.orbitrap()`` presets, or ``from_dict``). Nothing here is instrument-locked.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Optional, Tuple
+
+
+@dataclass
+class CalibrationConfig:
+    # ---- m/z matching ----
+    mz_tol_ppm: float = 15.0            # QTOF default (Orbitrap ~8)
+    mz_tol_min_da: float = 0.0          # optional absolute floor on the ppm window
+
+    # ---- RT search window around the native-template anchor RT (minutes) ----
+    rt_window_min: float = 0.5          # QTOF default (Orbitrap ~0.3)
+    # window used when NO native template exists and we must seed from reference RT
+    rt_window_seed_min: float = 2.0
+
+    # ---- iRT scale (fixed method constants; dimensionless, minute-derived) ----
+    scale_rt_lo_min: float = 1.0
+    scale_rt_hi_min: float = 18.4
+
+    # ---- anchor acceptance / warp robustness ----
+    min_anchors: int = 6                # below this -> low-confidence / uncalibrated
+    min_anchors_hard: int = 3           # below this -> refuse to calibrate
+    coverage_gap_min: float = 3.0       # max in-domain inter-anchor RT gap (minutes)
+    tie_epsilon_min: float = 0.005      # equal-RT tolerance for monotonicity guard
+    max_drop_anchors: int = 3           # cap on anchors removed by the guard
+
+    # ---- extrapolation ----
+    extrapolate: bool = False           # if False: RI = NaN beyond anchor span
+    max_extrapolation_min: float = 1.0  # only used when extrapolate=True
+
+    # ---- confidence thresholds (iRT units) ----
+    conf_high_irt: float = 0.6          # RI_uncertainty < this  -> high
+    conf_low_irt: float = 3.0           # RI_uncertainty > this  -> low
+    sigma_gap_factor: float = 0.1       # sigma_local ~= factor * nearest-anchor gap (min) * slope
+
+    # ---- optional peak-quality gate (applied only if the columns exist) ----
+    min_gaussian_similarity: float = 0.0    # 0 disables; spec suggests ~0.7
+    asymmetry_range: Tuple[float, float] = (0.0, 1e9)  # widen -> disabled
+
+    # ---- RT unit handling ----
+    rt_unit: Optional[str] = None       # None = auto (per-format default + range check)
+
+    # ---- misc ----
+    verbose: bool = True
+
+    def slope_irt_per_min(self) -> float:
+        return 100.0 / (self.scale_rt_hi_min - self.scale_rt_lo_min)
+
+    def irt_from_rt(self, rt_min: float) -> float:
+        return 100.0 * (rt_min - self.scale_rt_lo_min) / (self.scale_rt_hi_min - self.scale_rt_lo_min)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "CalibrationConfig":
+        from .errors import ConfigError
+        known = {f for f in cls.__dataclass_fields__}  # type: ignore[attr-defined]
+        unknown = set(d) - known
+        if unknown:
+            raise ConfigError(f"Unknown config keys: {sorted(unknown)}. Known: {sorted(known)}")
+        cfg = cls(**{k: v for k, v in d.items() if k in known})
+        if cfg.asymmetry_range is not None:
+            cfg.asymmetry_range = tuple(cfg.asymmetry_range)  # json gives lists
+        return cfg
+
+    # ---- instrument presets ----
+    @classmethod
+    def qtof(cls, **overrides) -> "CalibrationConfig":
+        return cls(**overrides)
+
+    @classmethod
+    def orbitrap(cls, **overrides) -> "CalibrationConfig":
+        base = dict(mz_tol_ppm=8.0, rt_window_min=0.3)
+        base.update(overrides)
+        return cls(**base)

rt_anchor-0.1.0/src/rt_anchor/errors.py

@@ -0,0 +1,40 @@
+"""Typed exceptions for rt_anchor.
+
+Every error carries an actionable message: what went wrong, which input it
+concerns, and (where possible) how to fix it. Callers can catch the base
+``RtAnchorError`` to handle any package-level failure.
+"""
+
+from __future__ import annotations
+
+
+class RtAnchorError(Exception):
+    """Base class for all rt_anchor errors."""
+
+
+class ConfigError(RtAnchorError):
+    """The configuration is invalid (unknown keys, bad values)."""
+
+
+class InputFormatError(RtAnchorError):
+    """The input file could not be parsed or its format could not be recognised."""
+
+
+class ColumnResolutionError(InputFormatError):
+    """A required logical column (m/z or RT) could not be located in the table."""
+
+
+class RTUnitError(RtAnchorError):
+    """Retention-time units are ambiguous or inconsistent with the declared unit."""
+
+
+class PanelError(RtAnchorError):
+    """The standard manifest / reference baseline is malformed or incomplete."""
+
+
+class AnchorIdentificationError(RtAnchorError):
+    """Too few standards could be identified to build a calibration."""
+
+
+class CalibrationError(RtAnchorError):
+    """The monotone warp could not be fitted (e.g. degenerate anchors)."""