From 124b3df49c1b924fa4a7090278611b7c88c24fe4 Mon Sep 17 00:00:00 2001 From: Longping Fu Date: Sun, 11 Oct 2026 14:36:05 -0400 Subject: [PATCH] peak_metrics(bridge_dropouts=k) and a public bridge_dropouts(): boundaries agree with find_peaks find_peaks bridged one-scan dropouts; peak_metrics did not, so on the same zero-filled trace the enclosing peak ended at the first empty scan while the peak list ran through it. On NGlycoM012 F21 that was most of the "partial overlap" between the QC's peak and IonQuant's feature (880 of 1,354: IonQuant's wider feature held our apex, our dropout-cut peak missed its apex). bridge_dropouts(intensity, max_gap) is the one implementation both use. With bridge_dropouts > 0 every peak_metrics value comes from the bridged trace except n_signal, which counts scans with the ion in the original. Default 0 is R. Co-Authored-By: Claude Opus 5.5 --- src/mzml_utils/__init__.py | 2 ++ src/mzml_utils/xic.py | 46 +++++++++++++++++++++++++++++++------- tests/test_xic.py | 20 +++++++++++++++++ 3 files changed, 60 insertions(+), 8 deletions(-) diff --git a/src/mzml_utils/__init__.py b/src/mzml_utils/__init__.py index 8974125..3126017 100644 --- a/src/mzml_utils/__init__.py +++ b/src/mzml_utils/__init__.py @@ -104,6 +104,7 @@ PeakMetrics, find_peaks, TracePeak, + bridge_dropouts, beta_values, ) @@ -226,6 +227,7 @@ "PeakMetrics", "find_peaks", "TracePeak", + "bridge_dropouts", "beta_values", # chrom_extract (peak table -> chromatograms across runs) "extract_chromatograms", diff --git a/src/mzml_utils/xic.py b/src/mzml_utils/xic.py index f6d2513..0f607c8 100644 --- a/src/mzml_utils/xic.py +++ b/src/mzml_utils/xic.py @@ -459,6 +459,30 @@ def _bounds_from_apex(inten: np.ndarray, apex: int, baseline: float, threshold: return int(left), int(right) +def bridge_dropouts(intensity, max_gap: int = 1) -> np.ndarray: + """A copy of ``intensity`` with every run of at most ``max_gap`` zero scans that has signal + on both sides filled by linear interpolation between its neighbours. + + A zero-filled XIC writes 0 for a scan without the ion. Near the Orbitrap's noise floor a + single scan inside an elution often lacks the centroid, and every valley walk stops there, + splitting one elution in two. Bridging rejoins it. Interpolated values lie between their + neighbours, so no maximum is created or moved. Leading and trailing zeros, and longer gaps, + are left as they are. ``max_gap=0`` returns an unchanged copy. + """ + return _bridge_gaps(np.asarray(intensity, dtype=float), int(max_gap)) + + +def _bridge_gaps(raw: np.ndarray, max_gap: int) -> np.ndarray: + out = raw.copy() + if max_gap <= 0: + return out + nz = np.flatnonzero(raw > 0) + for a, b in zip(nz[:-1], nz[1:]): + if 1 < b - a <= max_gap + 1: + out[a + 1:b] = np.interp(np.arange(a + 1, b), [a, b], [raw[a], raw[b]]) + return out + + def peak_boundary(xic: "XIC", *, contains_rt: Optional[float] = None, apex_window: Optional[Tuple[float, float]] = None, @@ -670,7 +694,8 @@ def peak_metrics(xic: "XIC", *, threshold: float = 0.1, baseline_threshold: float = 0.1, baseline_quantile: float = 0.1, - nearest_valley: bool = False) -> PeakMetrics: + nearest_valley: bool = False, + bridge_dropouts: int = 0) -> PeakMetrics: """Boundaries, in-boundary area and quality metrics of one peak in an XIC. The boundary arguments are those of :func:`peak_boundary`: ``contains_rt`` (or @@ -687,8 +712,18 @@ def peak_metrics(xic: "XIC", *, half (MAD) or a tenth (q10) of the trace is zero, as MsQuality returns NA -- common for a zero-filled XIC over a wide window. + ``bridge_dropouts=k`` measures the trace after :func:`bridge_dropouts` (runs of at most k + zero scans with signal on both sides filled), as :func:`find_peaks` does, so the two agree + on one zero-filled trace; every metric then comes from the bridged trace except + ``n_signal``, which counts the scans where the ORIGINAL trace has the ion. The default 0 + reproduces R. + These are measurements, not verdicts: no threshold is applied here. """ + raw = np.asarray(xic.intensity, dtype=float) + if bridge_dropouts > 0: + xic = XIC(target_mz=xic.target_mz, rt=np.asarray(xic.rt, dtype=float), + intensity=_bridge_gaps(raw, int(bridge_dropouts))) b = peak_boundary(xic, contains_rt=contains_rt, apex_window=apex_window, threshold=threshold, baseline_threshold=baseline_threshold, baseline_quantile=baseline_quantile, @@ -720,7 +755,7 @@ def peak_metrics(xic: "XIC", *, snr = apex_int / mad if mad > 0 else float("nan") q10 = float(np.quantile(inten, baseline_quantile)) prominence = (apex_int - q10) / q10 if q10 > 0 else float("nan") - n_signal = int(np.count_nonzero(seg_int > q10)) + n_signal = int(np.count_nonzero(raw[left:right + 1] > q10)) beta_cor, beta_snr = beta_values(seg_int, seg_rt) if len(seg_int) >= 5 else (float("nan"),) * 2 @@ -812,12 +847,7 @@ def find_peaks(xic: "XIC", *, if n < 3 or max_peaks < 1: return [] raw = inten - if bridge_dropouts > 0: - inten = inten.copy() - nz = np.flatnonzero(raw > 0) - for a, b in zip(nz[:-1], nz[1:]): - if 1 < b - a <= bridge_dropouts + 1: - inten[a + 1:b] = np.interp(np.arange(a + 1, b), [a, b], [raw[a], raw[b]]) + inten = _bridge_gaps(raw, int(bridge_dropouts)) baseline = float(np.quantile(inten, baseline_quantile)) # as peak_boundary prev_ok = np.r_[True, inten[1:] >= inten[:-1]] next_ok = np.r_[inten[:-1] >= inten[1:], True] diff --git a/tests/test_xic.py b/tests/test_xic.py index 117a119..3a88892 100644 --- a/tests/test_xic.py +++ b/tests/test_xic.py @@ -537,6 +537,26 @@ def test_bridge_dropouts_rejoins_the_split_elution(self): assert len(two) == 1 assert y[52] == 0.0 # the caller's trace is not modified + def test_bridge_dropouts_helper(self): + from mzml_utils import bridge_dropouts + y = np.array([0, 4, 0, 8, 0, 0, 2, 0], dtype=float) + assert bridge_dropouts(y, 1).tolist() == [0, 4, 6, 8, 0, 0, 2, 0] + assert bridge_dropouts(y, 2).tolist() == [0, 4, 6, 8, 6, 4, 2, 0] + assert bridge_dropouts(y, 0).tolist() == y.tolist() and y[2] == 0 # input untouched + + def test_peak_metrics_bridged_agrees_with_find_peaks(self): + from mzml_utils.xic import find_peaks + rt = np.linspace(0, 10, 101) + y = np.where(np.abs(rt - 5) < 1.5, _gauss(rt, 5, 0.5, 1e5), 0.0) + y[53] = 0.0 # a dropout just after the apex + xic = XIC(0.0, rt, y) + cut = peak_metrics(xic, contains_rt=5.0, nearest_valley=True) + assert cut.right_rt == pytest.approx(5.3) # unbridged: the dropout ends the peak + pm = peak_metrics(xic, contains_rt=5.0, nearest_valley=True, bridge_dropouts=1) + (p,) = find_peaks(xic, bridge_dropouts=1) + assert (pm.left_rt, pm.apex_rt, pm.right_rt) == (p.left_rt, p.apex_rt, p.right_rt) + assert pm.n_signal == p.n_signal == pm.n_points - 3 # two empty boundaries + the dropout + def test_n_signal_counts_only_scans_with_the_ion(self): from mzml_utils.xic import find_peaks rt = np.arange(11, dtype=float)