EHR Risk Framework

How it works — A to Z

End-to-end guide to the researcher workbench: start the stack, pick data, train with leakage-aware settings, audit, review metrics and SHAP, then predict. Screenshots use synthetic teaching data only.

Free demo server — it may be slow. Check it with a small amount of data. For larger workloads or freer experimentation, run locally or on your own server. Open live demo

A. Scope & what you get

The framework is a leakage-aware clinical ML workbench for research and teaching: task YAML (index time + horizon), temporal / patient splits, calibration (Brier / ECE), leakage audits, optional SHAP, FastAPI jobs, and an Angular UI.

Deep dive: Why it matters · Features · Architecture

B. Start the stack

Local one-command start (recommended for courses and labs):

git clone https://github.com/ranasl62/ehr-chronic-disease-risk-prediction.git
cd ehr-chronic-disease-risk-prediction
docker compose up --build
# UI  http://127.0.0.1:8080
# API http://127.0.0.1:8000/docs

Or open the hosted workbench without installing anything: https://ehr-risk-framework.larucare.com/

Free demo server — it may be slow. Check it with a small amount of data. For larger workloads or freer experimentation, run locally or on your own server.

Also: Quickstart · Docker Hub images

C. Home — researcher checklist

Route /. After the API is up, Home answers: is the API healthy, is demo data present, is model.pkl trained, and which trust artifacts (metrics, leakage audit, SHAP) exist?

Home page with setup checklist and metrics
Figure C — Home checklist and latest hold-out metrics summary
  1. Open the workbench URL and wait for status to leave “Checking workspace…”.
  2. Confirm green checks for API, demo data, and model (first boot may train via prepare).
  3. Prefer Start research wizard for a full study loop, or Run demo train / Datasets for a manual path.
  4. Failed items show a Fix link to Datasets, Train, or Results.

Detail page: Home UI tour · Workflow: Research workflow

C2. Research wizard

Route /research (also linked from Home). Guided steps: data & task → health → train → trust pack → leakage → external validation → export (ZIP, methods.md, Analytics, Predict). Same jobs and artifacts as the manual pages — intended so a researcher can finish a methods-style pass without jumping between screens.

  1. Pick a demo or uploaded CSV and a task preset (e.g. horizon_detection_30d).
  2. Run health; fix blockers before training.
  3. Train, then refresh trust; run leakage and optional external validation.
  4. Export ZIP / methods; open Analytics for ROC/PR/calibration PNG export after retrain.

Full sequence: Research workflow

D. Config Center

Route /config. Set research persona defaults (task, model family, windows), optional API key, and UI theme / density before a serious train loop.

Config Center with task and model defaults
Figure D — Config Center (workspace defaults and preferences)
  1. Choose a task preset (e.g. diabetes / custom) and model options to compare later.
  2. Set window days and split preferences that Train will inherit.
  3. If the API requires API_KEY, paste it here so jobs send X-API-Key.
  4. Save — values persist in workspace config for the session / volume.

Detail page: Config UI tour

E. Datasets & health

Route /datasets. Browse bundled demos under data/demo/, upload BYO CSV to data/uploads/, map columns, and run dataset health before Train.

Datasets page with demo list and health
Figure E — Datasets: demos, selection, and health gate
  1. Leave Show bundled demo datasets on for teaching fixtures.
  2. Select ehr_data.csv (tiny longitudinal) or a larger synthetic cohort.
  3. Run Dataset health — fix schema / integrity issues before training.
  4. For your own CSV: File upload → map columns → health → Continue to train.

Detail: Datasets UI · Data guide

F. Train & compare

Route /train. Pick format (longitudinal vs tabular), task, model(s), calibration, and optional multi-model compare. Training writes model.pkl, evaluation reports, and run metadata.

Train page with model compare options
Figure F — Train: task, calibrate, compare models
  1. Confirm data path (demo longitudinal CSV is the default teaching path).
  2. Select model(s): logreg, random forest, xgboost, lightgbm (as available).
  3. Enable isotonic calibration when you care about probability quality (Brier / ECE).
  4. Start training — wait for job completion, then open Results.

