"""Generate the paper figures from the delivered CSV and the trained model. Run from the ML worktree so the `pulsecast` package is importable: cd ML-py.git/feat-ml-bootstrap PYTHONPATH=src .venv/bin/python \ /home/noel/Documents/Hackathon_2026/paper/research/scripts/02_paper_figures.py Writes to `paper/figures/`. """ from __future__ import annotations import json from pathlib import Path import matplotlib matplotlib.use("Agg") import matplotlib.pyplot as plt import numpy as np import pandas as pd from matplotlib.patches import FancyArrowPatch, FancyBboxPatch ROOT = Path("/home/noel/Documents/Hackathon_2026") PAPER = ROOT / "paper" FIG = PAPER / "figures" FIG.mkdir(parents=True, exist_ok=True) CSV = ROOT / "data" / "raw" / "schwarz-pax.csv" SENSORS = [ "hn-stadtgalerie-01", "hn-neckarufer-01", "hn-hagenbuchersee-02", "hn-marahaus-01", "hn-hagenbuchersee-01", "hn-goetzentuem-01", "hn-soleo-01", "density-01", ] plt.rcParams.update( { "figure.dpi": 160, "savefig.dpi": 160, "font.size": 8, "axes.titlesize": 9, "axes.labelsize": 8, "legend.fontsize": 7, "xtick.labelsize": 7, "ytick.labelsize": 7, } ) def sensor_map() -> None: df = pd.read_csv(CSV) d = df[(df["type"] == "densityData") & (df["name"].isin(SENSORS))] coords = ( d.groupby("name")[["longitude", "latitude"]] .agg(["median"]) .droplevel(1, axis=1) .reindex(SENSORS) ) labels = { "hn-stadtgalerie-01": "Stadtgalerie", "hn-neckarufer-01": "Neckarufer", "hn-hagenbuchersee-02": "Hagenbuchersee 02", "hn-marahaus-01": "Marahaus", "hn-hagenbuchersee-01": "Hagenbuchersee 01", "hn-goetzentuem-01": "Götzenturm", "hn-soleo-01": "Soleo", "density-01": "density-01", } fig, ax = plt.subplots(figsize=(7.0, 3.5)) for i, (name, row) in enumerate(coords.iterrows(), start=1): ax.scatter(row["longitude"], row["latitude"], s=46, c="#0b6e99", zorder=3) ax.annotate( str(i), (row["longitude"], row["latitude"]), xytext=(4, 4), textcoords="offset points", fontsize=7, color="#0b3d4f", fontweight="bold", ) ax.set_xlabel("Longitude") ax.set_ylabel("Latitude") ax.set_title("Eight PAX counter locations, Heilbronn inner city") ax.grid(True, color="#e5e5e5", linewidth=0.5) ax.set_aspect("equal", adjustable="datalim") handles = [ plt.Line2D( [0], [0], marker="o", color="w", markerfacecolor="#0b6e99", markersize=5, label=f"{i} {labels[name]}", ) for i, name in enumerate(coords.index, start=1) ] ax.legend( handles=handles, loc="center left", bbox_to_anchor=(1.01, 0.5), frameon=False, fontsize=6.5, handletextpad=0.4, ) fig.tight_layout() fig.savefig(FIG / "fig_sensor_map.png", bbox_inches="tight") plt.close(fig) def forecast_plot() -> None: from pulsecast import config from pulsecast.model import fit, metrics from pulsecast.train import _load_inputs hourly, features, archive, forecast, meta, audit = _load_inputs() data_end = hourly["t"].max() test_start = data_end.floor("h") - pd.Timedelta(days=config.TEST_DAYS) train = features[features["t"] < test_start].copy() test = features[features["t"] >= test_start].copy() eval_frame = test[test["lag_168"].notna() & test["y"].notna()].copy() model = fit(train, config.FEATURE_WEEK_WEATHER) pred = np.clip(model.predict(eval_frame[config.FEATURE_WEEK_WEATHER]), 0.0, None) eval_frame["pred"] = pred sensor = "hn-stadtgalerie-01" g = eval_frame[eval_frame["sensor"] == sensor].sort_values("t").copy() if g.empty: sensor = sorted(eval_frame["sensor"].unique())[0] g = eval_frame[eval_frame["sensor"] == sensor].sort_values("t").copy() residual = g["y"].to_numpy() - g["pred"].to_numpy() sd = float(np.std(residual, ddof=1)) t = pd.to_datetime(g["t"]) fig, ax = plt.subplots(figsize=(6.4, 3.0)) ax.plot(t, g["y"], color="#222222", linewidth=1.0, label="actual") ax.plot(t, g["pred"], color="#0b6e99", linewidth=1.4, label="forecast") ax.fill_between( t, np.clip(g["pred"] - 1.96 * sd, 0, None), g["pred"] + 1.96 * sd, color="#0b6e99", alpha=0.16, linewidth=0, label="±1.96 residual SD", ) ax.set_title(f"Forecast vs actual, {sensor}, 28-day holdout") ax.set_ylabel("published index") ax.grid(True, color="#e5e5e5", linewidth=0.5) ax.legend(loc="upper left", frameon=False, ncol=3) fig.autofmt_xdate(rotation=0, ha="center") fig.tight_layout() fig.savefig(FIG / "fig_forecast.png", bbox_inches="tight") plt.close(fig) # Save the numbers used in the plot for reproducibility. (FIG / "fig_forecast_meta.json").write_text( json.dumps( { "sensor": sensor, "n": int(len(g)), "residual_sd": sd, "metrics": metrics(g["y"], g["pred"]), }, indent=2, ) + "\n" ) def architecture() -> None: fig, ax = plt.subplots(figsize=(7.8, 4.2)) ax.set_xlim(0, 11) ax.set_ylim(0, 6.5) ax.axis("off") def box(x, y, w, h, text, fc="#eef5f9", ec="#0b6e99"): p = FancyBboxPatch( (x, y), w, h, boxstyle="round,pad=0.05,rounding_size=0.12", linewidth=1.0, edgecolor=ec, facecolor=fc, ) ax.add_patch(p) ax.text(x + w / 2, y + h / 2, text, ha="center", va="center", fontsize=7) def arrow(x1, y1, x2, y2, ls="-"): ax.add_patch( FancyArrowPatch( (x1, y1), (x2, y2), arrowstyle="-|>", mutation_scale=9, linewidth=0.9, color="#444444", linestyle=ls, ) ) box(0.2, 4.9, 1.8, 0.8, "phones / laptop\nNuxt SSR + Onyx") box(2.5, 4.9, 1.8, 0.8, "Cloudflare\nedge + Tunnel") box(4.8, 4.9, 1.5, 0.8, "cloudflared\npod") box(7.0, 5.2, 1.7, 0.8, "Nuxt SSR\nweb pod") box(7.0, 3.6, 1.7, 0.8, "Go API\nSSE + cache") box(9.3, 3.6, 1.5, 0.8, "FastAPI ML\npredict / simulate") box(1.2, 1.2, 2.3, 0.8, "build-time batch\nCSV → model + JSON") box(4.2, 1.2, 2.3, 0.8, "baked images\nmodel + fallback JSON") arrow(2.0, 5.3, 2.5, 5.3) arrow(4.3, 5.3, 4.8, 5.3) arrow(5.55, 5.3, 7.0, 5.6) arrow(5.55, 5.15, 7.0, 4.0) arrow(7.85, 5.2, 7.85, 4.4) arrow(8.7, 4.0, 9.3, 4.0) arrow(3.5, 1.6, 4.2, 1.6) arrow(5.35, 2.0, 7.2, 3.6, ls="--") arrow(5.9, 2.0, 9.6, 3.6, ls="--") ax.text(8.0, 4.55, "internal HTTP", fontsize=6, color="#555555") ax.text(7.05, 3.42, "cached fallback", fontsize=6, color="#555555") ax.text(6.1, 2.35, "baked at build time", fontsize=6, color="#555555") ax.set_title("PulseCast deployment: three services, Cloudflare Tunnel, build-time batch") fig.tight_layout() fig.savefig(FIG / "fig_architecture.png", bbox_inches="tight") plt.close(fig) if __name__ == "__main__": sensor_map() forecast_plot() architecture() print("wrote figures to", FIG)