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}\!} $$

The observations file

data/raw/observations.csv holds one row per calendar day, per episode. Every column except date and episode may be left blank: the filter is built for missing data. wdm daily and wdm log write to it for you; you can also edit it by hand at any time.

Templates: data/templates/observations_template.csv (blank) and observations_example.csv (filled in).

date,episode,weight_lb,kcal,protein_g,carb_g,fat_g,fiber_g,alcohol_g,sodium_mg,exercise_kcal,steps,waist_in,notes
2026-10-27,current,207.9,2456,180,242,85,,,2781,310,8400,,
2026-10-28,current,203.6,520,38,41,22,,,,,,38.2,salty dinner the night before

Row k is day k: the weigh-in on its morning and everything eaten during it. Today’s row starts with the weight and fills in as you eat.

Columns

Column Units Range accepted Meaning
date YYYY-MM-DD Calendar date. Required. Unique within an episode.
episode text One continuous diet attempt. Required.
weight_lb lb 50 to 800 Morning scale weight. Blank on days you did not weigh in. (weight_kg, 25 to 360, also accepted.)
kcal kcal/day 0 to 12,000 Total energy eaten.
protein_g g/day 0 to 700 Protein.
carb_g g/day 0 to 2,000 Carbohydrate, total (including fiber), not net.
fat_g g/day 0 to 700 Fat.
fiber_g g/day 0 to 300 Dietary fiber; slightly reduces metabolizable energy.
alcohol_g g/day 0 to 500 Alcohol, 7 kcal/g; often left out of logs.
sodium_mg mg/day 0 to 30,000 Sodium; a major driver of day-to-day water weight.
exercise_kcal kcal/day 0 to 8,000 Deliberate exercise energy above baseline. Blank counts as 0.
steps count 0 to 150,000 Step count. Steps above or below the episode’s average add or remove walking energy (below).
waist_in in 15 to 90 Waist at the navel. (waist_cm, 38 to 230, also accepted.)
glucose_mg_dl mg/dL 20 to 600 Fasting blood glucose. A health reading.
ketones_mmol_l mmol/L 0 to 10 Blood ketones (beta-hydroxybutyrate). A health reading.
resting_hr_bpm bpm 25 to 200 Resting heart rate. A health reading.
bp_systolic_mmhg, bp_diastolic_mmhg mmHg 60 to 260, 30 to 160 Blood pressure. Health readings; a diastolic at or above the systolic draws a warning.
estimated 1 or blank 0 to 1 1 when the day’s food is an estimate; the filter then treats its energy as uncertain by about a quarter. wdm log --estimate sets it (and adds the column if the file lacks it).
exclude_weight 1 or blank 0 to 1 1 to keep the day’s weigh-in in the file but out of the model; the day’s food still counts. For a reading you know is off (below).
notes text Free text, never parsed. Useful when reviewing outliers.

The ranges catch unit errors and typos (a weight in kg typed into the lb column, a slipped decimal point), not unusual days. A row may give a quantity in one unit only: weight_lb or weight_kg, waist_in or waist_cm. Columns not listed here are ignored with a warning.

Rows and episodes

One row per day, no skipped days. On a day you missed, keep the row and leave its values blank. Explicit gaps let the filter propagate uncertainty through the missing days; an absent row would be treated as if no time had passed. wdm validate warns about calendar gaps within an episode.

An episode is one continuous attempt. Use any short label: past-01, past-02, current. Episodes matter because:

  • each gets its own initial condition: you started each attempt at a different weight, glycogen level, and adaptation state;
  • parameters are pooled across episodes: your maintenance energy and metabolic response are properties of you, so every episode contributes to estimating them, and weight-only history still teaches phase 1 how noisy your scale is;
  • a long stretch with no records between two diets needs no blank rows: start a new episode instead.

Within an episode, dates should be contiguous. Between episodes, gaps are fine. wdm daily and wdm log add new days to the most recent episode, so the first row of a new attempt is entered by hand.

What each column buys

weight_lb

Consistency matters far more than precision. Weigh under the same conditions every time: first thing in the morning, after the bathroom, before eating or drinking, same clothing (ideally none), same scale on the same spot. The day-to-day scatter is fluid, not instrument error, so this habit is worth more than a better scale. A scale that reads 1.5 lb heavy is harmless: the bias is absorbed into the initial condition. A scale used at random times of day injects noise that no filter can remove. If you weighed twice, keep the morning fasted value.

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 without deleting it: put 1 in exclude_weight and say why in notes. The model then treats the morning as one without a weigh-in. Use it rarely, for a known cause, not for a reading you merely dislike; the filter’s outlier gate already handles typing errors. (The first weigh-in of every diet is already treated as uncertain by about 1.5 kg, because pre-diet eating leaves food, glycogen and salt water that drain over the first days.)

