openecg 0.1.0__py3-none-any.whl

openecg/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

openecg/codec.py

@@ -0,0 +1,144 @@
+"""OpenECG token format codec — uint16 pack/unpack, frame expansion, ASCII render.
+
+Spec: docs/superpowers/specs/2026-05-03-ecgcode-stage1-design.md §5
+"""
+
+import numpy as np
+
+from openecg import vocab
+
+MS_PER_UNIT = 4
+MAX_LENGTH_MS = 255 * MS_PER_UNIT  # 1020 ms
+
+
+def _split_long(sym: int, length_ms: int) -> list[tuple[int, int]]:
+    chunks = []
+    while length_ms > MAX_LENGTH_MS:
+        chunks.append((sym, MAX_LENGTH_MS))
+        length_ms -= MAX_LENGTH_MS
+    if length_ms > 0:
+        chunks.append((sym, length_ms))
+    return chunks
+
+
+def encode(events: list[tuple[int, int]]) -> np.ndarray:
+    """Pack (symbol_id, length_ms) events to uint16 array.
+
+    Length is snapped to nearest 4ms (min 4ms). Long events split at 1020ms.
+    Raises ValueError if any event has length 0 or invalid symbol_id.
+    """
+    out = []
+    for sym, ms in events:
+        if ms <= 0:
+            raise ValueError(f"Event length must be positive, got {ms}")
+        if not (0 <= sym <= 255):
+            raise ValueError(f"Invalid symbol_id {sym}")
+        units = max(1, round(ms / MS_PER_UNIT))
+        snapped_ms = units * MS_PER_UNIT
+        for chunk_sym, chunk_ms in _split_long(sym, snapped_ms):
+            chunk_units = chunk_ms // MS_PER_UNIT
+            packed = (chunk_sym << 8) | chunk_units
+            out.append(packed)
+    return np.array(out, dtype=np.uint16)
+
+
+def decode(packed: np.ndarray) -> list[tuple[int, int]]:
+    """Unpack uint16 array to (symbol_id, length_ms) events.
+
+    Consecutive runs of the same symbol are merged so that long events split
+    by `encode` (>1020ms) round-trip losslessly.
+    """
+    types = (packed >> 8).astype(np.uint8)
+    units = (packed & 0xFF).astype(np.uint8)
+    out: list[tuple[int, int]] = []
+    for t, u in zip(types, units):
+        sym = int(t)
+        ms = int(u) * MS_PER_UNIT
+        if out and out[-1][0] == sym:
+            out[-1] = (sym, out[-1][1] + ms)
+        else:
+            out.append((sym, ms))
+    return out
+
+
+def to_frames(
+    events: list[tuple[int, int]],
+    frame_ms: int = 20,
+    total_ms: int | None = None,
+) -> np.ndarray:
+    """Expand RLE events to per-frame symbol array.
+
+    Rule: each frame gets the symbol with maximum overlap, with `*` (pacer)
+    as priority override (any frame containing a spike -> pacer label).
+    """
+    if total_ms is None:
+        total_ms = sum(ms for _, ms in events)
+    n_frames = round(total_ms / frame_ms)
+    out = np.zeros(n_frames, dtype=np.uint8)
+
+    # Build (start_ms, end_ms, sym) intervals
+    intervals = []
+    cum = 0
+    for sym, ms in events:
+        intervals.append((cum, cum + ms, sym))
+        cum += ms
+
+    for f in range(n_frames):
+        f_start = f * frame_ms
+        f_end = f_start + frame_ms
+        overlap = {}
+        spike_present = False
+        for s_start, s_end, sym in intervals:
+            if s_end <= f_start:
+                continue
+            if s_start >= f_end:
+                break
+            ov = min(s_end, f_end) - max(s_start, f_start)
+            if ov > 0:
+                if sym == vocab.ID_PACER:
+                    spike_present = True
+                else:
+                    overlap[sym] = overlap.get(sym, 0) + ov
+        if spike_present:
+            out[f] = vocab.ID_PACER
+        elif overlap:
+            out[f] = max(overlap, key=overlap.get)
+        else:
+            out[f] = vocab.ID_ISO
+    return out
+
+
+def render_compact(events: list[tuple[int, int]]) -> str:
+    """One char per event."""
+    return "".join(vocab.ID_TO_CHAR[sym] for sym, _ in events)
+
+
+def render_timed(events: list[tuple[int, int]], ms_per_char: int = 20) -> str:
+    """Char count proportional to duration. Minimum 1 char per event."""
+    chars = []
+    for sym, ms in events:
+        n = max(1, round(ms / ms_per_char))
+        chars.append(vocab.ID_TO_CHAR[sym] * n)
+    return "".join(chars)
+
+
+def render_json(events: list[tuple[int, int]]) -> list[dict]:
+    """Verbose JSON view: [{'sym': name, 'ms': length}, ...]."""
+    return [{"sym": vocab.ID_TO_NAME[sym], "ms": ms} for sym, ms in events]
+
+
+def from_frames(frames: np.ndarray, frame_ms: int = 20) -> list[tuple[int, int]]:
+    """Run-length encode per-frame array to list of (symbol_id, length_ms) events.
+
+    Inverse of to_frames at frame granularity. Output durations are multiples of frame_ms.
+    """
+    if len(frames) == 0:
+        return []
+    change_idx = np.flatnonzero(np.diff(frames)) + 1
+    boundaries = np.concatenate(([0], change_idx, [len(frames)]))
+    events = []
+    for start, end in zip(boundaries[:-1], boundaries[1:]):
+        sym = int(frames[start])
+        n_frames = end - start
+        events.append((sym, n_frames * frame_ms))
+    return events

