Skip to main content
$$ % 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}\!} $$

viz

viz

Diagnostic figures.

Design rules followed throughout, and worth stating because they are choices rather than defaults:

No dual-axis plots. Where two quantities of different scale must be shown over the same period – prescribed intake and predicted weight, say – they get stacked panels sharing an x-axis, never two y-scales on one frame. A dual axis lets the author place the crossing point anywhere, which makes the visual claim arbitrary.

Direct labels on every series. Color alone never carries identity. This matters for color-vision deficiency generally, and specifically because the aqua series sits below a 3:1 contrast ratio against the surface, so it must be labeled to be legible at all.

Recessive chrome. Gridlines and axes are hairlines in muted ink; the data is the only thing with weight.

Uncertainty is drawn, not implied. Every state estimate is a posterior with a credible band, and plotting the mean alone would misrepresent how much is actually known – particularly for fat mass, whose band is wide enough to be the main thing worth seeing.

Functions

Name Description
adherence Prescribed and eaten, day by day, for every finished day that had a plan.
mdates_num A plotted x value (date or number) in matplotlib’s internal units.
plot_adherence How closely the plan was followed: each day against its prescription, and the drift.
plot_attempts Every diet attempt’s weigh-ins, aligned on its first one.
plot_composition Fat and lean mass over time, with bands.
plot_health Morning glucose, ketones, resting heart rate and blood pressure, as logged.
plot_innovations Standardized one-step-ahead residuals, over time and as a histogram.
plot_intake_log Logged exercise, fiber, sodium, and steps.
plot_maintenance The maintenance estimate as it evolved, against what was eaten.
plot_parameter_evolution What the filter believed about each parameter, day by day.
plot_parameters Posterior medians and 90 % intervals, normalized to the prior center.
plot_plan Prescribed intake and predicted weight, as stacked panels.
plot_trajectory Raw weigh-ins, the smoothed trend, and its credible band.

adherence

viz.adherence(log_rows, episode, *, today=None)

Prescribed and eaten, day by day, for every finished day that had a plan.

A day’s prescription is the last plan logged with that start date, the one wdm log compares against. Only days before today (default: the calendar’s) count: a day still being logged would read as undereating. Eaten energy is the logged label total, as the plan prescribes it, so the fiber correction the model applies (wdm.io) is added back.

Returns (dates, prescribed, eaten): the dates, and for each column in ADHERENCE_ITEMS an array over them, NaN where not logged.

mdates_num

viz.mdates_num(x)

A plotted x value (date or number) in matplotlib’s internal units.

plot_adherence

viz.plot_adherence(log_rows, episode, *, today=None, path=None)

How closely the plan was followed: each day against its prescription, and the drift.

Four small panels, one per prescribed quantity (energy and the three macronutrients), each in its own units: the prescription as a step line with the band counted as on plan shaded around it, and each finished day’s intake as a dot; only the latest values are labeled, so the panels stay readable however many days accumulate. Their titles count the days inside the band. They are separate panels rather than four series on one, which this palette cannot keep apart. Below, the running total of energy eaten above or below plan: the part of the deficit that went missing, or was overdone, which is what moves the weight.

plot_attempts

viz.plot_attempts(episodes, *, path=None)

Every diet attempt’s weigh-ins, aligned on its first one.

Each attempt is drawn as change since its first weigh-in against days since it, so attempts that started at different weights and dates line up. The latest attempt is the one series in color; the earlier ones are gray, each labeled with the month it began, since there may be more of them than the palette has colors. Raw readings joined day to day, not filtered trends: the weight-only attempts have no food log for the filter to explain them with.

plot_composition

viz.plot_composition(fit_episode, *, path=None)

Fat and lean mass over time, with bands.

Worth reading with the bands rather than the lines. Fat mass is only weakly identified from scale data – it enters the dynamics solely through the effective energy density – so its interval is wide, and a narrow reading of the mean would be overclaiming.

plot_health

viz.plot_health(dates, readings, *, path=None)

Morning glucose, ketones, resting heart rate and blood pressure, as logged.

readings maps wdm.schema.HEALTH_COLUMNS names to arrays on dates; a column not given, or never logged, leaves its panel marked as such. The model uses none of these, so there is no estimate to draw: as in plot_intake_log, unlogged days are gaps.