The food columns

kcal and the macronutrients are the model’s input. Their quality decides what it can learn:

You log You get
nothing trend estimation only; no maintenance estimate
kcal only maintenance and adaptation estimates, but no glycogen-water correction
kcal and macronutrients the full model: carbohydrate drives the glycogen-water compartment, which explains much of the day-to-day scale noise (and part of the sodium-water one), and the protein/carb/fat split changes the thermic effect of food

A day counts as logged when it has kcal or a full protein/carb/fat split. A day with neither is treated as intake unknown, not as a fast; a real fast is kcal = 0.

Total carbohydrate, not net. Log carb_g as the label’s total carbohydrate, fiber included, and fiber in fiber_g; the model itself takes 2 kcal per gram of fiber off the day’s energy. Net carbs leave the macros short of kcal (which wdm validate flags), and a log that mixes the two moves the predicted glycogen water when nothing changed. Labels that list carbohydrate without fiber (European ones, and many apps’ net-carb view) need the fiber added back. A blank fiber_g reads as zero, overstating energy by about 60 kcal on a 30 g day. To fix days logged as net, wdm log --set --carb TOTAL --date YYYY-MM-DD.

On accuracy. Self-reported intake runs about 20% low on average. A constant bias is harmless; one that drifts as your logging improves looks exactly like metabolic adaptation (Limitations). Log with the same rigor on day 90 as on day 1, and note any change of method in notes.

sodium_mg

Optional but valuable if your tracker reports it. Sodium shifts extracellular water over one to two days and is often a larger source of scale noise than carbohydrate. Supplied, it drives the sodium-water compartment: roughly 0.2 kg of water per 1,000 mg/day of sustained change, and about half a kilogram the morning after a salty restaurant meal, gone in two or three days. Carbohydrate moves the same compartment: eating less of it than usual makes the kidneys excrete more sodium, so the model counts a cut in carbohydrate as a cut in sodium, 4,000 mg/day for removing all of it and in proportion for a partial cut (Hall, 2010; the model). Left blank, the day is taken at your habitual sodium (4,000 mg by default), so estimate rather than leave it blank on days you eat out (When you don’t know exactly).

exercise_kcal and steps

Both optional, and both enter the energy balance; they cover different things. exercise_kcal is workouts: deliberate exercise energy above baseline, added to the day’s expenditure. If you lift, Exercise energy estimates it per session. Treat wearable calorie estimates with suspicion; they are usually noisier than food logs.

steps is everyday walking, counted against your own average: each step above or below the episode’s mean step count adds or removes 0.0005 kcal per kg of body tissue, about 200 kcal/day for a 4,000-step swing at 100 kg. Your usual walking stays inside the estimated maintenance, so only the day-to-day changes are explained by steps. Do not count a walk in both columns: log a dedicated walk either as exercise or through the step count.

Left blank, a day’s exercise counts as 0 and its steps as your average. Steady activity is then absorbed into the estimated maintenance, which is often the more honest choice if your activity is stable.

waist_in

Optional, and the only reading that responds to fat mass directly; weekly is plenty. Protocol and what it buys: The waist tape.

Health readings

Fasting glucose, ketones, resting heart rate, and blood pressure are logged and plotted (wdm plots draws a health figure once any is logged) but never used by the model, so a blank one costs nothing. A file gets each column the first time it has a value. Take them the same way every morning, before exercise, since the trend is what is worth reading; a workout raises or lowers glucose, raises ketones, and leaves blood pressure low for hours. On a morning that has already had a workout, leave them blank:

  • Glucose and ketones: finger-stick, about two hours after waking, at the same time each day, still fasted: before food, coffee, or exercise. Not on waking: before you wake, cortisol and growth hormone make the liver release glucose (the dawn phenomenon), so a reading on waking can run noticeably above one taken a couple of hours later. Two hours on is also closer to a lab’s fasting draw, which comes after at least eight hours without food but rarely right out of bed. wdm daily runs too early for these two: skip them at its prompt and add them with wdm log --glucose MG_DL --ketones MMOL_L.
  • Resting heart rate: the watch’s own daily figure, read in the morning; it is measured asleep or at rest, steadier than a spot reading.
  • Blood pressure: before exercise, seated after five quiet minutes, arm supported at heart level, the same arm each time; the average of two readings a minute apart.

When you don’t know exactly

