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