From 7d1a35f6547829847f235573c814a518f98596d2 Mon Sep 17 00:00:00 2001 From: Longping Fu Date: Wed, 14 Oct 2026 11:36:48 -0400 Subject: [PATCH 1/2] recorded_precursor_ms1 on both readers: the MS1 the instrument recorded, with the fallback reason MzMLReader now reads the precursor's spectrumRef (the cache already stored it). The recorded scan is used when it exists and is MS1; otherwise the nearest earlier MS1 is returned with 'nearest_preceding:'. find_best_ms1 (strongest of the neighbours) is unchanged. Tested on a hand-written mzML and the cache built from it. Co-Authored-By: Claude Opus 5.5 --- src/mzml_utils/reader.py | 42 ++++++++++++++++ src/mzml_utils/spectrum_cache.py | 28 +++++++---- tests/test_recorded_precursor_ms1.py | 72 ++++++++++++++++++++++++++++ 3 files changed, 134 insertions(+), 8 deletions(-) create mode 100644 tests/test_recorded_precursor_ms1.py diff --git a/src/mzml_utils/reader.py b/src/mzml_utils/reader.py index d943ef5..00b8c6b 100644 --- a/src/mzml_utils/reader.py +++ b/src/mzml_utils/reader.py @@ -83,6 +83,16 @@ def _parse_scan_num(spec: dict) -> int: return 0 +def _scan_num_from_ref(ref: Optional[str]) -> Optional[int]: + """Scan number from a nativeID such as 'controllerType=0 controllerNumber=1 scan=1234'.""" + if ref and "scan=" in ref: + try: + return int(ref.split("scan=")[-1].split()[0]) + except ValueError: + return None + return None + + def _extract_spectrum(spec: dict) -> Spectrum: """Convert a pyteomics spectrum dict to a Spectrum object.""" scan_num = _parse_scan_num(spec) @@ -266,6 +276,38 @@ def find_best_ms1(self, ms2_scan: int, precursor_mz: float, best_scan = ms1_scans[0] return best_scan + def recorded_precursor_ms1(self, scan_num: int, max_lookback: int = 500) -> Tuple[Optional[int], str]: + """(MS1 scan, source) for an MSn scan: the scan its precursor element records. + + The recorded scan (``spectrumRef``) is used when it exists and is MS1; source + ``'recorded'``. Otherwise the nearest earlier MS1 is returned with source + ``'nearest_preceding:'`` (reason: ``no_recorded_ref``, ``recorded_ref_missing``, + ``recorded_ref_not_ms1``), or ``(None, reason)``. Unlike ``find_best_ms1`` this does not + look for the strongest precursor among neighbours: it is the scan the instrument chose. + Same method on ``SpectrumCache``. + """ + scan_id = f'controllerType=0 controllerNumber=1 scan={scan_num}' + try: + spec = self._reader.get_by_id(scan_id) + except (KeyError, IndexError): + return None, "scan_missing" + precs = (spec.get("precursorList") or {}).get("precursor") or [] + ref = _scan_num_from_ref(precs[0].get("spectrumRef")) if precs else None + if ref is None: + reason = "no_recorded_ref" + else: + rs = self.get_spectrum(ref) + if rs is not None and rs.ms_level == 1: + return ref, "recorded" + reason = "recorded_ref_missing" if rs is None else "recorded_ref_not_ms1" + s = scan_num - 1 + while s > 0 and scan_num - s <= max_lookback: + sp = self.get_spectrum(s) + if sp is not None and sp.ms_level == 1: + return s, f"nearest_preceding:{reason}" + s -= 1 + return None, reason + def extract_metadata(self, scan_num: int) -> Optional[Dict]: """ Extract metadata for a single scan as a plain dict. diff --git a/src/mzml_utils/spectrum_cache.py b/src/mzml_utils/spectrum_cache.py index 6f55e0f..4934144 100644 --- a/src/mzml_utils/spectrum_cache.py +++ b/src/mzml_utils/spectrum_cache.py @@ -43,7 +43,7 @@ import numpy as np # Reuse mzml_utils' own extraction + data model (never reimplement, never modify it). -from .reader import Spectrum, classify_activation, _extract_spectrum +from .reader import Spectrum, classify_activation, _extract_spectrum, _scan_num_from_ref SCHEMA_VERSION = 1 _HCD_RE = re.compile(r"@hcd([\d.]+)") @@ -116,13 +116,6 @@ def decode_peaks(mz_blob, int_blob) -> Tuple[np.ndarray, np.ndarray]: return mz, it -def _scan_num_from_ref(ref: Optional[str]) -> Optional[int]: - if ref and "scan=" in ref: - try: - return int(ref.split("scan=")[-1].split()[0]) - except ValueError: - return None - return None def _jsonable(obj, _depth=0): @@ -617,6 +610,25 @@ def find_preceding_ms1(self, scan_num: int) -> Optional[int]: (scan_num,)).fetchone() return r["scan_num"] if r else None + def recorded_precursor_ms1(self, scan_num: int, max_lookback: int = 500) -> Tuple[Optional[int], str]: + """(MS1 scan, source): the MS1 scan the precursor element records, checked to exist and to + be MS1 (source 'recorded'), else the nearest earlier MS1 with source + 'nearest_preceding:'. Same contract as MzMLReader.recorded_precursor_ms1.""" + r = self._conn.execute("SELECT precursor_spectrum_ref FROM scans WHERE scan_num=?", (scan_num,)).fetchone() + if r is None: + return None, "scan_missing" + ref = r["precursor_spectrum_ref"] + if not ref: + reason = "no_recorded_ref" + else: + rr = self._conn.execute("SELECT ms_level FROM scans WHERE scan_num=?", (ref,)).fetchone() + if rr is not None and rr["ms_level"] == 1: + return int(ref), "recorded" + reason = "recorded_ref_missing" if rr is None else "recorded_ref_not_ms1" + r = self._conn.execute("SELECT scan_num FROM scans WHERE ms_level=1 AND scan_num=? " + "ORDER BY scan_num DESC LIMIT 1", (scan_num, scan_num - max_lookback)).fetchone() + return (int(r["scan_num"]), f"nearest_preceding:{reason}") if r else (None, reason) + def meta(self) -> dict: return {r["key"]: json.loads(r["value"]) for r in self._conn.execute("SELECT key, value FROM meta")} diff --git a/tests/test_recorded_precursor_ms1.py b/tests/test_recorded_precursor_ms1.py new file mode 100644 index 0000000..89933b0 --- /dev/null +++ b/tests/test_recorded_precursor_ms1.py @@ -0,0 +1,72 @@ +"""recorded_precursor_ms1: the MS1 the instrument recorded for an MSn scan, on both readers. + +A hand-written five-scan mzML: MS1 1 and 2, then MS2 scans whose precursor element records MS1 1 +(not the nearest MS1, 2), nothing, a non-MS1 scan, and a scan that does not exist.""" +import base64 +import os + +import numpy as np + +from mzml_utils import spectrum_cache as sc +from mzml_utils.reader import MzMLReader + + +def _arr(values): + return base64.b64encode(np.asarray(values, dtype="' + '' + '' + '' + '' + '') + filt = "FTMS + p NSI Full ms" if level == 1 else "FTMS + c NSI d Full ms2 500.0@hcd30.00" + arrays = "".join( + f'' + '' + '' + f'{_arr(v)}' + for v, acc, name in ((mz, "MS:1000514", "m/z array"), (it, "MS:1000515", "intensity array"))) + return (f'' + f'' + f'' + f'' + f'{prec}{arrays}') + + +def _write(path): + specs = [(1, 1, None), (2, 1, None), (3, 2, 1), (4, 2, None), (5, 2, 3), (6, 2, 99)] + body = "".join(_spectrum(i, s, lv, ref) for i, (s, lv, ref) in enumerate(specs)) + path.write_text('{body}' + '') + + +EXPECTED = {3: (1, "recorded"), 4: (2, "nearest_preceding:no_recorded_ref"), + 5: (2, "nearest_preceding:recorded_ref_not_ms1"), 6: (2, "nearest_preceding:recorded_ref_missing"), + 42: (None, "scan_missing")} + + +def test_mzml_reader(tmp_path): + p = tmp_path / "run.mzML" + _write(p) + with MzMLReader(str(p)) as r: + assert {s: r.recorded_precursor_ms1(s) for s in EXPECTED} == EXPECTED + + +def test_cache_agrees_with_the_mzml(tmp_path): + p = tmp_path / "run.mzML" + _write(p) + db = sc.cache_path_for(str(p)) + os.makedirs(os.path.dirname(db), exist_ok=True) + sc.build_cache(str(p), db, local_copy=False) + with sc.SpectrumCache(db, mirror_local=False) as c: + assert {s: c.recorded_precursor_ms1(s) for s in EXPECTED} == EXPECTED From e6d4cf4aac3e0eade292f5213d83fc72e5ec209d Mon Sep 17 00:00:00 2001 From: Longping Fu Date: Wed, 14 Oct 2026 11:39:04 -0400 Subject: [PATCH 2/2] changelog: recorded_precursor_ms1 Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 361bc1f..027c2c0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,9 @@ All notable changes to this project are documented here. The format follows `cap_peaks()` (msconvert's rule, ties at the threshold excluded), so one tool can run on capped and uncapped MS1 side by side. `ms1_cap_status()` / `warn_if_ms1_capped()` tell a tool when its MS1 is capped and unpatched. +- `recorded_precursor_ms1(scan)` on `MzMLReader` and `SpectrumCache`: the MS1 scan the + precursor element records (`spectrumRef`), checked to exist and be MS1, else the nearest + earlier MS1 with the reason. `find_best_ms1` (strongest of the neighbours) is unchanged. - Match provenance: `MatchedIon.origin` (`deisotoped` / `raw` / `raw_fallback`, set by `canonical_match`) and `match_peaks(exclusive=False)` / `canonical_match(exclusive=False)`, which report a peak once per identity it fits instead of giving it to the first in priority