Add CLI, CI, tests, CITATION, badges and synthetic ECG sample

- meditech_decode.py / meditech_arrhythmia.py: argparse CLI (input paths,
  --channels/--rate/--gain/--header-len/--baseline, --report-only); no more
  hardcoded recording params, works on any CardioMera layout. Start time is
  read from FC1_PRG.DAT. Robust length-prefixed metadata parsing.
- tests/synthetic.py: PHI-free synthetic recording generator in device format.
- tests/test_smoke.py: decode roundtrip + beat-detection smoke tests.
- .github/workflows/ci.yml + ruff.toml: lint + tests on py3.10/3.12.
- README: MIT/Python/CI badges + synthetic 3-lead ECG screenshot; CLI docs.
- CITATION.cff for scholarly citation.
- .gitignore: allow only the synthetic docs image through the *.png rule.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: kkeker

.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install ruff pytest
+
+      - name: Lint (ruff)
+        run: ruff check .
+
+      - name: Smoke test (synthetic data — no PHI)
+        run: pytest -q

.gitignore

@@ -13,6 +13,8 @@ FC1_PRG.DAT
 *.csv
 *.png
 *.pdf
+# ...except the synthetic (PHI-free) documentation image
+!docs/sample_ecg.png
 
 # ── Python ───────────────────────────────────────────────────────────────────
 __pycache__/

CITATION.cff

@@ -0,0 +1,31 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+title: "meditech-cardiomera-decoder: an open decoder and format specification for Meditech CardioMera (FC1) Holter ECG recordings"
+abstract: >-
+  An open-source Python decoder and reverse-engineered file-format specification
+  for Holter ECG recordings produced by the Meditech CardioMera (FC1) ambulatory
+  recorder. It parses the proprietary on-card files (ECG.DAT and FC1_PRG.DAT),
+  losslessly reconstructs the multi-channel ECG from the device's int8
+  delta-encoded 1024-byte blocks, and exports EDF+ in microvolts for use in any
+  standard ECG viewer. Includes a rough, rhythm-based ectopic-burden estimate.
+type: software
+authors:
+  - given-names: Klaus
+    alias: kkeker
+    affiliation: "NexaTech Ltd"
+repository-code: "https://github.com/nexatech-ltd/meditech-cardiomera-decoder"
+url: "https://github.com/nexatech-ltd/meditech-cardiomera-decoder"
+license: MIT
+version: "1.0.0"
+date-released: "2026-07-02"
+keywords:
+  - Holter
+  - ECG
+  - electrocardiogram
+  - Meditech
+  - CardioMera
+  - CardioVisions
+  - EDF
+  - file format
+  - reverse engineering
+  - medical devices

README.md

