Files
Noel Sabia 1ff3bc8290
release-please / release-please (push) Failing after 3s
docs(mission): add weather and holiday context
2026-11-13 20:27:06 +01:00

129 lines
8.2 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Paper — what "halfway good" means and how to get it fast
Status: **hackathon deliverable**, due Sunday 13:00. Target a 4–5 page technical report (PDF). AI can write the prose; you verify every number and citation. The demo takes priority over LaTeX polish.
## What makes it halfway good
A paper is not good because it is long. It is good when a reader can answer these six questions:
1. **What problem, for whom?** A store manager needs a next-week shift plan from footfall data.
2. **What data, with what limits?** 8 sensors, 5 months, 15-minute cadence, 580 m cluster, devices not people.
3. **What method, and why?** Global gradient-boosted model, weather fusion, multi-horizon forecasting, transparent staffing heuristic.
4. **Did it work?** A time-based holdout, a seasonal-naive baseline, MAE/WAPE/R², an ablation. Real numbers.
5. **Does it run?** Nuxt SSR + Go + FastAPI on SKE, Cloudflare Tunnel, SSE, cached fallback, 120-user load test.
6. **What does it not do?** No city-wide heatmap, no POS/labor data, no live sensors, no annual seasonality, no causal claims.
If those six are clear, it is halfway good. Novelty is a bonus, not a requirement for a hackathon technical report.
## Structure (4–5 pages)
| Section | Length | Content |
|---|---:|---|
| Abstract | 150–200 words | Problem, data, method, headline result, deployment. |
| 1. Introduction | 0.5 page | The decision gap; why a dashboard is not enough; three contributions. |
| 2. Data | 0.75 page | PAX counters, 8 sensors, 5 months, 15 min, 580 m, coverage/gaps, device-penetration bias, privacy, Open-Meteo weather, Baden-Württemberg holidays. |
| 3. Method | 1 page | Preprocessing, features (time, lags, weather, holiday), global HistGB, horizons, time-based split, staffing heuristic. |
| 4. System | 0.75 page | Nuxt SSR, Go API/SSE, FastAPI, Cloudflare Tunnel, SKE namespace-only, build-time batch, cached fallback. |
| 5. Evaluation | 1 page | Baseline comparison, weather ablation, holiday effect, per-sensor errors, plan latency, 120-client load test. |
| 6. Discussion & limitations | 0.5 page | 8 sensors, 5 months, observed weather, no POS/labor data, single replica, no auth. |
| 7. Related work | 0.25 page | PAX counters/privacy, pedestrian forecasting, gradient boosting, smart-city dashboards. |
| 8. Conclusion & future work | 0.25 page | More sensors, POS/event data, multi-store, city operations. |
| References | 8–12 | Real, verifiable sources only. |
## Required figures and tables
**Figures (4–5):**
1. Sensor map of the 580 m cluster (8 points; label the sensor names).
2. Hourly and weekday footfall profile (the "pulse").
3. Forecast vs actual for one sensor over the 28-day test (with uncertainty band), with weather/holiday context markers.
4. Architecture diagram (three services + Cloudflare Tunnel + SKE).
5. The staffing plan screen (or a table if the screenshot is weak).
**Tables (3–4):**
1. Data coverage per sensor: readings, mean, p95, max, max gap.
2. Model comparison: seasonal naive vs no-weather vs weather, MAE/WAPE/R².
3. Ablation: weather on/off, holiday on/off; per-sensor MAE.
4. System metrics: plan generation latency, 120 SSE clients, image sizes, deployment time.
## Facts and numbers to use (do not invent)
- **Data:** 192,464 rows total; 96,232 density readings; 12 device IDs; **8 usable sensors**; 3 excluded test sensors.
- **Window:** 2026-06-12 → 2026-11-07 for the 8-sensor network (~5 months); one sensor has 13 months.
- **Cadence:** ~15 minutes (median 15.3); gaps up to 6 days per sensor; 351 days covered overall.
- **Spatial:** ~584 m × 284 m cluster; not city-wide.
- **Values:** 0–292.6; multi-sensor mean ~14.4; median 7.7; p95 46.9; p99 78.4.
- **Pattern:** peak 18:00–21:00 local, top 19:00; Saturday busiest (mean 19.1).
- **Model:** global HistGB; train 2026-06-12 → 2026-10-10; test last 28 days.
- **Baseline:** seasonal naive MAE 5.40, WAPE 44.7%, R² 0.462.
- **No weather:** MAE 4.20, WAPE 34.8%, R² 0.678.
- **With temperature/rain:** MAE **3.36**, WAPE **27.8%**, R² **0.779**.
- **7-day:** MAE 4.37, WAPE 36.2%, R² 0.672.
- **Caveat:** weather is observed, not forecast; no event data; 4-week test; values are device estimates, not people.
- **Weather:** Open-Meteo historical archive for training; forecast API for the dashboard. Temp/rain are the useful features; cloud/wind did not improve the short test.
- **Holidays:** German/Baden-Württemberg public holidays 2025–2026; `is_holiday` feature + dashboard badges. The holiday-only feature added little in the 28-day test (4.15 vs 4.20 without weather; 3.44 vs 3.36 with weather). Report honestly.
- **System:** 3 Deployments + `cloudflared`; no Ingress, no cert-manager, no Jobs; build-time batch; Cloudflare Tunnel; SSE + polling fallback; Go cache; plan < 2 s.
- **Load test:** fill in after k6; do not claim a number you did not measure.
## AI writing prompt
Copy this into the agent that writes the paper. Replace the bracketed values with the real ones after the load test.
```text
You are writing a 4–5 page technical report for a hackathon. Use ONLY the facts in
mission/data.md, mission/mvp.md, mission/architecture.md and the facts below. Do not
invent citations, numbers, datasets, or results. If a fact is missing, write
"[TODO: verify]" instead of guessing.
Topic: PulseCast — a staffing copilot for an inner-city store, built on 8 PAX
counters in Heilbronn. The paper documents the forecasting/scenario core, not the UI.
Facts:
- 192,464 CSV rows; 96,232 density readings; 12 device IDs; 8 usable sensors; 3 excluded.
- 8-sensor window 2026-06-12 to 2026-11-07; ~15-min cadence; 580 m cluster.
- Values are estimated devices, not people; device penetration unknown.
- Peak 18:00–21:00 local; Saturday busiest.
- Weather from Open-Meteo; German/Baden-Württemberg holidays as context features.
- Global HistGradientBoostingRegressor; time-based holdout of 28 days.
- Seasonal naive: MAE 5.40, WAPE 44.7%, R2 0.462.
- No weather: MAE 4.20, WAPE 34.8%, R2 0.678.
- With temperature/rain: MAE 3.36, WAPE 27.8%, R2 0.779.
- 7-day: MAE 4.37, WAPE 36.2%, R2 0.672.
- Weather is observed, not forecast; no event data; 4-week test.
- System: Nuxt 4 SSR + Go API/SSE + FastAPI on STACKIT SKE, namespace-only,
Cloudflare Tunnel, no Ingress/cert-manager/Jobs, build-time batch, cached fallback.
- Staffing plan generated in under 2 seconds from a transparent heuristic with
configurable assumptions (visitors per staff per hour, labor cost, shift length,
minimum staff, safety factor). No POS/sales/labor data.
- Load test: [TODO: k6 result] concurrent SSE clients; [TODO: p95 latency].
Write Markdown with the sections: Abstract, Introduction, Data, Method, System,
Evaluation, Discussion and Limitations, Related Work, Conclusion, References.
Include 4 figure placeholders and 3 table placeholders with captions. Use past tense,
first-person plural, precise numbers, and an explicit limitations paragraph. Cite only
real sources you are confident exist; otherwise write "[CITATION TODO]".
```
## Verification checklist before submission
- [ ] Every number matches `mission/data.md` or a measured result.
- [ ] The baseline table is present; the model is compared to seasonal naive, not only to itself.
- [ ] Weather is described as observed for training, forecast/current for the dashboard.
- [ ] Holidays are described as context/feature, not as a large accuracy lift.
- [ ] The 8-sensor/5-month/580 m limitation is explicit.
- [ ] "Devices, not people" appears at least once.
- [ ] No claim of live sensor data; replay/nowcast is labeled.
- [ ] No fake citations; every reference is real and relevant.
- [ ] The system section matches the actual deployment (Cloudflare Tunnel, no Ingress, no Jobs).
- [ ] The staffing plan is described as decision support with assumptions, not an optimizer with proven ROI.
- [ ] Repo link, data access note, privacy statement, author/acknowledgment.
- [ ] PDF renders; figures are legible; tables fit.
- [ ] 4–5 pages, not 12.
## Schedule
- **Saturday:** agent drafts from the docs; you review the numbers and references; generate figures from the real data.
- **Sunday 07:00–09:00:** finalize the PDF, check the checklist, submit with the deck and code.
- **Do not** let LaTeX or citation hunting delay the demo. A 4-page honest report beats an 8-page invented one.