PPG Models (v1.0)¶

PPG release artifacts and comparison lanes at 64 Hz. The published HuggingFace bundles are RVQ neural codecs; the local golden registry also includes SPIHT DSP and hybrid AI+DSP lanes for standardized comparison.

Published RVQ results¶

The table below summarizes the published RVQ bundles. These are the v1 packages available through HuggingFace and the runtime loader.

All metrics are on the validation set. HR/HRV metrics are from long-recording overlap-add evaluation (60 s windows, 50% hop).

Codec tradeoffs under noise and artifacts¶

PPG has three release-facing comparison lanes:

The robustness sweep scores each lane against a filtered clean-truth proxy after injecting empirical noise or additive artifacts. Lower PRD is better. This is a different question from faithful reconstruction of a clean validation frame: it asks which codec best preserves the recoverable pulse waveform when the input is already corrupted.

The practical read is that SPIHT is a strong low-noise baseline, RVQ is the published neural operating surface, and hybrid approaches become important when the input looks more like a wrist-worn signal with empirical noise or drift. See PPG CR vs fidelity and Validation Scorecard for the detailed scorecard definitions and noise-aware metrics.

Model Details¶

Architecture¶

All PPG models share the same architecture:

• Encoder: Strided Conv2D blocks (stride 2 per stage) with depthwise-separable convolutions, followed by a 1x1 projection to embedding_dim=16
• RVQ bottleneck: EMA-updated codebooks with 256 entries, 8 bits/index
• Decoder: UpSampling2D + Conv2D mirror of the encoder
• Training: EMA decay 0.99, base filters 48, filter multiplier 1.25, 200 epochs

Compression Ratio Breakdown¶

Frame size = 320 samples (5 s at 64 Hz). Raw frame = 5120 bits (16-bit). Codebook size K = 256 (8 bits/index).

Loss Function¶

• Primary: MSE
• Auxiliary: Derivative loss (weight 0.1) — preserves waveform first-derivative (morphology)

HR/HRV Preservation¶

Long-recording evaluation uses overlap-add reconstruction on 60 s continuous segments, then computes physiological metrics with physioKit:

Dataset: Open unified PPG v1¶

The published v1 PPG goldens use ppg-unified-strict-sanitize-v1: a unified mixture of BIDMC, BUT PPG, PPG-DaLiA, and WESAD. The release-facing PPG goldens are MESA-free so users can reproduce the published artifacts without restricted NSRR data.

MESA remains a supported restricted source for internal or custom experiments, but it is not used in the published v1 PPG goldens. See Dataset Setup for source-specific licensing and cache-building commands.

Build the cache¶

# Build the open sources used by the v1 PPG goldens.
uv run python scripts/build_ppg_cache.py \
    --sources bidmc butppg ppg_dalia wesad

Training¶

# Reproduce a specific published operating point.
uv run compressionkit golden run ppg-rvq-8x

# Reproduce all PPG RVQ goldens.
uv run compressionkit golden run-all --modality ppg --method rvq

Output Structure¶

results/ppg_rvq_64hz_08x_golden/
├── best_model.weights.h5       # Best checkpoint
├── config.json                 # Frozen config
├── summary.json                # Training metrics
├── long_recording_eval.json    # HR/HRV preservation metrics
├── training_history_*.csv      # Epoch-by-epoch metrics
├── tensorboard/                # TensorBoard logs
├── plots/                      # Reconstruction plots
└── deploy/                     # Deployment artifacts
    ├── encoder.tflite          # INT8 quantized encoder
    ├── encoder.h               # C header for encoder
    ├── encoder.keras           # Keras encoder model
    ├── decoder.keras           # Keras decoder model
    ├── decoder_float32.tflite  # Float32 LiteRT decoder for host-side decode
    ├── decoder.tflite          # Optional INT8 decoder for on-device decode
    ├── decoder.h               # Optional C header for INT8 decoder
    ├── codebook.npz            # RVQ codebook weights
    ├── codebook.h              # C header for codebook
    ├── sample_data.npz         # 50 validation samples
    ├── model_card.json         # Metadata used for publishing
    └── deploy_manifest.json    # Artifact manifest

Deployment¶

For the full runtime guide, see Deployment Guide.

Runtime Profile¶

• Frame shape: (1, 1, 320, 1) float32
• Sample rate: 64 Hz
• Default HuggingFace repo pattern: Ambiq/compressionkit-ppg-{cr}x-v1.0

Quickstart¶

import numpy as np

from compressionkit.runtime import RVQCodec

t = np.arange(320, dtype=np.float32) / 64.0
signal = (0.6 * np.sin(2.0 * np.pi * 1.2 * t) + 0.1 * np.sin(2.0 * np.pi * 2.4 * t)).reshape(1, 1, 320, 1)

codec = RVQCodec.from_pretrained("Ambiq/compressionkit-ppg-4x-v1.0")
indices = codec.encode(signal.astype(np.float32))
reconstruction = codec.decode(indices)

Deployment Notes¶

• Use encoder.tflite plus codebook.h for the lowest-footprint embedded path.
• Use decoder_float32.tflite when reconstruction runs on a host or cloud service.
• Add the two-stage prior only when bitrate is more constrained than compute or memory.

Extending¶

To create a new PPG model variant:

1. Copy an existing golden config: cp configs/ppg_rvq_64hz_08x_golden.yaml configs/ppg_rvq_64hz_08x_v2.yaml
2. Modify parameters (e.g. base_filters, num_levels, learning_rate)
3. Train: uv run train-ppg-rvq --config configs/ppg_rvq_64hz_08x_v2.yaml
4. Compare results against the golden baseline