nutramilo-nis

Reference implementation of the Nutramilo Insulin Score (NIS) — an open-source algorithm designed to estimate the relative insulinogenic potential of a meal from its nutritional composition. NIS is intended for research, educational use, software development, and exploratory nutritional analysis. It should not be interpreted as a clinically validated predictor of postprandial insulin response. ⚠️ Scientific status. NIS v1.1.9 represents an exploratory methodology. The algorithm is intended for comparative analysis of meals and hypothesis generation rather than diagnostic or therapeutic decision-making.

✨ Why NIS?

Scientific Status

NIS has been evaluated during development using internal validation procedures and independent test subsets.

The methodology is intended to provide a transparent, reproducible, and open framework for estimating relative meal insulinogenicity from nutritional composition.

Users should interpret outputs as comparative estimates rather than direct physiological measurements.

Future independent validation studies may further clarify the strengths, limitations, and potential applications of the methodology.

📦 Install

pip install nutramilo-nis

Optional extras:

pip install "nutramilo-nis[validation]"   # numpy / pandas / scipy for re-running the regression notebook
pip install "nutramilo-nis[dev]"          # pytest, ruff, coverage

🚀 Quick start — 30 seconds

from nutramilo_nis import compute_nis

# A balanced lunch: salmon + quinoa + broccoli
result = compute_nis(
    carbs_g=35,
    protein_g=30,
    fat_g=15,
    fiber_g=8,
)

print(result.nis_percent)   # → 55.4
print(result.tier)          # → "Medium"
print(result.tier_color)    # → "#F59E0B"
print(result.contributions) # → {"carbs": 26.19, "protein": 11.93, "fat": 10.84, "fiber": -5.49}
print(result.citation)
# → "See CITATION.cff for citation metadata."

JSON-serialisable for APIs:

import json
print(json.dumps(result.to_dict(), indent=2))

🧪 Worked examples

Computed with default mixed source-type and calibration on (slope = 0.7275, intercept = 8.111). See tests/test_nis_v1_1_*.py for the full pinned numerical regression suite.

📐 Algorithm (5-step pipeline, v1.1.9)

1. Per-1000-kJ normalisation using Atwater factors (17·C + 17·P + 37·F kJ/g).
2. Linear regression layer — independent OLS on the frozen HoltBellBao_v1_frozen_2026.csv cohort (n = 147 foods). Coefficients exposed as NIS_COEFFICIENTS: carbs = +1.61 · protein = +0.66 · fat = +1.20 · fiber = −1.14 (per 1000 kJ). Protein and fat scaled by source-type multipliers (plant/mixed/animal: protein 0.55/1.00/1.30, fat 0.45/1.00/1.25).
3. Pure-fat extrapolation guard — when (net-carb + protein) / 1000 kJ < 5 g the regression output is scaled by 0.15× (energy-normalised, serving- invariant since v1.1.1).
4. Cross-cohort linear calibration — obs ≈ 0.7275 × pct + 8.111 (fit on the n = 63 cross-cohort validation set; opt-out via apply_calibration=False).
5. Optional Holt cross-track + clinical-tier floor, then Final NIS = max(regression_cal, holt, floor), clamped [0, 100].

Note on validation framing. The n = 147 training cohort and the n = 63 cross-cohort calibration set share Holt 1997 foods (derivational overlap, see see project documentation). All inferential claims in v1.1.9 are therefore restricted to the n = 25 strictly out-of-sample subset (Bao 2011, Nilsson 2004, Boirie 1997, Trichopoulou 2003, Sahyoun 2008).

📘 API reference

compute_nis(carbs_g, protein_g, fat_g, fiber_g=0.0, *, insulin_impact_tier="low", il_total_g=None, fat_type="mixed", protein_type="mixed", sugar_g=0.0, apply_calibration=True) → NisResult

NisResult (frozen dataclass)

Use .to_dict() → JSON-serialisable.

Reproducibility

All calculations are fully reproducible from the published source code and released package versions.

™ Trademark Notice

NIS, Nutramilo Insulin Score, and Nutramilo may be used to identify the project and associated materials.

The Apache 2.0 license applies to the software source code.

Commercial use of names, logos, and branding elements may be subject to separate intellectual property rights where applicable.

⚖️ Disclaimer & regulatory framing

NIS is intended for educational and research purposes. It is not a medical device, does not diagnose any disease, and should not replace professional clinical judgement.

🏗️ Roadmap (semver-frozen)

• v1.x — patch fixes only; coefficients never change.
• v2.0.x — prospective CGM trial re-regression.

| GDPR | No personal data processed by the library itself |

🤝 NIS vs DIL — different questions, different units

NIS and DIL are complementary, not interchangeable:

If you need both layers (per-meal NIS for ranking + daily DIL for budget), combine compute_nis here with the open compute_dil formula: DIL_g = max(0, 0.69·protein + max(0, carbs − fiber)).

📜 Licence

Apache 2.0 — see NOTICE for the mandatory citation clause.

💬 Contact