@@ -1,11 +1,20 @@
 # meditech-cardiomera-decoder
 
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+[![CI](https://github.com/nexatech-ltd/meditech-cardiomera-decoder/actions/workflows/ci.yml/badge.svg)](https://github.com/nexatech-ltd/meditech-cardiomera-decoder/actions/workflows/ci.yml)
+
 An open-source decoder and **reverse-engineered format specification** for
 Holter ECG recordings produced by the **Meditech CardioMera (FC1)** ambulatory
 recorder (Meditech Kft, Budapest). It reads the raw SD-card files `ECG.DAT` and
 `FC1_PRG.DAT`, reconstructs the multi-channel ECG, and exports **EDF+** that
 opens in any standard ECG viewer (EDFbrowser, WFDB tools, etc.).
 
+![Reconstructed 3-lead ECG (synthetic sample)](docs/sample_ecg.png)
+
+*Reconstructed 3-lead ECG. This sample is generated from **synthetic** data
+(`tests/synthetic.py`) — no patient data is included anywhere in this repo.*
+
 The vendor's own software (**CardioVisions**) is Windows-only and there is **no
 public documentation of the on-card file format**. This project documents that
 format and provides a cross-platform (Python) reader so the data is not locked
@@ -64,6 +73,24 @@ python3 meditech_decode.py
 python3 meditech_arrhythmia.py
 ```
 
+Both tools take CLI flags so they work on any CardioMera recording, not just
+the default 3-channel / 300 Hz layout:
+
+```bash
+python3 meditech_decode.py path/to/ECG.DAT path/to/FC1_PRG.DAT \
+    -o out.edf --channels 3 --rate 300 --gain 4.0 --baseline butter
+python3 meditech_decode.py --report-only            # metadata + integrity only
+
+python3 meditech_arrhythmia.py path/to/ECG.DAT --rate 300 --detect-channel 2
+python3 meditech_decode.py -h                        # full option list
+```
+
+Run the test suite (uses synthetic data — no real recording needed):
+
+```bash
+python3 tests/test_smoke.py        # or: pytest -q
+```
+
 Programmatic use:
 
 ```python

docs/sample_ecg.png

@@ -8,26 +8,23 @@
 and a clinician / certified Holter software. Use this only to get a sense of the
 order of magnitude.
 
+Note: the ectopic percentage is derived from R-R timing with a self-scaling
+detection threshold, so it is invariant to the ADC gain -- microvolt calibration
+does not change these numbers.
+
 Pipeline:
-  1. Reconstruct one channel (CH3 -- sharpest R waves, fewest artifacts) in
-     chunks with a continuous cumulative sum.
+  1. Reconstruct one channel in chunks with a continuous cumulative sum.
   2. Band-pass 5-25 Hz (QRS enhancement; removes drift/respiration/noise).
   3. R-peak detection: adaptive threshold + 250 ms refractory + T-wave rejection.
-  4. Per-beat classification against the local R-R:
-       - premature (ectopic): RR < PREMATURE * local-median RR, and the next
-         RR > COMPENSATORY * local-median (compensatory pause);
-       - pause: RR > PAUSE_S seconds.
+  4. Per-beat classification against the local R-R (premature + compensatory pause).
   5. Percentages + per-hour breakdown.
 """
-import numpy as np
+import argparse
 import datetime
+import numpy as np
 from scipy.signal import butter, filtfilt, find_peaks
 
-BLK, HDR, NCH = 1024, 13, 3
-SPB = (BLK - HDR) // NCH          # 337
-FS = 300
-CH = 2                            # CH3 (index 2) -- cleanest for detection
-START = datetime.datetime(2026, 7, 1, 10, 12, 17)
+BLOCK_SIZE = 1024
 
 # rhythm-classification thresholds
 PREMATURE    = 0.80   # RR shorter than 80% of local median = premature
@@ -37,27 +34,30 @@
 TWAVE_RATIO  = 0.55   # a peak below 55% of the previous one within the window = likely T
 
 
-def bandpass(x, lo=5, hi=25):
-    b, a = butter(2, [lo / (FS / 2), hi / (FS / 2)], "band")
+def bandpass(x, fs, lo=5, hi=25):
+    b, a = butter(2, [lo / (fs / 2), hi / (fs / 2)], "band")
     return filtfilt(b, a, x)
 
 
-def detect_all(path="ECG.DAT"):
-    mm = np.fromfile(path, dtype=np.uint8).reshape(-1, BLK)
-    nblk = int(np.where(mm.any(axis=1))[0].max()) + 1
-    payload = mm[:nblk, HDR:HDR + SPB * NCH].reshape(-1, NCH)[:, CH].astype(np.int8).astype(np.int32)
+def detect_all(path, fs, channels, header_len, detect_channel):
+    mm = np.fromfile(path, dtype=np.uint8).reshape(-1, BLOCK_SIZE)
+    nz = np.where(mm.any(axis=1))[0]
+    nblk = int(nz.max()) + 1 if nz.size else 0
+    spb = (BLOCK_SIZE - header_len) // channels
+    payload = (mm[:nblk, header_len:header_len + spb * channels]
+               .reshape(-1, channels)[:, detect_channel].astype(np.int8).astype(np.int32))
     total = payload.size
 
-    CHUNK, OVER = 300_000, 3_000   # ~1000 s chunks, overlap to keep edge beats
+    CHUNK, OVER = 300_000, 3_000
     acc, pos = 0, 0
     peaks, amps = [], []
     while pos < total:
         a, b = max(0, pos - OVER), min(total, pos + CHUNK)
         base = acc - int(payload[a:pos].sum()) if pos > a else acc
         sig = np.cumsum(payload[a:b]) + base
-        f = bandpass(sig.astype(float))
+        f = bandpass(sig.astype(float), fs)
         thr = max(4.0 * np.median(np.abs(f)) / 0.6745, 1.0)
-        pk, props = find_peaks(f, height=thr, distance=int(0.25 * FS))
+        pk, props = find_peaks(f, height=thr, distance=int(0.25 * fs))
         gpk = pk + a
         keep = gpk >= pos
         peaks.extend(gpk[keep].tolist())
@@ -68,16 +68,15 @@ def detect_all(path="ECG.DAT"):
     order = np.argsort(peaks)
     peaks, amps = peaks[order], amps[order]
 
-    # T-wave rejection: a peak soon after a much larger one
-    keep = np.ones(peaks.size, bool)
+    keep = np.ones(peaks.size, bool)              # T-wave rejection
     for i in range(1, peaks.size):
-        if (peaks[i] - peaks[i - 1]) / FS < TWAVE_WIN and amps[i] < TWAVE_RATIO * amps[i - 1]:
+        if (peaks[i] - peaks[i - 1]) / fs < TWAVE_WIN and amps[i] < TWAVE_RATIO * amps[i - 1]:
             keep[i] = False
     return peaks[keep], amps[keep], total
 
 
-def classify(peaks):
-    rr = np.diff(peaks) / FS
+def classify(peaks, fs):
+    rr = np.diff(peaks) / fs
     n = peaks.size
     med = np.empty(rr.size)
     for i in range(rr.size):
@@ -92,10 +91,9 @@ def classify(peaks):
     return rr, premature, pause
 
 
-def signal_quality_mask(peaks, rr):
-    """Flag ~10 s windows as unreliable (noise): extreme R-R variability, an
-    implausible sustained rate, or too many physiologically-fast intervals."""
-    WIN = 10 * FS
+def signal_quality_mask(peaks, rr, fs):
+    """Flag ~10 s windows as unreliable (noise)."""
+    WIN = 10 * fs
     good = np.ones(rr.size, bool)
     for e in np.arange(0, peaks[-1] + WIN, WIN):
         m = (peaks[:-1] >= e) & (peaks[:-1] < e + WIN)
@@ -109,41 +107,71 @@ def signal_quality_mask(peaks, rr):
     return good
 
 
-def main():
-    print("== Ectopic-burden estimate (rhythm-based) ==")
-    peaks, amps, nsamp = detect_all()
-    dur_h = nsamp / FS / 3600
-    rr, premature, pause = classify(peaks)
-    good = signal_quality_mask(peaks, rr)
+def _resolve_start(args):
+    if args.start:
+        return datetime.datetime.fromisoformat(args.start)
+    try:                                          # read from FC1_PRG.DAT if present
+        import meditech_decode
+        s = meditech_decode.parse_prg(args.prg).get("recording_start")
+        if s:
+            return s
+    except Exception:
+        pass
+    return datetime.datetime(1970, 1, 1)
+
+
+def _parse_args(argv=None):
+    p = argparse.ArgumentParser(description="Rough rhythm-based ectopic-burden estimate "
+                                            "for a CardioMera Holter recording (NOT a diagnosis).")
+    p.add_argument("ecg", nargs="?", default="ECG.DAT")
+    p.add_argument("--prg", default="FC1_PRG.DAT", help="config file for the start timestamp")
+    p.add_argument("--start", default=None, help="override start time (ISO 8601)")
+    p.add_argument("--channels", type=int, default=3)
+    p.add_argument("--rate", type=int, default=300)
+    p.add_argument("--header-len", type=int, default=13)
+    p.add_argument("--detect-channel", type=int, default=2, help="channel index for R detection")
+    p.add_argument("--events-out", default="arrhythmia_events.npz")
+    return p.parse_args(argv)
+
+
+def main(argv=None):
+    a = _parse_args(argv)
+    start = _resolve_start(a)
+    print("== Ectopic-burden estimate (rhythm-based; NOT a diagnosis) ==")
+    peaks, amps, nsamp = detect_all(a.ecg, a.rate, a.channels, a.header_len, a.detect_channel)
+    dur_h = nsamp / a.rate / 3600
+    rr, premature, pause = classify(peaks, a.rate)
+    good = signal_quality_mask(peaks, rr, a.rate)
     total = peaks.size
     hr = 60 / rr
-
     npre_all = int(premature.sum())
     npre_clean = int((premature[:-1] & good).sum())
     nbeat_clean = int(good.sum())
 
     print(f"Length: {dur_h:.2f} h,  total beats: {total:,}")
-    print(f"Median HR: {np.median(hr):.0f} bpm  (p2 {np.percentile(hr,2):.0f}, p98 {np.percentile(hr,98):.0f})")
-    print(f"Premature beats (all): {npre_all:,} = {100*npre_all/total:.2f}% of beats")
-    print(f"Premature beats (quality-gated): {npre_clean:,} = {100*npre_clean/max(nbeat_clean,1):.2f}%")
+    print(f"Median HR: {np.median(hr):.0f} bpm  (p2 {np.percentile(hr,2):.0f}, "
+          f"p98 {np.percentile(hr,98):.0f})")
+    print(f"Premature beats (all): {npre_all:,} = {100*npre_all/max(total,1):.2f}% of beats")
+    print(f"Premature beats (quality-gated): {npre_clean:,} = "
+          f"{100*npre_clean/max(nbeat_clean,1):.2f}%")
     print(f"Excluded as noise/unreliable: {100*(1-good.mean()):.1f}% of intervals")
     print(f"Pauses > {PAUSE_S:.0f} s: {int(pause.sum())}")
 
-    hours = (peaks / FS / 3600).astype(int)
+    hours = (peaks / a.rate / 3600).astype(int)
     print("\nPer-hour burden (recording hour : beats : ectopics : %):")
     for hh in range(int(dur_h) + 1):
         m = hours == hh
         tb = int(m.sum())
         if tb == 0:
             continue
         eb = int(premature[m].sum())
-        ts = (START + datetime.timedelta(hours=hh)).strftime("%m-%d %H:%M")
+        ts = (start + datetime.timedelta(hours=hh)).strftime("%m-%d %H:%M")
         bar = "#" * min(40, int(60 * eb / max(tb, 1)))
         print(f"  h{hh:2d} [{ts}]: {tb:5d} : {eb:4d} : {100*eb/tb:5.2f}% {bar}")
 
-    np.savez("arrhythmia_events.npz", peaks=peaks, premature=premature,
-             pause=pause, good=np.append(good, False), fs=FS)
-    print("\nEvents saved: arrhythmia_events.npz")
+    np.savez(a.events_out, peaks=peaks, premature=premature, pause=pause,
+             good=np.append(good, False), fs=a.rate)
+    print(f"\nEvents saved: {a.events_out}")
 
 
 if __name__ == "__main__":