Technical Documentation

Modellarchitektur, Feature Engineering, Evaluation und API — für Data Scientists, ML Engineers und alle, die es genau wissen wollen. 📘 Interactive API Docs (Swagger)

1. System Overview

Multi-Horizon Occupancy Forecasting für 110 Parkhäuser in 5 Schweizer Städten. Vier unabhängige Modelle (h ∈ {1, 2, 4, 8}) prognostizieren alle 15 Minuten die Belegungsquote occ = (total − free) / total ∈ [0, 1]. Zusätzlich ein Quantil-Modell (α = 0.2) und ein Binärklassifikator (P(free < 5)) pro Horizont.

2. Model Architecture

2.1 Regression (Punktprognose)

2.2 Quantile Regression (pessimistisch)

2.3 Binary Classifier (Voll-Wahrscheinlichkeit)

2.4 Baseline (Referenzmodell)

Saisonaler Mittelwert je (parkhaus, wochentag, stunde, viertelstunde) über 8 Wochen, mit Rückfallkette auf Stundenmittel → Stadtmittel → Hausmittel. Additive Zuschläge für aktive Events (+Bonus) und Regen > 0.5 mm (+2 pp). Dient ausschliesslich als Benchmark — kein Ensemble-Bestandteil.

2.5 Bias-Korrektur (Post-Processing)

Pro (city, pls_id, horizon_h) wird der gewichtete mittlere Bias der letzten 14 Tage berechnet:

w(d) = exp(−0.14 × d)              Halbwertszeit ≈ 5 Tage
bias = Σ(bias_free × n × w(d)) / Σ(n × w(d))    letzte 14 Tage, min. 50 Evaluationen
free_korrigiert = free − round(bias)

Exponentiell gewichtet: jüngere Tage haben mehr Einfluss, damit der Bias schnell auf Veränderungen reagiert (z.B. Baustellen, geänderte Kapazitäten). Wird nur auf ML-Prognosen angewandt, nicht auf Baseline.

3. Feature Engineering

40 Features pro Observation, gruppiert nach Kategorie:

Temporal (zyklisch kodiert)

hour quarter weekday is_weekend month sin_hour cos_hour sin_weekday cos_weekday sin_month cos_month

Kalender

is_holiday is_bridge_day is_school_holiday

Kantonale Feiertage (BS, BE, LU, SG, ZH) inkl. Osterdatum-basierte bewegliche Feiertage. Brückentage zwischen Feiertag und Wochenende. Schulferien pro Kanton und Jahr. Gespeichert in ai_feiertage und ai_schulferien.

Lag Features & Statistiken

occ_now occ_1h_ago occ_2h_ago occ_3d_ago occ_24h_ago occ_7d_ago delta_occ_1h trend_2h occ_mean_3h occ_mean_24h occ_std_24h prior_occ

prior_occ = saisonaler Erwartungswert aus dem Trainingsteil (kein Leakage ins Holdout). delta_occ_1h = Momentum der letzten Stunde. Fehlende Lags bleiben NaN — LightGBM handhabt das nativ.

Wetter

temperature precipitation is_raining temp_bin temp_sq

Quelle: Open-Meteo API, stündlich pro Stadt. is_raining = binäres Flag bei > 0.1 mm. Zum Zielzeitpunkt interpoliert.

Events

event_active event_soon event_bonus event_category

Echte Veranstaltungsdaten von Venue-Websites (Hallenstadion, Tonhalle, Stadtcasino Basel, Luzerner Theater, OLMA). event_bonus = kategorieabhängiger Zuschlag (Konzert 0.40, Sport 0.45, Messe 0.50 etc.). event_soon = Event beginnt innerhalb der nächsten 3 Stunden. event_category = kategorische Variable (Konzert, Sport, Messe, …).

Interaktions-Features

weekend_event rain_hour

weekend_event = is_weekend × event_active — Events am Wochenende haben stärkeren Effekt. rain_hour = is_raining × hour — Regen wirkt je nach Tageszeit unterschiedlich.

