EHR Risk Framework

Why this framework matters

Chronic-disease and other horizon-based risk models are easy to demo and hard to trust. This project makes the trustworthy path the default for education and research prototypes.

The problem students and labs hit

Temporal leakage is silent

Features built from “all history” often include post-index labs or diagnoses. Accuracy looks great; the science does not.

Probabilities are uncalibrated

A model can rank well (AUROC) while reporting risk percentages that do not match observed rates.

Explainability is bolted on late

SHAP and schema-aligned inference are often missing from classroom notebooks, so demos stop at a CSV score column.

Reproducibility is optional

Without task presets, manifests, and a results pack, two students cannot compare the same experiment.

What “useful” means here

AudienceConcrete outcome
Course / thesis student A complete loop you can cite: data → health → train → leakage audit → SHAP → predict UI
Research lab Shared Docker baseline, task YAML, named runs, downloadable metrics/figures for methods appendices
Open-source contributor Clear non-goals, tests spanning API↔UI contracts, and documentation that matches the code
Instructor Demo data that runs offline; students learn trust surfaces before chasing leaderboard metrics

Use cases

  1. Classroom lab — Run Docker, train on the tiny longitudinal demo, inspect leakage audit and calibration plots, submit a short methods write-up.
  2. Thesis baseline — Fork, map your BYO CSV columns, lock a task YAML, report AUROC/PR-AUC/Brier/ECE with an explicit limitations section.
  3. Lab onboarding — New members reproduce the demo end-to-end before touching credentialed extracts.
  4. Methods comparison — Multi-model compare with promote-best; keep artifacts under reports/ for peer review.
  5. API teaching — Call /v1/model/schema and /v1/predict to show schema-driven inference and explanations.

Relevance to U.S. healthcare research

U.S. healthcare systems carry a heavy chronic-disease burden. Research progress on predictive models requires tooling that makes temporal integrity, calibration, and explanation the default— especially in university labs and health-informatics classrooms that train the next workforce.

Stronger methods culture

Index/horizon discipline and leakage audits reduce silent errors that inflate published AUROC and mislead follow-on work.

Workforce-ready practice

Students learn the same loop used in research prototypes: health checks, compare, calibrate, SHAP, schema-driven predict.

Reproducible sharing

Task YAML, named runs, and results ZIPs help U.S. academic teams share methods appendices without exchanging PHI.

Equity-aware evaluation

When group columns exist, fairness helpers and Analytics filters support subgroup reporting expected in careful health AI research.

This software is a research and education prototype—not a clinical product or medical device.

Impact without overclaiming

The framework’s value is methodological hygiene + researcher UX, not clinical deployment. That honesty is intentional: it keeps the project useful for learning, peer review, and open science, and avoids implying regulated medical-device status.

Temporal integrity Calibration Explainability Reproducible packs Explicit limits

Next: Features in detail · How it works · Limits & model card · Full map