kudam47/zimsec-olevel-passrate-prediction
Domain:
educationRecord type:
modelsoftware
Creator:
kud
Host:
Predictive modelling for O-Level pass rates at district level in Zimbabwe (CRISP-DM, XGBoost R2=0.976, FastAPI dashboard). Demo login: admin@zimsec.ac.zw / admin123
# ZIMSEC O-Level Predictive Analytics — Updated Bundle
**Author:** Cesario Machinga
**Date:** April 2026
This bundle contains the redesigned modelling pipeline, retrained models, and an
upgraded frontend stylesheet for the ZIMSEC O-Level pass-rate prediction project.
---
## What changed and why
The original pipeline reported R² = 0.975 from a model that included the prior-year
pass rate as a feature, evaluated with random K-fold cross-validation. Two
issues motivated the redesign:
1. **Feature dominance.** `Previous_Year_Pass_Rate_Pct` correlates 0.96 with the
target on its own. A single-feature linear regression on it alone reaches
R² = 0.92, meaning everything else in the dataset added only ~0.05 of R²
on top of pure persistence.
2. **Data leakage in CV.** 78.8% of pass-rate variance lies *between* districts
and is persistent over time. Random K-fold places the same district in both
training and test folds across different years, so the model partly memorises
district baselines rather than learning generalisable patterns.
### The fix — two model families, honest evaluation
| Family | Includes Prior-Year? | Use case |
|---|---|---|
| **Forecast model** | Yes | "What will this district score next year?" |
| **Driver model** | No | "What underlying factors drive pass rates?" |
Both are evaluated with:
- **Temporal hold-out:** train on 2015–2021, test on 2022–2024.
- **GroupKFold by District:** 5-fold cross-validation where each held-out fold
contains districts the model has never seen.
### Final results
**Forecast family (best: XGBoost)**
| Metric | Value |
|---|---|
| Hold-out R² (2022–2024) | **0.9754** |
| Hold-out MAE | **2.25 pp** |
| GroupKFold-by-district CV R² | **0.9404 ± 0.030** |
**Driver family (best: Random Forest)**
| Metric | Value |
|---|---|
| Hold-out R² (2022–2024) | **0.9195** |
| Hold-out MAE | **4.04 pp** |
| GroupKFold-by-district CV R² | **0.520 ± 0.316** |
The wide CV variance on the driver model is itself the main policy find …