electrotrace 1.9.0__tar.gz

electrotrace-1.9.0/LICENSE

@@ -0,0 +1,20 @@
+GNU AFFERO GENERAL PUBLIC LICENSE
+Version 3, 19 November 2007
+
+Copyright (c) 2026 Virelion Biotech
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+For the full license text, see:
+https://www.gnu.org/licenses/agpl-3.0.html

electrotrace-1.9.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: electrotrace
+Version: 1.9.0
+Summary: Reproducible ECG/electrophysiology annotation, benchmarking, phenotyping, and leakage-safe validation toolkit
+License: AGPL-3.0-or-later
+Project-URL: Homepage, https://github.com/Virelion-Biotech/Virelion-ElectroTrace
+Project-URL: Documentation, https://github.com/Virelion-Biotech/Virelion-ElectroTrace/tree/main/docs
+Project-URL: Repository, https://github.com/Virelion-Biotech/Virelion-ElectroTrace
+Project-URL: Issues, https://github.com/Virelion-Biotech/Virelion-ElectroTrace/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: scipy>=1.10
+Requires-Dist: scikit-learn>=1.4
+Provides-Extra: wfdb
+Requires-Dist: wfdb>=4.1; extra == "wfdb"
+Provides-Extra: edf
+Requires-Dist: pyedflib>=0.1.38; extra == "edf"
+Provides-Extra: server
+Requires-Dist: flask>=3.0; extra == "server"
+Provides-Extra: models
+Requires-Dist: skops>=0.14; extra == "models"
+Provides-Extra: all
+Requires-Dist: wfdb>=4.1; extra == "all"
+Requires-Dist: pyedflib>=0.1.38; extra == "all"
+Requires-Dist: flask>=3.0; extra == "all"
+Requires-Dist: skops>=0.14; extra == "all"
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: wfdb>=4.1; extra == "test"
+Requires-Dist: pyedflib>=0.1.38; extra == "test"
+Requires-Dist: skops>=0.14; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Requires-Dist: wfdb>=4.1; extra == "dev"
+Requires-Dist: pyedflib>=0.1.38; extra == "dev"
+Requires-Dist: flask>=3.0; extra == "dev"
+Requires-Dist: skops>=0.14; extra == "dev"
+Dynamic: license-file
+
+# ElectroTrace
+
+**Current source version:** 1.9.0 (release candidate)
+
+**A reproducible ECG/electrophysiology annotation and benchmarking workbench.**
+
+ElectroTrace is built around a simple principle: **the evidence is the product**. It provides one place to run detectors, compare them under declared protocols, preserve record/subject-level statistics, and carry hashes, software versions, and provenance alongside results.
+
+The repository also ships its own Stage-1 and two-stage Random Forest detector, but that detector is not the project's only or primary claim. The current evidence is deliberately mixed: the two-stage model performs strongly on its locked MIT-BIH split, and two successive model generations have both shown a cross-database drop on INCART. That gap is preserved and documented rather than hidden.
+
+## Current evidence
+
+**Two distinct model generations exist for the two-stage detector and must not be conflated** (see `validation_reports/VALIDATION_STATUS.md` for the full history). The original locked MIT-BIH row below is the `candidate-features-v3` model from 1.8.1. The current `candidate-features-v4` / windowed-std model now also has explicit MIT-BIH legacy non-regression audits, including the leakage-safe 0.0/0.0 polarity-gate result (F1 0.9644). Those audits do not become clean prospective evidence because MIT-BIH historically informed the adaptive-polarity mechanism.
+
+| Protocol | Detector | Model generation | Records | Sensitivity | PPV | F1 |
+|---|---|---|---:|---:|---:|---:|
+| Locked MIT-BIH held-out | ElectroTrace two-stage | v3 (1.8.1 lock) | 12 | 0.9924 | 0.9879 | 0.9902 |
+| MIT-BIH leakage-safe gate audit | ElectroTrace two-stage | v4 (legacy non-regression) | 12 | 0.9390 | 0.9913 | 0.9644 |
+| Locked MIT-BIH held-out | Pan-Tompkins reimplementation | — | 12 | 0.9908 | 0.9954 | 0.9931 |
+| Locked MIT-BIH held-out | Hamilton reimplementation | — | 12 | 0.9990 | 0.9303 | 0.9634 |
+| Locked MIT-BIH held-out | ElectroTrace Stage-1 | — | 12 | 0.9931 | 0.7553 | 0.8580 |
+| INCART external comparison | ElectroTrace two-stage | v3 | 68 | 0.3239 | 0.9679 | 0.4854 |
+| INCART external comparison | ElectroTrace two-stage | v4 (windowed-std) | 68 | 0.9011 | 0.7594 | 0.8242 |
+| INCART certified WFDB comparison | WFDB gqrs | — | 68 | 0.9324 | 0.9265 | 0.9294 |
+| INCART complete source cohort | ElectroTrace two-stage | v4 frozen / development data | 75 | 0.8977 | 0.7633 | 0.8251 |
+| INCART complete source cohort | WFDB gqrs | certified reference baseline | 75 | 0.9372 | 0.9310 | 0.9341 |
+| INCART complete source cohort | WFDB sqrs | certified reference baseline | 75 | 0.7617 | 0.9537 | 0.8469 |
+| European ST-T prospective external | ElectroTrace two-stage | v4 frozen | 90 | 0.9056 | 0.9644 | 0.9341 |
+
+These values come from the repository's locked/archived validation artifacts. They are research results, not clinical validation and not evidence of universal detector superiority. **INCART informed v4 feature-scaling development and remains exposed development data**, so neither its historical 68-record row nor the completed 75-record row is a clean generalization estimate. The 75-record completion exists to finish the source cohort reproducibly, including the seven formerly malformed edge annotations under a two-certified-detector repair rule. A later one-shot prospective evaluation on all 90 European ST-T Database records provides independent external evidence for the unchanged frozen v4 configuration (F1 0.9341), but does not make INCART held-out or validate future post-hoc retuning. See `validation_reports/VALIDATION_STATUS.md` and `docs/CROSS_DATABASE_POLICY.md` for the evidence boundaries.
+
+## Why ElectroTrace exists
+
+Most ECG software answers "what detector should I use?" ElectroTrace is aimed at a different question:
+
+> **Under one explicit protocol, how does this detector behave, and can someone else reproduce the answer?**
+
+Primary statistics should treat records or subjects as the experimental unit rather than pretending individual beats are independent biological replicates. Validation artifacts can carry dataset hashes, detector configuration, software version, git commit, and protocol metadata.
+
+### Primary use cases
+
+**Preclinical electrophysiology:** batch animal recordings, retain explicit subject identifiers, and export record/subject-level tables for downstream statistics.
+
+**Methods-heavy human ECG research:** evaluate an existing detector on held-out records and retain an auditable artifact for papers, reviews, and lab handoff.
+
+**Detector development:** register a detector plugin and compare it against fixed baselines under the same matching rules.
+
+ElectroTrace is research software. It is not a clinical device and the current models are not validated for clinical deployment.
+
+## Install
+
+Python 3.10+ is required.
+
+**v1.9.0 is release-ready, but this repository does not claim PyPI availability until the tagged Trusted Publishing workflow succeeds.** Until then, install from source:
+
+~~~bash
+git clone https://github.com/Virelion-Biotech/Virelion-ElectroTrace.git
+cd Virelion-ElectroTrace
+python -m pip install -e ".[test,dev]"
+~~~
+
+## Five-minute start
+
+~~~bash
+electrotrace list
+electrotrace detect recording.edf --detector pan-tompkins --channel 0 -o peaks.csv
+electrotrace batch data/ --detector pan-tompkins --workers 4 -o results/
+electrotrace report validation.json -o validation.html
+~~~
+
+Batch outputs:
+
+~~~text
+results/
+├── beats.csv
+├── records.csv
+├── subjects.csv
+├── failures.csv
+├── manifest.json
+├── batch_state.json
+└── peaks/
+~~~
+
+Subject information is never inferred from filenames. Supply a two-column CSV with record and subject_id using --subject-map when subject aggregation is appropriate.
+
+## Validation and benchmarking
+
+~~~bash
+electrotrace validate .cache/physionet/mitdb/100 --detector pan-tompkins -o validation.json
+electrotrace bench .cache/physionet/mitdb --detectors pan-tompkins,hamilton --tolerance-ms 75 -o bench.json
+~~~
+
+Bench currently operates on local WFDB records. The repository does not vendor PhysioNet data.
+
+The frozen experimental QRS boundary locator has also completed a 105-record QT
+Database tolerance-curve study. Reference-centered joint onset/offset success
+was 0.589 at 20 ms, 0.845 at 40 ms, 0.925 at 60 ms, 0.954 at 80 ms, and 0.994
+at 100 ms, with record-level bootstrap uncertainty. This is delineation
+characterization, not an end-to-end detector or clinical-performance claim;
+see `docs/QTDB_VALIDATION.md` and `docs/QRS_DELINEATION.md`.
+
+The detector plugin interface is already present. The next benchmark phase will add external package adapters and a regenerated multi-database leaderboard rather than a single scalar ranking.
+
+## Model artifacts
+
+The two-stage Random Forest is opt-in. New model persistence uses .skops plus a metadata sidecar. Legacy pickle models are migration-only and rejected by default.
+
+A model records its feature schema and training scikit-learn major version. Loading stops when the runtime major version is incompatible or when the .skops file contains unknown serialized types.
+
+The complete 75-record INCART result is part of the evidence surface: cross-database behavior must be measured instead of inferred from MIT-BIH. The research-use policy for unseen domains is documented in `docs/CROSS_DATABASE_POLICY.md`; ElectroTrace does not silently infer that a new database is in-domain or automatically promote the RF path over established reference baselines.
+
+## Validation philosophy
+
+- record-level rather than beat-level primary statistics;
+- one-to-one matching under a declared tolerance;
+- locked splits with explicit seeds;
+- bootstrap confidence intervals over records;
+- SHA-256 input hashes and software/git provenance;
+- separate timing error, sensitivity, PPV, and F1;
+- explicit limitations and non-claims.
+
+## What is not claimed
+
+ElectroTrace does not claim clinical performance, real-time streaming performance, population generalization, or superiority over established QRS detectors.
+
+## Documentation and citation
+
+See docs/, mkdocs.yml, and CITATION.cff. The repository includes Zenodo metadata for v1.9.0, but a DOI is not claimed until an actual tagged release is archived by Zenodo.
+
+## License
+
+AGPL-3.0-or-later at present. Any future core/server license split will be an explicit project decision.

