ease-ecg 0.0.1__tar.gz

ease_ecg-0.0.1/CLAUDE.md

@@ -0,0 +1,75 @@
+# EASE — Ecg Analysis SoftwarE
+
+## What this is
+
+A Python port of a MATLAB ECG analysis tool. It analyses 10-second 12-lead ECG snippets:
+automatically detects fiducial points, lets the user confirm caliper positions and labels
+in a browser-based review UI, then computes several hundred parameters per record.
+
+Target users are research students processing hundreds to thousands of snippets on their
+own laptops, with no Python knowledge required beyond `uvx ease-ecg`.
+
+The original MATLAB source lives OUTSIDE this repo (sibling directory `../ease-matlab/`,
+read-only reference). Never copy it into this repo; its ownership and licensing are
+separate from the Python port.
+
+## Names
+
+- PyPI distribution: `ease-ecg`
+- Import name: `ease_ecg`
+- CLI command: `ease-ecg`
+- Licence: MIT
+
+## Architecture rules
+
+- `src/ease_ecg/` is the analysis library. It must have NO UI dependencies
+  (no dash, plotly, or any web framework imports).
+- `src/ease_ecg/ui/` is a thin Dash shell over the library's data model. No signal
+  processing or parameter calculation lives here. Dash/plotly are an optional extra
+  (`pip install ease-ecg[ui]`).
+- `src/ease_ecg/cli.py` exposes `ease-ecg batch` and `ease-ecg review`.
+- Core data model in `src/ease_ecg/model.py`: `Record` (signal, sampling rate, lead names,
+  metadata), `Fiducials`, `Annotations` (labels, review status), `Results`.
+  Pydantic models or dataclasses; decide once and be consistent.
+- On-disk formats: one JSON sidecar per record (fiducials, annotations, review status),
+  parameters in Parquet. Every results file records the ease-ecg version and the analysis
+  parameters used. Treat the schema as a contract; changes require a migration note.
+- Workflow is batch-then-review: automatic analysis over a whole folder first, then a
+  keyboard-driven review queue. Design for throughput of human review, not per-record
+  analysis.
+
+## Correctness
+
+- `tests/reference/` contains inputs and MATLAB outputs for a set of reference records.
+  These are the oracle. Public test data must be synthetic or openly licensed
+  (e.g. PhysioNet PTB-XL); real study data stays private.
+- Every ported function gets a test comparing against the MATLAB output with an explicit,
+  justified tolerance. Never loosen a tolerance to make a test pass; investigate the
+  difference and report it.
+- Known MATLAB -> NumPy traps: 1-based indexing, `round` (half-away-from-zero vs
+  banker's), `filtfilt` padding defaults, FFT normalisation, `std` ddof, column-major
+  `reshape`, `find` semantics, inclusive ranges. When one bites, add a comment at the
+  call site explaining the MATLAB-equivalence choice.
+- If MATLAB code looks buggy, do not silently port the bug. Stop, describe it, and ask
+  whether to replicate or fix.
+
+## Tooling
+
+- Python >=3.12, managed with `uv`. Commands: `uv sync`, `uv run pytest`,
+  `uv run ruff check`, `uv run ruff format`, `uv run mypy src`, `uv build`.
+- Build backend: hatchling. Type hints everywhere.
+- Core deps: numpy, scipy, pandas, pyarrow, pydantic. I/O: wfdb, pyedflib.
+  UI extra: dash, plotly. Ask before adding anything else.
+- CI: GitHub Actions. Pin third-party actions to full commit SHAs. Publishing uses
+  PyPI trusted publishing (OIDC) only; never API tokens.
+- Conventional commits. Update CHANGELOG.md (Unreleased section) for user-visible changes.
+
+## Working style
+
+- Port one function at a time, test-first against the reference data, then commit.
+- Do not port MATLAB GUI logic. Only signal processing, fiducial detection and parameter
+  calculation. The UI is redesigned, not translated.
+- Maintain `PORTING_NOTES.md`: every MATLAB function, with status
+  (ported / skipped / blocked) and a one-line reason.
+- Prefer small, reviewable changes. Show a plan before multi-file changes.
+- Do not push or create tags unless explicitly asked.

ease_ecg-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tuomas Kenttä
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ease_ecg-0.0.1/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.5
+Name: ease-ecg
+Version: 0.0.1
+Summary: EASE (Ecg Analysis SoftwarE): automated analysis of 12-lead ECG snippets with interactive caliper review.
+Project-URL: Homepage, https://github.com/tkentta/ease-ecg
+Author: Your Name
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 1 - Planning
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# EASE: ECG Analysis Software
+
+Automated analysis of 10-second 12-lead ECG snippets with interactive review. Python port of the original MATLAB tool.
+
+**Status:** early development — not yet usable. Watch this repo or check back
+for the first release.
+
+## Licence
+
+MIT

ease_ecg-0.0.1/README.md

@@ -0,0 +1,10 @@
+# EASE: ECG Analysis Software
+
+Automated analysis of 10-second 12-lead ECG snippets with interactive review. Python port of the original MATLAB tool.
+
+**Status:** early development — not yet usable. Watch this repo or check back
+for the first release.
+
+## Licence
+
+MIT

ease_ecg-0.0.1/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ease-ecg"
+version = "0.0.1"
+description = "EASE (Ecg Analysis SoftwarE): automated analysis of 12-lead ECG snippets with interactive caliper review."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Your Name" }]
+requires-python = ">=3.12"
+classifiers = [
+  "Development Status :: 1 - Planning",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Medical Science Apps.",
+]
+
+[project.urls]
+Homepage = "https://github.com/tkentta/ease-ecg"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ease_ecg"]

ease_ecg-0.0.1/src/ease_ecg/__init__.py

@@ -0,0 +1,3 @@
+"""EASE — Ecg Analysis SoftwarE. Placeholder release; not yet functional."""
+
+__version__ = "0.0.1"