openecg/delineate.py

@@ -0,0 +1,71 @@
+# openecg/delineate.py
+"""NeuroKit2 ecg_delineate wrapper.
+
+NK provides per-beat onset/peak/offset for P, QRS, T plus separate Q/S peaks.
+Missing waves are marked with NaN inside NK output; we keep that and let
+labeler handle (via np.isnan checks).
+
+Spec: docs/superpowers/specs/2026-05-03-ecgcode-stage1-design.md §6
+"""
+
+from dataclasses import dataclass
+
+import neurokit2 as nk
+import numpy as np
+
+
+@dataclass
+class DelineateResult:
+    """Per-lead wave delineation output. All arrays length = num beats.
+    Missing wave indices stored as NaN."""
+    p_onsets: np.ndarray
+    p_peaks: np.ndarray
+    p_offsets: np.ndarray
+    q_peaks: np.ndarray
+    r_onsets: np.ndarray
+    r_peaks: np.ndarray
+    r_offsets: np.ndarray
+    s_peaks: np.ndarray
+    t_onsets: np.ndarray
+    t_peaks: np.ndarray
+    t_offsets: np.ndarray
+
+    @classmethod
+    def empty(cls) -> "DelineateResult":
+        e = np.array([], dtype=float)
+        return cls(*([e] * 11))
+
+    @property
+    def n_beats(self) -> int:
+        return len(self.r_peaks)
+
+
+def run(signal: np.ndarray, fs: int = 500, method: str = "dwt") -> DelineateResult:
+    """Run NK ecg_peaks + ecg_delineate. Returns DelineateResult.
+
+    On any NK exception or 0 R peaks detected, returns DelineateResult.empty().
+    """
+    try:
+        _, info = nk.ecg_peaks(signal, sampling_rate=fs)
+        rpeaks = np.asarray(info["ECG_R_Peaks"], dtype=float)
+        if len(rpeaks) == 0:
+            return DelineateResult.empty()
+        _, waves = nk.ecg_delineate(
+            signal, rpeaks=rpeaks.astype(int), sampling_rate=fs, method=method
+        )
+    except Exception:
+        return DelineateResult.empty()
+
+    return DelineateResult(
+        p_onsets=np.asarray(waves["ECG_P_Onsets"], dtype=float),
+        p_peaks=np.asarray(waves["ECG_P_Peaks"], dtype=float),
+        p_offsets=np.asarray(waves["ECG_P_Offsets"], dtype=float),
+        q_peaks=np.asarray(waves["ECG_Q_Peaks"], dtype=float),
+        r_onsets=np.asarray(waves["ECG_R_Onsets"], dtype=float),
+        r_peaks=rpeaks,
+        r_offsets=np.asarray(waves["ECG_R_Offsets"], dtype=float),
+        s_peaks=np.asarray(waves["ECG_S_Peaks"], dtype=float),
+        t_onsets=np.asarray(waves["ECG_T_Onsets"], dtype=float),
+        t_peaks=np.asarray(waves["ECG_T_Peaks"], dtype=float),
+        t_offsets=np.asarray(waves["ECG_T_Offsets"], dtype=float),
+    )

