Quickstart: round-trip a golden ECG codec

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. 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

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"

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

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")

Saved output

Fetching 15 files: 100%|██████████| 15/15 [00:00<00:00, 76445.39it/s]

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

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

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}")

Saved output

Fetching 15 files: 100%|██████████| 15/15 [00:00<00:00, 34817.13it/s]

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

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}")

Saved output

encoded bits : 2048  ->  measured CR 8.00x (vs 32-bit float)
PRD          : 6.65%
cosine sim   : 0.9978

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

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}")

Saved output

frames evaluated : 500
measured CR      : 8.00x
PRD %            : median 6.37   mean 7.06
cosine           : median 0.9980   mean 0.9970

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 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.