Metadaten

log_total city pls_key

log_total = log(Kapazität) — normalisiert den Grösseneffekt. city und pls_key sind kategorial kodiert.

4. Training Pipeline

5. Evaluation & Metriken

5.1 Aktuelle Performance (letzte 7 Tage, Prod)

Metriken erklärt:

• MAE_free — Mean Absolute Error in freien Plätzen. Anschaulich, aber abhängig von der Hausgrösse.
• MAE_occ — MAE in Belegungsprozentpunkten. Vergleichbar über unterschiedlich grosse Häuser.
• Bias_free — systematische Abweichung. Positiv = Modell überschätzt die freien Plätze.
• Skill Score — 1 − MAE(ML) / MAE(Baseline). 0.72 = 72 % weniger Fehler als der saisonale Durchschnitt. Negativ = Modell schlechter als Baseline.
• R² (Bestimmtheitsmass) — 1 − SSres / SStot. Anteil der erklärten Varianz. 0.85 = das Modell erklärt 85 % der Belegungsschwankungen. Berechnet auf dem Holdout (letzte 14 Tage) und beim Training gespeichert.
• Bewusst kein MAPE: bei free → 0 explodiert der relative Fehler.

5.2 Evaluation Pipeline

1. Alle 15 Min: gereifte Prognosen dem nächsten Messwert zuordnen (±20 Min Toleranz)
2. Fehler berechnen: error = predicted_free − actual_free
3. Tagesweise aggregieren in ai_accuracy_daily: MAE, Bias, Anzahl je (day, city, pls_id, model_type, horizon_h)
4. Stadtweite und globale Aggregate separat (mit pls_id = '')

6. Data Pipeline

Scanner (alle 15 Min)
│  Stadt-APIs → pls_fetch_current (~1.6 Mio Zeilen)
│  Open-Meteo  → weather_forecasts (2× täglich)
│  Venues      → local_events + event_parkhaus (2× täglich, automatisch)
│
FastAPI-ML (Port 80)
├── :10/:25/:40/:55  predict.py   → ai_predictions
│   └── Bias-Korrektur aus ai_accuracy_daily
├── :13/:28/:43/:58  evaluate.py  → ai_accuracy_daily
├── 03:15            identity.py  → ai_parkhaus_map
└── 03:30            train.py     → ai_model_runs + models_store/
                     └── Regression + Quantile + Classifier × 4 Horizonte

Rasterung & Preprocessing

• Messwerte werden auf ein striktes 15-Minuten-Raster gelegt (letzter Wert je Slot)
• Lücken bis 1 Stunde: Forward-Fill. Längere Lücken: NaN (fallen aus dem Training)
• Zielgrösse: occ = (total − free) / total — ermöglicht ein globales Modell über Häuser mit 50 bis 1100 Plätzen
• Rückrechnung auf freie Plätze via letztes bekanntes total

7. Parkhaus Identity Mapping

Die Messwert-IDs (pls_fetch_current.id) und Stammdaten-IDs (parkhaeuser.id) verwenden unterschiedliche Namenskonventionen:

Zentral gelöst in core/identity.py, Ergebnis in ai_parkhaus_map. Häuser ohne Treffer werden trotzdem prognostiziert — nur ohne Event-Features.

8. REST API

Vollständige, interaktive Dokumentation: 📘 Swagger UI öffnen

Alle Endpunkte akzeptieren ?env=prod|test.

9. Datenbank-Schema

MariaDB, zwei parallele Instanzen: ph_fetch_prod und ph_fetch_test. Die KI-App liest bestehende Tabellen nur und schreibt ausschliesslich in ai_-präfixierte Tabellen.

Scanner-Tabellen (read-only)

KI-Tabellen (read-write)

10. Stack & Deployment

11. Change History

Änderungsprotokoll aus der Zusammenarbeit mit Claude Code — Anfrage und Umsetzung.