Metadata-Version: 2.4
Name: ecg-integrity
Version: 0.1.0
Summary: ECG signal integrity analysis — an upstream quality gate for clinical ECG pipelines
Project-URL: Homepage, https://github.com/axium-health/ecg-integrity
Project-URL: Repository, https://github.com/axium-health/ecg-integrity
Project-URL: Issues, https://github.com/axium-health/ecg-integrity/issues
Author: Axium Health
License: MIT License
        
        Copyright (c) 2026 Axium Health
        
        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.
License-File: LICENSE
Keywords: artifact-detection,cardiology,clinical-ai,ecg,medical-device,signal-integrity
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Healthcare Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: numpy>=1.24.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer[all]>=0.9.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Provides-Extra: edf
Requires-Dist: pyedflib>=0.1.22; extra == 'edf'
Provides-Extra: report
Requires-Dist: matplotlib>=3.7.0; extra == 'report'
Provides-Extra: wfdb
Requires-Dist: wfdb>=4.0.0; extra == 'wfdb'
Description-Content-Type: text/markdown

# ecg-integrity

**ECG signal integrity validation — an upstream quality gate for clinical ECG pipelines.**

Built by [Axium](https://github.com/axium-health). Part of the signal integrity infrastructure layer for cardiac AI.

---

## What it does

`ecg-integrity` analyzes raw ECG signals and returns a structured integrity score before any diagnostic model, algorithm, or regulatory submission touches the data. It detects 7 clinically-relevant artifact types, scores each lead independently, and classifies the overall signal into a three-zone usability label.

**Garbage-in, garbage-out is a data problem. This is the solution.**

---

## The 7 failure modes detected

| # | Failure Mode | Clinical Impact |
|---|---|---|
| 1 | Baseline wander | Shifts ST segment, distorts morphology |
| 2 | Powerline interference (50/60 Hz) | Obscures low-amplitude features |
| 3 | EMG artifact (muscle noise) | Broadband noise masking signal |
| 4 | Electrode motion artifact | Transient distortion, mimics arrhythmia |
| 5 | Saturation / clipping | Irrecoverable amplitude data loss |
| 6 | Lead disconnection | Partial or complete signal loss |
| 7 | Flatline / dropout | Zero-signal or near-zero variance segments |

---

## Scoring model

```
score = clamp(1.0 − Σ(weightᵢ × severityᵢ), worst_floor, 1.0)
```

Each failure mode has a severity-weighted penalty and a worst-case floor. Critical modes (lead disconnection, flatline) cap the score regardless of other artifacts.

### Three-zone output

| Score | Label | Meaning |
|---|---|---|
| ≥ 0.85 | **PASS** | Safe to use — proceed to AI model or analysis |
| 0.60 – 0.84 | **REVIEW** | Usable with caution — log for audit |
| < 0.60 | **FAIL** | Discard — re-acquire if possible |

### Thresholds by clinical context

| Use case | Recommended threshold |
|---|---|
| FDA-cleared diagnostic ECG | ≥ 0.85 |
| Real-time bedside monitoring | ≥ 0.80 |
| Ambulatory / Holter monitoring | ≥ 0.75 |
| Research / dataset curation | ≥ 0.70 |
| Screening / wellness wearable | ≥ 0.60 |

---

## Installation

**Core (CSV input, CLI, scoring):**
```bash
pip install ecg-integrity
```

**With WFDB support (PhysioNet / MIT-BIH):**
```bash
pip install "ecg-integrity[wfdb]"
```

**With EDF support:**
```bash
pip install "ecg-integrity[edf]"
```

**With HTML report generation:**
```bash
pip install "ecg-integrity[report]"
```

**Everything:**
```bash
pip install "ecg-integrity[wfdb,edf,report]"
```

Requires Python ≥ 3.11.

---

## CLI usage

### Single recording

```bash
ecg-integrity analyze \
  --input recording.csv \
  --fs 500 \
  --output report.json \
  --html report.html
```

**Options:**
- `--fs` — sampling rate in Hz (required for CSV; inferred for EDF/WFDB)
- `--line-freq` — AC line frequency, `50` or `60` (default: `60`)
- `--output` — save result as JSON
- `--html` — save self-contained HTML report
- `--no-header` — CSV has no header row
- `--leads` — override lead names

**Exit codes:** `0` = PASS, `1` = REVIEW or FAIL (CI-friendly).

### Batch processing

```bash
ecg-integrity batch \
  --input-dir recordings/ \
  --fs 500 \
  --pattern "*.csv" \
  --html batch_report.html \
  --output batch_results.json
```

**Options:**
- `--recursive` — search subdirectories
- `--pattern` — file glob filter (repeatable)

---

## Python API

### Quick start

```python
import numpy as np
from ecg_integrity import run_detectors, aggregate_results

# Load your signal however you want
signal = np.loadtxt("lead_I.csv")

# Run all 7 detectors on one lead
detections = run_detectors(signal, fs=500, line_freq=60)

# Score a multi-lead recording
scores = aggregate_results({
    "lead_I":  run_detectors(signal_I,  fs=500),
    "lead_II": run_detectors(signal_II, fs=500),
})

print(scores.aggregate_score)      # 0.9241
print(scores.usability_label)      # "PASS"
print(scores.confidence_interval)  # (0.89, 0.96)
print(scores.to_dict())            # full JSON-serializable result
```

### Load ECG files directly

```python
from ecg_integrity import load

# CSV
ecg = load("recording.csv", fs=500)

# EDF (requires pip install "ecg-integrity[edf]")
ecg = load("recording.edf")

# PhysioNet / WFDB (requires pip install "ecg-integrity[wfdb]")
ecg = load("mit-bih/100")

print(ecg.signals.shape)   # (samples, leads)
print(ecg.lead_names)      # ["MLII", "V5"]
print(ecg.fs)              # 360.0
```

### Inspect individual failure modes

```python
from ecg_integrity import run_detectors

detections = run_detectors(signal, fs=500)

for result in detections:
    if result.detected:
        print(f"{result.mode.value}")       # "powerline_interference"
        print(f"  severity: {result.severity:.2f}")  # 0.73
        print(f"  confidence: {result.confidence:.2f}")
```

### JSON response structure

```json
{
  "aggregate_score": 0.87,
  "confidence_interval": [0.81, 0.93],
  "usability_label": "PASS",
  "dominant_failure_modes": ["powerline_interference"],
  "per_lead_scores": {
    "lead_I":  { "score": 0.91, "worst_floor": 0.20, "confidence": 0.94 },
    "lead_II": { "score": 0.83, "worst_floor": 0.20, "confidence": 0.88 }
  },
  "source_file": "recording.csv",
  "fs": 500.0
}
```

---

## Supported file formats

| Format | Extension | Extra install |
|---|---|---|
| CSV / TSV / TXT | `.csv`, `.txt` | — (core) |
| European Data Format | `.edf` | `pip install "ecg-integrity[edf]"` |
| PhysioNet / WFDB | `.hea` / record name | `pip install "ecg-integrity[wfdb]"` |

---

## Validated on MIT-BIH Arrhythmia Database

The scoring thresholds and failure mode weights are grounded in the [MIT-BIH Arrhythmia Database](https://physionet.org/content/mitdb/1.0.0/) (PhysioNet). To load and analyze a record:

```python
from ecg_integrity import load, run_detectors, aggregate_results

ecg = load("mitdb/100", fs=None)   # fs inferred from header

lead_detections = {
    name: run_detectors(ecg.signals[:, i], fs=ecg.fs)
    for i, name in enumerate(ecg.lead_names)
}

result = aggregate_results(lead_detections)
print(result.usability_label)   # "PASS" | "REVIEW" | "FAIL"
```

---

## Who this is for

**Medical device companies** validating ECG pipelines before FDA submission.

**Wearable OEMs** filtering low-quality signals before feeding downstream models.

**Research labs** curating clean datasets from large ECG databases.

**Clinical AI vendors** adding a quality gate upstream of diagnostic inference.

---

## Architecture

```
ecg_integrity/
├── io/            # File loading — CSV, EDF, WFDB (PhysioNet)
├── preprocessing/ # Bandpass filter, notch filter, normalization
├── features/      # Single-pass FFT — 11 time + frequency domain features
├── models/
│   ├── detectors.py   # 7 artifact detectors
│   ├── scoring.py     # Severity-weighted integrity scoring engine
│   └── batch.py       # Batch runner with error resilience
├── explain/       # HTML report generation
├── schemas/       # Pydantic-compatible data types
└── utils/         # RMS, moving statistics, Welch PSD
```

All three delivery forms share one core:

```
ecg_integrity (this package)
       │
       ├── REST API  — wrap in FastAPI for SaaS
       ├── SDK       — compile with Cython for embedded/offline use
       └── Certification harness — test battery for FDA audit support
```

---

## Development

```bash
git clone https://github.com/axium-health/ecg-integrity
cd ecg-integrity

pip install -e ".[wfdb,edf,report,dev]"
pytest
```

164 tests, 160 passing (4 skipped — optional scipy dependency).

---

## License

MIT — see [LICENSE](LICENSE).

---

## About Axium

Axium builds signal integrity infrastructure for clinical ECG AI. `ecg-integrity` is the open-source core of the Axium platform — the upstream quality gate that runs before any diagnostic model, regulatory submission, or clinical decision.

[axium.health](https://axium.health) · [GitHub](https://github.com/axium-health)