electrotrace-1.9.0/README.md

@@ -0,0 +1,132 @@
+# ElectroTrace
+
+**Current source version:** 1.9.0 (release candidate)
+
+**A reproducible ECG/electrophysiology annotation and benchmarking workbench.**
+
+ElectroTrace is built around a simple principle: **the evidence is the product**. It provides one place to run detectors, compare them under declared protocols, preserve record/subject-level statistics, and carry hashes, software versions, and provenance alongside results.
+
+The repository also ships its own Stage-1 and two-stage Random Forest detector, but that detector is not the project's only or primary claim. The current evidence is deliberately mixed: the two-stage model performs strongly on its locked MIT-BIH split, and two successive model generations have both shown a cross-database drop on INCART. That gap is preserved and documented rather than hidden.
+
+## Current evidence
+
+**Two distinct model generations exist for the two-stage detector and must not be conflated** (see `validation_reports/VALIDATION_STATUS.md` for the full history). The original locked MIT-BIH row below is the `candidate-features-v3` model from 1.8.1. The current `candidate-features-v4` / windowed-std model now also has explicit MIT-BIH legacy non-regression audits, including the leakage-safe 0.0/0.0 polarity-gate result (F1 0.9644). Those audits do not become clean prospective evidence because MIT-BIH historically informed the adaptive-polarity mechanism.
+
+| Protocol | Detector | Model generation | Records | Sensitivity | PPV | F1 |
+|---|---|---|---:|---:|---:|---:|
+| Locked MIT-BIH held-out | ElectroTrace two-stage | v3 (1.8.1 lock) | 12 | 0.9924 | 0.9879 | 0.9902 |
+| MIT-BIH leakage-safe gate audit | ElectroTrace two-stage | v4 (legacy non-regression) | 12 | 0.9390 | 0.9913 | 0.9644 |
+| Locked MIT-BIH held-out | Pan-Tompkins reimplementation | — | 12 | 0.9908 | 0.9954 | 0.9931 |
+| Locked MIT-BIH held-out | Hamilton reimplementation | — | 12 | 0.9990 | 0.9303 | 0.9634 |
+| Locked MIT-BIH held-out | ElectroTrace Stage-1 | — | 12 | 0.9931 | 0.7553 | 0.8580 |
+| INCART external comparison | ElectroTrace two-stage | v3 | 68 | 0.3239 | 0.9679 | 0.4854 |
+| INCART external comparison | ElectroTrace two-stage | v4 (windowed-std) | 68 | 0.9011 | 0.7594 | 0.8242 |
+| INCART certified WFDB comparison | WFDB gqrs | — | 68 | 0.9324 | 0.9265 | 0.9294 |
+| INCART complete source cohort | ElectroTrace two-stage | v4 frozen / development data | 75 | 0.8977 | 0.7633 | 0.8251 |
+| INCART complete source cohort | WFDB gqrs | certified reference baseline | 75 | 0.9372 | 0.9310 | 0.9341 |
+| INCART complete source cohort | WFDB sqrs | certified reference baseline | 75 | 0.7617 | 0.9537 | 0.8469 |
+| European ST-T prospective external | ElectroTrace two-stage | v4 frozen | 90 | 0.9056 | 0.9644 | 0.9341 |
+
+These values come from the repository's locked/archived validation artifacts. They are research results, not clinical validation and not evidence of universal detector superiority. **INCART informed v4 feature-scaling development and remains exposed development data**, so neither its historical 68-record row nor the completed 75-record row is a clean generalization estimate. The 75-record completion exists to finish the source cohort reproducibly, including the seven formerly malformed edge annotations under a two-certified-detector repair rule. A later one-shot prospective evaluation on all 90 European ST-T Database records provides independent external evidence for the unchanged frozen v4 configuration (F1 0.9341), but does not make INCART held-out or validate future post-hoc retuning. See `validation_reports/VALIDATION_STATUS.md` and `docs/CROSS_DATABASE_POLICY.md` for the evidence boundaries.
+
+## Why ElectroTrace exists
+
+Most ECG software answers "what detector should I use?" ElectroTrace is aimed at a different question:
+
+> **Under one explicit protocol, how does this detector behave, and can someone else reproduce the answer?**
+
+Primary statistics should treat records or subjects as the experimental unit rather than pretending individual beats are independent biological replicates. Validation artifacts can carry dataset hashes, detector configuration, software version, git commit, and protocol metadata.
+
+### Primary use cases
+
+**Preclinical electrophysiology:** batch animal recordings, retain explicit subject identifiers, and export record/subject-level tables for downstream statistics.
+
+**Methods-heavy human ECG research:** evaluate an existing detector on held-out records and retain an auditable artifact for papers, reviews, and lab handoff.
+
+**Detector development:** register a detector plugin and compare it against fixed baselines under the same matching rules.
+
+ElectroTrace is research software. It is not a clinical device and the current models are not validated for clinical deployment.
+
+## Install
+
+Python 3.10+ is required.
+
+**v1.9.0 is release-ready, but this repository does not claim PyPI availability until the tagged Trusted Publishing workflow succeeds.** Until then, install from source:
+
+~~~bash
+git clone https://github.com/Virelion-Biotech/Virelion-ElectroTrace.git
+cd Virelion-ElectroTrace
+python -m pip install -e ".[test,dev]"
+~~~
+
+## Five-minute start
+
+~~~bash
+electrotrace list
+electrotrace detect recording.edf --detector pan-tompkins --channel 0 -o peaks.csv
+electrotrace batch data/ --detector pan-tompkins --workers 4 -o results/
+electrotrace report validation.json -o validation.html
+~~~
+
+Batch outputs:
+
+~~~text
+results/
+├── beats.csv
+├── records.csv
+├── subjects.csv
+├── failures.csv
+├── manifest.json
+├── batch_state.json
+└── peaks/
+~~~
+
+Subject information is never inferred from filenames. Supply a two-column CSV with record and subject_id using --subject-map when subject aggregation is appropriate.
+
+## Validation and benchmarking
+
+~~~bash
+electrotrace validate .cache/physionet/mitdb/100 --detector pan-tompkins -o validation.json
+electrotrace bench .cache/physionet/mitdb --detectors pan-tompkins,hamilton --tolerance-ms 75 -o bench.json
+~~~
+
+Bench currently operates on local WFDB records. The repository does not vendor PhysioNet data.
+
+The frozen experimental QRS boundary locator has also completed a 105-record QT
+Database tolerance-curve study. Reference-centered joint onset/offset success
+was 0.589 at 20 ms, 0.845 at 40 ms, 0.925 at 60 ms, 0.954 at 80 ms, and 0.994
+at 100 ms, with record-level bootstrap uncertainty. This is delineation
+characterization, not an end-to-end detector or clinical-performance claim;
+see `docs/QTDB_VALIDATION.md` and `docs/QRS_DELINEATION.md`.
+
+The detector plugin interface is already present. The next benchmark phase will add external package adapters and a regenerated multi-database leaderboard rather than a single scalar ranking.
+
+## Model artifacts
+
+The two-stage Random Forest is opt-in. New model persistence uses .skops plus a metadata sidecar. Legacy pickle models are migration-only and rejected by default.
+
+A model records its feature schema and training scikit-learn major version. Loading stops when the runtime major version is incompatible or when the .skops file contains unknown serialized types.
+
+The complete 75-record INCART result is part of the evidence surface: cross-database behavior must be measured instead of inferred from MIT-BIH. The research-use policy for unseen domains is documented in `docs/CROSS_DATABASE_POLICY.md`; ElectroTrace does not silently infer that a new database is in-domain or automatically promote the RF path over established reference baselines.
+
+## Validation philosophy
+
+- record-level rather than beat-level primary statistics;
+- one-to-one matching under a declared tolerance;
+- locked splits with explicit seeds;
+- bootstrap confidence intervals over records;
+- SHA-256 input hashes and software/git provenance;
+- separate timing error, sensitivity, PPV, and F1;
+- explicit limitations and non-claims.
+
+## What is not claimed
+
+ElectroTrace does not claim clinical performance, real-time streaming performance, population generalization, or superiority over established QRS detectors.
+
+## Documentation and citation
+
+See docs/, mkdocs.yml, and CITATION.cff. The repository includes Zenodo metadata for v1.9.0, but a DOI is not claimed until an actual tagged release is archived by Zenodo.
+
+## License
+
+AGPL-3.0-or-later at present. Any future core/server license split will be an explicit project decision.

