# Quickstart: round-trip a golden ECG codec

<!-- notebook-generated-page -->

Download notebookView sourceOpen in Colab

Open in Colab opens the source notebook only. Before running cells, use a Python 3.12 runtime and install compressionKIT into that runtime. See [notebook environment setup](https://ambiqai.github.io/compressionkit/examples/#notebook-environment-setup). Hosted execution has not been validated by this documentation build.

This example displays saved outputs. Building the documentation does not run training. Check dataset paths for your notebook working directory before running.

Load a published **compressionKIT** golden ECG codec, compress and decompress a
physiological frame, and measure the true compression ratio and fidelity.

**No dataset required.** Every deploy package ships a small set of
representative, license-safe reference frames (`reference_vectors.npz`) that we
use here, so the notebook runs anywhere.

> Loading from HuggingFace needs internet access. To run fully offline, point
> `CODEC_SOURCE` at a local deploy package you built with
> `compressionkit golden run ...`.

```python title="Python"
from pathlib import Path

import matplotlib.pyplot as plt
import numpy as np

from compressionkit.evaluation.metrics import compute_signal_metrics
from compressionkit.runtime import load_codec, resolve_deploy_dir

# A published golden codec (downloads from HuggingFace) ...
# "-v1.0" repos are the current release track. Uncomment any line below to
# try a different compression ratio or codec family (RVQ = learned/AI, SPIHT =
# DSP-only wavelet codec, hybrid = learned denoiser + SPIHT). All three families
# implement the same Codec interface, so nothing below this cell needs to change.
CODEC_SOURCE = "Ambiq/compressionkit-ecg-8x-v1.0"
# CODEC_SOURCE = "Ambiq/compressionkit-ecg-2x-v1.0"
# CODEC_SOURCE = "Ambiq/compressionkit-ecg-4x-v1.0"
# CODEC_SOURCE = "Ambiq/compressionkit-ecg-16x-v1.0"
# CODEC_SOURCE = "Ambiq/compressionkit-ecg-32x-v1.0"
# CODEC_SOURCE = "Ambiq/compressionkit-ecg-64x-v1.0"
# SPIHT (DSP-only, no trained weights) and hybrid (learned denoiser + SPIHT):
# CODEC_SOURCE = "Ambiq/compressionkit-ecg-spiht-8x-v1.0"
# CODEC_SOURCE = "Ambiq/compressionkit-ecg-hybrid-8x-v1.0"
# ... or a local deploy package you built yourself:
# CODEC_SOURCE = "results/ecg_rvq_256hz_04x_golden/deploy"
```

```text title="Saved output"
2026-07-02 01:19:05.830539: I tensorflow/core/util/port.cc:153] oneDNN custom operations are on. You may see slightly different numerical results due to floating-point round-off errors from different computation orders. To turn them off, set the environment variable `TF_ENABLE_ONEDNN_OPTS=0`.
2026-07-02 01:19:05.854934: I tensorflow/core/platform/cpu_feature_guard.cc:210] This TensorFlow binary is optimized to use available CPU instructions in performance-critical operations.
To enable the following instructions: AVX2 AVX_VNNI FMA, in other operations, rebuild TensorFlow with the appropriate compiler flags.
2026-07-02 01:19:06.397691: I tensorflow/core/util/port.cc:153] oneDNN custom operations are on. You may see slightly different numerical results due to floating-point round-off errors from different computation orders. To turn them off, set the environment variable `TF_ENABLE_ONEDNN_OPTS=0`.
```

```python title="Python"
codec = load_codec(CODEC_SOURCE)

print(f"name        : {codec.name}")
print(f"modality    : {codec.modality}")
print(f"sample_rate : {codec.sample_rate} Hz")
print(f"frame_size  : {codec.frame_size} samples ({codec.frame_size / codec.sample_rate:.2f} s)")
print(f"target CR   : {codec.target_cr:g}x")
```

```text title="Saved output"
Fetching 15 files: 100%|██████████| 15/15 [00:00<00:00, 76445.39it/s]
```

```text title="Saved output"
name        : ecg_rvq_256hz_08x_golden_empirical_midpoint
modality    : ecg
sample_rate : 256 Hz
frame_size  : 512 samples (2.00 s)
target CR   : 8x
```

```text title="Saved output"

INFO: Created TensorFlow Lite XNNPACK delegate for CPU.
```

## Representative frames

Release packages include license-safe frames for smoke tests and demos. When
`reference_vectors.npz` is present, the notebook uses its exact runtime
conformance inputs. Otherwise it falls back to `sample_stimulus.npz` or
`sample_data.npz` from the deploy package.

```python title="Python"
deploy = Path(resolve_deploy_dir(CODEC_SOURCE))

sample_candidates = [
    ("reference_vectors.npz", ("input_frames", "inputs", "stimulus")),
    ("sample_stimulus.npz", ("input_frames", "inputs", "stimulus")),
    ("sample_data.npz", ("input_frames", "inputs", "stimulus")),
]

for filename, keys in sample_candidates:
    sample_path = deploy / filename
    if not sample_path.exists():
        continue
    sample_npz = np.load(sample_path)
    for key in keys:
        if key in sample_npz:
            sample_source = f"{filename}:{key}"
            raw_frames = sample_npz[key]
            break
    else:
        continue
    break
else:
    raise FileNotFoundError(
        f"No sample frame artifact found in {deploy}. Expected one of: "
        + ", ".join(name for name, _ in sample_candidates)
    )

raw_frames = np.asarray(raw_frames, dtype="float32")
if raw_frames.ndim == 1:
    frames = raw_frames.reshape(1, -1)
elif raw_frames.ndim == 2:
    frames = raw_frames
else:
    frames = raw_frames.reshape(raw_frames.shape[0], -1)

if frames.shape[1] != codec.frame_size:
    raise ValueError(
        f"Sample frames from {sample_source} have {frames.shape[1]} samples, "
        f"but codec.frame_size is {codec.frame_size}."
    )

print(f"Loaded {len(frames)} sample frames from {sample_source}")
```

```text title="Saved output"
Fetching 15 files: 100%|██████████| 15/15 [00:00<00:00, 34817.13it/s]
```

```text title="Saved output"
Loaded 500 sample frames from sample_stimulus.npz:inputs
```

## Round-trip a single frame

Compression ratio is reported against a **32-bit float** sample baseline — the
toolkit's reference raw representation, which matches the headline `target CR`.

```python title="Python"
frame = frames[0]
encoded = codec.compress(frame)
recon = codec.decompress(encoded)

raw_bits = frame.size * 32  # 32-bit float baseline
true_cr = raw_bits / encoded.nbits
m = compute_signal_metrics(frame, recon)

print(f"encoded bits : {encoded.nbits}  ->  measured CR {true_cr:.2f}x (vs 32-bit float)")
print(f"PRD          : {m['prd_percent']:.2f}%")
print(f"cosine sim   : {m['cosine_similarity']:.4f}")
```

```text title="Saved output"
encoded bits : 2048  ->  measured CR 8.00x (vs 32-bit float)
PRD          : 6.65%
cosine sim   : 0.9978
```

```python title="Python"
t = np.arange(frame.size) / codec.sample_rate
plt.figure(figsize=(10, 3))
plt.plot(t, frame, label="original", lw=1.5)
plt.plot(t, recon, label="reconstruction", lw=1.2, alpha=0.85)
plt.xlabel("time (s)")
plt.ylabel("amplitude")
plt.title(f"{codec.name}  ·  PRD {m['prd_percent']:.2f}%  ·  CR {true_cr:.2f}x")
plt.legend()
plt.tight_layout()
plt.show()
```

Saved output · cell 8

## Aggregate over many frames

A single number hides the spread. Round-trip a batch and look at the
distribution of fidelity alongside the realized compression ratio.

```python title="Python"
N = min(500, len(frames))
batch = frames[:N]

total_bits = 0
prd, cos = [], []
for f in batch:
    e = codec.compress(f)
    r = codec.decompress(e)
    total_bits += e.nbits
    mm = compute_signal_metrics(f, r)
    prd.append(mm["prd_percent"])
    cos.append(mm["cosine_similarity"])

prd = np.asarray(prd)
cos = np.asarray(cos)
print(f"frames evaluated : {N}")
print(f"measured CR      : {(batch.size * 32) / total_bits:.2f}x")
print(f"PRD %            : median {np.median(prd):.2f}   mean {prd.mean():.2f}")
print(f"cosine           : median {np.median(cos):.4f}   mean {cos.mean():.4f}")
```

```text title="Saved output"
frames evaluated : 500
measured CR      : 8.00x
PRD %            : median 6.37   mean 7.06
cosine           : median 0.9980   mean 0.9970
```

```python title="Python"
plt.figure(figsize=(10, 3))
plt.hist(prd, bins=30, color="#4C78A8")
plt.axvline(np.median(prd), color="k", ls="--", label=f"median {np.median(prd):.2f}%")
plt.xlabel("PRD %")
plt.ylabel("frames")
plt.title("Per-frame fidelity distribution")
plt.legend()
plt.tight_layout()
plt.show()
```

Saved output · cell 11

## Next steps

- Swap `CODEC_SOURCE` for any tier in the [Model Zoo](https://ambiqai.github.io/compressionkit/models/) as more ECG CRs are published under the `-v1.0` track.
- Try the PPG version: `01_quickstart_golden_codec.ipynb`.
- Evaluate on **your own recordings** — see `02_evaluate_on_your_data.ipynb`.
- Reproduce a golden end-to-end: `compressionkit golden run ecg-rvq-4x`.