Configuratie

De pipeline wordt geconfigureerd via configuration/configuration.json.

Beginnen

Voer eenmalig studentprognose init uit in je werkmap. Dit schrijft een startconfiguratie met alle standaardwaarden. Je hoeft daarna alleen de velden aan te passen die bij jouw instelling afwijken.

Hoe configuratie laden werkt

De pipeline laadt altijd eerst de ingebakken standaardwaarden uit het package, en past jouw configuration.json daar bovenop als een overschrijving. Dat betekent:

• Je hoeft alleen te specificeren wat afwijkt van de standaard.
• Een ontbrekend veld in jouw bestand valt automatisch terug op de standaardwaarde.
• Als het configuratiebestand helemaal niet bestaat, worden de standaardwaarden gebruikt en verschijnt er een waarschuwing.

Het bestand heeft de volgende secties: paths, runtime, model_config, numerus_fixus, excluded_data_points, ensemble_override_cumulative, exclude_from_combined, ensemble_weights en columns.

paths — bestandspaden

Alle paden zijn relatief aan de werkmap waar je de pipeline uitvoert.

Sleutel	Standaard	Omschrijving
path_cumulative	data/input/vooraanmeldingen_cumulatief.csv	Cumulatieve vooraanmelddata (ETL-output)
path_individual	data/input/vooraanmeldingen_individueel.csv	Individuele aanmelddata (ETL-output)
path_cumulative_new	""	Optioneel nieuw cumulatief bestand; wordt ingemergt en daarna verwijderd — zie waarschuwing
path_latest_cumulative	data/input/totaal_cumulatief.xlsx	Historische cumulatieve voorspellingen (post-processing output)
path_latest_individual	data/input/totaal_individueel.xlsx	Historische individuele voorspellingen (post-processing output)
path_ensemble_weights	data/input/ensemble_weights.xlsx	Ensemble-gewichten per opleiding/herkomst/examentype
path_raw_october	data/input_raw/oktober_bestand.xlsx	Telbestand studenten (ruwe bron, eigen levering instelling). De sleutel heet _october om historische redenen.
path_raw_telbestanden	data/input_raw/telbestanden	Map met Studielink telbestanden
path_raw_individueel	data/input_raw/individuele_aanmelddata.csv	Ruwe individuele aanmelddata
path_student_count_first-years	data/input/student_count_first-years.xlsx	Werkelijk aantal eerstejaars (afgeleid uit telbestand studenten)
path_student_volume	data/input/student_volume.xlsx	Totaal studentvolume (afgeleid uit telbestand studenten)
path_ratios	data/input/ratiobestand.xlsx	Ratiobestand (optioneel)

telbestand_filename_patterns — bestandsnaampatronen voor telbestanden

Standaard: ["telbestandY{year}W{week}"]

De pipeline herkent telbestanden in path_raw_telbestanden aan hun bestandsnaam. Instellingen met afwijkende naamconventies kunnen hier hun eigen patroon opgeven. De ETL en de validatie gebruiken hetzelfde patroon om jaar en weeknummer uit de bestandsnaam te halen.

Placeholder-syntax:

• {year} — vierdigit collegejaar (bijv. 2024)
• {week} — weeknummer (1–2 cijfers, gevalideerd op bereik 1–53)
• Alle andere karakters worden letterlijk gematcht. Punten, streepjes en underscores zijn veilig (re.escape op de achtergrond).

Voorbeelden:

{
    "telbestand_filename_patterns": [
        "telbestandY{year}W{week}",
        "VU_telbestand_{year}_W{week}"
    ]
}

Met meerdere patronen kan de pipeline bestanden van verschillende leveranciers naast elkaar verwerken — handig tijdens een migratie van oude naar nieuwe naamgeving.

Foutgedrag: Een patroon zonder {year} of {week} leidt tot een configuratiefout en stopt de pipeline direct, met een melding die het probleempatroon noemt.

runtime — uitvoerparameters

Instellingen die bepalen hoe de pipeline zich gedraagt tijdens uitvoer (los van de modelkeuze).

cpu_count

Standaard: null

