← Fan Shen

Life Matters

An open framework and model library for health and behavioral decisions

Reference EngineModel libraryLatest releaseContact

Published findings about health and behavior rarely become something that can be run, compared or combined, and as they spread they tend to lose the dose, population and duration they were found under. Life Matters (LM) is an attempt to let findings travel together with the conditions under which they hold. A model is a plain YAML file that states its variables, equations, a simulation setup and, optionally, an optimization problem, and each parameter records the study it came from, or is marked as lacking one. The Reference Engine runs the models, searches for good regimens across several objectives, and lets models from different fields work together in one simulation. Every number traces to its source, so each step can be checked.

LM is an aid for analysis. It shows what a set of published findings implies and how they can be put to work together. It does not give medical advice. Review of the models is still limited in coverage, and the models shown here serve as demonstrations of the interface.

An example it is built around

For a patient with chronic kidney disease at stage 3, protecting kidney function and keeping muscle both bear on protein intake, and each comes with its own recommended range. The CKD model in the library brings both mechanisms together, along with how well a patient keeps to a restricted diet over time, and looks for the balance between them. The tour below follows that model, and a few others, through the interface.

Read and run

The model library on the left and the description page of a CKD model: problem, method, result and limitations, with the review mark boxed.
Read a model. Each model is a runnable paper: the problem, the method, the result and the limits on one page, with how far it has been reviewed in plain view.
The references section of the CKD model, each study beside a note on what it supports, with two entries boxed.
Every number can be checked. Each parameter points to the study it came from, and where there is none it is marked, not left blank. A reader who knows the field can check the model without guessing.
Three training plans compared on fitness, fatigue and performance curves.
See the consequences. A plan becomes a curve over time, with several plans side by side and the uncertainty shown, so a finding stated as an effect size turns into something you can look at.

Optimize

Most hard choices in life are not a search for one best answer but several goals pulling against each other. LM writes the pull as a structure that runs, shows what it costs to favor one goal over another, and leaves the order to the person who chooses.

The optimizer setup of the CKD model, with the Pareto front boxed.
State the problem, see the trade-off. What can be adjusted, what to pursue and which limits must hold go in, and a whole front of trade-offs comes out rather than a single answer. In the CKD model, protein intake pulls kidney function and muscle mass in different directions.
Six plans of the CKD model compared on kidney function, muscle mass and blood urea nitrogen.
Compare with clinical practice. Plans from the front run beside clinical-style plans on the same curves, so a discussion has a shared picture.

Find, build and compose

A paper-doll body with the organs and everyday inputs that twelve ticked models act on, and the model tree filtered to them.
Find what is there. Start from an organ or a part of everyday life and see which models in the library point to it. It answers what the library holds, not what the outcome would be.
The model library editor with three models side by side.
Read and edit a model. Every part of a model is laid out in plain sections, with several models side by side. The online demo is read only, and editing is available in the local version.
The variables and equations of one model as a graph, and of three models together with shared variables marked by dashed rings.
See the structure. Variables and equations are laid out as a graph that shows what depends on what. Across several models a shared variable becomes one node, which shows where they meet.
Three sports models that write the same variables, flagged in red.
Check before joining models. Models that share variables can be joined, and a clash, such as two models updating the same variable, is flagged before a merge. This says which models can connect, not what the combination predicts.

In motion

Composing models. A ready-made combination first, then one where models write the same variables.
The structure graph. Nodes dragged around, and the layout switched between two views.

How it fits together

Status

Models differ in maturity, and each one records how far it has been reviewed, together with ratings for its variables, equations, simulation and confidence. Review is still limited in coverage at this stage, and the models in the tour above serve as demonstrations. Comments and criticism are welcome, by an issue on GitHub or by email.

The code of the Reference Engine was written with AI coding assistance for code generation, automated testing and documentation. Citation details are in CITATION.cff.