electrotrace-1.9.0/pyproject.toml

@@ -0,0 +1,94 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "electrotrace"
+version = "1.9.0"
+description = "Reproducible ECG/electrophysiology annotation, benchmarking, phenotyping, and leakage-safe validation toolkit"
+readme = "README.md"
+license = { text = "AGPL-3.0-or-later" }
+requires-python = ">=3.10"
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering",
+]
+dependencies = [
+  "numpy>=1.24",
+  "pandas>=2.0",
+  "scipy>=1.10",
+  "scikit-learn>=1.4",
+]
+
+[project.optional-dependencies]
+wfdb = ["wfdb>=4.1"]
+edf = ["pyedflib>=0.1.38"]
+server = ["flask>=3.0"]
+models = ["skops>=0.14"]
+all = [
+  "wfdb>=4.1",
+  "pyedflib>=0.1.38",
+  "flask>=3.0",
+  "skops>=0.14",
+]
+test = [
+  "pytest>=8.0",
+  "wfdb>=4.1",
+  "pyedflib>=0.1.38",
+  "skops>=0.14",
+]
+dev = [
+  "pytest>=8.0",
+  "ruff>=0.6",
+  "build>=1.2",
+  "mypy>=1.11",
+  "wfdb>=4.1",
+  "pyedflib>=0.1.38",
+  "flask>=3.0",
+  "skops>=0.14",
+]
+
+[project.scripts]
+electrotrace = "electrotrace.cli:main"
+electrotrace-hearttwin = "electrotrace.hearttwin_adapter:main"
+
+[project.entry-points."electrotrace.detectors"]
+# Third-party detector packages register callables here.
+
+[project.urls]
+Homepage = "https://github.com/Virelion-Biotech/Virelion-ElectroTrace"
+Documentation = "https://github.com/Virelion-Biotech/Virelion-ElectroTrace/tree/main/docs"
+Repository = "https://github.com/Virelion-Biotech/Virelion-ElectroTrace"
+Issues = "https://github.com/Virelion-Biotech/Virelion-ElectroTrace/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src", "."]
+testpaths = ["tests"]
+addopts = "--strict-markers"
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["electrotrace", "scripts"]
+
+[tool.mypy]
+python_version = "3.10"
+ignore_missing_imports = true
+check_untyped_defs = true
+warn_unused_ignores = true

