2. Synthetic data
A record with a known answer: 120 days of morning weigh-ins, food logs and weekly waist readings, generated from a metabolism that is deliberately not the prior. Steps 3 to 8 all use this episode, rebuilt from the same seed, and score themselves against its hidden truth.
uv run python walkthrough/02_synthetic.pyThe script
"""Step 2: synthetic data with a known truth.
Generate 120 days of the record the subject would keep: a morning weigh-in on
most days, a food log on most days, and a tape-measure waist reading once a
week. The generator runs the same model as step 1, with parameters deliberately
away from the prior, and keeps the hidden states so later steps can be scored.
"""
import jax.numpy as jnp
import numpy as np
from wdm.config import Subject
from wdm.models import Params
from wdm.synthetic import SyntheticSpec, make_episode
subj = Subject(sex="male", age_years=40, height_cm=175.0, body_fat_frac=0.30)
c0, c1 = subj.expenditure_prior(100.0)
prior = Params.prior(c0, c1)
# The "true" metabolism: offset from the prior, so recovering it is a real test.
true = Params(
rmr_intercept=jnp.asarray(c0 * 1.18),
rmr_slope=jnp.asarray(c1 * 0.90),
at_gain=jnp.asarray(0.22),
at_tau=jnp.asarray(11.0),
gly_gain=jnp.asarray(0.0042),
gly_tau=jnp.asarray(2.0),
na_gain=jnp.asarray(2.5e-4),
na_tau=jnp.asarray(1.0),
partition_kappa=jnp.asarray(0.06),
)
carb_ref, sodium_ref = subj.habitual_intake()
spec = SyntheticSpec(
n_days=120,
start_weight_kg=100.0,
body_fat_frac=0.30,
intake_fraction=0.80, # eat 80 % of true initial maintenance, +-250 kcal/day
obs_sd_kg=0.45,
weigh_in_rate=0.85,
logging_rate=0.90,
waist_every_days=7, # waist = 75 cm + 1.2 cm/kg x fat, read to +-1.5 cm
habitual_carb_g=carb_ref,
habitual_sodium_mg=sodium_ref,
)
ep, truth = make_episode(spec, true, name="current", start_date="2026-06-01", seed=7)
print(ep.summary())
print(f"reference intake: {ep.carb_ref_g:.0f} g carb, {ep.sodium_ref_mg:.0f} mg sodium (habitual)")
print()
print("true parameters vs the prior center")
for name in ("rmr_intercept", "rmr_slope", "at_gain", "at_tau", "gly_gain", "partition_kappa"):
t, p = float(getattr(true, name)), float(getattr(prior, name))
print(f" {name:16s} {t:10.4g} prior {p:10.4g} ({t / p - 1:+.0%})")
print()
print("first ten days ('-' = not recorded)")
print(" date reading truth kcal pro carb fat sodium waist")
for k in range(10):
w = f"{ep.weight_kg[k]:7.2f}" if ep.weight_observed[k] else " -"
food = (
(
f"{ep.energy_kcal[k]:5.0f} {ep.protein_g[k]:5.0f} {ep.carb_g[k]:5.0f}"
f" {ep.fat_g[k]:4.0f} {ep.sodium_mg[k]:7.0f}"
)
if ep.intake_known[k]
else " - - - - -"
)
waist = f"{ep.waist_cm[k]:6.1f}" if np.isfinite(ep.waist_cm[k]) else " -"
print(f" {ep.dates[k]} {w} {truth['scale_kg'][k]:6.2f} {food} {waist}")
print()
resid = ep.weight_kg[ep.weight_observed] - truth["scale_kg"][ep.weight_observed]
logged = ep.intake_known
print(
f"weigh-ins {ep.n_observations}/{ep.n_days}, food logs {logged.sum()}/{ep.n_days},"
f" waist readings {ep.n_waist}"
)
print(
f"reading minus truth: mean {resid.mean():+.3f} kg, sd {resid.std(ddof=1):.3f} kg"
f" (set to {spec.obs_sd_kg})"
)
print(
f"logged intake: mean {np.nanmean(ep.energy_kcal):.0f} kcal/day,"
f" carb {ep.carb_g[logged].mean():.0f} g/day"
)
print()
print("hidden truth, day 0 -> day 119")
for key in ("scale_kg", "tissue_kg", "fat_kg", "gly_water_kg", "na_water_kg", "adapt_kcal"):
a, b = truth[key][0], truth[key][-1]
print(f" {key:13s} {a:8.2f} -> {b:8.2f} ({b - a:+.2f})")current 2026-06-01 to 2026-09-28 120 d weigh-ins 107 ( 89.2%) intake 106 ( 88.3%) macros yes
reference intake: 260 g carb, 4000 mg sodium (habitual)
true parameters vs the prior center
rmr_intercept 1538 prior 1303 (+18%)
rmr_slope 13.05 prior 14.5 (-10%)
at_gain 0.22 prior 0.15 (+47%)
at_tau 11 prior 14 (-21%)
gly_gain 0.0042 prior 0.003 (+40%)
partition_kappa 0.06 prior 0.05 (+20%)
first ten days ('-' = not recorded)
date reading truth kcal pro carb fat sodium waist
2026-06-01 - 100.00 - - - - - 110.3
2026-06-02 99.50 99.51 2537 180 278 78 2527 -
2026-06-03 99.43 99.36 2440 180 264 74 2905 -
2026-06-04 99.39 99.37 2156 180 205 68 1402 -
2026-06-05 99.15 98.30 2056 180 172 72 2095 -
2026-06-06 97.13 97.60 1792 180 116 68 3290 -
2026-06-07 96.32 97.02 2102 180 174 76 1297 -
2026-06-08 96.48 96.94 2609 180 277 87 3677 108.2
2026-06-09 96.90 97.50 2339 180 243 72 1603 -
2026-06-10 97.79 97.46 - - - - - -
weigh-ins 107/120, food logs 106/120, waist readings 18
reading minus truth: mean -0.091 kg, sd 0.410 kg (set to 0.45)
logged intake: mean 2233 kcal/day, carb 211 g/day
hidden truth, day 0 -> day 119
scale_kg 100.00 -> 87.57 (-12.43)
tissue_kg 98.10 -> 87.49 (-10.62)
fat_kg 29.43 -> 22.02 (-7.41)
gly_water_kg 0.00 -> -0.73 (-0.73)
na_water_kg 0.00 -> -0.51 (-0.51)
adapt_kcal 0.00 -> -158.27 (-158.27)
What to notice
- Missing days. 107 of 120 mornings have a weigh-in and 106 days a food log, against set rates of 85 % and 90 %, drawn independently: 2026-06-10 has a weigh-in but no food log, 2026-06-01 neither. A missing value is a missing observation, not a missing row.
- The truth is off the prior. The maintenance intercept is 18 % above the prior and the mass slope 10 % below; adaptation is 47 % stronger and 21 % faster; glycogen holds 40 % more water per gram; the sodium gain (not printed; step 4 scores it) is 25 % above its prior. If the truth sat at the prior, an estimator that ignored the data would look perfect.
- Readings scatter around the truth. On 2026-06-05 the scale reads 99.15 kg against a truth of 98.30 kg, +0.85 kg (1.9 standard deviations). Over all 107 readings the error has mean −0.091 kg and standard deviation 0.410 kg, a sample from the 0.45 kg set.
- The food log. Protein is 180 g every day, fat 30 % of energy, and carbohydrate the rest plus a weekly ±60 g cycle (278 g on 06-02, 116 g on 06-06) that exercises the glycogen compartment. Logged energy averages 2233 kcal/day, near the target of 80 % of true day-0 maintenance, 0.80 × (1538 + 13.05 × 100) = 2274.
- Sodium moves the truth from day to day. The 1402 mg on 2026-06-04, with 205 g of carbohydrate (which counts as 4000 × 55/260 = 846 mg less sodium), pulls sodium water toward 2.5·10⁻⁴ × (1402 − 4000 − 846) = −0.86 kg. With a 1-day time constant 63 % of the gap closes by the next morning, so sodium water falls 0.38 kg; with 0.51 kg of glycogen water, the truth on 06-05 is 1.07 kg below the day before. Step 3 shows what this does to the scale’s apparent noise.
- Both water compartments sit below zero, because carbohydrate averages 211 g against a habitual 260 g and sodium is drawn around 3000 mg against 4000 mg. Sodium water averages −0.44 kg over days 30 to 119, which is 2.5·10⁻⁴ × (3000 − 4000 − 4000 × 49/260): the carbohydrate cut counts as less sodium too. On day 119 it is −0.51 kg.
- The tape. 18 weekly readings. Day 0’s 110.3 cm matches 75 + 1.2 × 29.43 = 110.3 cm plus a 1.5 cm reading error.
- The hidden truth. The 100 kg start holds 1.90 kg of gut content, the level of pre-diet eating, so tissue starts at 98.10 kg and fat at 30 % of it. Over 120 days the scale falls 12.43 kg, tissue 10.62 kg and fat 7.41 kg (70 % of tissue); gut content falls to 1.32 kg (not printed: the scale minus the other compartments), and adaptation ends at −158 kcal/day. Steps 4 and 5 try to recover these.
The code
| What | Where (under wdm) |
|---|---|
| The episode’s settings and the generator | synthetic: SyntheticSpec, make_episode |
| Process noise scales | models.dynamics.NoiseModel |
| The episode container and its summary line | io.Episode |
| Past episodes with weigh-ins only (step 3) | synthetic.make_weight_only_episode |
How the data are generated
- The data come from the estimator’s own model, so this tests the estimator, not the model; whether the model describes a person is the backtest’s question (step 6).
- The food log is exact when present. A real log’s bias lands in
rmr_intercept(Limitations). - Reading noise is Gaussian, 0.45 kg, with no gross errors, so the filter’s outlier gate is not exercised.
- Process noise only on tissue (0.08 kg/day) and glycogen water (0.15 kg/day); gut content follows intake exactly, although the filter allows it 0.10 kg/day.
- Sodium is drawn independently each day, 3000 ± 800 mg, and logged exactly; this day-to-day variation is what lets phase 2 see the sodium gain.
- Weigh-ins and logs are missing at random. Real missing days are not: unlogged days tend to be high-intake days.
- Waist is linear in fat mass, 75 cm + 1.2 cm/kg, read to ±1.5 cm: the form the filter assumes (The waist).
Try this
- Lower
logging_rateto 0.5 and rerun steps 2 and 4. On unlogged days the filter assumes intake equals expenditure and widens its uncertainty (Unlogged days); watch the maintenance interval widen. - Under-log by 10 %: in step 4, fit
dataclasses.replace(ep, energy_kcal=0.9 * ep.energy_kcal)and see how farrmr_interceptand the maintenance estimate move. The fitted maintenance describes the log, not the body. - Change
seed=7to another value. Every later step rebuilds this episode, so all their numbers change; the conclusions should not.