synthdiet

Other languages: Türkçe · Español · Français · Deutsch · Português · Italiano · 中文 · 日本語

A Python library for generating synthetic patients with realistic clinical conditions and simulating dietary interventions on them.

synthdiet is built for dietitians, clinical-nutrition researchers, and educators who want to prototype diets, run virtual trials, and stress-test nutritional recommendations against hundreds or thousands of synthetic patients before bringing them to a clinic.

Disclaimer: synthdiet is a research and teaching tool. The numbers it produces are not clinical recommendations and the synthetic patients are not real people. Always defer to a qualified registered dietitian for patient care.

---

Author

Buğra Ayan — Ankara / Türkiye

• Website: https://bugraayan.com
• Email: bugraayan.com@gmail.com
• Google Scholar: https://scholar.google.com/citations?user=VHGqzNMAAAAJ&hl=tr

---

Features

Core domain model

• A typed Patient aggregating demographics, anthropometrics, lifestyle, lab biomarkers, diagnoses, and current medications.
• A registry of 25+ diseases spanning endocrine, cardiovascular, renal, hepatic, gastrointestinal, metabolic, musculoskeletal, oncologic, psychiatric, and allergy categories.
• A registry of 19 clinically important drug-nutrient interactions (metformin → B12, statins → grapefruit, warfarin → vitamin K, levothyroxine timing, MAOI tyramine crisis, etc.).
• 5 synthetic patient generators (random, distribution, copula, cohort, Markov progression).
• A 45-item food database with macro/micro nutrient breakdown and 8 preset diets (Mediterranean, DASH, keto, low-FODMAP, low-sodium renal, diabetic, vegan, standard).

Methodological depth (v0.1 expansion)

• Hall 2011 body composition model as an opt-in (DietSimulator(engine="hall_2011")) with fat-mass / lean-mass partitioning via the Forbes equation and adaptive thermogenesis.
• Adherence and dropout dynamics: constant, decaying, Weibull dropout, stochastic skip, perceived-burden.
• RCT engine (synthdiet.trials) supporting parallel-arm, crossover, and 2×2 factorial designs, with stratified / block / minimisation randomisation, dropout modelling, and ITT/PP/AT analyses.
• Causal inference (synthdiet.causal): counterfactual simulation, ATE/CATE estimators, propensity-confounding experiments with IPTW and g-formula adjustment, lightweight DAGs.
• Diet quality indices (synthdiet.indices): HEI-2020, AHEI-2010, MEDAS, DASH score, PHDI, DII.
• Statistical helpers (synthdiet.stats): power analysis for continuous and binary outcomes, bootstrap CI, permutation tests, Benjamini-Hochberg + Holm-Bonferroni adjustments, baseline-adjusted ANCOVA.
• Measurement-error and missing-data injection (synthdiet.noise): per-assay CV%, self-report bias, MCAR/MAR/MNAR patterns.
• 15 clinical case studies + OSCE-style grading (synthdiet.education).
• Validation suite against 5 landmark RCTs (synthdiet.validation): DASH-Sodium, PREDIMED, DiRECT, Look AHEAD, Diabetes Prevention Program.
• Visualisation (synthdiet.viz, optional): CONSORT diagram, forest plot, trajectory ribbon, Table 1.

---

Installation

pip install synthdiet

Optional extras:

pip install "synthdiet[viz]"     # matplotlib visualisations
pip install "synthdiet[causal]"  # networkx DAG export
pip install "synthdiet[app]"     # Streamlit + Plotly interactive app
pip install "synthdiet[docs]"    # Sphinx + furo + myst-parser
pip install "synthdiet[dev]"     # pytest + ruff + mypy + matplotlib

Try the interactive app

pip install "synthdiet[app]"
streamlit run app/streamlit_app.py

A multi-page Streamlit interface with animated Plotly charts, a custom CONSORT flow diagram and OSCE-style grading. See app/README.md for full details and Streamlit Community Cloud deployment instructions.

