mbo-bekostiging-bestanden
Leest DUO MBO-bekostigingsbestanden in en zet ze om naar schone, onderzoeksklare data.
Context
MBO-instellingen worden bekostigd op basis van bestanden die DUO publiceert. Die
bestanden zijn ruw en lastig direct te gebruiken. Deze repo leest ze in,
decodeert de velden en controleert de kwaliteit. Dat levert twee producten op:
- Brondata per levering (
data/02-prepared/): elk DUO-bestand per
recordtype, getrouw aan de levering en alleen getypeerd.
- Analysemodel (
data/03-output/…/star/): een star schema (dimensies +
feiten) waarin de leveringen zijn samengevoegd, met vastgelegde
ontwerpkeuzes (canonicalisatie, hoofdinschrijving, peildatum, …).
Andere CEDA-projecten kunnen op beide voortbouwen.
Doelgroep: analisten en onderzoekers bij mbo-instellingen die met
bekostigingsdata werken.
Quick start
uv sync
export MBO_PSEUDONIMISERING_SALT="$(python3 -c 'import secrets; print(secrets.token_hex(32))')"
uv run streamlit run app/main.py
Op Windows: zie Aan de slag.
De repo bevat demo-data, zodat alles direct werkt zonder eigen bestanden.
Pseudonimisering (fail-closed): persoons-identifiers worden gehasht met
HMAC-SHA256 plus deze salt, al bij het verwerken van een levering (mbo verwerk,
of "Verwerk bestanden" in de app): 02-prepared/ bevat geen BSN, onderwijsnummer
of PGN, alleen het pseudoniem _persoon_id (#173). Zonder
MBO_PSEUDONIMISERING_SALT weigert die stap te draaien. De brondata blijft
persoonsgegevens (zie Aan de slag).
Productie gebruikt uitsluitend de environment
(secret manager); lokaal genereert het export-commando hierboven een
willekeurige salt per shell. Bewaar die zelf als je pseudoniemen tussen sessies
wilt kunnen koppelen. Bewaar echte salts nooit in git — een
app/config.toml-fallback is puur voor demo en bevat geen salt meer.
Alleen voor een vertrouwde omgeving die DUO-gegevens intern aan een eigen
administratie koppelt, kun je expliciet kiezen voor identifiers behouden
(geen salt, BSN/ONR/PGN blijven in de uitvoer). Een ontbrekende salt kiest
dat nooit. Zie Aan de slag.
Alleen lokaal gebruiken: de app is een lokale, single-user analysetool en
wordt bewust níet gehost (ook niet op SURF). Er is geen login, geen
rolgebaseerd exportrecht en geen audit-log: wie de app draait, kan een tabel
desgewenst mét persoonsgegevens downloaden (standaard staan die uit).
Stap 1 — Bestanden verwerken
Open de app en bekijk de ontdekte bestanden. De twee producten zijn aparte stappen:
- Verwerk bestanden — normaliseert alle ruwe DUO-bestanden naar brondata (Parquet per levering).
- Bouw analysemodel — stapelt de brondata en bouwt het star schema. Dit kan los
opnieuw, zonder de ruwe bestanden opnieuw te verwerken.
Stap 2 — Dashboard
Na de verwerking toont het Dashboard een visueel overzicht verdeeld over vijf
tabs: rendementen (JR), bekostigingstrechter, opleidingen (BOL/BBL, BPV, KZD),
studenten (geslacht, herkomst, gemeente) en GEO-examencijfers.
Stap 3 — Werkbare data en analysemodel bekijken en downloaden
De zijbalk scheidt de twee producten: Werkbare data (ruw omgezet naar brondata
per levering) en Analysemodel (het star schema). Op beide pagina's kies je een
tabel, bekijk je een preview van de eerste 1 000 rijen en download je de volledige
tabel als CSV. Persoonsgegevens zijn in preview en download standaard verborgen.
CLI:
# Verwerk één ruw bestand naar prepared
uv run mbo verwerk data/01-raw/demo/h15/RO_27DV_20240731_20260324.csv \
data/02-prepared/demo/h15/RO_27DV_20240731_20260324
# Bouw star schema vanuit meerdere prepared-mappen
uv run mbo star \
data/02-prepared/demo/h15/RO_27DV_20240731_20260324 \
data/02-prepared/demo/h16/TBGI_25LX_2027_20251124 \
data/02-prepared/demo/h17/GRONDSLAG_IP_MBO_27DV_20251119_2025 \
--output data/03-output/demo/star \
--relative-to data/02-prepared/demo
Python API:
from mbo_bekostiging_bestanden.pipeline import run_auto_pipeline, run_star
run_auto_pipeline("data/01-raw/demo/h15/RO_27DV_20240731_20260324.csv",
"data/02-prepared/demo/h15/RO_27DV_20240731_20260324")
run_star(
sources=["data/02-prepared/demo/h15/RO_27DV_20240731_20260324",
"data/02-prepared/demo/h16/TBGI_25LX_2027_20251124",
"data/02-prepared/demo/h17/GRONDSLAG_IP_MBO_27DV_20251119_2025"],
target="data/03-output/demo/star",
relative_to="data/02-prepared/demo",
)
# Star schema staat in data/03-output/demo/star/datamodel/
Kwaliteitsoordeel: run_star voert de kwaliteitscontrole uit en
schrijft quality.json. Directe aanroepen van build_star() of
stack_prepared() (bijv. in een notebook) geven geen kwaliteitssignaal. Voor
gevalideerde data: gebruik altijd run_star.
Eigen data verwerken
Wijs app/config.toml naar je eigen mappen en draai dezelfde stappen:
[data]
raw = "data/01-raw/eigen"
prepared = "data/02-prepared/eigen"
output = "data/03-output/eigen"
Zet je ruwe DUO-bestanden (RO_*.csv, TBGI_*.XML, GRONDSLAG_IP_MBO_*.csv) in
de raw-map. De app ontdekt en verwerkt ze automatisch. Echte data staat niet in
git.
Data
- Input: ruwe bekostigingsbestanden in
data/01-raw/. Drie typen:
RO_*.csv (h15), TBGI_*.XML (h16), GRONDSLAG_IP_MBO_*.csv (h17).
- Prepared: genormaliseerde Parquet per recordtype in
data/02-prepared/,
één submap per leveringsbestand (groep/bestandsstam/).
- Output: star-schema-tabellen in
data/03-output/star/datamodel/
(zie docs/datamodel.md voor een volledig overzicht)
- Echte data staat niet in git; alleen demo-data in
data/*/demo/.
Ontwikkeling
export MBO_PSEUDONIMISERING_SALT="ci-test-key-do-not-use-in-production" # alleen tests/CI
uv run pytest # tests
uv run ruff check # lint
De tests draaien fail-closed op persoons-pseudonimisering; zonder
MBO_PSEUDONIMISERING_SALT faalt de stap die het analysemodel bouwt (zie
Quick start).
De vaste testwaarde is publiek en dus herleidbaar: gebruik hem uitsluitend op
synthetische data (tests, CI), nooit voor het verwerken van echte bestanden.
Open de repo in de devcontainer (VS Code / GitHub Codespaces) voor een kant-en-klare omgeving.
Referenties
Contact
Onderhouden door CEDA (cedanl). Bijdragen via issues en pull requests.
License
MIT
