$$ % Define your custom commands here \newcommand{\bmat}[1]{\begin{bmatrix}#1\end{bmatrix}} \newcommand{\E}{\mathbb{E}} \newcommand{\P}{\mathbb{P}} \newcommand{\S}{\mathbb{S}} \newcommand{\R}{\mathbb{R}} \newcommand{\S}{\mathbb{S}} \newcommand{\norm}[2]{\|{#1}\|_{{}_{#2}}} \newcommand{\pd}[2]{\frac{\partial #1}{\partial #2}} \newcommand{\pdd}[2]{\frac{\partial^2 #1}{\partial #2^2}} \newcommand{\vectornorm}[1]{\left|\left|#1\right|\right|} \newcommand{\abs}[1]{\left|{#1}\right|} \newcommand{\mbf}[1]{\mathbf{#1}} \newcommand{\mc}[1]{\mathcal{#1}} \newcommand{\bm}[1]{\boldsymbol{#1}} \newcommand{\nicefrac}[2]{{}^{#1}\!/_{\!#2}} \newcommand{\argmin}{\operatorname*{arg\,min}} \newcommand{\argmax}{\operatorname*{arg\,max}} \newcommand{\dd}{\operatorname{d}\!} $$

synthetic

synthetic

Synthetic data generation, for testing and for calibrating expectations.

Two distinct uses.

Validation. Parameter recovery on data generated from known parameters is the only way to know whether the estimator works. Real data has no ground truth, so a plausible-looking fit there proves nothing at all.

Power analysis. Before you spend four months logging, it is worth knowing what four months of data can actually resolve. Generating synthetic episodes of varying length and logging quality, then looking at how wide the posteriors come out, answers that honestly – and the answer for some parameters is “not much”. Better to learn that from a simulation than from a spreadsheet in December.

Classes

Name	Description
SyntheticSpec	Configuration for one synthetic episode.

SyntheticSpec

synthetic.SyntheticSpec(
    n_days=120,
    start_weight_kg=100.0,
    body_fat_frac=0.3,
    intake_fraction=0.8,
    intake_sd_kcal=250.0,
    protein_g_per_kg=1.8,
    fat_fraction_of_kcal=0.3,
    carb_weekly_amplitude_g=60.0,
    obs_sd_kg=0.45,
    weigh_in_rate=0.85,
    logging_rate=0.9,
    sodium_mean_mg=3000.0,
    sodium_sd_mg=800.0,
    include_sodium=True,
    habitual_carb_g=None,
    habitual_sodium_mg=None,
    waist_every_days=0,
    waist_offset_cm=75.0,
    waist_slope_cm_per_kg=1.2,
    waist_sd_cm=1.5,
)

Configuration for one synthetic episode.

Functions

Name	Description
demo_subject	The synthetic subject of `wdm demo` and the report’s validation chapter.
make_episode	Simulate one episode and return it alongside the hidden ground truth.
make_weight_only_episode	A past episode with weigh-ins but no food log, mimicking old history.

demo_subject

synthetic.demo_subject(days=120, *, waist_every_days=0)

The synthetic subject of wdm demo and the report’s validation chapter.

A 40-year-old man with parameters offset from the priors on purpose (an estimator that ignored the data would fail), two weight-only past diets of 40 days, and a current diet of days days with full macronutrients (and a waist reading every waist_every_days days, if positive). Returns (cfg, true_params, episodes, truth), where truth is the current episode’s hidden trajectory.

make_episode

synthetic.make_episode(
    spec,
    true_params,
    *,
    name='synthetic',
    start_date='2026-01-01',
    seed=0,
    noise=None,
)

Simulate one episode and return it alongside the hidden ground truth.

The simulation runs the same dynamics the estimator uses, which makes this a test of the estimator rather than of the model. That is the correct scope: whether the model resembles human physiology is a question for the literature and for residual diagnostics on real data, not for a self-test.

Returns

Name	Type	Description
	episode	An `~wdm.io.Episode` as if loaded from a CSV.
	truth	Dict of the hidden trajectories: `tissue_kg`, `fat_kg`, `gly_water_kg`, `na_water_kg`, `adapt_kcal`, and the noise-free `scale_kg`.

make_weight_only_episode

synthetic.make_weight_only_episode(spec, true_params, *, name, start_date, seed)

A past episode with weigh-ins but no food log, mimicking old history.