Metadata-Version: 2.4
Name: ecginterpret
Version: 0.2.1
Summary: Rule-based ECG interpretation statements over ecg-records measurements (research and engineering software; not a medical device)
Author: humansys-lab
Maintainer: humansys-lab
License-Expression: Apache-2.0
Project-URL: Homepage, https://humansys-lab.github.io/ecg-records/
Project-URL: Documentation, https://humansys-lab.github.io/ecg-records/
Project-URL: Issues, https://github.com/humansys-lab/ecg-records/issues
Keywords: ecg,electrocardiography,interpretation,research
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Typing :: Typed
Requires-Python: <3.15,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: ecg-records[engine]<0.4,>=0.3
Requires-Dist: numpy<3,>=1.26
Dynamic: license-file

# ecginterpret

Rule-based ECG interpretation statements (rhythm, conduction, hypertrophy,
ischemia, pediatric and Glasgow-style rule sets) computed from the
measurements produced by [`ecg-records`](../feature_extraction/README.md).
The output is a separately versioned **Interpretation document**; it is not
part of the ECG Record measurement contract.

> This software is research and engineering software. It is not a medical
> device and is not intended to diagnose, treat, cure, or prevent disease.
> Outputs require independent validation for the intended use and must not be
> used as a substitute for professional medical judgment.

## Install

```bash
pip install ecginterpret          # or: pip install "ecg-records[interpret]"
```

## Use

```python
import ecgfeat
from ecginterpret import analyze, render_report

signal = ecgfeat.read_signal("ptbxl/records500/00000/00001_hr.hea")   # or ecgfeat.load_example("lbbb")
record, document = analyze(signal, profile="all")    # one engine run: ECG Record + Interpretation document
print(render_report(document, record))                # text; format="markdown" or "html"
result = document.as_dict()
result["interpretation"]["heart_rate_class"]        # e.g. "normal"
result["interpretation"]["bundle_branch_block"]     # e.g. "LBBB", or None
[s["statement"] for s in result["clinical"]["final_statements"]]
```

`analyze` measures once and returns the same record as `ecgfeat.ecg_record`
and the same document as `interpret_record` (the generation timestamp aside),
in about half the time.  From the command line:

```bash
ecg-interpret ptbxl/00001_hr.hea --format markdown --record rec.json
```

`interpret_record(record, signal=signal)` interprets a saved record; it needs
the raw signal because ECG Record schema 1.x does not
carry every measurement the rule engines read (representative-lead
morphology, rhythm and P-wave evidence), so the interpreter re-derives them
from the signal with the record's own resolved configuration after checking
the signal against the record's raw-signal SHA-256.  `interpret_features` takes
the legacy measurement object from `ecgfeat.compat.api_v0.ECGFeatureExtractor`
directly (compatibility input, removed with `ecgfeat.compat`).

## Versioning

The Interpretation document carries `schema_version` (currently `1.0.0`),
independent of both the package version and the ECG Record schema version.
The JSON Schema ships at `ecginterpret/schemas/interpretation/1.0/schema.json`.
Supported input: ECG Record schema major `1` (1.0 and 1.1). Requires `ecg-records[engine]>=0.3,<0.4` (installed automatically).
