Getting started
Install
The prerequisite is uv. The package pins Python 3.13, because JAX wheels lag new CPython releases; uv fetches 3.13 for this project only. The code is in a private repository (why these pages exist anyway).
cd weight-dynamics/code
uv sync --extra dev # one time: creates .venv with the pinned dependencies
uv run python -m pytest # the test suite, about 20 s
uv run wdm demo # the whole pipeline on synthetic data: confirms the installuv run wdm ... works from weight-dynamics/code. To type plain wdm from any directory, put the virtual environment’s entry point on your PATH, for example:
ln -s "$PWD/.venv/bin/wdm" ~/.local/bin/wdmThe repository
weight-dynamics/
├── data/
│ ├── schema.md every column of observations.csv, and the rules
│ ├── templates/ blank and filled-in examples of every input file
│ ├── raw/ your data: observations.csv, subject.toml, routine.csv
│ └── plans/ the plans log, written by wdm daily
├── code/ the wdm package, its tests, pyproject.toml, plan.csv
└── report/ the technical report (LaTeX)
Every command reads data/raw/observations.csv and data/raw/subject.toml unless given other paths, so wdm daily and wdm log need no arguments. Body-weight and food logs are personal health data: keep data/raw/ and data/plans/ out of any public copy.
Set up your files
The subject file. Copy
data/templates/subject_template.tomltodata/raw/subject.toml. Fill in sex, age, and height; review the safety limits; add a goal if you have a date in mind (The subject file).The observations file. Copy
data/templates/observations_template.csvtodata/raw/observations.csv(observations_example.csvis a filled-in example). It holds one row per day (The observations file).History, if you have it. Enter past diets one row per day, each with its own
episodelabel (past-01,past-02, …). Weight alone is enough: past weigh-ins without a food log still teach phase 1 how noisy your scale is.The first row of the current diet. Add it by hand: the date, a new episode label such as
current, and that morning’s weight. From then onwdm dailyandwdm logadd rows to the latest episode.Check it.
wdm validate150 rows | 3 episodes | 122 weigh-ins | 66 intake records no problems foundFix anything it reports; it exits with code 1 on errors. Then follow The daily routine.
Try it without your own data
wdm demo generates a synthetic subject with known metabolic parameters (two weight-only past diets and a current one, 120 days by default), runs both estimation phases and the controller, and reports how many of the true parameters fall inside their 90% intervals:
wdm demo --days 60 --figures /tmp/wdm-demoPhase 2 -- posterior parameter estimates
parameter median 90% interval shift
rmr_intercept 1338.9 [1070, 1674] +2.7%
...
ground-truth recovery: 9/9 parameters inside their 90% interval
smoothed trend RMSE vs hidden truth: 237 g
(single-weigh-in noise was 595 g)
It reads and writes nothing of yours. The walkthrough takes the same pipeline apart one step at a time.