Add PulseCast paper drafts, figures, references, and research notes

This commit is contained in:
Noel Sabia committed 2026-11-14 06:32:23 +01:00
commit c691324227
69 files changed
+23137

No files matched your search

+240
View File
@@ -0,0 +1,240 @@
"""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)