Reading the output
The examples on this page come from a synthetic subject with 70 days of a current diet and two weight-only past diets. It is not the walkthrough’s 120-day subject, and the numbers are illustrative, not anyone’s.
The plan
Plan (deadline mode, 155 day horizon)
date kcal pro carb fat pro% carb% fat% pred lb lb/wk loss%/wk
2026-10-28 2164 149 64 146 27 12 61 204.5 2.02 0.63
2026-10-29 2164 149 64 146 27 12 61 204.2 1.89 0.64
...
... 141 more days
Forecast assumes 0 kcal/day of exercise, steps +0/day from your usual, and sodium +0 mg/day from habitual (recent averages).
plan written to plan.csv
all safety constraints satisfied
Today: 2164 kcal | 149 g protein (27%) | 64 g carb (12%) | 146 g fat (61%)
Only today's line is a prescription. The rest is what the model currently
expects, and it will change as more weigh-ins arrive.
| Column | Meaning |
|---|---|
kcal, pro, carb, fat |
Prescribed energy and grams of protein, carbohydrate, fat for that day. Constant within each decision block (7 days by default). |
pro%, carb%, fat% |
Each macronutrient’s share of energy |
pred lb |
Predicted morning scale weight, water included |
lb/wk |
Predicted rate of scale-weight loss, water included |
loss%/wk |
Predicted rate of loss of settled tissue, as a percentage per week: the quantity max_loss_frac_per_week limits |
The Today: line is the prescription. Every other row is what the model currently expects, and tomorrow’s run replaces it: plan weeks ahead, eat one day, re-estimate, replan. The plan starts this morning while the last row is dated today, however much food it holds, so a rerun gives the same prescription for the same data (the full rule).
lb/wk and loss%/wk disagree, especially early, because scale weight includes water and gut content that move fast; in the first days of a diet the scale can drop several pounds a week with tissue loss well inside the limit.
The Forecast assumes line. The plan prescribes food only, so its forecast holds everything else at what you have been doing: your average exercise, step count and sodium over the last 14 logged days, steps as the difference from the episode’s average and sodium as the difference from your habitual intake. If you stop training or eat much more salt from tomorrow, the pred lb column is off accordingly, and the prescription adjusts once the weigh-ins show it. (This synthetic subject logs no exercise, steps or sodium, so all three are zero.)
pro is the same every day: protein is fixed at protein_g_per_kg (1.6 g per kg of the plan’s starting weight by default), not chosen by the optimizer (why).
What can appear below the plan:
| Message | Meaning |
|---|---|
all safety constraints satisfied |
An independent check of the finished plan (not the optimizer’s own word) found every limit in [safety] met. |
CONSTRAINT VIOLATIONS (do not follow this plan) |
That check failed; the list says which limit on which day. Do not eat this plan. Loosen nothing in a hurry: rerun, and if it persists, report it. |
NOTE: target of 170 lb by 2026-12-01 is not reachable within your 1%/week limit; the earliest achievable date at that maximum rate is 2027-03-07 |
The deadline is too aggressive for your rate limit. The plan still respects the limit (it goes as fast as allowed); move the date in subject.toml, or use sustainable mode. |
NOTE: target of 170 lb by 2027-03-07 is not reachable at your 1500 kcal/day floor; the model's forecast at the floor reaches it on 2027-05-20 |
The rate limit allows the date, but your expenditure is too low for eating at the calorie floor every day to get there in time. The date given is the model’s forecast at the floor, with the plan’s protein and fat share and your recent exercise and sodium. Move the date; do not lower the floor without a doctor or dietitian. |
Refusing to plan: the most recent state estimate is from ... days ago |
The current episode’s last weigh-in is more than three days old. Weigh in and log it. |
goal date ... has already passed |
Set a new target_date. |
In deadline mode the controller aims at the goal by its date, within the limits. In sustainable mode there is no date: it loses at a safe steady rate over a 28-day window and reports the timeline that results; without a real date in mind, it is the more honest choice. In maintain mode expect intake near the weight-stable level, a flat pred lb column, and no NOTE.
Phase 1: the scale’s noise
wdm fit-noise (and the top of wdm filter):
Phase 1 -- noise identification
episodes used 3
weigh-ins used 114
log-likelihood -106.32
observation sd 0.492 kg (1.09 lb) x/1.09
level innovation sd 0.09789 kg/day x/2.03
slope innovation sd 0.00182 kg/day^2 unidentified
steady-state gain 0.195
effective window 5.1 days
- Observation sd is how far a single morning reading scatters around your true weight: mostly fluid, not the instrument.
x/1.09is the multiplicative uncertainty (a factor of 1.09 either way). Well above 0.6 kg usually means inconsistent weighing; fix that before anything else. - Level and slope innovation sd are how much the underlying trend and its rate wander from day to day.
unidentifiedmeans the data cannot pin that scale down; it is reported, not hidden, and does no harm. - Steady-state gain is how much of each new reading’s surprise moves the trend; the effective window is its reciprocal, roughly how many days of readings the trend averages over. A short window means the trend follows readings closely; a long one, that they are averaged heavily.
Phase 1 uses weight alone, from every episode, food log or not (Estimation).
Phase 2: parameters and state
wdm filter:
Phase 2 -- posterior parameter estimates
parameter median 90% interval shift
rmr_intercept 1338.6 [1071, 1671] +2.7%
rmr_slope 15.33 [12.13, 19.35] +5.7%
at_gain 0.13141 [0.04568, 0.3245] -12.4%
at_tau 12.927 [5.66, 29.6] -7.7%
gly_gain 0.0027997 [0.001351, 0.005868] -6.7%
gly_tau 1.5735 [0.8391, 2.952] +4.9%
na_gain 1.1672e-05 [3.629e-06, 3.727e-05] -2.7%
na_tau 0.99015 [0.5074, 1.917] -1.0%
partition_kappa 0.047795 [-0.03371, 0.1321] -4.4%
waist_offset_cm 68.425 [59.21, 77.56] +1.8%
waist_slope_cm_per_kg 1.2473 [0.9729, 1.604] +4.3%
Estimate as of 2026-10-28 (episode 'current')
trend weight 204.9 lb
fat mass 28.2 kg
lean mass 65.1 kg
adaptive thermogenesis -118 kcal/day
maintenance 2765 kcal/day
weight-stable intake 3072 kcal/day
Read the shift column first. It is how far each parameter’s median has moved from its prior. A shift near zero means the data have not spoken about that parameter yet, and its interval is the prior’s. The parameters are defined in the model; the two waist_ rows appear only when the file has waist readings.
Then read the state. Maintenance is the energy you would spend today at your current tissue mass (the filtered estimate, without the water and gut content the trend weight includes, which cost no energy to maintain), and weight-stable intake the logged intake that would hold your weight steady; these combinations are much better determined than the coefficients behind them (why). Fat mass is weakly identified from a scale: read its trend, not its level, and expect its interval to span several kilograms. Adaptive thermogenesis is the expenditure your body has shed in response to the deficit so far.
--figures DIR writes the filter’s figures; Latest figures says how to read each.
The backtest
wdm backtest replays each episode day by day and scores the forecasts of weigh-ins the filter had not yet seen:
Backtest -- forecasts of the scale reading (Gaussian noise)
horizon n bias RMSE persist skill z sd 50% cov 90% cov log score
1 d 58 -0.25 1.12 1.75 +36% 0.65 66% 100% -0.877
7 d 52 -0.46 1.18 2.27 +48% 0.58 65% 100% -0.973
skillfirst: the RMSE improvement over persistence (“the next reading equals the last one”). A model that cannot beat persistence at a week is not earning its complexity.- Calibration next:
z sdnear 1, and coverage near 50% and 90%, mean the stated intervals are honest. Below 1 and above 90% means the intervals are too wide (cautious); the reverse means overconfident. log scoreis the mean log predictive density per reading; higher is better. It is the fair way to compare noise models (--student-t 4against the Gaussian default), because it rewards honest intervals as well as accurate means.
The scores are mildly optimistic and the effective sample is smaller than n (caveats).
By origin date
The pooled bias can hide a model that is wrong in opposite directions at different times. wdm backtest --by-origin adds the same scores for each horizon in 7-day bins of the date the forecast was made from:
Forecast error by origin date (7-day bins; observed minus predicted)
...
7-day forecasts
episode origins n bias RMSE mean z
current 2026-08-03 to 2026-08-09 6 +0.01 0.89 -0.02
current 2026-08-10 to 2026-08-16 4 -0.43 0.63 -0.22
current 2026-08-17 to 2026-08-23 6 -0.18 1.11 -0.09
current 2026-08-24 to 2026-08-30 6 +0.50 0.92 +0.27
current 2026-08-31 to 2026-09-06 6 -1.09 1.39 -0.58
...
Bias is observed minus predicted, in lb: positive means the scale came in heavier than forecast, so the model expected more loss than happened. A sound model has bias scattered around zero, as here (the synthetic subject is simulated from the model itself). A sign that flips from one period to the next points to a structural error rather than noise: too little predicted loss in a diet’s first weeks and too much later is the signature of early water or gut loss booked as tissue, which inflates the maintenance estimate. mean z is the bin’s average standardized error; a bin with only a few forecasts says little on its own.
The plans log
wdm daily (and wdm plan --log-dir DIR) archive every plan as data/plans/<start>.csv, in the same format as plan.csv, and append one row to data/plans/log.csv:
run_at,start,mode,target_weight_lb,target_date,horizon_days,kcal,protein_g,carb_g,fat_g,trend_lb,maintenance_kcal,constraints_ok,wdm_commit,command
2026-10-28T18:04:25,2026-10-28,deadline,185,2027-04-01,155,2164,149,64,146,204.9,2765,yes,bb15534,wdm daily
| Field | Meaning |
|---|---|
run_at |
When the plan was made |
start |
The plan’s first day; the prescription below is for this day |
mode, target_weight_lb, target_date, horizon_days |
What it aimed at (the target is blank in sustainable mode) |
kcal, protein_g, carb_g, fat_g |
The day’s prescription |
trend_lb, maintenance_kcal |
The estimate it was based on |
constraints_ok |
Whether the independent check passed |
wdm_commit |
The package’s git commit, with +dirty if it had uncommitted changes |
command |
The exact command line |
A replan on the same day overwrites that day’s archived plan but adds a log row, so every prescription ever issued is kept. plan.csv holds only the latest; the log can reproduce a past decision. wdm log reads today’s prescription from it, and wdm plots draws it against what was eaten in the adherence figure.
What to expect, and when
| Elapsed | What becomes available |
|---|---|
| Week 1 | Nothing reliable. The trend exists but is dominated by its prior. |
| Weeks 2 to 3 | A usable trend and rate of loss. This alone is worth the trouble. |
| Weeks 4 to 6 | Maintenance separates from its prior. The prescriptions become worth acting on rather than merely looking at. |
| Months 2 to 3 | The glycogen parameters are well identified; the water/tissue split becomes informative about individual days. |
| Month 4 and on | The adaptation parameters begin to move, if intake varied enough to produce a transient. If not, they stay at their priors. |
In week 1 the filter reports its prior back, slightly perturbed, in output that looks as authoritative as it ever will. Shifts near zero mean the data have not spoken yet.
After four months of consistent data, expect a trend much better than the raw scale, a maintenance figure good to perhaps 5 to 8% with an honest interval, a usable tissue/water split, and prescriptions grounded in your own data. Do not expect a reliable body-composition measurement, an adaptation estimate unless you varied intake, or any insight into whether you will follow the plan, which is, empirically, what decides the outcome.
Improving your estimates
Roughly in order of value per unit of effort:
- Weigh under identical conditions, every morning. The noise is fluid variation, not instrument error, so this habit is worth more than a better scale.
- Weigh daily. Gaps cost precision.
- Log macronutrients, not just calories. This unlocks the glycogen compartment and the thermic effect of food.
- Log with constant rigor, not increasing rigor: a drifting log bias looks like metabolic adaptation. Note any change of method in
notes. - Track sodium if your tracker reports it.
- Estimate what you cannot measure rather than leaving it blank.
- Set your habitual intake in
subject.tomlif you know it. - Measure your waist weekly.
- Log
exercise_kcalon training days (Exercise energy). - Vary intake deliberately. A diet break or refeed week creates the transient that makes adaptation identifiable: for once the experimentally optimal action is the pleasant one.
Leave a reading that looks wrong in the file, with a note; the outlier gate downweights it. A reading you know is off for a reason the model cannot see, such as a diet’s first morning after a large pre-diet meal, can be set aside with exclude_weight (Missing data and outliers).
Troubleshooting
| Symptom | Likely cause and response |
|---|---|
| Parameters barely move off their priors | Not enough data yet, or intake too constant to be informative. Expected before weeks 4 to 6. |
| Innovation sd well above 1 | Noise understated. Check for inconsistent weighing or a stretch of erratic logging. |
| Weekly pattern in the innovations | Weekend eating the log misses. Log weekends more carefully rather than changing the model. |
| Maintenance implausibly low | A drifting log bias, or real adaptation. The data cannot tell these apart; treat the estimate cautiously. |
| The plan sits on the rate limit or the calorie floor every day | The deadline is aggressive for your limits. Look for the NOTE, or use sustainable mode. |
--by-origin bias changes sign between periods |
A structural error that the pooled bias hides, not noise (By origin date). |
| Fat-mass interval enormous | Expected. Read the trend, not the level. |
wdm fit-noise refuses: too few weigh-ins |
Correct. Three noise scales cannot be identified from a handful of points. |
| Warning or refusal: the state is days old | The latest episode’s last weigh-in is more than three days old. Weigh in (wdm daily). |
wdm daily refuses to write a value |
The cell already holds a different value. If the old one is wrong, wdm log --date ... --set replaces it. |
wdm log says no plan is logged for today |
Run wdm daily first. |
wdm daily asks for yesterday’s food when you did eat |
Yesterday’s row has neither kcal nor a full macro split. Answer, or fill it in by hand. A day of zeros is read as a fast, not as unknown. |