docs(mission): add weather and holiday context
release-please / release-please (push) Failing after 3s

This commit is contained in:
Noel Sabia committed 2026-11-13 20:27:06 +01:00
1 parent 8afb767585
commit 1ff3bc8290
8 files changed
+109 -25

No files matched your search

+48 -4
View File
@@ -50,7 +50,51 @@ Across the multi-sensor period the weighted mean is ~14.4. Over the full file th
- The inner city peaks **18:00–21:00 local**, with the top at 19:00. Morning is quiet.
- **Saturday is the busiest day** (mean 19.1), then Friday (16.3). Sunday is quieter (11.4) than Monday (11.9).
- The three busiest locations are **Stadtgalerie, Neckarufer and Hagenbuchersee-02**. That is a retail/leisure cluster, which fits the staffing story.
- Weather is a real signal: the quick model below improves by ~20% when temperature/rain/cloud/wind are added.
- Weather is a real signal: the quick model below improves by ~20% when temperature/rain are added.
## Context features: latest weather + German holidays
The dashboard is not just footfall. It also shows the latest Heilbronn weather and the German/Baden-Württemberg public holidays from the past, and the ML microservice uses the same context as features. This is the "why" layer: it explains spikes and makes the forecast feel less like a black box.
### Weather
- **Source:** Open-Meteo, no API key.
- **Historical:** `archive-api.open-meteo.com` for the training/validation window.
- **Current/forecast:** `api.open-meteo.com/v1/forecast` for the dashboard and what-if scenarios.
- **Fields:** `temperature_2m`, `precipitation`, `cloud_cover`, `wind_speed_10m`, `relative_humidity_2m`.
- **Timezone:** `Europe/Berlin`; handle DST explicitly.
- **Dashboard:** current conditions, a 7-day weather strip, and a "weather context" card on the forecast/plan screens.
- **Model:** temperature + rain are the useful features; cloud/wind did not improve the short test. Keep them in the payload for display, but do not claim they improve accuracy.
### German holidays (Baden-Württemberg)
Public holidays in the training window and around the demo:
| Year | Dates |
|---|---|
| 2025 | Jan 1, Jan 6, Apr 18, Apr 21, May 1, May 29, Jun 9, Jun 19, Oct 3, Nov 1, Dec 25, Dec 26 |
| 2026 | Jan 1, Jan 6, Apr 3, Apr 6, May 1, May 14, May 25, Jun 4, Oct 3, Nov 1, Dec 25, Dec 26 |
- **Feature:** `is_holiday` binary + `holiday_name` for display.
- **Dashboard:** holiday badges on the time-series and plan; a tooltip explains "public holiday in Baden-Württemberg."
- **Honest effect:** in the quick 28-day test, the holiday feature alone added little (MAE 4.15 vs 4.20 without weather; 3.44 vs 3.36 with weather). Weather is the main driver. Keep holidays as context and a feature, but do not claim a large accuracy lift.
- **Not included:** school holidays, local events, bridge days. Those are future work.
### How it flows
```text
Open-Meteo historical ──► features ──► training/validation
Open-Meteo current/7d ──► dashboard cards + scenario inputs
BW holiday calendar ──► is_holiday feature + timeline badges
│
▼
FastAPI /predict + /simulate
│
▼
Go API cache ──► Nuxt SSR dashboard
```
The dashboard can show the latest weather without the ML service being available: Go caches the last context payload. The ML service uses weather/holiday inputs when it is healthy; if it is down, the cached forecast still renders.
## What the data does **not** support
@@ -80,10 +124,10 @@ A deliberately small, reproducible baseline — not a tuned model. Hourly target
2. Merge `density-01` device IDs into one logical sensor.
3. Exclude `maker-fair`, `niklas-01`, `hn-bollwerksturm-01`.
4. Aggregate to hourly means per sensor; keep 15-minute data for the drill-down view.
5. Join historical/forecast weather from Open-Meteo; join Baden-Württemberg holidays.
5. Join historical/forecast weather from Open-Meteo; join Baden-Württemberg holidays; export a `context.json` for the dashboard.
6. Train the global model; validate on a time-based holdout; export `forecasts.json`, `metrics.json`, `sensors.json`.
7. Bake the JSON into the Go binary (or serve from a volume). No runtime Python dependency.
8. Show data coverage and model metrics in the app's "About the data" panel.
7. Bake the model into the FastAPI image and the fallback JSON into Go. No runtime data fetch is required for the demo.
8. Show data coverage, weather/holiday context and model metrics in the app's "About the data" panel.
## Open data questions for the mentors