Estimate. A rough figure on the right day beats a blank, because a blank is not “unknown” to the model in the way you might expect:

Left blank What the model assumes that day
kcal, with no macros either You ate exactly what you spent, give or take 600 kcal: no information about the day’s balance
The macros, with kcal given Carbohydrate at your habitual level (260 g by default), no protein effect on the fat/lean split, a flat thermic effect of food
One or two macros The same as all three: a partial split (protein only, say) is ignored, because the model needs all three
sodium_mg Your habitual sodium (4,000 mg by default): about a restaurant day, which is wrong for a quiet day at home
steps Your average step count for the episode: no walking energy above or below the usual

So at a restaurant or a friend’s, log your best guess at all of it, and mark the day as an estimate:

wdm log --kcal 1100 --protein 45 --carb 90 --fat 62 --sodium 2200 --estimate

--estimate sets the day’s estimated column to 1. The filter then takes the day’s energy as the logged value give or take a quarter of it, so a guessed day teaches it less than a weighed one, but still more than a blank: a blank says “no information”, an estimate says “about this much”.

Calories

Use the posted number when there is one (US chains with 20 or more locations must post calories; many publish full nutrition online). Posted values are close on average, but individual dishes can be off by 100 kcal or more. Otherwise take the closest entry in your food tracker, and count the extras: bread, drinks, dressing, dessert, the cooking oil.

Macronutrients

When the restaurant publishes them, use them. Otherwise estimate in order of what matters to the model:

  1. Carbohydrate first. It drives the glycogen water, the largest day-to-day swing on the scale.
  2. Protein second. It shifts the fat/lean split and costs the most to digest.
  3. Fat by difference, so the three add up to the calories: fat ≈ (kcal − 4 × protein − 4 × carb) / 9. This also keeps wdm validate from flagging the day.
Portion Roughly
Palm-sized piece of cooked meat or fish (about 4 oz) 25 to 35 g protein
Two eggs 12 g protein
A cup of cooked rice or pasta 45 g carbohydrate
A slice of bread or a small roll 15 g carbohydrate
A large flour tortilla 35 g carbohydrate
A medium potato, or a medium order of fries 35 to 45 g carbohydrate
A can of regular soda 40 g carbohydrate
Restaurant dishes generally 40 to 50% of calories from fat (butter, oil, sauces)

Sodium

Meal Sodium, roughly
Sit-down restaurant entrée 1,500 to 2,500 mg, more with bread, soup or appetizers
Fast-food meal 1,000 to 2,000 mg
Soy-sauce dishes, ramen, pho, curries 3,000 mg or more
Pizza 600 to 700 mg per slice
Home cooking at a friend’s 800 to 1,200 mg per plate

What an error costs

  • Calories. A random error averages out over the days around it, and a consistent under-estimate is absorbed into the estimated maintenance. What hurts is a habit that drifts (On accuracy).
  • Carbohydrate. An error of 100 g shifts the predicted glycogen water by up to about 0.3 kg for a day or two: less than one weigh-in’s own noise. Guessing 80 g when it was 130 g is fine; leaving it blank on a 60 g day (and so assuming 260 g) is not.
  • Sodium. It moves only water, and only for a day or two; its error never reaches the tissue estimate.

Missing data and outliers

Situation What to do
Missed a weigh-in Keep the row; leave weight_lb blank
Missed logging food Keep the row; leave the food columns blank
Weighed twice in a day Keep the morning fasted value only
Long gap between diets Start a new episode
A reading looks wrong Keep it and say why in notes; the filter’s outlier gate downweights it
A reading you know is off (a diet’s first morning after a large pre-diet meal) Keep it, set exclude_weight to 1, and say why in notes

Do not delete inconvenient rows or interpolate missing values by hand: both corrupt the noise estimates that everything downstream depends on. Reporting a gap honestly is strictly better than filling it in.

Validation

wdm validate (and wdm daily, before it plans) checks the file. Errors mean it cannot be interpreted and block everything: a missing date or episode column, an unparseable date, a blank episode label, a duplicate (episode, date), a non-numeric value, a value outside its range, or both units of one quantity in a row. Warnings mean it can be read but deserves a look: unrecognized columns, no weight column, calendar gaps in an episode, and days whose macronutrients do not account for the energy total:

\[ \text{kcal} \approx 4\,\text{protein\_g} + 4\,\text{carb\_g} + 9\,\text{fat\_g} + 7\,\text{alcohol\_g}, \]

within 12% or 60 kcal, whichever is larger. A persistent gap usually means net rather than total carbohydrate, unlogged alcohol, or an under-recorded macronutrient, all of which bias the maintenance estimate.