studentprognose 1.5.0

Studentprognose tool voor het voorspellen van eerstejaars instroom in het hoger onderwijs

Voorspel je studentinstroom maanden vooruit — met je eigen data, op je eigen machine.

[!NOTE] Dit model is oorspronkelijk ontwikkeld door Radboud Universiteit en vervolgens samen met CEDA open source gemaakt zodat andere instellingen er ook van kunnen profiteren. Lees meer in het VOX-artikel.

---

📦 Aan de slag

Vereisten: Python 3.12

Installeer met uv:

uv tool install studentprognose

Heb je uv nog niet? Eenmalig installeren met curl -LsSf https://astral.sh/uv/install.sh | sh (macOS/Linux) of powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" (Windows). Voor pip-instructies, zie de documentatie.

Na installatie:

studentprognose init        # mapstructuur + configuratie aanmaken
studentprognose -w 6 -y 2024

init maakt de benodigde mapstructuur aan en legt uit welke bestanden je moet aanleveren.

Voor geautomatiseerde runs (cron, taakplanner) — sla de interactieve prompt over:

studentprognose -w 6 -y 2024 --yes

[!NOTE] Heb je afwijkende kolomnamen in je Studielink-export? Voeg een "columns"-blok toe aan configuration/configuration.json. Zie Configuratie voor uitleg en voorbeelden.

Zie de documentatie voor een complete walkthrough met uitleg over Python-installatie, data klaarzetten en veelvoorkomende fouten.

---

Waarom dit model?

Dit model is gebouwd voor data-analisten bij Nederlandse onderwijsinstellingen die werken met Studielink-data. Je hebt geen machine learning-expertise nodig.

Bring Your Own Data	Je levert je eigen data aan — er wordt niets extern gedeeld
Privacy-vriendelijk	Draait volledig lokaal op je eigen machine
Open source	Transparant, aanpasbaar en gratis te gebruiken
Demo data inbegrepen	Direct uitproberen zonder eigen data — demobestanden zitten in data/input_raw/

---

🛠️ Aan de slag voor ontwikkelaars

Via de broncode (met demodata):

# 1. Installeer uv (zie https://docs.astral.sh/uv/getting-started/installation/)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Clone de repository
git clone https://github.com/cedanl/studentprognose.git
cd studentprognose

# 3. Draai het model met demodata
uv run studentprognose -w 6 -y 2020

[!NOTE] Demodata is meegeleverd in data/input_raw/, zodat je direct kunt starten. Gebruik -y 2020 t/m -y 2024 en -w 1 t/m -w 52.

---

🗃️ Studielink Data

[!IMPORTANT] Dit model werkt met Studielink-telbestanden. Je hebt deze data nodig om voorspellingen te maken voor jouw instelling. Demodata is meegeleverd zodat je het model eerst kunt uitproberen.

---

✨ Gebruik

studentprognose -w 6 -y 2024                  # specifieke week en jaar
studentprognose -w 10 : 20 -y 2023            # weekbereik
studentprognose -d c                           # alleen cumulatief spoor
studentprognose -y 2023 2024 -w 10 : 20 -d b  # meerdere jaren, beide sporen

Vlag	Beschrijving	Opties
-w	Voorspelweek(en)	weeknummers of bereik, bijv. 10 : 20
-y	Voorspeljaar(en)	bijv. 2024 of 2023 2024
-d	Dataset	individual, cumulative, both (standaard)
--noetl	Sla ETL over	als je al verwerkte data in data/input/ hebt
--yes	Sla interactieve prompts over	voor CI/CD en cron

Zie de documentatie voor alle vlaggen, configuratie, validatie-instellingen en uitgebreide voorbeelden.

---

📁 Beschrijving van bestanden

Input

Bestand	Beschrijving
individual	Individuele (voor)aanmeldingen per student. Voedt het individueel model (XGBoost classifier + SARIMA) en levert de SARIMA_individual voorspelling.
cumulative	Aantal aanmeldingen per opleiding, herkomst, jaar, week en herinschrijving. Wordt gebruikt voor de SARIMA_cumulative voorspelling. Verkregen via Studielink.
latest	Per opleiding, herkomst, jaar en week: aanmeldingen, voorspellingen en foutwaarden (MAE/MAPE).
student_count_first-years	Werkelijk aantal eerstejaars studenten per jaar, opleiding en herkomst.
student_volume	Werkelijk totaal aantal ingeschreven studenten per jaar, opleiding en herkomst (alleen nodig bij -sy v).
weighted_ensemble	Gewichten per model voor de ensemble-voorspelling.

Output

Bestand	Beschrijving
output_prelim.xlsx	Voorlopige output met alle voorspellingen van de huidige run.
output_first-years.xlsx	Volledige output met voorspellingen voor eerstejaars studenten.
output_volume.xlsx	Volledige output met volume-voorspellingen (totaal).

---

🏗️ Architectuur

Pipeline executievolgorde

Gedeelde stappen (alle modi):

Stap	Fase	Bestand
1	CLI parsing	cli.py
2	Validatie ruwe data (skip met --noetl)	data/validation
3	ETL (skip met --noetl)	data/etl
4	Configuratie laden	config.py
5	Data laden	loader → preprocessing/add_zero_weeks
6	CI subset (indien --ci)	utils/ci_subset

Modus-specifieke stappen:

Stap	Fase	Individual (-d i)	Cumulative (-d c)	Both (-d b)
6	Preprocessing	strategies/individual	strategies/cumulative	individual → cumulative
7	Filtering	strategies/base	strategies/base	strategies/base
8	Classificatie	xgboost_classifier	—	xgboost_classifier
9	Transformatie	transforms	—	transforms
10	SARIMA	sarima (individual)	sarima → transforms	sarima (both)
11	XGBoost regressor	—	xgboost_regressor	xgboost_regressor
12	Ratio model	—	ratio	ratio
13	Postprocessing + Opslaan	postprocessor	postprocessor	postprocessor

Zie de Technische README voor meer details over de architectuur. Voor een end-to-end uitleg van het individueel spoor (inclusief Mermaid-flow), zie Individueel model in de methodologische documentatie.

---

🤝 Bijdragen

Dit project wordt actief onderhouden door CEDA. Wil je bijdragen of meedenken? Sluit je aan bij de werkgroep.

🆘 Ondersteuning

Voor vragen of problemen:

• GitHub Issues: Probleem melden

---

_{Gebouwd met ❤️ door de CEDANL community}