Wekelijkse onderhandelingsbrief

Focus: kortere-termijn (4 weken vooruit – 12 weken vooruit) prijsvooruitblik, top 3 aanjagers, voorgestelde gespreksstof. Highlights uit deze run:

• CV: €6.35 · Δ ▼ 4.88 · Model None
• 4 weken vooruit: €6.64 · Δ ▼ 1.03 · Model GradientBoosting_ARDL
• 8 weken vooruit: €10.69 · Δ ▲ 0.52 · Model GradientBoosting_ARDL

Download CSV- / JSON-bestanden direct vanuit /data (zie manifest hieronder).

Maandelijkse deep dive

Gebaseerd op ARDL_Analysis_Final_Report.md en NW_EUROPE_POTATO_MARKET_EVENTS_2025.md. 28 weken vooruit laat 56.2% verbetering t.o.v. de baseline zien, grotendeels gedreven door futures_sentiment- en logistics_disruption-factoren.

Slide-deckfragmenten behandelen: areaal & plantsnelheid, dieselkostengevoeligheid, opslagverliesmonitoring en exportvraagimpulsen.

Brondocumentatie

Manifest en artefacten

Bronpad: /app/experiments/FAMILY_HORIZON_FEATURES_ALL/production_models/2025-12-06_00-45-53

Modelkaart

Doelstelling: Voorspel Nederlandse verwerkingsaardappelprijzen 4–28 weken vooruit ter ondersteuning van onderhandelingen.

Doelvariabelen: Canonieke wekelijkse Landbouw + Boerderij-prijs (EUR/100 kg).

Featurefamilies:

• Autoregressieve prijsvertragingen (0, 1, 8 weken)
• Voortschrijdende gemiddelden van CBS-dieselprijzen (4w/8w)
• Open-Meteo-opbouw van groeigraad­dagen
• LLM-afgeleide signalen voor verwerkingsbenutting & bewaarbaarheid
• Kalender­pulsen (weeknummer, afstand tot feestdagen)

Veiligheidsnotities:

• Handmatige QA op 4.644 nieuwsartikelen onthulde een dag-maand-verwisselfout van 41,5% (FINAL_COMPREHENSIVE_DATE_EXTRACTION_REPORT.md).
• Gegevensherkomst wordt per run gelogd — zie het manifest in de voorspellingsmap.

Ethische waarborgen:

• Geen individuele telersdata; uitsluitend geaggregeerde marktindicatoren.
• Menselijke beoordeling voordat onderhandelingsbrieven worden verspreid.

Primaire onderzoeksartefacten

Validatiestatistieken

Databronnen

Featurelegenda

Wijzigingslogboek

• 2025-12-06T02:40:40Z — Laatste productierun · CSV- en modelartefacten geëxporteerd vanuit /app/experiments/FAMILY_HORIZON_FEATURES_ALL/production_models/2025-12-06_00-45-53.
• 2025-08-27 — Eventcatalogus 1.0 · NW_EUROPE_POTATO_MARKET_EVENTS_2025.md gepubliceerd met grensoverschrijdende dynamiek.
• 2025-05-14 — Datum-QA-mijlpaal · 41,5%-wisselfout vastgelegd in FINAL_COMPREHENSIVE_DATE_EXTRACTION_REPORT.md met herstelplan.

Hoe trainen we de 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 · `train_and_predict_production.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 RandomForest, Ridge en LinearRegression varianten (de code staat in predictions_multiple_horizons_ARDL.py). In productie houden we het bij GradientBoosting omdat die het beste presteert en robuust is voor kleine feature-sets.
• 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: train_and_predict_production.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

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 feature_sets_config.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.

Procesoverzicht

1. 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).

2. 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).

3. Modeltraining

   `train_and_predict_production.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.

4. 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.

CV-instellingen

• 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
• Naïeve check Vandaag = morgen (referentie voor sanity checks)
• Trendscore Correcte richting t.o.v. actuele prijs, alleen wanneer |Δ| ≥ €2

Horizonprestaties

Scenario-checklist

• Pas de schuiven voor areaal, opbrengst, opslag, energie en vraag aan om contracten te stress-testen.
• Bewaar scenario-uitvoer als onderdeel van de onderhandelingsdocumenten voor coöperatiebesturen.

Onze reis tot nu toe

Rollen & workflows

• Hypotheseredacteur (HE) — Houdt het hypotheseregister scherp en afgestemd op de datapraktijk (team/roles.md).
• Experimentator (EX) — Voert rolling-origin-CV uit, draait Diebold–Mariano-tests en logt artefacten naar MLflow bij elke release.
• Onderzoeksagent (RA) — Brengt externe agronomische inzichten boven tafel, valideert databronnen en borgt documentatie.

Zie team/roles.md en team/all.md voor draaiboeken over hoe we experimenten uitvoeren, bevindingen documenteren en hypotheses scherp houden.