#!/usr/bin/env python3
"""Render dependency-free SVG figures from ``artifacts/metrics.json``.
The paper figures are generated from the measured holdout metrics, never
hand-written. Run ``make figures`` after ``make train``.
"""
from __future__ import annotations
import argparse
import json
from pathlib import Path
from xml.sax.saxutils import escape
from pulsecast import config
MODEL_COLOR = "#2563eb"
BASELINE_COLOR = "#94a3b8"
PRODUCTION_COLOR = "#0f766e"
TEXT_COLOR = "#0f172a"
GRID_COLOR = "#e2e8f0"
def _svg_document(
title: str,
subtitle: str,
body: list[str],
width: int,
height: int,
footer: str = "Source: artifacts/metrics.json · PulseCast 28-day time-based holdout",
) -> str:
return "\n".join(
[
f'",
"",
]
)
def _bar_chart(
title: str,
subtitle: str,
rows: list[dict],
*,
value_key: str = "mae",
secondary_key: str | None = None,
secondary_label: str | None = None,
primary_label: str = "MAE",
production: str | None = None,
) -> str:
width = 960
left = 230
right = 96
top = 86
row_height = 38
height = top + row_height * len(rows) + 56
plot_width = width - left - right
values = [row[value_key] for row in rows]
if secondary_key:
values += [row[secondary_key] for row in rows]
maximum = max(values) * 1.08 if values else 1.0
body: list[str] = []
for tick in range(5):
x = left + plot_width * tick / 4
value = maximum * tick / 4
body.append(
f''
)
body.append(
f'{value:.1f}'
)
legend_y = top - 34
if secondary_key:
body.append(
f''
f''
f"{escape(secondary_label or 'baseline')}"
)
body.append(
f''
f''
f"{escape(primary_label)}"
)
for index, row in enumerate(rows):
y = top + index * row_height
label = str(row.get("name") or row.get("sensor"))
body.append(
f'{escape(label)}'
)
if secondary_key:
baseline_width = plot_width * row[secondary_key] / maximum
body.append(
f''
)
body.append(
f'{row[secondary_key]:.2f}'
)
model_width = plot_width * row[value_key] / maximum
body.append(
f''
)
body.append(
f'{row[value_key]:.2f}'
)
else:
color = PRODUCTION_COLOR if production and row.get("name") == production else MODEL_COLOR
bar_width = plot_width * row[value_key] / maximum
body.append(
f''
)
body.append(
f'{row[value_key]:.2f}'
)
return _svg_document(title, subtitle, body, width, height)
def _confusion_svg(small: dict) -> str:
matrix = small["confusion_matrix"]
metrics = small["metrics"]
width, height = 760, 520
left, top, cell = 200, 130, 190
values = {
(0, 0): ("TN", matrix["tn"]),
(0, 1): ("FP", matrix["fp"]),
(1, 0): ("FN", matrix["fn"]),
(1, 1): ("TP", matrix["tp"]),
}
maximum = max(value for _, value in values.values())
body: list[str] = []
body.append(
f'Predicted not busy'
)
body.append(
f'Predicted busy'
)
row_labels = ("Actually\nnot busy", "Actually\nbusy")
for row, label in enumerate(row_labels):
y = top + row * cell
body.append(
f'{escape(label).replace(chr(10), " ")}'
)
for (row, column), (code, value) in values.items():
x = left + column * cell
y = top + row * cell
intensity = 0.12 + 0.88 * (value / maximum)
red = round(219 + (29 - 219) * intensity)
green = round(234 + (78 - 234) * intensity)
blue = round(254 + (216 - 254) * intensity)
fill = f"#{red:02x}{green:02x}{blue:02x}"
text_color = "#ffffff" if intensity > 0.55 else TEXT_COLOR
row_total = matrix["tn"] + matrix["fp"] if row == 0 else matrix["fn"] + matrix["tp"]
share = 100.0 * value / row_total if row_total else 0.0
body.append(
f''
)
body.append(
f'{value:,}'
)
body.append(
f'{code} · {share:.1f}% of row'
)
subtitle = (
f"n={metrics['n_test']:,} · accuracy {metrics['accuracy']:.3f} · "
f"precision {metrics['precision']:.3f} · recall {metrics['recall']:.3f} · "
f"F1 {metrics['f1']:.3f} · ROC-AUC {metrics['roc_auc']:.3f}"
)
return _svg_document(
"Small busy-hour classifier: holdout confusion matrix",
subtitle,
body,
width,
height,
footer="Source: artifacts/small_metrics.json · chronological 80/20 split",
)
def main(argv: list[str] | None = None) -> int:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument(
"--artifacts",
type=Path,
default=config.artifacts_dir(),
help="artifact directory containing metrics.json (default: %(default)s)",
)
parser.add_argument(
"--out",
type=Path,
default=Path(__file__).resolve().parents[1] / "docs" / "figures",
help="output directory for SVG files (default: %(default)s)",
)
args = parser.parse_args(argv)
metrics = json.loads((args.artifacts / "metrics.json").read_text())
holdout = f"Holdout {metrics['test_from']} .. {metrics['test_to']}, n={metrics['metrics']['n_eval']}"
args.out.mkdir(parents=True, exist_ok=True)
ablation = _bar_chart(
"Ablation: holdout MAE by feature set",
holdout,
[
{
"name": row["name"].replace("_", " "),
"mae": row["mae"],
}
for row in metrics["ablation"]
],
production="week weather",
)
ablation_path = args.out / "ablation_mae.svg"
ablation_path.write_text(ablation)
per_sensor = _bar_chart(
"Per-sensor holdout MAE: production model vs seasonal naive",
holdout,
metrics["per_sensor"],
secondary_key="baseline_mae",
secondary_label="seasonal naive",
primary_label="weather-7d",
)
per_sensor_path = args.out / "per_sensor_mae.svg"
per_sensor_path.write_text(per_sensor)
confusion_path = args.out / "small_model_confusion.svg"
confusion_path.write_text(_confusion_svg(metrics["small"]))
print(f"wrote {ablation_path}")
print(f"wrote {per_sensor_path}")
print(f"wrote {confusion_path}")
return 0
if __name__ == "__main__":
raise SystemExit(main())