# TimePPG (PPG heart-rate regression)

`helia_edge.models.timeppg.build` builds the TEMPONet-derived TimePPG regressor from
[Q-PPG](https://arxiv.org/abs/2203.14907) (Burrello et al., 2022).
`TimePPGParams` holds the backend-free config. The presets
`timeppg_big`, `timeppg_medium` and `timeppg_small` use the channel widths in
upstream `precision_search/model/TimePPG_float.py` at `eml-eda/q-ppg@ddf3866d`.

```python
from helia_edge.models import TIMEPPG_PRESETS, ModelSpec, build

model = build(ModelSpec(params=TIMEPPG_PRESETS["timeppg_medium"], input_shape=(256, 4)))
```

**Input:** a channels-last window. The reference uses 256 samples: blood
volume pulse decimated from 64 Hz to 32 Hz, plus three accelerometer axes
(PPG-DaLiA, 8 s windows with a 2 s hop). Normalization and channel order belong
to the caller.

**Architecture:** three stages. Each stage has two dilated temporal blocks
followed by one strided convolution block, then two dense regressor layers and a
single linear output. Upstream order is kept exactly:

| Block | Layers | Parameters |
|---|---|---|
| Temporal | Conv1D, then BatchNorm, then ReLU6 | kernel 3, dilations 2/2, 4/4, 8/8, same padding, no bias |
| Strided convolution | Conv1D, then AveragePooling 2, then BatchNorm, then ReLU6 | kernel 5, strides 1/2/4, explicit padding 2/2/4, no bias; a 256-sample window reaches 128, 32 and 4 steps |
| Regressor | Dense without bias, then BatchNorm, then ReLU6 | two layers |

- Features are flattened channel-major, matching the upstream PyTorch layout.
- BatchNorm uses PyTorch's defaults (epsilon 1e-5, momentum 0.1). During
  training, Keras updates the running variance with the biased batch variance
  where PyTorch uses the unbiased one, so running statistics drift slightly
  apart; inference is unaffected.
- Trainable parameter counts equal the upstream definition. For example,
  `timeppg_medium` has 40,542 parameters and about 3.9M MACs per window.

## Weights and terms

Upstream publishes no trained checkpoints. These constructors produce
untrained models, suited to performance measurement only; no heart-rate
accuracy is implied. The upstream code is Apache-2.0, and its notice is
retained in `helia_edge/models/licenses/timeppg-apache-2.0.txt`. PPG-DaLiA is
CC BY 4.0.