📋 Cohort Builder — interactive prevalence sliders → live age × sex × BMI × diagnosis distributions, CSV export.	🍽️ Diet Simulator — pick any of 8 preset diets and watch HbA1c, BP, LDL and weight trajectories animate week by week.
🧪 RCT Engine — parallel-arm trials with Weibull dropout, custom CONSORT flow diagram, forest plot and ITT/PP/AT analyses.	📚 Case Studies — 15 built-in clinical scenarios with OSCE-style automatic grading of student diet plans.

synthdiet requires Python 3.9+ and depends on numpy, pandas, and scipy.

---

60-second tour

from synthdiet import (
    CohortGenerator, CohortSpec, DiseaseSpec,
    DietSimulator, mediterranean_diet,
    evaluate_simulation, format_evaluation_report,
)

spec = CohortSpec(
    size=100,
    diseases=[
        DiseaseSpec("type_2_diabetes", prevalence=0.40),
        DiseaseSpec("hypertension",     prevalence=0.45),
    ],
)
cohort = CohortGenerator(spec, seed=42).generate()

simulator = DietSimulator(adherence=0.8)
diet = mediterranean_diet(daily_energy_kcal=1800)

for patient in cohort[:3]:
    result = simulator.run(patient, diet, duration_weeks=12)
    evaluation = evaluate_simulation(result)
    print(format_evaluation_report(evaluation))
    print("-" * 60)

More end-to-end scripts live in examples/.

---

Project layout

src/synthdiet/
├── patients/          # Demographics, anthropometrics, biomarkers, lifestyle
├── diseases/          # 25+ disease classes + registry
├── interactions/      # Medication catalogue + drug-nutrient registry
├── nutrition/         # Foods, nutrients, DRIs
├── diets/             # DietPlan + 8 preset diets
├── generators/        # 5 synthetic patient generators
├── simulation/        # Diet simulator (simple + Hall 2011 body composition)
├── behavior/          # Adherence + Weibull dropout models
├── trials/            # RCT engine (parallel/crossover/factorial + ITT/PP)
├── causal/            # Counterfactual + ATE/CATE + IPTW + DAG
├── indices/           # HEI-2020, AHEI-2010, MEDAS, DASH, PHDI, DII
├── stats/             # Power analysis, bootstrap, ANCOVA, FDR/Holm
├── noise/             # Lab CV% + MCAR/MAR/MNAR missing-data injection
├── validation/        # DASH-Sodium / PREDIMED / DiRECT / Look AHEAD / DPP
├── education/         # 15 case studies + OSCE rubric + Markdown/HTML
├── viz/               # CONSORT, trajectories, forest, Table 1 (matplotlib)
├── evaluation/        # Outcome metrics + reports
└── utils/             # Constants, validators, random-state helpers

Tutorials live in docs/tutorials/ (English) and in language-specific subfolders (docs/tr/, docs/es/, docs/fr/, docs/de/, docs/pt/, docs/it/, docs/zh/, docs/ja/). A draft JOSS paper lives in paper/. See docs/README.md for the full multilingual index.

---

Extending synthdiet

Add a new disease by subclassing Disease and registering it:

from synthdiet.diseases.base import Disease, NutritionalConstraints
from synthdiet.diseases.registry import register


@register
class FattyLiverGradeII(Disease):
    name = "fatty_liver_grade_ii"
    icd10 = "K76.0"
    category = "hepatic"

    def nutritional_constraints(self, patient):
        return NutritionalConstraints(
            carbohydrate_pct_range=(0.35, 0.45),
            added_sugar_pct_max=0.05,
            fiber_g_min=30,
        )

After import, the class is automatically discoverable through get_disease("fatty_liver_grade_ii") and selectable in DiseaseSpec.

---

Citation

If you use synthdiet in academic work, please cite it via CITATION.cff or the BibTeX entry below:

@software{ayan_synthdiet_2026,
  author  = {Buğra Ayan},
  title   = {synthdiet: A Python library for simulating diets on synthetic patients},
  year    = {2026},
  version = {0.1.0},
  url     = {https://bugraayan.com}
}

---

License

MIT — see LICENSE.