electrotrace-1.9.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

electrotrace-1.9.0/src/electrotrace/__init__.py

@@ -0,0 +1,28 @@
+"""ElectroTrace: reproducible ECG/electrophysiology research and benchmarking tools."""
+
+__version__ = "1.9.0"
+
+from .candidate_suppressor import CandidateSuppressor
+from .io import load_recording
+from .provenance import DatasetManifest, manifest_from_dict
+from .qrs_delineation import delineate_qrs
+from .research_validation import build_validation_report, summarize_records_rigorous, write_validation_report
+from .signal import apply_pipeline
+from .validation import validate_record
+from .validation_detectors import detect_r_peaks, detect_r_peaks_two_stage
+
+__all__ = [
+    "__version__",
+    "CandidateSuppressor",
+    "DatasetManifest",
+    "manifest_from_dict",
+    "load_recording",
+    "apply_pipeline",
+    "detect_r_peaks",
+    "detect_r_peaks_two_stage",
+    "delineate_qrs",
+    "validate_record",
+    "build_validation_report",
+    "summarize_records_rigorous",
+    "write_validation_report",
+]

electrotrace-1.9.0/src/electrotrace/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

electrotrace-1.9.0/src/electrotrace/annotations.py

@@ -0,0 +1,194 @@
+"""Annotation model, validation, serialization, review state, and agreement metrics."""
+from __future__ import annotations
+
+import json
+import math
+import uuid
+from dataclasses import asdict, dataclass, field
+from typing import Literal, Optional
+
+AnnotationType = Literal["interval", "point"]
+ReviewStatus = Literal["unreviewed", "accepted", "flagged"]
+DEFAULT_LABELS = ["P Wave", "QRS", "T Wave", "Pacemaker Spike", "R Peak", "Artifact", "Abnormal Beat", "Graft Activation", "Arrhythmia", "Custom"]
+
+
+@dataclass
+class Annotation:
+    label: str
+    type: AnnotationType
+    channel: str
+    start: Optional[float] = None
+    end: Optional[float] = None
+    time: Optional[float] = None
+    confidence: float = 1.0
+    notes: str = ""
+    annotator: str = ""
+    status: ReviewStatus = "unreviewed"
+    reviewer: str = ""
+    review_notes: str = ""
+    id: str = field(default_factory=lambda: uuid.uuid4().hex[:10])
+
+    def validate(self, duration_s: float | None = None, start_time_s: float = 0.0, end_time_s: float | None = None) -> None:
+        if not self.label.strip():
+            raise ValueError("label must not be empty")
+        if not self.channel.strip():
+            raise ValueError("channel must not be empty")
+        if not math.isfinite(float(self.confidence)) or not 0.0 <= self.confidence <= 1.0:
+            raise ValueError("confidence must be between 0 and 1")
+        if self.status not in {"unreviewed", "accepted", "flagged"}:
+            raise ValueError("invalid review status")
+        start_bound = float(start_time_s)
+        end_bound = float(end_time_s) if end_time_s is not None else (start_bound + float(duration_s) if duration_s is not None else None)
+        if not math.isfinite(start_bound) or (end_bound is not None and not math.isfinite(end_bound)) or (end_bound is not None and end_bound < start_bound):
+            raise ValueError("invalid recording time bounds")
+        if self.type == "interval":
+            if self.start is None or self.end is None:
+                raise ValueError("interval annotations require start and end")
+            if not math.isfinite(self.start) or not math.isfinite(self.end):
+                raise ValueError("interval coordinates must be finite")
+            if self.end <= self.start:
+                raise ValueError("end must be greater than start")
+            if self.time is not None:
+                raise ValueError("interval annotations must not define time")
+            if end_bound is not None and (self.start < start_bound or self.end > end_bound):
+                raise ValueError("interval is outside the recording bounds")
+        elif self.type == "point":
+            if self.time is None:
+                raise ValueError("point annotations require time")
+            if not math.isfinite(self.time):
+                raise ValueError("point time must be finite")
+            if self.start is not None or self.end is not None:
+                raise ValueError("point annotations must not define start/end")
+            if end_bound is not None and not start_bound <= self.time <= end_bound:
+                raise ValueError("point is outside the recording bounds")
+        else:
+            raise ValueError(f"unknown annotation type: {self.type}")
+
+    @property
+    def position(self) -> float:
+        return self.start if self.type == "interval" else self.time  # type: ignore[return-value]
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+class AnnotationStore:
+    def __init__(self, duration_s: float | None = None, start_time_s: float = 0.0, end_time_s: float | None = None):
+        self.duration_s = duration_s
+        self.start_time_s = float(start_time_s)
+        self.end_time_s = float(end_time_s) if end_time_s is not None else (self.start_time_s + float(duration_s) if duration_s is not None else None)
+        self._items: list[Annotation] = []
+
+    @property
+    def items(self) -> list[Annotation]:
+        return list(self._items)
+
+    def add(self, ann: Annotation) -> Annotation:
+        ann.validate(self.duration_s, self.start_time_s, self.end_time_s)
+        if any(a.id == ann.id for a in self._items):
+            raise ValueError(f"duplicate annotation id: {ann.id}")
+        self._items.append(ann)
+        self._sort()
+        return ann
+
+    def update(self, ann_id: str, **changes) -> Annotation:
+        for idx, existing in enumerate(self._items):
+            if existing.id == ann_id:
+                data = {**asdict(existing), **changes}
+                updated = Annotation(**data)
+                updated.validate(self.duration_s, self.start_time_s, self.end_time_s)
+                self._items[idx] = updated
+                self._sort()
+                return updated
+        raise KeyError(ann_id)
+
+    def delete(self, ann_id: str) -> bool:
+        before = len(self._items)
+        self._items = [a for a in self._items if a.id != ann_id]
+        return len(self._items) != before
+
+    def duplicate(self, ann_id: str) -> Annotation:
+        for existing in self._items:
+            if existing.id == ann_id:
+                data = asdict(existing)
+                data["id"] = uuid.uuid4().hex[:10]
+                data["status"] = "unreviewed"
+                data["reviewer"] = ""
+                data["review_notes"] = ""
+                return self.add(Annotation(**data))
+        raise KeyError(ann_id)
+
+    def clear(self) -> None:
+        self._items.clear()
+
+    def _sort(self) -> None:
+        self._items.sort(key=lambda a: a.position)
+
+    def to_dict(self, source_file: str = "", metadata: dict | None = None) -> dict:
+        meta = dict(metadata or {})
+        meta.setdefault("time_start_s", self.start_time_s)
+        if self.end_time_s is not None:
+            meta.setdefault("time_end_s", self.end_time_s)
+        return {"schema": "electrotrace.annotation/v2", "file": source_file, "metadata": meta, "annotations": [a.to_dict() for a in self._items]}
+
+    def to_json(self, source_file: str = "", metadata: dict | None = None) -> str:
+        return json.dumps(self.to_dict(source_file, metadata), indent=2)
+
+    @classmethod
+    def from_dict(cls, data: dict, duration_s: float | None = None, start_time_s: float | None = None, end_time_s: float | None = None) -> "AnnotationStore":
+        metadata = data.get("metadata") or {}
+        start = float(metadata.get("time_start_s", 0.0) if start_time_s is None else start_time_s)
+        end = metadata.get("time_end_s") if end_time_s is None else end_time_s
+        store = cls(duration_s=duration_s, start_time_s=start, end_time_s=float(end) if end is not None else None)
+        schema = data.get("schema", data.get("annotation_schema", ""))
+        if schema and schema not in {"electrotrace.annotation/v2", "v1"}:
+            raise ValueError(f"unsupported annotation schema: {schema}")
+        for raw in data.get("annotations", []):
+            store.add(Annotation(**raw))
+        return store
+
+    @classmethod
+    def from_json(cls, text: str, duration_s: float | None = None, start_time_s: float | None = None, end_time_s: float | None = None) -> "AnnotationStore":
+        try:
+            data = json.loads(text)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"invalid JSON: {exc}") from exc
+        return cls.from_dict(data, duration_s=duration_s, start_time_s=start_time_s, end_time_s=end_time_s)
+
+    def to_csv_rows(self, source_file: str = "") -> list[dict]:
+        return [{"file": source_file, "id": a.id, "type": a.type, "label": a.label, "channel": a.channel, "start": a.start, "end": a.end, "time": a.time, "confidence": a.confidence, "notes": a.notes, "annotator": a.annotator, "status": a.status, "reviewer": a.reviewer, "review_notes": a.review_notes} for a in self._items]
+
+
+def point_agreement(a: list[Annotation], b: list[Annotation], tolerance_s: float = 0.04) -> dict:
+    if tolerance_s <= 0 or not math.isfinite(tolerance_s):
+        raise ValueError("tolerance_s must be positive and finite")
+    left = [x for x in a if x.type == "point"]
+    right = [x for x in b if x.type == "point"]
+    used: set[str] = set()
+    errors = []
+    matches = 0
+    for x in left:
+        candidates = [
+            y for y in right
+            if y.id not in used
+            and y.label == x.label
+            and y.channel == x.channel
+            and y.time is not None
+            and x.time is not None
+            and abs(y.time - x.time) <= tolerance_s
+        ]
+        if candidates:
+            y = min(candidates, key=lambda z: abs(z.time - x.time))
+            used.add(y.id)
+            matches += 1
+            errors.append(abs(y.time - x.time))
+    total = max(len(left), len(right), 1)
+    return {"matches": matches, "agreement_rate": matches / total, "mean_absolute_error_s": sum(errors) / len(errors) if errors else None}
+
+
+def interval_iou(a: Annotation, b: Annotation) -> float:
+    if a.type != "interval" or b.type != "interval":
+        return 0.0
+    inter = max(0.0, min(a.end, b.end) - max(a.start, b.start))  # type: ignore[arg-type]
+    union = max(a.end, b.end) - min(a.start, b.start)  # type: ignore[arg-type]
+    return inter / union if union else 0.0