openecg/eval.py

@@ -0,0 +1,189 @@
+"""Evaluation metrics — frame-level F1 (4-class) + boundary error (Martinez-style).
+
+Spec: docs/superpowers/specs/2026-05-03-ecgcode-stage1-design.md §7
+"""
+
+import numpy as np
+
+from openecg import vocab
+
+# Supercategory IDs for LUDB-compat 4-class comparison
+SUPER_OTHER = 0
+SUPER_P = 1
+SUPER_QRS = 2
+SUPER_T = 3
+SUPER_NAMES = {SUPER_OTHER: "other", SUPER_P: "P", SUPER_QRS: "QRS", SUPER_T: "T"}
+
+# Sentinel for masked frames (boundary regions where the model has one-sided
+# context and predictions are unreliable). PyTorch cross_entropy supports
+# `ignore_index` natively; our focal_cross_entropy does too.
+IGNORE_INDEX = 255
+
+_SUPER_MAP = {
+    vocab.ID_PAD: SUPER_OTHER,
+    vocab.ID_UNK: SUPER_OTHER,
+    vocab.ID_ISO: SUPER_OTHER,
+    vocab.ID_PACER: SUPER_OTHER,
+    vocab.ID_P: SUPER_P,
+    vocab.ID_Q: SUPER_QRS,
+    vocab.ID_R: SUPER_QRS,
+    vocab.ID_S: SUPER_QRS,
+    vocab.ID_W: SUPER_QRS,
+    vocab.ID_T: SUPER_T,
+    vocab.ID_U: SUPER_T,    # U is repolarization-adjacent
+    vocab.ID_D: SUPER_QRS,  # delta is QRS-adjacent
+    vocab.ID_J: SUPER_QRS,
+}
+
+
+def to_supercategory(frames: np.ndarray) -> np.ndarray:
+    """Map per-frame v1 alphabet IDs → LUDB-compat 4-class."""
+    out = np.zeros_like(frames, dtype=np.uint8)
+    for src, dst in _SUPER_MAP.items():
+        out[frames == src] = dst
+    return out
+
+
+def frame_f1(pred: np.ndarray, true: np.ndarray) -> dict:
+    """Per-supercategory precision/recall/F1.
+
+    Frames where `true == IGNORE_INDEX` are excluded from all counts (TP/FP/FN).
+    Pred values at those positions are also ignored regardless of their value.
+
+    Returns: {super_id: {'precision': p, 'recall': r, 'f1': f, 'tp', 'fp', 'fn'}}
+    """
+    valid = true != IGNORE_INDEX
+    pred = pred[valid]
+    true = true[valid]
+    out = {}
+    for sc in (SUPER_OTHER, SUPER_P, SUPER_QRS, SUPER_T):
+        tp = int(np.sum((pred == sc) & (true == sc)))
+        fp = int(np.sum((pred == sc) & (true != sc)))
+        fn = int(np.sum((pred != sc) & (true == sc)))
+        p = tp / (tp + fp) if (tp + fp) > 0 else 0.0
+        r = tp / (tp + fn) if (tp + fn) > 0 else 0.0
+        f1 = 2 * p * r / (p + r) if (p + r) > 0 else 0.0
+        out[sc] = {"precision": p, "recall": r, "f1": f1, "tp": tp, "fp": fp, "fn": fn}
+    return out
+
+
+def boundary_error(
+    pred_indices: list[int],
+    true_indices: list[int],
+    tolerance_ms: float,
+    fs: int,
+) -> dict:
+    """Greedy nearest-match boundary comparison (Martinez 2004 style).
+
+    For each true boundary, find nearest predicted within tolerance.
+    Returns sensitivity, PPV, mean/median/p95 error in ms, hit/miss counts.
+    """
+    tolerance_samples = tolerance_ms * fs / 1000
+    pred_arr = np.sort(np.array(pred_indices, dtype=int))
+    true_arr = np.sort(np.array(true_indices, dtype=int))
+
+    if len(true_arr) == 0 and len(pred_arr) == 0:
+        return _empty_boundary_result()
+
+    matched_pred = set()
+    errors_samples = []
+    n_hits = 0
+
+    for t in true_arr:
+        if len(pred_arr) == 0:
+            break
+        best_idx = -1
+        best_err = float("inf")
+        for j, p in enumerate(pred_arr):
+            if j in matched_pred:
+                continue
+            err = abs(int(p) - int(t))
+            if err < best_err:
+                best_err = err
+                best_idx = j
+        if best_idx >= 0 and best_err <= tolerance_samples:
+            matched_pred.add(best_idx)
+            errors_samples.append(best_err)
+            n_hits += 1
+
+    if errors_samples:
+        errors_ms = np.array(errors_samples) * 1000.0 / fs
+        mean_err = float(np.mean(errors_ms))
+        median_err = float(np.median(errors_ms))
+        p95_err = float(np.percentile(errors_ms, 95))
+    else:
+        mean_err = median_err = p95_err = 0.0
+
+    sensitivity = n_hits / len(true_arr) if len(true_arr) > 0 else 0.0
+    ppv = n_hits / len(pred_arr) if len(pred_arr) > 0 else 0.0
+
+    return {
+        "sensitivity": sensitivity,
+        "ppv": ppv,
+        "n_hits": n_hits,
+        "n_true": int(len(true_arr)),
+        "n_pred": int(len(pred_arr)),
+        "mean_error_ms": mean_err,
+        "median_error_ms": median_err,
+        "p95_error_ms": p95_err,
+    }
+
+
+def boundary_f1(pred_indices, true_indices, tolerance_ms, fs):
+    """Compute F1 from boundary_error sensitivity and PPV.
+
+    Literature standard: each true boundary matched to a predicted boundary within
+    tolerance_ms gives a TP. Sensitivity = TP / |true|, PPV = TP / |pred|.
+    F1 = 2 * sens * PPV / (sens + PPV).
+    """
+    res = boundary_error(pred_indices, true_indices, tolerance_ms=tolerance_ms, fs=fs)
+    sens = res["sensitivity"]
+    ppv = res["ppv"]
+    f1 = 2 * sens * ppv / (sens + ppv) if (sens + ppv) > 0 else 0.0
+    return {**res, "f1": f1}
+
+
+def _empty_boundary_result():
+    return {
+        "sensitivity": 0.0, "ppv": 0.0, "n_hits": 0, "n_true": 0, "n_pred": 0,
+        "mean_error_ms": 0.0, "median_error_ms": 0.0, "p95_error_ms": 0.0,
+    }
+
+
+def events_to_super_frames(events, n_samples, fs=500, frame_ms=20):
+    """Pipeline events → per-frame supercategory array.
+    Used by validate_v1.py and ablate_methods.py."""
+    from openecg import codec
+    total_ms = round(n_samples * 1000.0 / fs)
+    frames = codec.to_frames(events, frame_ms=frame_ms, total_ms=total_ms)
+    return to_supercategory(frames)
+
+
+def gt_to_super_frames(gt_ann, n_samples, fs=500, frame_ms=20):
+    """LUDB cardiologist annotation dict → per-frame supercategory array (majority per frame).
+
+    samples_per_frame is fixed by physical time (fs * frame_ms / 1000) so each
+    output frame represents exactly frame_ms of signal. n_frames = n_samples //
+    samples_per_frame; trailing samples that don't fit a full frame are dropped.
+    Earlier versions computed samples_per_frame = n_samples // n_frames, which
+    introduced cumulative time drift (up to 500ms by frame 499) when n_samples
+    was not a clean multiple of samples-per-frame (e.g. ISP records of 9998-9999
+    samples at 1000Hz with frame_ms=20).
+    """
+    samples_per_frame = round(fs * frame_ms / 1000.0)
+    if samples_per_frame < 1:
+        samples_per_frame = 1
+    sample_labels = np.full(n_samples, SUPER_OTHER, dtype=np.uint8)
+    for on, off in zip(gt_ann["p_on"], gt_ann["p_off"]):
+        sample_labels[on:off + 1] = SUPER_P
+    for on, off in zip(gt_ann["qrs_on"], gt_ann["qrs_off"]):
+        sample_labels[on:off + 1] = SUPER_QRS
+    for on, off in zip(gt_ann["t_on"], gt_ann["t_off"]):
+        sample_labels[on:off + 1] = SUPER_T
+    n_frames = n_samples // samples_per_frame
+    out = np.zeros(n_frames, dtype=np.uint8)
+    for f in range(n_frames):
+        seg = sample_labels[f * samples_per_frame: (f + 1) * samples_per_frame]
+        vals, counts = np.unique(seg, return_counts=True)
+        out[f] = vals[np.argmax(counts)]
+    return out

