Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
42 changes: 42 additions & 0 deletions src/mzml_utils/reader.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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>'`` (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.
Expand Down
28 changes: 20 additions & 8 deletions src/mzml_utils/spectrum_cache.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.]+)")
Expand Down Expand Up @@ -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):
Expand Down Expand Up @@ -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:<reason>'. 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<? 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")}

Expand Down
72 changes: 72 additions & 0 deletions tests/test_recorded_precursor_ms1.py
Original file line number Diff line number Diff line change
@@ -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="<f8").tobytes()).decode()


def _spectrum(idx, scan, level, ref=None):
nid = f"controllerType=0 controllerNumber=1 scan={scan}"
mz, it = [400.0, 500.0], [10.0, 20.0]
prec = ""
if level == 2:
ref_attr = f' spectrumRef="controllerType=0 controllerNumber=1 scan={ref}"' if ref else ""
prec = (f'<precursorList count="1"><precursor{ref_attr}><selectedIonList count="1"><selectedIon>'
'<cvParam cvRef="MS" accession="MS:1000744" name="selected ion m/z" value="500.0"/>'
'<cvParam cvRef="MS" accession="MS:1000041" name="charge state" value="2"/>'
'</selectedIon></selectedIonList><activation>'
'<cvParam cvRef="MS" accession="MS:1000422" name="beam-type collision-induced dissociation" value=""/>'
'</activation></precursor></precursorList>')
filt = "FTMS + p NSI Full ms" if level == 1 else "FTMS + c NSI d Full ms2 500.0@hcd30.00"
arrays = "".join(
f'<binaryDataArray encodedLength="{len(_arr(v))}">'
'<cvParam cvRef="MS" accession="MS:1000523" name="64-bit float" value=""/>'
'<cvParam cvRef="MS" accession="MS:1000576" name="no compression" value=""/>'
f'<cvParam cvRef="MS" accession="{acc}" name="{name}" value=""/><binary>{_arr(v)}</binary></binaryDataArray>'
for v, acc, name in ((mz, "MS:1000514", "m/z array"), (it, "MS:1000515", "intensity array")))
return (f'<spectrum index="{idx}" id="{nid}" defaultArrayLength="2">'
f'<cvParam cvRef="MS" accession="MS:1000511" name="ms level" value="{level}"/>'
f'<scanList count="1"><scan><cvParam cvRef="MS" accession="MS:1000016" name="scan start time" '
f'value="{scan / 10:.2f}" unitCvRef="UO" unitAccession="UO:0000031" unitName="minute"/>'
f'<cvParam cvRef="MS" accession="MS:1000512" name="filter string" value="{filt}"/></scan></scanList>'
f'{prec}<binaryDataArrayList count="2">{arrays}</binaryDataArrayList></spectrum>')


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('<?xml version="1.0" encoding="utf-8"?><mzML xmlns="http://psi.hupo.org/ms/mzml" '
f'version="1.1.0"><run id="r"><spectrumList count="{len(specs)}">{body}'
'</spectrumList></run></mzML>')


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
Loading