---
license: other
license_name: ambiq-model-weights-license
license_link: https://github.com/AmbiqAI/compressionkit/blob/main/LICENSE-MODEL-WEIGHTS.md
library_name: compressionkit
pipeline_tag: other
tags:
  - compressionkit
  - signal-compression
  - ecg
  - rvq
  - tflite
  - edge-ai
---

# compressionkit-ecg-8x-v1.0

A **ECG** signal compression codec using Residual Vector Quantization (RVQ), optimized for edge and wearable devices.

## Model Details

- **Modality:** ECG
- **Sample Rate:** 256 Hz
- **Compression Ratio:** 8x
- **Quantization:** INT8
- **RVQ Levels:** 4
- **Codebook Size:** 256 entries × 16D
- **Encoder Input:** `[None, 1, 512, 1]`
- **Encoder Output:** `[None, 1, 64, 16]`

## Quality Metrics

### Fidelity & Robustness

Both fidelity yardsticks are reported so the codec is judged fairly: **faithfulness** is PRD vs the recorded (still-noisy) input, while **truth fidelity** is PRD vs clean ground truth. Lower is better.

| Metric | Value |
|--------|-------|
| Truth PRD vs clean (%) | 3.84 |
| Truth PRD at native noise (%) | 37.90 |
| Faithful PRD vs input (%) | 6.03 |
| PRD degradation slope (PRD%/dB) | 3.92 |
| PRD at 0 dB SNR (%) | 49.99 |
| PRD at -6 dB SNR (%) | 77.83 |
| Pure-noise imprint autocorr | 0.2552 |

### Time Domain

_PRD here is faithfulness (vs the recorded input); see **Fidelity & Robustness** above for the clean-truth and noise-regime view._

| Metric | Mean | Median | P90 |
|--------|------|--------|-----|
| PRD vs input — faithfulness (%) | 6.0330 | 5.1601 | 9.7251 |
| RMSE | 0.0580 | 0.0501 | 0.0921 |
| Cosine Similarity | 0.9977 | 0.9987 | 0.9994 |

### Spectral

- **Band Total Relative Error (median):** 0.0631

### Bitrate

- **Codec CR (uniform):** 8.0x
- **Codec CR (learned prior):** 15.24x

## Encoder Precision Parity

Difference from FP32 reconstruction on a disjoint real-data holdout; lower is better.

| Encoder | P90 PRD | Worst PRD | Status |
|---|---:|---:|---|
| FP16 | 1.24% | 2.98% | recommended |
| INT16X8 | 3.86% | 6.36% | recommended |
| INT8 | 9.22% | 13.02% | recommended |

## Usage

### Python (compressionkit runtime)

```python
from compressionkit.runtime import RVQCodec

codec = RVQCodec.from_pretrained("Ambiq/compressionkit-ecg-8x-v1.0")

# Encode: float32 signal → RVQ indices
indices = codec.encode(signal)

# Decode: RVQ indices → reconstructed signal
recon = codec.decode(indices)
```

### Local deployment directory

```python
codec = RVQCodec("path/to/deploy/")
```

## Files

| File | Description |
|------|-------------|
| `encoder_int8.tflite` | INT8 quantized encoder (on-device) |
| `encoder_float32.tflite` | Float32 encoder for browser/server runtimes |
| `encoder_fp16.tflite` | FP16 encoder variant for supported edge runtimes |
| `encoder_int16x8.tflite` | INT16x8 encoder variant for supported edge runtimes |
| `encoder.h` | C header for encoder |
| `encoder.keras` | Float32 Python reference encoder (training/inspection use) |
| `decoder_float32.tflite` | Float32 decoder (server-side evaluation) |
| `decoder_int8.tflite` | INT8 decoder (optional, on-device) |
| `decoder.keras` | Float32 Python reference decoder (training/inspection use) |
| `codebook.npz` | RVQ codebook tables |
| `codebook.h` | C header for codebook |
| `config.json` | Deployment manifest |
| `sample_stimulus.npz` | Synthetic test data |
| `demo_recordings.npz` | 10 real, quality-gated browser-demo recordings |
| `demo_recordings_manifest.json` | Recording provenance, license, and quality metadata |
| `quality_scorecard.json` | Full evaluation metrics |

## Dataset & License

Training data: PTB-XL (CC BY 4.0). Sample data may include excerpts under the original license terms.
Demo recordings: MIT-BIH Arrhythmia Database v1.0.0 ([source](https://physionet.org/content/mitdb/1.0.0/)); real, quality-gated excerpts are released under ODC-By-1.0. [https://opendatacommons.org/licenses/by/1-0/](https://opendatacommons.org/licenses/by/1-0/)

Model weights are released under the **Ambiq Model Weights License** — deployment is restricted to Ambiq silicon devices. See `LICENSE-MODEL-WEIGHTS.md` for full terms.

## Citation

```bibtex
@software{compressionkit,
  author = {Ambiq AI},
  title = {compressionKIT: Signal Compression for Edge AI},
  url = {https://github.com/AmbiqAI/compressionkit}
}
```