Methodiek & Validatie

Hoe trainden we de oude direct-price modellen?

• Gegevensopbouw · We laden canonieke weekprijzen uit de gecombineerde Landbouw + Boerderij-feed, synchroniseren ze via `_canonicalize_weekly_prices` en koppelen externe bronnen (CBS diesel, Open-Meteo, Boerderij-sentiment en Gemini-nieuwsfeatures).
• Feature-engineering · Per horizon gebruiken we de samengestelde ‘mixed v4’-sets (diesel MA's, kwaliteit/bewaarsentiment, verwerkingsbenutting, cumulatieve groeigraden, week-of-year en feestdag-afstanden) met prijs-lags (0,1,8) en exogene lags (0,1,8,12).
• Modeltraining · `src/forecasting/production_training.py` bouwt één consistent ARDL-datasetpakket, draait rolling-origin CV per horizon en traint vervolgens `GradientBoostingRegressor` op alle complete rijen met dezelfde scaler/pipeline als in productie.
• Export & Controle · Elke horizon levert `model.joblib`, `scaler.joblib`, CV-predictions, live voorspellingen, feature-insights en een manifest zodat de dashboardservice exact dezelfde artefacten kan renderen.

Van ruwe data naar modelklare dataset

1. Ontsluiten: APIs en scrapers leveren dagelijkse of wekelijkse reeksen. We bewaren elke bron in zijn eigen map onder src/sources zodat updates traceerbaar blijven.
2. Kalenderen: _canonicalize_weekly_prices zet álle weekreeksen op dezelfde ISO-week (maandag) en dwingt unieke sleutel week_start af. Hierdoor missen we nooit een horizon doordat er een RVO-week “ontbreekt”.
3. Lags en gaps: Via _calendar_lag_merge voegen we prijs- en exogene lags toe zónder shift-trucs. Korte gaten (≤16 weken) worden forward-filled, langere gaten blijven NaN en worden uitgesloten zodat we geen verzonnen data creëren.
4. CV-pakketten: create_experiment_datasets levert meteen AR- én ARDL-matrices plus metadata (laglijsten, aantal weeks). Deze bestanden gaan rechtstreeks de training, de productie-run en het dashboard in.

Het gevolg: dezelfde dataset voedt zowel onderzoek, productie als visualisatie. Geen “it worked on my notebook”-effecten.

Hoe ziet de modellering er exact uit?

• Modelbibliotheek: Naast GradientBoosting trainen we tijdens onderzoek ook XGBoost, RandomForest, Ridge en LinearRegression varianten (de code staat nu in src/forecasting/ardl_feature_training.py). In productie houden we het bij GradientBoosting omdat dat op deze branch nog steeds de beste gevalideerde ARDL-score laat zien; XGBoost blijft volledig ondersteund voor reproduceerbare trainingsruns.
• Train/test scheiding: Rolling-origin CV (expanderend venster, 4-weekse stappen) simuleert een realistische live omgeving. Elke fold levert één voorspelling per horizon, zodat we statistische toetsen (Diebold-Mariano, Harvey-Leybourne-Newbold) kunnen uitvoeren.
• Bewaren van modellen: De recepten voor de laatste fold (scalers, pipelines, modelobjecten) worden opgeslagen in production_models/<timestamp>. Het dashboard gebruikt exact dezelfde bestanden voor zowel historische als actuele voorspellingen.
• Uitlegbaarheid: feature_insights.json bevat importances, correlaties en de laatste featurewaarden. Deze bestanden voeden direct de driver-tabellen en toelichtingen op het dashboard.

Omdat alles (datasets, CV-resultaten, feature-insights) als Parquet/JSON wordt weggeschreven, kunnen we elke run achteraf volledig reproduceren of inspecteren. Geen verborgen “handmatige fixes”.

Belangrijkste databronnen en wat ze betekenen

Wat doen we vóór een productie-run?

1. Nieuwsfeatures bijwerken: ensure_news_features_up_to_date checkt of de geconsolideerde JSON alle ISO-weken dekt. Ontbrekende weken triggeren automatisch fetch → clean → dedup → sample → extract → convert.
2. Dataset sanity: create_experiment_datasets wordt voor elke horizon één keer gedraaid zodat alle metingen gelijk “vers” zijn (zelfde window, zelfde lagregels).
3. Training + evaluatie: src/forecasting/production_training.py start CV, fit het volledige model, exporteert predictions + rapporten en logt alles in production_models/<timestamp>.
4. Weekly predictions service: services/weekly_predictions kan hetzelfde proces in Docker draaien en de outputs rechtstreeks naar service_outputs dumpen voor het dashboard.

Zo houden we research, productie en visualisatie in één lijn en kunnen we exact zien welke data en modellen een dashboard-run bevatten.

Kruisvalideringsopzet

Initieel trainvenster

104 weken (expanderend)

Stapgrootte

4 weken

CV-folds

70–95 (afhankelijk van horizon)

Doel

Prijsniveau (EUR/100 kg) op h weken vooruit

Baseline

GradientBoosting met alleen prijs-lags (vergelijkingsbaseline)

Naïeve check

Vandaag = morgen (referentie voor sanity checks)

Trendscore

Correcte richting t.o.v. actuele prijs, alleen wanneer |Δ| ≥ €2

De trendscore die je hieronder ziet is afgeleid van de CV-voorspellingen: we vergelijken de voorspelde prijsverandering versus de laatste bekende prijs en tellen alleen weken mee waarin de gerealiseerde beweging groter is dan €2. Dat sluit de ruis rond vlakke periodes uit.

Horizonresultaten (laatste productie-run)

Merk vooral het verschil tussen 24 w en 28 w op: dezelfde featurefamilie, maar 28 w ontwijkt de drukke decemberperiode en blijft daardoor op MAE ≈ €3,9 met een trendscore van 89%. Voor 24 w werken we aan extra vraag-/feestdagfeatures om de staartfouten te verkleinen.

Hoe interpreteer je de cijfers?

• MAE vertelt hoeveel euro de voorspelling gemiddeld naast de realisatie zat. Onder €4 betekent praktisch bruikbare signalen voor onderhandelingen.
• MAPE stijgt bij lange horizons omdat het prijsbereik enorm is (van €5 tot €60). Kijk daarom altijd ook naar de absolute fout.
• Trendscore is dé beslismetric: het aandeel weken waarin we de richting correct hebben zodra de markt écht beweegt (> €2). Waarden boven 80% geven vertrouwen voor alerts en scenario’s.
• Baseline en naïef dienen als sanity check. Als de productie-run ooit slechter presteert dan “vandaag = morgen”, stoppen we de deployment automatisch.

Featurefamilies per horizon

De exacte kolomnamen vind je in src/pipeline/feature_sets.py en in de feature_insights.json per horizon. Alles wat we tonen in het dashboard komt rechtstreeks uit die bestanden.

Wat betekenen de extra metrics?

• Trendscore (Δ ≥ €2): alleen weken waarin het verschil tussen actuele prijs en doelprijs groter is dan €2 tellen mee. Een vlakke markt wordt zo niet overschat.
• Naïeve benchmark: “Vandaag = morgen”. Geeft direct aan hoeveel absolute fout er puur door ruis ontstaat. In onze CV-run blijft deze regel steevast boven €11 voor de lange horizons.
• Baseline (GB + prijs): laat zien wat er gebeurt als we alle exogene signalen weglaten. Als de ARDL-variant ooit slechter scoort dan deze baseline, gaat er iets mis in de feature-pipeline.

Tip: combineer de trendscore met MAE voor beslissingen. Een horizon met MAE ±€4 maar 90% richtingsnauwkeurigheid is bruikbaarder dan een horizon met MAE ±€3 maar slechts 60% juiste richting.

Verder lezen

Wil je de volledige beschrijving inclusief testscripts, exact dezelfde tabel en een samenvatting van de 24 w vs. 28 w-analyse meekrijgen? Bekijk dan docs/model_training_report.md in de repo. Daar linken we ook naar tmp_model_cv_summary.csv en tmp_model_cv_direction.csv, zodat je onze tabel makkelijk kunt importeren in eigen rapportages.

Daarnaast vind je in docs/model_performance_summary.md een compacte versie van de tabellen en in docs/methodology-secties een Engelstalige breakdown. Alles draait rond dezelfde artefacten die dit dashboard ook gebruikt – er is geen verborgen logica buiten de repo.