diff --git a/src/mzml_utils/__init__.py b/src/mzml_utils/__init__.py index 5fc92a8..8974125 100644 --- a/src/mzml_utils/__init__.py +++ b/src/mzml_utils/__init__.py @@ -102,6 +102,8 @@ peak_boundary, peak_metrics, PeakMetrics, + find_peaks, + TracePeak, beta_values, ) @@ -222,6 +224,8 @@ "peak_boundary", "peak_metrics", "PeakMetrics", + "find_peaks", + "TracePeak", "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 4f8254b..f6d2513 100644 --- a/src/mzml_utils/xic.py +++ b/src/mzml_utils/xic.py @@ -630,6 +630,11 @@ class PeakMetrics: """A boundary sits on an end of the trace: the extraction window cut the peak.""" n_points: int = 0 """Scans between the boundaries, inclusive.""" + n_signal: int = 0 + """Scans between the boundaries whose intensity is above the trace baseline (the + ``baseline_quantile`` quantile): the scans where the ion was seen. ``n_points`` + also counts the boundary scans, which on a zero-filled trace are the empty scans on + either side, so a one-scan blip has ``n_points`` 3 and ``n_signal`` 1.""" area: float = 0.0 """Trapezoidal area between the boundaries.""" fwhm: float = float("nan") @@ -715,18 +720,146 @@ 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)) beta_cor, beta_snr = beta_values(seg_int, seg_rt) if len(seg_int) >= 5 else (float("nan"),) * 2 return PeakMetrics(apex_rt=apex_rt, apex_intensity=apex_int, left_rt=float(rt[left]), right_rt=float(rt[right]), boundary_is_truncated=(left == 0 or right == len(inten) - 1), - n_points=int(right - left + 1), area=area, + n_points=int(right - left + 1), n_signal=n_signal, area=area, fwhm=fwhm, fwhm_is_truncated=fwhm_trunc, points_across_peak=pts, asymmetry=asym, snr=snr, prominence=prominence, beta_cor=beta_cor, beta_snr=beta_snr) +@dataclass +class TracePeak: + """One peak of an XIC, as found by :func:`find_peaks`. + + Retention times are in the trace's unit (minutes). + """ + + apex_rt: float + apex_intensity: float + left_rt: float + right_rt: float + n_points: int + """Scans between the boundaries, inclusive.""" + n_signal: int + """Scans between the boundaries whose intensity in the ORIGINAL trace is above the + baseline: scans where the ion was seen. A bridged dropout is not counted.""" + area: float + """Trapezoidal area between the boundaries.""" + rel_height: float + """Height above baseline relative to the tallest peak's: 1.0 for the tallest.""" + is_truncated: bool + """A boundary sits on an end of the trace: the extraction window cut the peak.""" + + def contains(self, rt: float) -> bool: + return self.left_rt <= rt <= self.right_rt + + +def find_peaks(xic: "XIC", *, + min_rel_height: float = 0.2, + max_peaks: int = 5, + threshold: float = 0.1, + baseline_threshold: float = 0.1, + baseline_quantile: float = 0.1, + nearest_valley: bool = True, + bridge_dropouts: int = 0) -> List[TracePeak]: + """Every separate peak in an XIC, tallest first, with boundaries that never overlap. + + :func:`peak_boundary` measures ONE peak. A glycopeptide XIC often holds more than + one (an isomer, a +/-1 Da neighbour, a second elution), and a reader who sees only + the peak that contains the MS2 time cannot tell that another, perhaps taller, + peak sits a minute away. This lists them all. + + Candidates are the trace's local maxima above the baseline. Taken tallest first, + each is bounded exactly as :func:`peak_boundary` bounds its apex (same baseline + quantile, valley walk and threshold fallback), and a boundary is clipped where it + would run into a peak already found, so neighbours may share a boundary scan but + never overlap. A local maximum inside an earlier peak's boundaries is a shoulder or + noise on that peak and is not reported separately; in particular two partly + resolved peaks whose valley stays above ``baseline_threshold`` are ONE peak, as in + R. The walk stops after ``max_peaks`` peaks, or at the first candidate whose height + above baseline is below ``min_rel_height`` of the tallest's. + + The tallest peak is the one :func:`peak_boundary` returns with the same arguments + and no selector. ``nearest_valley`` defaults to True here, unlike there: on a + zero-filled trace R's left walk crosses the whole flat floor, to the foot of the + next peak or the trace start, so boundaries, ``n_points`` and ``is_truncated`` + would describe empty scans rather than the elution. + + An internal dropout (a scan inside a peak where the ion is absent, intensity 0) + cuts every valley walk, so it splits one elution into two peaks that share a + zero-intensity boundary scan. ``bridge_dropouts=k`` fills every run of at most + ``k`` zero scans that has signal on both sides by linear interpolation before the + peaks are found; apexes, areas and boundaries then come from the bridged trace and + ``n_signal`` from the original. On a low-abundance glyco MS1 trace one-scan + dropouts are common (the Orbitrap drops centroids near its noise floor), so + ``bridge_dropouts=1`` is the usual setting there; the default 0 leaves the trace + as extracted. Look at the trace before reading two adjacent peaks as two species. + These are measurements, not verdicts. + + Returns ``[]`` for fewer than 3 points or a trace with nothing above baseline. + """ + inten = np.asarray(xic.intensity, dtype=float) + rt = np.asarray(xic.rt, dtype=float) + n = len(inten) + if np.isnan(inten).any(): + raise ValueError("find_peaks: intensity contains NaN (write 0 for an absent ion)") + 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]]) + 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] + cand = np.flatnonzero((inten > baseline) & prev_ok & next_ok) + if cand.size == 0: + return [] + # Tallest first; equal heights keep index order, so the first is np.argmax's choice. + cand = cand[np.argsort(-inten[cand], kind="stable")] + top = float(inten[cand[0]]) - baseline + + found: List[Tuple[int, int, int]] = [] + for a in cand: + a = int(a) + rel = (float(inten[a]) - baseline) / top + if rel < min_rel_height: + break + if any(l <= a <= r for l, _, r in found): + continue + left, right = _bounds_from_apex(inten, a, baseline, threshold, baseline_threshold, + nearest_valley) + for l2, _, r2 in found: + if r2 < a: + left = max(left, r2) + elif l2 > a: + right = min(right, l2) + found.append((left, a, right)) + if len(found) == max_peaks: + break + + peaks = [] + for left, a, right in found: + area = float(_trapz(inten[left:right + 1], rt[left:right + 1])) if right > left else 0.0 + peaks.append(TracePeak(apex_rt=float(rt[a]), apex_intensity=float(inten[a]), + left_rt=float(rt[left]), right_rt=float(rt[right]), + n_points=int(right - left + 1), + n_signal=int(np.count_nonzero(raw[left:right + 1] > baseline)), + area=area, + rel_height=(float(inten[a]) - baseline) / top, + is_truncated=(left == 0 or right == n - 1))) + return peaks + + # --------------------------------------------------------------------------- # Isotope co-elution -- trace-level precursor evidence # --------------------------------------------------------------------------- diff --git a/tests/test_xic.py b/tests/test_xic.py index ac1808a..117a119 100644 --- a/tests/test_xic.py +++ b/tests/test_xic.py @@ -456,6 +456,118 @@ def test_degenerate_inputs(self): peak_boundary(XIC(0.0, np.arange(5.0), np.array([0, 1, np.nan, 1, 0.0]))) +class TestFindPeaks: + """find_peaks lists every separate peak; peak_boundary measures one.""" + + def test_two_separated_peaks_tallest_first(self): + from mzml_utils.xic import find_peaks + rt = np.linspace(0, 10, 101) + y = _gauss(rt, 3, 0.4, 1e5) + _gauss(rt, 6.5, 0.4, 6e4) + 100.0 + 0.01 * rt + xic = XIC(0.0, rt, y) + peaks = find_peaks(xic) + assert [round(p.apex_rt, 6) for p in peaks] == [3.0, 6.5] + assert peaks[0].rel_height == 1.0 and 0.55 < peaks[1].rel_height < 0.65 + # The tallest peak is the one peak_boundary measures with the same arguments. + left, apex, right = peak_boundary(xic, nearest_valley=True) + assert (peaks[0].left_rt, peaks[0].apex_rt, peaks[0].right_rt) == (rt[left], rt[apex], rt[right]) + assert peaks[0].contains(3.4) and not peaks[0].contains(6.5) and peaks[1].contains(6.5) + + def test_boundaries_never_overlap(self): + from mzml_utils.xic import find_peaks + rt = np.linspace(0, 12, 121) + y = (_gauss(rt, 3, 0.5, 1e5) + _gauss(rt, 5.2, 0.5, 7e4) + _gauss(rt, 8, 0.4, 5e4) + + 100.0 + 0.01 * rt) + peaks = sorted(find_peaks(XIC(0.0, rt, y), min_rel_height=0.0), key=lambda p: p.apex_rt) + for a, b in zip(peaks, peaks[1:]): + assert a.right_rt <= b.left_rt # may share a boundary scan, never overlap + + def test_min_rel_height_and_max_peaks(self): + from mzml_utils.xic import find_peaks + rt = np.linspace(0, 12, 121) + y = (_gauss(rt, 3, 0.4, 1e5) + _gauss(rt, 6, 0.4, 5e4) + _gauss(rt, 9, 0.4, 1e4) + + 100.0 + 0.01 * rt) + xic = XIC(0.0, rt, y) + assert len(find_peaks(xic, min_rel_height=0.05)) == 3 + assert [round(p.apex_rt, 6) for p in find_peaks(xic)] == [3.0, 6.0] # 0.1 < 0.2 + assert [round(p.apex_rt, 6) for p in find_peaks(xic, max_peaks=1)] == [3.0] + + def test_partly_resolved_high_valley_is_one_peak(self): + from mzml_utils.xic import find_peaks + rt = np.linspace(0, 10, 101) + y = _gauss(rt, 4.6, 0.5, 1e5) + _gauss(rt, 5.6, 0.5, 9e4) + 100.0 + 0.01 * rt + peaks = find_peaks(XIC(0.0, rt, y)) + assert len(peaks) == 1 and peaks[0].left_rt < 4.0 and peaks[0].right_rt > 6.0 + + def test_zero_floor_is_not_counted_inside_a_peak_with_nearest_valley(self): + from mzml_utils.xic import find_peaks + rt = np.linspace(0, 10, 101) + y = np.where(np.abs(rt - 3) < 1.0, _gauss(rt, 3, 0.3, 5e4), 0.0) + y = y + np.where(np.abs(rt - 7) < 1.0, _gauss(rt, 7, 0.3, 1e5), 0.0) + xic = XIC(0.0, rt, y) + peaks = find_peaks(xic) + assert [round(p.apex_rt, 6) for p in peaks] == [7.0, 3.0] + assert peaks[0].left_rt == pytest.approx(6.0) and not peaks[1].is_truncated + # R's walk crosses the flat zero floor: the tallest peak's left boundary lands + # at the smaller peak's foot, and the smaller one's runs to the trace start. + r_mode = find_peaks(xic, nearest_valley=False) + assert [round(p.apex_rt, 6) for p in r_mode] == [7.0, 3.0] + assert r_mode[0].left_rt == pytest.approx(4.0) and r_mode[0].n_points > peaks[0].n_points + assert r_mode[1].left_rt == 0.0 and r_mode[1].is_truncated + + def test_internal_dropout_splits_one_elution(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[52] = 0.0 # one scan without the ion + peaks = find_peaks(XIC(0.0, rt, y)) + assert len(peaks) == 2 # documented: look at the trace + a, b = sorted(peaks, key=lambda p: p.apex_rt) + assert a.right_rt == b.left_rt == rt[52] + + def test_bridge_dropouts_rejoins_the_split_elution(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[52] = 0.0 + y[55:57] = 0.0 # a two-scan gap: bridged only with k >= 2 + one = find_peaks(XIC(0.0, rt, y), bridge_dropouts=1) + assert len(one) == 2 and one[0].apex_rt == pytest.approx(5.0) + assert one[0].n_signal == one[0].n_points - 2 - 1 # boundaries and the bridged scan + two = find_peaks(XIC(0.0, rt, y), bridge_dropouts=2) + assert len(two) == 1 + assert y[52] == 0.0 # the caller's trace is not modified + + def test_n_signal_counts_only_scans_with_the_ion(self): + from mzml_utils.xic import find_peaks + rt = np.arange(11, dtype=float) + y = np.array([0, 0, 0, 0, 0, 7, 0, 0, 0, 0, 0], dtype=float) + (p,) = find_peaks(XIC(0.0, rt, y)) + assert (p.n_points, p.n_signal) == (3, 1) + pm = peak_metrics(XIC(0.0, rt, y), nearest_valley=True) + assert (pm.n_points, pm.n_signal) == (3, 1) + + def test_flat_top_is_one_peak(self): + from mzml_utils.xic import find_peaks + rt = np.arange(9, dtype=float) + y = np.array([0, 1, 5, 9, 9, 9, 5, 1, 0], dtype=float) + peaks = find_peaks(XIC(0.0, rt, y), min_rel_height=0.0) + assert len(peaks) == 1 and peaks[0].apex_rt == 3.0 and peaks[0].n_points == 9 + assert peaks[0].area == pytest.approx(float(np.trapezoid(y, rt)) if hasattr(np, "trapezoid") + else float(np.trapz(y, rt))) + + def test_degenerate_inputs(self): + from mzml_utils.xic import find_peaks + assert find_peaks(XIC(0.0, np.array([1.0, 2.0]), np.array([5.0, 3.0]))) == [] + assert find_peaks(XIC(0.0, np.arange(5.0), np.zeros(5))) == [] + assert find_peaks(XIC(0.0, np.arange(5.0), np.array([0, 1, 5, 1, 0.0])), max_peaks=0) == [] + with pytest.raises(ValueError): + find_peaks(XIC(0.0, np.arange(5.0), np.array([0, 1, np.nan, 1, 0.0]))) + + def test_exported_at_package_level(self): + import mzml_utils + assert mzml_utils.find_peaks is not None and mzml_utils.TracePeak is not None + + class TestPeakMetrics: def test_area_is_within_boundaries_not_whole_trace(self): rt = np.linspace(0, 20, 201)