#!/usr/bin/env python3 """ Render a static, single-file HTML report comparing the SHIPPED heart model against one retraining CANDIDATE — for a room screen, not a dashboard. python scripts/render_candidate_report.py [--out reports/x.html] Reads only `candidate_card.json` from the given candidate directory (never the pkl, never the merged training CSV — no patient row is read or shown). Writes one self-contained HTML file: no external CSS/JS, no network calls, so it opens identically offline and on a projector. Nothing here writes to the shipped bundle, `reference_scores.json`, or MLflow. This is a read-only view of a `candidate_card.json` that a retraining run already produced. """ from __future__ import annotations import argparse import html import json from pathlib import Path PROJECT_ROOT = Path(__file__).resolve().parent.parent DECISIONS = ("referral", "no_referral", "uncertain") DECISION_LABEL = { "referral": "Referral", "no_referral": "No referral", "uncertain": "Uncertain", } CELLS = ("F0", "F1", "M0", "M1") CELL_LABEL = { "F0": "Female, no disease", "F1": "Female, disease", "M0": "Male, no disease", "M1": "Male, disease", } def esc(x) -> str: return html.escape(str(x)) def pct(x: float) -> str: return f"{x * 100:.2f}%" def render_transition_table(matrix: dict) -> str: counts = matrix["counts"] rows = [] for before in DECISIONS: cells = [] for after in DECISIONS: n = counts[f"{before}__to__{after}"] cls = "diag" if before == after else ("moved" if n else "zero") cells.append(f'{n}') rows.append( f'{DECISION_LABEL[before]}{"".join(cells)}' ) header = "".join(f"{DECISION_LABEL[d]}" for d in DECISIONS) return f""" {header}{"".join(rows)}
Decision transition — shipped model (rows) → candidate (columns), n = {matrix['n']}
shipped ↓ / candidate →
""" def render_coverage_table(coverage: dict) -> str: target = coverage["declared_target"] def row(label: str, kind_key: str, badge: str, badge_cls: str) -> str: c = coverage[kind_key] cells = "".join( f'{pct(c[cell])}n={c[f"n_{cell}"]}' for cell in CELLS ) below = " below-target" if c["marginal"] < target else "" return ( f'{label} ' f'{badge}' f'{pct(c["marginal"])}{cells}' ) header = "".join(f"{CELL_LABEL[c]}" for c in CELLS) return f""" {header} {row("Shipped", "shipped_in_sample", "by construction", "by-construction")} {row("Shipped", "shipped_cross_conformal", "cross-conformal", "cross-conformal")} {row("Candidate", "candidate_in_sample", "by construction", "by-construction")} {row("Candidate", "candidate_cross_conformal", "cross-conformal", "cross-conformal")}
Conformal coverage vs. declared target 1−α = {pct(target)} — by construction = measured on the same rows the quantile was taken from (an identity check, not an estimate); cross-conformal = measured on rows whose Mondrian cell was computed WITHOUT them (5-fold)
Marginal
""" def render_provenance_table(card: dict) -> str: def sha_row(label: str, value: str) -> str: # label is a static string we author, already valid HTML (may carry an # entity like —); only the value, which comes off the card, is # escaped. Escaping the label too turned "—" into the literal # text "—" on the page instead of an em dash. return f'{label}{esc(value)}' def val_row(label: str, value) -> str: return f'{label}{esc(value)}' return f""" {val_row("MLflow run id", card["mlflow_run_id"])} {val_row("Created at (UTC)", card["created_at"])} {val_row("Config version", card["config_version"])} {val_row("Conformal alpha", card["conformal_alpha"])} {val_row("Rows — base UCI / from review queue / rejected / total", f'{card["rows_base_uci"]} / {card["rows_from_review_queue"]} / ' f'{card["rows_rejected"]} / {card["rows_total"]}')} {sha_row("Candidate bundle sha256", card["bundle_sha256"])} {sha_row("Merged training data sha256", card["training_data_sha256"])} {sha_row("Base training CSV sha256", card["base_training_csv_sha256"])} {sha_row("Shipped bundle sha256 (unchanged by this run)", card["shipped_bundle_sha256"])} {sha_row("reference_scores.json sha256 (unchanged by this run)", card["reference_scores_sha256"])}
Identifiers, row counts, and sha256 hashes for this run
""" TEMPLATE = """ Heart candidate vs. shipped — {run_id}

Heart CAD retraining — candidate vs. shipped

Spline-GLM + IVAP + Mondrian conformal · comparison over the 920-patient UCI cohort

CANDIDATE, NOT a replacement promoted: no shipped bundle & reference_scores.json: read-only, unchanged

Decision movement, shipped → candidate

{decisions_changed}
decisions changed / {n_total}
{moved_out}
moved OUT of uncertain
(candidate committed)
{moved_in}
moved INTO uncertain
(candidate withdrew)
{transition_table}

Conformal coverage

{coverage_table}

Provenance

{provenance_table}

Scientific limit

Not a validated model — evidence for a human decision.

{limit_text}
""" def render(card: dict, card_path: Path) -> str: import datetime matrix = card["transition_matrix"] return TEMPLATE.format( run_id=esc(card["mlflow_run_id"]), decisions_changed=matrix["decisions_changed_total"], n_total=matrix["n"], moved_out=matrix["moved_out_of_uncertain"], moved_in=matrix["moved_into_uncertain"], transition_table=render_transition_table(matrix), coverage_table=render_coverage_table(card["conformal_coverage"]), provenance_table=render_provenance_table(card), limit_text=esc(card["limit"]), generated_at=datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%d %H:%M UTC"), card_path=esc(card_path.relative_to(PROJECT_ROOT)), ) def main() -> int: parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("candidate_dir", type=Path, help="models/heart_disease/candidates//") parser.add_argument("--out", type=Path, default=None) args = parser.parse_args() card_path = (args.candidate_dir / "candidate_card.json").resolve() card = json.loads(card_path.read_text()) out = args.out or (PROJECT_ROOT / "reports" / f"heart_candidate_{card['mlflow_run_id'][:12]}.html") out.parent.mkdir(parents=True, exist_ok=True) out.write_text(render(card, card_path)) print(f"wrote {out}") return 0 if __name__ == "__main__": raise SystemExit(main())