openecg/isp.py

@@ -0,0 +1,110 @@
+# openecg/isp.py
+"""ISP ECG delineation dataset loader.
+
+Source: https://zenodo.org/records/14679837 (475 records, 12-lead, ~10s @ 1000Hz,
+2-cardiologist annotations of P/QRS/T onset+offset).
+
+Target format: list of (class_id, onset_sample, offset_sample) where class 0=P, 1=QRS, 2=T.
+"""
+
+import csv
+import os
+import re
+import zipfile
+from pathlib import Path
+
+import numpy as np
+import wfdb
+
+ISP_INNER_DIR = "isp_delineation_dataset"
+LEADS_12 = ("i", "ii", "iii", "avr", "avl", "avf",
+            "v1", "v2", "v3", "v4", "v5", "v6")
+FS_NATIVE = 1000
+
+_TUPLE_RE = re.compile(r"\((\d+)\s*,\s*(\d+)\s*,\s*(\d+)\)")
+
+
+def _zip_path() -> Path:
+    p = os.environ.get("OPENECG_ISP_ZIP")
+    if not p:
+        raise FileNotFoundError("Set OPENECG_ISP_ZIP env var")
+    return Path(p)
+
+
+def _cache_path() -> Path:
+    p = os.environ.get("OPENECG_ISP_CACHE")
+    if p:
+        return Path(p).expanduser()
+    return Path.home() / ".cache" / "openecg" / "isp"
+
+
+def ensure_extracted() -> Path:
+    cache = _cache_path()
+    inner = cache / ISP_INNER_DIR
+    if inner.exists():
+        return inner
+    cache.mkdir(parents=True, exist_ok=True)
+    with zipfile.ZipFile(_zip_path()) as z:
+        z.extractall(cache)
+    return inner
+
+
+def _parse_target(s: str) -> list[tuple[int, int, int]]:
+    """Parse target string like '[(0, 100, 150), (1, 200, 250), ...]' safely via regex."""
+    return [(int(a), int(b), int(c)) for a, b, c in _TUPLE_RE.findall(s)]
+
+
+def _load_csv(path: Path) -> dict[int, list[tuple[int, int, int]]]:
+    """Returns {file_name (int): list of (class, onset, offset)}."""
+    out = {}
+    with open(path) as f:
+        for row in csv.DictReader(f):
+            fid = int(row["file_name"])
+            out[fid] = _parse_target(row["target"])
+    return out
+
+
+def load_split() -> dict[str, list[int]]:
+    """ISP's predefined train/test split. Returns {'train': [...], 'test': [...]}."""
+    inner = ensure_extracted()
+    train_ann = _load_csv(inner / "train_isp_delineation_data.csv")
+    test_ann = _load_csv(inner / "test_isp_delineation_data.csv")
+    return {"train": sorted(train_ann.keys()), "test": sorted(test_ann.keys())}
+
+
+def _load_annotations(record_id: int, split: str) -> list[tuple[int, int, int]]:
+    """split: 'train' or 'test'. Returns annotation list."""
+    inner = ensure_extracted()
+    csv_path = inner / f"{split}_isp_delineation_data.csv"
+    ann = _load_csv(csv_path)
+    return ann.get(record_id, [])
+
+
+def load_record(record_id: int, split: str = "train") -> dict[str, np.ndarray]:
+    """Load 12-lead ECG. Returns {lead_name: signal[9998 or so]} at 1000Hz."""
+    inner = ensure_extracted()
+    record_path = str(inner / f"{split}_data" / str(record_id))
+    record = wfdb.rdrecord(record_path)
+    return {lead: record.p_signal[:, i].astype(np.float64)
+            for i, lead in enumerate(LEADS_12)}
+
+
+def load_annotations_as_super(record_id: int, split: str = "train") -> dict[str, list[int]]:
+    """Convert ISP annotation tuples to LUDB-style dict for use with gt_to_super_frames.
+    Maps class 0->P, 1->QRS, 2->T."""
+    raw = _load_annotations(record_id, split)
+    out = {"p_on": [], "p_off": [],
+           "qrs_on": [], "qrs_off": [],
+           "t_on": [], "t_off": [],
+           "p_peak": [], "qrs_peak": [], "t_peak": []}  # peaks unused but expected
+    for cls, on, off in raw:
+        if cls == 0:
+            out["p_on"].append(on)
+            out["p_off"].append(off)
+        elif cls == 1:
+            out["qrs_on"].append(on)
+            out["qrs_off"].append(off)
+        elif cls == 2:
+            out["t_on"].append(on)
+            out["t_off"].append(off)
+    return out