Het aantal CPU-cores dat de pipeline gebruikt voor parallelle voorspellingen. De voorspelling van individuele SARIMA-modellen wordt verdeeld over deze cores via joblib.Parallel.

Waarde	Gedrag
null	Automatisch — os.cpu_count() wordt gebruikt, of 1 als het besturingssysteem geen waarde teruggeeft (kan voorkomen in containers met cgroup-limieten).
Geheel getal >= 1	Gebruikt deze waarde. Als de waarde hoger is dan het aantal beschikbare cores, wordt deze automatisch verlaagd naar dat aantal en verschijnt er een waarschuwing.

Pas dit aan als:

• De pipeline crasht omdat os.cpu_count() geen betrouwbare waarde teruggeeft op jouw hardware of in jouw container (achtergrond van issue #162).
• Je het CPU-gebruik wilt beperken op een gedeelde machine.

Ongeldige waarden (0, negatieve getallen, niet-gehele getallen) leiden tot een configuratiefout en stoppen de pipeline direct.

model_config — modelparameters

status_mapping

Bepaalt welke inschrijfstatussen als "ingeschreven" (1) of "niet-ingeschreven" (0) worden gelabeld voor het XGBoost-classificatiemodel.

Standaardwaarden:

Status	Label
Ingeschreven	1
Uitgeschreven	1
Geannuleerd	0
Verzoek tot inschrijving	0
Studie gestaakt	0
Aanmelding vervolgen	0

Pas dit aan als jouw instelling andere statuswaarden gebruikt. Onbekende statussen worden niet gemapt en veroorzaken een fout.

min_training_year

Standaard: 2016

Het vroegste collegejaar dat als trainingsdata wordt meegenomen. Data van vóór dit jaar wordt genegeerd. Verlaag dit alleen als je betrouwbare historische data hebt die verder teruggaat.

cumulative_timeseries

Standaard: "sarima"

Het tijdreeksmodel voor de cumulatieve curve-extrapolatie (stap 1 van het cumulatieve spoor). De keuze bepaalt hoe de vooraanmelderscurve tot week 38 wordt geëxtrapoleerd.

Waarde	Model	Omschrijving
sarima	SARIMA(1,0,1)×(1,1,1,52)	Standaard — vaste ordes, bewezen in productie
ets	AutoETS	Automatische componentkeuze (error/trend/seizoen), stabieler bij korte reeksen
theta	AutoTheta	Zeer simpel, competitief bij korte tijdreeksen
auto_arima	AutoARIMA	Automatische orde-selectie via AICc, flexibeler dan vaste SARIMA

Gebruik studentprognose benchmark om te vergelijken welk model het best presteert op jouw data.

cumulative_regressor

Standaard: "xgboost"

Het regressiemodel dat vooraanmelderscijfers vertaalt naar verwachte inschrijvingen (stap 2 van het cumulatieve spoor).

Waarde	Model	Omschrijving
xgboost	XGBoost Regressor	Standaard — gradient boosting, krachtig bij voldoende data
ridge	Ridge Regression	L2-regularisatie, stabiel bij weinig trainingsdata en multicollineariteit
random_forest	Random Forest	Robuust bij kleine datasets, ingebouwde feature importance

numerus_fixus

Een object met opleidingsnamen als sleutels en het maximale inschrijvingsaantal als waarde:

{
    "numerus_fixus": {
        "B Geneeskunde": 340,
        "B Tandheelkunde": 50
    }
}

Als de gesommeerde voorspelling over herkomstgroepen het maximum overschrijdt, wordt het overschot afgetrokken van de NL-herkomstgroep. Opleidingen die hier niet staan worden niet gecapped.

excluded_data_points — anomaliejaren uitsluiten van trainingsdata

Optionele lijst van filterregels voor het verwijderen van bekende problematische datapunten uit de trainingsdata. De tool past de regels toe vóór elk model wordt getraind. Het voorspeljaar (predict_year) wordt altijd beschermd en nooit uitgesloten, ongeacht de regels.

Gebruik dit alleen voor aantoonbare datakwaliteitsproblemen: foutieve Studielink-snapshots, deadlineverschuivingen die een historische reeks onvergelijkbaar maken, of structureel afwijkende populaties. Uitsluiten om een betere modelfit te forceren is misbruik — documenteer altijd de reden.

{
    "excluded_data_points": [
        {
            "year": 2024,
            "herkomst": "Niet-EER",
            "examentype": ["Bachelor", "Pre-master"]
        },
        {
            "year_before": 2024,
            "examentype": "Pre-master",
            "opleiding": "B Voorbeeldopleiding"
        }
    ]
}

Filtersleutels per regel

Alle sleutels binnen één regel worden gecombineerd met AND. Meerdere regels worden gecombineerd met OR.

Sleutel	Type	Omschrijving
year	int	Sluit exact dit collegejaar uit
year_before	int	Sluit alle jaren vóór (exclusief) deze waarde uit
year_after	int	Sluit alle jaren na (exclusief) deze waarde uit
herkomst	str of list[str]	Filter op herkomst ("NL", "EER", "Niet-EER")
examentype	str of list[str]	Filter op examentype ("Bachelor", "Master", "Pre-master")
opleiding	str of list[str]	Filter op Croho groepeernaam

Een lege lijst ([]) schakelt uitsluiting volledig uit — dit is de standaard.

Gebruik dit bewust

Elk uitgesloten datapunt verkleint de trainingsset. Bij kleine opleidingen kan dat de modelkwaliteit ernstig verslechteren. Beperk uitsluiting tot jaren waarvan je kunt aantonen dat de data structureel fout of onvergelijkbaar is.

ensemble_override_cumulative — ensemble-uitzondering per opleiding

Een lijst van opleidingsnamen (op Croho groepeernaam) waarvoor de ensemble-logica altijd het SARIMA-cumulatief model gebruikt, ongeacht weeknummer of examentype.

{
    "ensemble_override_cumulative": [
        "B Geneeskunde",
        "B Biomedische Wetenschappen",
        "B Tandheelkunde"
    ]
}

Gebruik dit voor opleidingen met een numerus fixus of een sterk afwijkend aanmeldpatroon waarbij het cumulatieve SARIMA-model aantoonbaar beter presteert. Lege lijst ([]) schakelt de uitzondering uit voor alle opleidingen.

De waarden in de demo-configuratie zijn Radboud-specifiek. Vervang of maak deze lijst leeg voor je eigen instelling.

exclude_from_combined — uitsluiting van combined-modus

Een lijst van opleidingsnamen (op Croho groepeernaam) die worden overgeslagen in de combined-modus (-d both). Opleidingen op deze lijst worden niet meegenomen in de combined-voorspelling.

{
    "exclude_from_combined": [
        "M Educatie in de Mens- en Maatschappijwetenschappen"
    ]
}

Gebruik dit voor opleidingen waarvoor de combined-modus aantoonbaar slechter werkt dan het cumulatieve spoor alleen. Lege lijst schakelt de uitsluiting uit.

De waarde in de demo-configuratie is Radboud-specifiek. Vervang of maak deze lijst leeg voor je eigen instelling.

ensemble_weights — weging SARIMA-individueel vs. SARIMA-cumulatief

Bepaalt per weekperiode hoe zwaar het individuele en het cumulatieve SARIMA-model meewegen in de ensemble-voorspelling. Elke sleutel is een situatie; de waarde is een object met individual en cumulative (moeten optellen tot 1.0).

{
    "ensemble_weights": {
        "master_week_17_23": {"individual": 0.2, "cumulative": 0.8},
        "week_30_34":        {"individual": 0.6, "cumulative": 0.4},
        "week_35_37":        {"individual": 0.7, "cumulative": 0.3},
        "default":           {"individual": 0.5, "cumulative": 0.5}
    }
}

Sleutel	Van toepassing wanneer
master_week_17_23	Examentype = Master én weeknummer 17–23
week_30_34	Weeknummer 30–34
week_35_37	Weeknummer 35–37
default	Alle overige gevallen

Week 38 is altijd 100% individueel en wordt niet door deze instelling beïnvloed. Zie Ensemble voor achtergrond bij de keuze van gewichten.

Weekgrenzen zijn niet configureerbaar

De sleutelnamen (zoals week_30_34) beschrijven de weekperiode waarop een gewicht van toepassing is, maar de weekgrenzen zelf zijn in de code vastgelegd. Alleen de gewichten zijn instelbaar via dit blok. Wil je de weekgrenzen aanpassen, dan vereist dat een codewijziging in output/postprocessor.py.

columns — kolomnamen mapping

Maakt het mogelijk dat instellingen andere kolomnamen gebruiken dan de kanonieke namen die de pipeline intern hanteert. Specificeer alleen de namen die afwijken — ontbrekende sleutels vallen terug op de kanonieke naam.

individual — individuele aanmelddata

Volledige lijst van kanonieke kolomnamen die gemapped kunnen worden:

Sleutel, Datum Verzoek Inschr, Ingangsdatum, Collegejaar, Datum intrekking vooraanmelding, Inschrijfstatus, Faculteit, Examentype, Croho, Croho groepeernaam, Opleiding, Hoofdopleiding, Eerstejaars croho jaar, Is eerstejaars croho opleiding, Is hogerejaars, BBC ontvangen, Type vooropleiding, Nationaliteit, EER, Geslacht, Geverifieerd adres postcode, Geverifieerd adres plaats, Geverifieerd adres land, Studieadres postcode, Studieadres land, School code eerste vooropleiding, School eerste vooropleiding, Plaats code eerste vooropleiding, Land code eerste vooropleiding, Aantal studenten

oktober — telbestand studenten

Collegejaar, Groepeernaam Croho, Aantal eerstejaars croho, EER-NL-nietEER, Examentype code, Aantal Hoofdinschrijvingen

De sleutel heet oktober om historische redenen — zie Je data voorbereiden.

cumulative — Studielink cumulatieve data

Korte naam instelling, Collegejaar, Weeknummer rapportage, Weeknummer, Faculteit, Type hoger onderwijs, Groepeernaam Croho, Naam Croho opleiding Nederlands, Croho, Herinschrijving, Hogerejaars, Herkomst, Gewogen vooraanmelders, Ongewogen vooraanmelders, Aantal aanmelders met 1 aanmelding, Inschrijvingen

Dit zijn de kolommen ná de ETL-transformatie (na het inlezen en hernoemen van de ruwe Studielink-velden). Zie Studielink telbestanden voor de mapping van ruwe PvL-velden naar deze kanonieke namen.

validation — validatiedrempels overschrijven

Optionele sectie. Hoeft niet in je configuratiebestand te staan. Voeg alleen toe wat afwijkt van de standaard:

{
    "validation": {
        "nan_error_threshold": 0.20,
        "telbestand": {
            "herkomst_allowed": ["N", "E", "R", "ONBEKEND"]
        }
    }
}

Sleutel	Standaard	Omschrijving
nan_warning_threshold	0.05	Fractie ontbrekende waarden die een waarschuwing geeft
nan_error_threshold	0.30	Fractie ontbrekende waarden die een fout geeft
collegejaar_min_offset	15	Collegejaren ouder dan huidig jaar - 15 geven een fout
collegejaar_max_offset	2	Collegejaren na huidig jaar + 2 geven een fout
telbestand.herkomst_allowed	["N","E","R"]	Toegestane herkomstwaarden in telbestanden

Zie Validatie voor een volledig overzicht van alle controles.

Voorbeeld minimale configuratie

Omdat de pipeline standaardwaarden inbouwt, hoef je alleen te specificeren wat afwijkt. Een typische startconfiguratie bevat alleen de instelling-specifieke velden:

{
    "numerus_fixus": {
        "B Geneeskunde": 340
    },
    "ensemble_override_cumulative": [
        "B Geneeskunde"
    ]
}

Alle overige velden — paden, kolomnamen, modelparameters, ensemble-gewichten — vallen terug op de ingebakken standaardwaarden. Voer studentprognose init uit om een volledig ingevuld startbestand te krijgen dat je als referentie kunt gebruiken.