Skip to content

Commit 48c3f51

Browse files
maccursoragent
mac
and
cursoragent
committed
docs: add multilingual documentation in 9 languages
Add full documentation (README + index + api + 6 tutorials) for Turkish, Spanish, French, German, Portuguese, Italian, Chinese (Simplified) and Japanese, alongside the existing English docs. - Each language lives under docs/<lang>/ with the same file layout (index.md, api.md, tutorials/01-06.md) so cross-language linking is straightforward. - Root READMEs (README.<lang>.md) added with a language switcher row. - New docs/README.md acts as a multilingual index. - Code blocks are kept verbatim (English API names) to preserve a single API contract; only narrative text is translated. Co-authored-by: Cursor <cursoragent@cursor.com>
1 parent 93e7ffd commit 48c3f51

75 files changed

Lines changed: 6744 additions & 2 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎README.de.md‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
# synthdiet
2+
3+
[![PyPI](https://img.shields.io/pypi/v/synthdiet.svg)](https://pypi.org/project/synthdiet/)
4+
[![Python](https://img.shields.io/pypi/pyversions/synthdiet.svg)](https://pypi.org/project/synthdiet/)
5+
[![Lizenz: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6+
[![CI](https://github.com/bugraayancom/synthdiet/actions/workflows/ci.yml/badge.svg)](https://github.com/bugraayancom/synthdiet/actions/workflows/ci.yml)
7+
8+
> Andere Sprachen: [English](README.md) · [Türkçe](README.tr.md) · [Español](README.es.md) · [Français](README.fr.md) · [Português](README.pt.md) · [Italiano](README.it.md) · [中文](README.zh.md) · [日本語](README.ja.md)
9+
Eine Python-Bibliothek zum **Erzeugen synthetischer Patientinnen und
10+
Patienten** mit realistischen klinischen Tableaus und zur
11+
**Simulation diätetischer Interventionen** an ihnen.
12+
13+
`synthdiet` richtet sich an Diätassistent\*innen, klinische
14+
Ernährungsforscher\*innen und Lehrende, die Diäten prototypisch
15+
entwickeln, virtuelle Studien durchführen und Ernährungsempfehlungen
16+
an Hunderten oder Tausenden synthetischer Patient\*innen
17+
stresstesten möchten, bevor sie in die Klinik gelangen.
18+
19+
> Hinweis: `synthdiet` ist ein Forschungs- und Lehrwerkzeug. Die
20+
> erzeugten Zahlen sind **keine klinischen Empfehlungen** und die
21+
> synthetischen Patient\*innen sind **keine realen Personen**. Für die
22+
> Patientenversorgung wenden Sie sich stets an eine\*n qualifizierte\*n
23+
> registrierte\*n Diätassistent\*in.
24+
25+
---
26+
27+
## Autor
28+
29+
**Buğra Ayan** — Ankara / Türkei
30+
- Webseite: <https://bugraayan.com>
31+
- E-Mail: <bugraayan.com@gmail.com>
32+
- Google Scholar: <https://scholar.google.com/citations?user=VHGqzNMAAAAJ&hl=tr>
33+
34+
---
35+
36+
## Funktionsumfang
37+
38+
### Kerndomänenmodell
39+
- Eine typisierte `Patient`-Klasse, die Demografie, Anthropometrie,
40+
Lebensstil, Laborbiomarker, Diagnosen und aktuelle Medikation
41+
zusammenführt.
42+
- Ein Register mit **mehr als 25 Krankheiten** aus den Bereichen
43+
Endokrinologie, Kardiologie, Nephrologie, Hepatologie,
44+
Gastroenterologie, Stoffwechsel, Bewegungsapparat, Onkologie,
45+
Psychiatrie und Allergologie.
46+
- Ein Register mit **19 klinisch relevanten Arzneimittel-Nährstoff-
47+
Wechselwirkungen** (Metformin → B12, Statine → Grapefruit,
48+
Warfarin → Vitamin K, L-Thyroxin-Einnahmezeitpunkt, Tyramin-Krise
49+
unter MAO-Hemmern usw.).
50+
- 5 Generatoren synthetischer Patient\*innen (zufällig, verteilungs-
51+
basiert, Copula, Kohorte, Markow-Progression).
52+
- Eine 45 Lebensmittel umfassende Datenbank mit Makro-/Mikronährstoff-
53+
Aufschlüsselung und 8 voreingestellten Diäten (Mediterran, DASH,
54+
Keto, Low-FODMAP, natriumarm bei Niereninsuffizienz, Diabetiker,
55+
vegan, Standard).
56+
57+
### Methodische Tiefe (v0.1)
58+
- **Hall-Körperzusammensetzungsmodell (2011)** als optionale Engine
59+
(`DietSimulator(engine="hall_2011")`) mit Fett-/Magermassen-
60+
Aufteilung über die Forbes-Gleichung und adaptiver Thermogenese.
61+
- **Adhärenz- und Drop-out-Dynamik**: konstant, abklingend, Weibull,
62+
stochastische Aussetzer, wahrgenommene Belastung.
63+
- **RCT-Engine** (`synthdiet.trials`): Parallelarm-, Crossover- und
64+
2×2-faktorielle Designs; geschichtete / Block- /
65+
Minimierungs-Randomisierung; Drop-out-Modellierung; ITT/PP/AT-
66+
Analysen.
67+
- **Kausale Inferenz** (`synthdiet.causal`): kontrafaktische
68+
Simulation, ATE/CATE-Schätzer, Konfundierungs-Experimente mit
69+
IPTW und g-Formel, leichtgewichtige DAGs.
70+
- **Indizes der Ernährungsqualität** (`synthdiet.indices`): HEI-2020,
71+
AHEI-2010, MEDAS, DASH-Score, PHDI, DII.
72+
- **Statistische Helfer** (`synthdiet.stats`): Power-Analysen für
73+
stetige und binäre Endpunkte, Bootstrap-KI, Permutationstests,
74+
Benjamini-Hochberg- und Holm-Bonferroni-Korrekturen,
75+
baseline-adjustierte ANCOVA.
76+
- **Mess- und Fehlende-Daten-Injektion** (`synthdiet.noise`):
77+
Assay-CV%, Selbstauskunfts-Bias, MCAR/MAR/MNAR-Muster.
78+
- **15 Fallstudien + OSCE-artige Bewertung**
79+
(`synthdiet.education`).
80+
- **Validierungssuite** gegen 5 Meilenstein-RCTs
81+
(`synthdiet.validation`): DASH-Sodium, PREDIMED, DiRECT,
82+
Look AHEAD, Diabetes Prevention Program.
83+
- **Visualisierung** (`synthdiet.viz`, optional): CONSORT-Diagramm,
84+
Forest-Plot, Trajektorien-Band, Tabelle 1.
85+
86+
---
87+
88+
## Installation
89+
90+
```bash
91+
pip install synthdiet
92+
```
93+
94+
Optionale Extras:
95+
96+
```bash
97+
pip install "synthdiet[viz]" # matplotlib-Visualisierungen
98+
pip install "synthdiet[causal]" # networkx-DAG-Export
99+
pip install "synthdiet[docs]" # Sphinx + furo + myst-parser
100+
pip install "synthdiet[dev]" # pytest + ruff + mypy + matplotlib
101+
```
102+
103+
`synthdiet` benötigt Python 3.9+ und stützt sich auf `numpy`, `pandas`,
104+
`scipy`.
105+
106+
---
107+
108+
## 60-Sekunden-Tour
109+
110+
```python
111+
from synthdiet import (
112+
CohortGenerator, CohortSpec, DiseaseSpec,
113+
DietSimulator, mediterranean_diet,
114+
evaluate_simulation, format_evaluation_report,
115+
)
116+
117+
spec = CohortSpec(
118+
size=100,
119+
diseases=[
120+
DiseaseSpec("type_2_diabetes", prevalence=0.40),
121+
DiseaseSpec("hypertension", prevalence=0.45),
122+
],
123+
)
124+
cohort = CohortGenerator(spec, seed=42).generate()
125+
126+
simulator = DietSimulator(adherence=0.8)
127+
diet = mediterranean_diet(daily_energy_kcal=1800)
128+
129+
for patient in cohort[:3]:
130+
result = simulator.run(patient, diet, duration_weeks=12)
131+
evaluation = evaluate_simulation(result)
132+
print(format_evaluation_report(evaluation))
133+
print("-" * 60)
134+
```
135+
136+
Vollständige Beispiele in [`examples/`](examples/); deutsche
137+
Tutorials in [`docs/de/`](docs/de/).
138+
139+
---
140+
141+
## Zitation
142+
143+
```bibtex
144+
@software{ayan_synthdiet_2026,
145+
author = {Buğra Ayan},
146+
title = {synthdiet: A Python library for simulating diets on synthetic patients},
147+
year = {2026},
148+
version = {0.1.0},
149+
url = {https://bugraayan.com}
150+
}
151+
```
152+
153+
## Lizenz
154+
155+
MIT — siehe [`LICENSE`](LICENSE).

‎README.es.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
# synthdiet
2+
3+
[![PyPI](https://img.shields.io/pypi/v/synthdiet.svg)](https://pypi.org/project/synthdiet/)
4+
[![Python](https://img.shields.io/pypi/pyversions/synthdiet.svg)](https://pypi.org/project/synthdiet/)
5+
[![Licencia: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6+
[![CI](https://github.com/bugraayancom/synthdiet/actions/workflows/ci.yml/badge.svg)](https://github.com/bugraayancom/synthdiet/actions/workflows/ci.yml)
7+
8+
> Otros idiomas: [English](README.md) · [Türkçe](README.tr.md) · [Français](README.fr.md) · [Deutsch](README.de.md) · [Português](README.pt.md) · [Italiano](README.it.md) · [中文](README.zh.md) · [日本語](README.ja.md)
9+
Una biblioteca de Python para **generar pacientes sintéticos** con
10+
condiciones clínicas realistas y **simular intervenciones dietéticas**
11+
sobre ellos.
12+
13+
`synthdiet` está pensado para nutricionistas-dietistas, investigadores
14+
de nutrición clínica y educadores que quieran prototipar dietas,
15+
ejecutar ensayos virtuales y poner a prueba recomendaciones nutricionales
16+
sobre cientos o miles de pacientes sintéticos antes de llevarlas a la
17+
clínica.
18+
19+
> Aviso: `synthdiet` es una herramienta de investigación y enseñanza.
20+
> Los números que produce **no son recomendaciones clínicas** y los
21+
> pacientes sintéticos **no son personas reales**. Para la atención al
22+
> paciente consulte siempre a un dietista-nutricionista cualificado.
23+
24+
---
25+
26+
## Autor
27+
28+
**Buğra Ayan** — Ankara / Turquía
29+
- Sitio web: <https://bugraayan.com>
30+
- Correo: <bugraayan.com@gmail.com>
31+
- Google Scholar: <https://scholar.google.com/citations?user=VHGqzNMAAAAJ&hl=tr>
32+
33+
---
34+
35+
## Características
36+
37+
### Modelo de dominio principal
38+
- Una clase `Patient` tipada que agrega demografía, antropometría,
39+
estilo de vida, biomarcadores de laboratorio, diagnósticos y
40+
medicación actual.
41+
- Un registro de **más de 25 enfermedades** que cubren las categorías
42+
endocrina, cardiovascular, renal, hepática, gastrointestinal,
43+
metabólica, musculoesquelética, oncológica, psiquiátrica y alérgica.
44+
- Un registro de **19 interacciones fármaco-nutriente** clínicamente
45+
relevantes (metformina → B12, estatinas → pomelo, warfarina →
46+
vitamina K, momento de la levotiroxina, crisis tiramínica con IMAO,
47+
etc.).
48+
- 5 generadores de pacientes sintéticos (aleatorio, por distribución,
49+
por cópula, cohorte, progresión de Markov).
50+
- Una base de datos de 45 alimentos con desglose macro/micronutriente
51+
y 8 dietas predefinidas (mediterránea, DASH, cetogénica, baja en
52+
FODMAP, renal baja en sodio, diabética, vegana, estándar).
53+
54+
### Profundidad metodológica (expansión v0.1)
55+
- **Modelo de composición corporal de Hall (2011)** opcional
56+
(`DietSimulator(engine="hall_2011")`), con partición de masa
57+
grasa/magra mediante la ecuación de Forbes y termogénesis
58+
adaptativa.
59+
- **Dinámica de adherencia y abandono**: constante, decreciente,
60+
abandono Weibull, salto estocástico, carga percibida.
61+
- **Motor de ECA** (`synthdiet.trials`) con diseños paralelos,
62+
cruzados y factoriales 2×2; aleatorización estratificada / por
63+
bloques / por minimización; modelado de abandono; análisis ITT/PP/AT.
64+
- **Inferencia causal** (`synthdiet.causal`): simulación
65+
contrafactual, estimadores ATE/CATE, experimentos de confusión con
66+
IPTW y g-fórmula, DAGs ligeros.
67+
- **Índices de calidad de la dieta** (`synthdiet.indices`): HEI-2020,
68+
AHEI-2010, MEDAS, puntuación DASH, PHDI, DII.
69+
- **Ayudas estadísticas** (`synthdiet.stats`): cálculo de potencia
70+
para resultados continuos y binarios, IC bootstrap, pruebas de
71+
permutación, ajustes de Benjamini-Hochberg + Holm-Bonferroni,
72+
ANCOVA ajustada por línea base.
73+
- **Inyección de error de medida y datos faltantes**
74+
(`synthdiet.noise`): CV% por ensayo, sesgo de auto-reporte,
75+
patrones MCAR/MAR/MNAR.
76+
- **15 casos clínicos + evaluación tipo OSCE**
77+
(`synthdiet.education`).
78+
- **Suite de validación** contra 5 ECAs históricos
79+
(`synthdiet.validation`): DASH-Sodium, PREDIMED, DiRECT,
80+
Look AHEAD, Diabetes Prevention Program.
81+
- **Visualización** (`synthdiet.viz`, opcional): diagrama CONSORT,
82+
forest plot, banda de trayectorias, Tabla 1.
83+
84+
---
85+
86+
## Instalación
87+
88+
```bash
89+
pip install synthdiet
90+
```
91+
92+
Extras opcionales:
93+
94+
```bash
95+
pip install "synthdiet[viz]" # visualizaciones con matplotlib
96+
pip install "synthdiet[causal]" # exportación de DAG con networkx
97+
pip install "synthdiet[docs]" # Sphinx + furo + myst-parser
98+
pip install "synthdiet[dev]" # pytest + ruff + mypy + matplotlib
99+
```
100+
101+
`synthdiet` requiere Python 3.9+ y depende de `numpy`, `pandas` y `scipy`.
102+
103+
---
104+
105+
## Recorrido en 60 segundos
106+
107+
```python
108+
from synthdiet import (
109+
CohortGenerator, CohortSpec, DiseaseSpec,
110+
DietSimulator, mediterranean_diet,
111+
evaluate_simulation, format_evaluation_report,
112+
)
113+
114+
spec = CohortSpec(
115+
size=100,
116+
diseases=[
117+
DiseaseSpec("type_2_diabetes", prevalence=0.40),
118+
DiseaseSpec("hypertension", prevalence=0.45),
119+
],
120+
)
121+
cohort = CohortGenerator(spec, seed=42).generate()
122+
123+
simulator = DietSimulator(adherence=0.8)
124+
diet = mediterranean_diet(daily_energy_kcal=1800)
125+
126+
for patient in cohort[:3]:
127+
result = simulator.run(patient, diet, duration_weeks=12)
128+
evaluation = evaluate_simulation(result)
129+
print(format_evaluation_report(evaluation))
130+
print("-" * 60)
131+
```
132+
133+
Ejemplos completos en [`examples/`](examples/) y tutoriales en español
134+
en [`docs/es/`](docs/es/).
135+
136+
---
137+
138+
## Citación
139+
140+
```bibtex
141+
@software{ayan_synthdiet_2026,
142+
author = {Buğra Ayan},
143+
title = {synthdiet: A Python library for simulating diets on synthetic patients},
144+
year = {2026},
145+
version = {0.1.0},
146+
url = {https://bugraayan.com}
147+
}
148+
```
149+
150+
## Licencia
151+
152+
MIT — véase [`LICENSE`](LICENSE).

0 commit comments

Comments
 (0)