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
4 changes: 4 additions & 0 deletions src/mzml_utils/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,8 @@
peak_boundary,
peak_metrics,
PeakMetrics,
find_peaks,
TracePeak,
beta_values,
)

Expand Down Expand Up @@ -222,6 +224,8 @@
"peak_boundary",
"peak_metrics",
"PeakMetrics",
"find_peaks",
"TracePeak",
"beta_values",
# chrom_extract (peak table -> chromatograms across runs)
"extract_chromatograms",
Expand Down
135 changes: 134 additions & 1 deletion src/mzml_utils/xic.py
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Expand Down Expand Up @@ -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
# ---------------------------------------------------------------------------
Expand Down
112 changes: 112 additions & 0 deletions tests/test_xic.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
Loading