openecg/labeler.py

@@ -0,0 +1,154 @@
+# openecg/labeler.py
+"""Convert NK delineate output + pacer spikes -> RLE token stream.
+
+Algorithm (per the spec section 6):
+1. Initialize sample-level array as iso
+2. Mark P / T regions
+3. Decompose each QRS into q/r/s by midpoint, with wide-QRS fallback (w)
+4. Override with pacer spikes (priority: spike > wave > iso)
+5. Run-length compress to (symbol_id, length_ms) events
+"""
+
+import numpy as np
+
+from openecg import vocab
+from openecg.delineate import DelineateResult
+
+WIDE_QRS_THRESHOLD_MS = 120.0
+
+
+def _safe_int(x, n: int):
+    """Cast NK index (float, possibly NaN) to int and clamp to [0, n-1]. Returns None if NaN."""
+    if x is None:
+        return None
+    try:
+        if np.isnan(x):
+            return None
+    except (TypeError, ValueError):
+        pass
+    return max(0, min(n - 1, int(x)))
+
+
+def _has(x) -> bool:
+    if x is None:
+        return False
+    try:
+        return not np.isnan(x)
+    except (TypeError, ValueError):
+        return True
+
+
+def label(
+    dr: DelineateResult,
+    spike_idx,
+    n_samples: int,
+    fs: int = 500,
+) -> list:
+    """Build sample-level label array, then run-length compress to RLE events.
+
+    Returns list of (symbol_id, length_ms) tuples.
+    """
+    ms_per_sample = 1000.0 / fs
+
+    # NK total failure -> entire signal as one ? event
+    if dr.n_beats == 0:
+        return [(vocab.ID_UNK, int(round(n_samples * ms_per_sample)))]
+
+    labels = np.full(n_samples, vocab.ID_ISO, dtype=np.uint8)
+
+    # 1. P waves
+    for on_f, off_f in zip(dr.p_onsets, dr.p_offsets):
+        if not (_has(on_f) and _has(off_f)):
+            continue
+        on = _safe_int(on_f, n_samples)
+        off = _safe_int(off_f, n_samples)
+        labels[on:off + 1] = vocab.ID_P
+
+    # 2. T waves
+    for on_f, off_f in zip(dr.t_onsets, dr.t_offsets):
+        if not (_has(on_f) and _has(off_f)):
+            continue
+        on = _safe_int(on_f, n_samples)
+        off = _safe_int(off_f, n_samples)
+        labels[on:off + 1] = vocab.ID_T
+
+    # 3. QRS - q/r/s decomposition with wide-QRS fallback
+    n_beats = dr.n_beats
+    for i in range(n_beats):
+        if not (_has(dr.r_onsets[i]) and _has(dr.r_offsets[i])):
+            continue
+        on = _safe_int(dr.r_onsets[i], n_samples)
+        off = _safe_int(dr.r_offsets[i], n_samples)
+        r = _safe_int(dr.r_peaks[i], n_samples)
+        q_raw = dr.q_peaks[i] if i < len(dr.q_peaks) else None
+        s_raw = dr.s_peaks[i] if i < len(dr.s_peaks) else None
+        q = _safe_int(q_raw, n_samples)
+        s = _safe_int(s_raw, n_samples)
+
+        # Duration in ms: (off - on) samples gives the span
+        qrs_ms = (off - on) * ms_per_sample
+        has_q = q is not None
+        has_s = s is not None
+
+        # Wide-QRS fallback: no Q peak AND no S peak AND duration > 120ms
+        if not has_q and not has_s and qrs_ms > WIDE_QRS_THRESHOLD_MS:
+            labels[on:off + 1] = vocab.ID_W
+            continue
+
+        # Standard q/r/s decomposition by midpoints
+        if r is None:
+            # No R peak available; treat whole QRS as r
+            labels[on:off + 1] = vocab.ID_R
+            continue
+
+        q_end = (q + r) // 2 if has_q else on
+        s_start = (r + s) // 2 if has_s else off + 1
+
+        if has_q:
+            labels[on:q_end] = vocab.ID_Q
+        labels[q_end:s_start] = vocab.ID_R
+        if has_s:
+            labels[s_start:off + 1] = vocab.ID_S
+
+    # 4. Pacer spikes - highest priority override
+    for idx in spike_idx:
+        idx_int = int(idx)
+        if 0 <= idx_int < n_samples:
+            labels[idx_int] = vocab.ID_PACER
+
+    # 5. RLE compress
+    return _rle_compress(labels, ms_per_sample)
+
+
+def _rle_compress(labels: np.ndarray, ms_per_sample: float) -> list:
+    """Group consecutive identical labels -> list of (symbol_id, length_ms).
+
+    Lengths are snapped to the codec grid (4ms) using cumulative rounding so
+    rounding error never drifts more than 4ms from the true total. Single-sample
+    pacer spikes are always emitted as 4ms (the minimum codec quantum).
+    """
+    from openecg.codec import MS_PER_UNIT
+
+    if len(labels) == 0:
+        return []
+    change_idx = np.flatnonzero(np.diff(labels)) + 1
+    boundaries = np.concatenate(([0], change_idx, [len(labels)]))
+
+    events = []
+    cum_true_ms = 0.0
+    cum_emitted_ms = 0
+    for start, end in zip(boundaries[:-1], boundaries[1:]):
+        sym = int(labels[start])
+        n = int(end - start)
+        cum_true_ms += n * ms_per_sample
+        # Snap cumulative end to 4ms grid; segment length = grid_end - prev_emitted
+        grid_end = int(round(cum_true_ms / MS_PER_UNIT)) * MS_PER_UNIT
+        ms = grid_end - cum_emitted_ms
+        if ms <= 0:
+            # Segment too short to land on a new grid line; force 1 quantum so
+            # we don't drop the symbol (e.g. a single-sample pacer spike).
+            ms = MS_PER_UNIT
+            grid_end = cum_emitted_ms + MS_PER_UNIT
+        events.append((sym, ms))
+        cum_emitted_ms = grid_end
+    return events