Detail: Train UI · Fine-tuning

G. Leakage audit

From Train (or Results jobs), run the leakage audit against the trained artifact. It checks post-index features and split integrity so inflated AUROCs from future information are caught early.

  1. After a successful train, start the leakage-audit job from the Train / Results job panel.
  2. Wait until Home shows Leakage audit present.
  3. Read the audit JSON / report in Results or the reports ZIP — treat failures as blockers for “honest” metrics.

Concept guide: Prevent data leakage in clinical AI · Temporal diagrams

H. Results, light HPO & SHAP

Route /results. Review hold-out metrics, calibration plots, optional light HPO trials, fairness jobs, SHAP summaries, and downloadable figures.

Results page with metrics and download
Figure H1 — Results: metrics, figures, ZIP entry points
Results light HPO best trial card
Figure H2 — Light HPO: best-trial card and trial table (research / teaching only)
  1. Open Results after train — check ROC / PR when available, Brier, ECE, accuracy family metrics.
  2. Optionally run light HPO — inspect best trial (not clinical AutoML).
  3. Generate SHAP when supported; Home checklist updates when the summary exists.
  4. Run external validation and bind leakage/SHAP to a run_id for the trust pack.
  5. Promote a named run when you want that artifact as the active model.

Detail: Results UI · Prefer the Research wizard (/research) for a guided first pass.

I. Analytics

Route /analytics. Cohort charts, hold-out ROC / PR / calibration curves (after retrain), PNG export, and print layout for methods appendix figures — teaching EDA and reporting.

Analytics dashboard with cohort charts
Figure I — Analytics cohort dashboard
  1. Select the dataset you trained on (or another demo).
  2. Explore filters and charts — confirm class balance and feature distributions look sane.
  3. After retrain, open ROC / PR / calibration cards; export PNG or Print for the appendix.
  4. Use findings to adjust windows / task config, then retrain if needed.

Detail: Analytics UI

J. Predict & explain

Route /predict. Submit schema-aligned features to POST /v1/predict, view risk output, and inspect SHAP / vs-median explanations when available.

Predict page with risk and explanation
Figure J — Predict: disclaimer banner, form, and explanation
  1. Confirm a trained model is active (Home: Model trained).
  2. Fill the feature form (or paste JSON aligned to the training schema).
  3. Submit — read probability / label as research output only.
  4. Review local explanations; do not use them for clinical decisions.

Detail: Predict UI · API overview

K. OpenAPI & in-app Docs

Interactive Swagger lives at the API /docs (local :8000/docs or hosted API docs). The workbench /docs route links to this documentation website (not raw GitHub Markdown).

FastAPI OpenAPI Swagger UI
Figure K1 — OpenAPI: try health, datasets, train jobs, predict
In-app Docs page with guide links
Figure K2 — In-app Docs: named links to this site (Help, Quickstart, limits)

Detail: OpenAPI tour · In-app Docs tour · Help library

L. Download results ZIP

From Home or Results, download the methods pack: metrics JSON, figures, audit artifacts, and run metadata for reproducibility write-ups.

  1. Complete at least one train (+ optional audit / SHAP).
  2. Click Download results ZIP (or hit /v1/reports/download.zip on the API).
  3. Archive the ZIP with your paper / homework submission — still no PHI.

M. Hosted / split deploy

The public demo UI and API can run on separate hosts. The web image bakes API_ENDPOINT=https://ehr-api.larucare.com at build time; the API allows the UI origin via CORS_ORIGINS=https://ehr-risk-framework.larucare.com.

Docker images · INSTALLATION.md

N. Limits & next steps

Synthetic and teaching metrics are not clinical performance. Prefer credentialed hospital systems for care; use this stack for methods teaching and reproducible research software.

HomeC → DatasetsE → TrainF–G → ResultsH → AnalyticsI → PredictJ