plot_innovations

viz.plot_innovations(fit_episode, *, path=None)

Standardized one-step-ahead residuals, over time and as a histogram.

The primary check that the model is adequate. If it is, these are white noise with unit variance. Structure in the left panel means the dynamics are missing something; a histogram wider than the reference curve means the noise model is understated, which shows up downstream as overconfident intervals.

plot_intake_log

viz.plot_intake_log(episode, *, steps=None, path=None)

Logged exercise, fiber, sodium, and steps.

Energy and macronutrients are left to the adherence and maintenance figures. Like them, this plots inputs rather than filtered state – there is no estimation to distrust, only gaps to be honest about. Days without a food log are left as gaps rather than the reference values the model substitutes internally (~wdm.io.Episode fills unknown sodium with the reference intake, habitual eating, so the water states have something to condition on); plotting those fill values here would make logging coverage look better than it is. Exercise is the one series where zero is the honest default for an unlogged day, per Episode’s own convention, so it is drawn as bars that are simply absent on rest days. Steps – not part of the model at all – are passed in separately from the raw CSV.

plot_maintenance

viz.plot_maintenance(
    fit,
    fit_episode,
    episode,
    *,
    path=None,
    n_samples=2000,
    seed=0,
)

The maintenance estimate as it evolved, against what was eaten.

Maintenance here is the non-adaptive expenditure at each day’s trend weight, c0 + c1 W, under that day’s filtered belief about the two coefficients. The band comes from sampling their joint filtered distribution: the two are strongly correlated, so their sum is far better known than either, and adding marginal variances would overstate the band. The logged intake on the same axis makes the deficit visible directly; both are kcal/day, so one axis is honest.

plot_parameter_evolution

viz.plot_parameter_evolution(fit, fit_episode, *, path=None)

What the filter believed about each parameter, day by day.

The filtered (not smoothed) estimate: each day shows only what the record up to that morning implied, so the panels replay how the evidence accumulated. Values are relative to the prior center, as in plot_parameters; a band that stays as wide as it started has learned nothing, whatever its median does. Small multiples rather than one crowded frame, since the parameters share no scale and need no comparison by color. The waist offset and slope follow the nine metabolic parameters when the record has waist readings; before the first one their bands are the prior.

plot_parameters

viz.plot_parameters(fit, *, path=None)

Posterior medians and 90 % intervals, normalized to the prior center.

Normalizing is what makes the figure readable: the parameters span nine orders of magnitude in natural units, and the interesting question is not their absolute values but whether the data moved them off the prior at all. Each posterior is drawn over its prior’s 90 % interval (the pale bar), so a parameter has learned something only where the dark interval is visibly shorter than the pale one or sits off-center in it. The waist calibration is included when the record has waist readings.

plot_plan

viz.plot_plan(plan, *, fit_episode=None, episode=None, max_days=28, path=None)

Prescribed intake and predicted weight, as stacked panels.

Two panels rather than two y-axes. Intake is in kilocalories and weight in pounds; overlaying them on a shared frame would require choosing where the two scales cross, and that choice would silently determine which of the two “leads” the other.

max_days caps how much of the plan is drawn, independent of how long a horizon it was actually solved over. Deadline-mode plans can span months; plotting all of it would swamp the readable near-term detail with a long, increasingly speculative tail, when only the first stretch is close to being acted on. None plots the whole thing.

The weight panel is future-only – just the optimizer’s horizon – unless fit_episode is given, in which case the filtered scale/tissue trend leading up to today is drawn in the same two series, distinguished from the plan only by a lower alpha and a “today” marker. Without that context a plan reads as an isolated, disconnected forecast; with it, the plan reads as a continuation of where you actually are. episode adds the raw weigh-ins the trend was fitted to, when available.

plot_trajectory

viz.plot_trajectory(
    fit_episode,
    episode,
    *,
    path=None,
    title='Weight trajectory',
)

Raw weigh-ins, the smoothed trend, and its credible band.

The single most useful figure here. The raw points scatter by a pound or more day to day; the trend line is what actually moved. Seeing both together is the whole argument for filtering.