129 lines
8.2 KiB
Markdown
129 lines
8.2 KiB
Markdown
# 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.
|