nutramilo-health 0.2.0

Scientific SDK for peer-reviewed nutritional pattern indices (NIS, UIS, EDIP, DII, EDIH, NEAP, PRAL).

nutramilo-health

Scientific SDK for peer-reviewed nutritional pattern indices used by the Nutramilo Health OS platform.

Status: beta — formulas validated against published cohorts (Holt n=147, Tabung 2016, Shivappa 2014, Frassetto 1998); API surface stable for 0.x.

---

What's inside

Index	Description	Citation
NIS — Nutramilo Insulin Score	0-100 % postprandial insulin response forecast	Holt 1997 · Bell 2014 · Bao 2009
UIS — Unified Inflammation Score	0-100 % composite of EDIP+DII+NEAP	Nutramilo 2026
EDIP	Empirical Dietary Inflammatory Pattern	Tabung 2016 (PMID 27358416)
DII	Dietary Inflammatory Index (9-param meal proxy)	Shivappa 2014 (PMID 23824729)
EDIH	Empirical Dietary Index for Hyperinsulinemia	Tabung 2017 (PMID 28196579)
NEAP	Net Endogenous Acid Production	Frassetto 1998 (PMID 9734733)
PRAL	Potential Renal Acid Load	Remer & Manz 1995 (PMID 7797810)

All formulas are deterministic, citation-backed, EU AI Act Article 50 compliant — no opaque ML, no proprietary model weights.

---

Install

Currently published on TestPyPI while the SDK is in beta. Once stable we will publish to the real PyPI index.

pip install --index-url https://test.pypi.org/simple/ --no-deps nutramilo-health

After v0.2.0 (real PyPI):

pip install nutramilo-health

Validation extras (pandas, numpy, matplotlib for the Colab notebook):

pip install "nutramilo-health[validation]"

---

Quick start

from nutramilo_health import (
    PlateFood,
    nutramilo_insulin_score,
    unified_inflammation_score,
)

plate = [
    PlateFood(name="grilled salmon", grams=150, protein_g=30, fat_g=10,
              category="fish"),
    PlateFood(name="quinoa", grams=120, carbs_g=39, fiber_g=4.5, protein_g=8,
              fat_g=3.5, category="grain_whole"),
    PlateFood(name="spinach", grams=80, fiber_g=4, protein_g=3,
              category="vegetable_leafy"),
]

nis = nutramilo_insulin_score(plate)
print(f"NIS = {nis['percent']} %  ({nis['tier']})")

uis = unified_inflammation_score(plate)
print(f"UIS = {uis['percent']} %  ({uis['tier_en']})")

NIS = 31.5 %  (moderate)
UIS = 12.4 %  (Strongly anti-inflammatory)

---

Methodology

NIS (Nutramilo Insulin Score) — v2.0-regression

# Per-1000-kJ scaled (Atwater factors: 17·C + 17·P + 37·F → kJ)
PIRU_v2     = max(0, 1.61·net_carbs_p1k + 0.66·protein_p1k
                       + 1.20·fat_p1k − 1.14·fiber_p1k)
regression% = piecewise_linear_map(PIRU_v2,
                                   anchors=[(0, 0%), (30, 50%), (75, 100%)])
holt%       = clip((il_total / 60) × 100, [0, 100])     # cross-track
tier_floor% = {low:0, medium:30, high:55}[dil_tier]     # clinical floor
NIS_final_% = max(regression%, holt%, tier_floor%)

Coefficients independently derived via OLS regression on HoltBellBao_v1_frozen_2026.csv (n=147, sha256 b41eb157…). Stable across Ridge α=1, Ridge α=10, LASSO α=0.5, and Bayesian Ridge (max delta < 0.05). On the same cohort: MAE 13.04 (vs Kendall heuristic 25.53), R² 0.572 (vs -0.315). See notebooks/independent_regression_v2.py.

Interpretation note. Within the harmonized per-1000-kJ dataset, fat content contributed positively to predictive accuracy in mixed-meal contexts. This is an empirical regression result on the n=147 cohort and should NOT be interpreted as a direct physiological claim that fat alone stimulates insulin secretion.

Production parity: SDK v0.2.0+ reproduces the exact NIS computed by the production /api/plate-simulator/analyze endpoint when called with holt_il_track=... and tier_floor=... parameters.

UIS (Unified Inflammation Score)

UIS% = 50 · (1 + Σ wᵢ · normalize(scoreᵢ))
where w = (0.40, 0.40, 0.20) for (EDIP, DII, NEAP)
and normalize() linearly maps cohort-anti / cohort-pro cutoffs to [-1, +1].

Component cutoffs:

• EDIP: anti = -0.20, pro = +0.30 (Tabung 2016 quintiles)
• DII: anti = -1.5, pro = +1.5 (Shivappa 2014 cohort)
• NEAP: anti = +20, pro = +80 (Frassetto 1998 cohort)

---

API

from nutramilo_health import (
    PlateFood,
    nutramilo_insulin_score,
    piru_to_percent,
    unified_inflammation_score,
    edip_score, dii_score, edih_score, neap_score, pral_score,
)

Each scoring function takes an iterable of PlateFood and returns a dict with at minimum: percent (or score), tier labels (BG / EN / ES for UIS), component breakdown, citations, methodology string.

---

License

MIT. See LICENSE.

Citation

If you use this SDK in research, please cite:

Nutramilo Labs (2026). nutramilo-health: A scientific SDK for peer-reviewed nutritional pattern indices. Version 0.1.0. https://github.com/nutramilo/health-os