OULAD Early-Risk Prediction

Reproducibility note: The committed data/processed/ tables let readers inspect the prepared dataset and generated outputs immediately. To rerun the full workflow from scratch with make run, place the original OULAD CSV files in data/raw/ first; the raw files are not committed.

Machine-learning group project for ELEN4025 using the Open University Learning Analytics Dataset (OULAD). The project predicts whether a student is at risk of an unfavourable final outcome (Fail or Withdrawn) using only data available early in the course.

The reproducible workflow builds leakage-safe feature tables at four early checkpoints, trains nine comparison pipelines, evaluates them on a fixed train/test split with cross-validation summaries, runs threshold sweeps and ablation studies, and generates report-ready tables and figures.

Project Goals

• Predict favourable (Pass, Distinction) vs unfavourable (Fail, Withdrawn) outcomes.
• Restrict features to information available by weeks 2, 4, 6, and 8.
• Compare course and self-learned models under a shared preprocessing and evaluation workflow.
• Produce reproducible CSV tables and PNG figures for the final report.
• Preserve individual notebooks for contribution provenance without committing row-level derived data.

Quick Start

Requires Python 3.11 or later.

make install

This creates .venv/ and installs the project with the optional advanced dependencies used by the full pipeline, including XGBoost and imbalanced-learn.

Place the OULAD CSV files in data/raw/ before running the workflow. Raw data is intentionally gitignored and must be obtained separately.

Required files:

• studentInfo.csv
• studentVle.csv
• vle.csv

Optional files used when present:

• assessments.csv
• studentAssessment.csv
• studentRegistration.csv
• courses.csv

Run The Workflow

make run

Builds processed feature tables in data/processed/, trains the registered pipelines across all cutoffs, runs ablation studies, and writes generated CSV outputs to reports/tables/.

make plots

Generates report figures in reports/figures/. This step expects the metric tables from make run; some plots re-fit models on the same fixed split used by the evaluation workflow.

make all

Runs the full workflow end to end.

make clean

Removes generated processed data, report tables, and report figures so the workflow can be rebuilt from scratch.

Data And Outputs

Raw OULAD CSV files are not committed. The curated data/processed/ feature tables are committed to reduce review friction, and can also be rebuilt locally from the original OULAD CSV files.

OULAD is released under the Creative Commons Attribution 4.0 International license (CC BY 4.0). The processed feature tables are derived from OULAD and should be attributed to:

Kuzilek, J., Hlosta, M. & Zdrahal, Z. Open University Learning Analytics dataset. Scientific Data 4, 170171 (2017). https://doi.org/10.1038/sdata.2017.171

Original dataset page: https://analyse.kmi.open.ac.uk/open-dataset

Generated feature tables:

• data/processed/week2_feature_table.csv
• data/processed/week4_feature_table.csv
• data/processed/week6_feature_table.csv
• data/processed/week8_feature_table.csv
• data/processed/feature_summary.csv
• data/processed/loaded_table_quality_summary.csv

Generated report tables are written locally to:

• reports/tables/pipeline_comparison_metrics.csv
• reports/tables/best_pipeline_per_week.csv
• reports/tables/threshold_sweeps.csv
• reports/tables/ablation_table.csv
• reports/tables/ablation_table_extended.csv
• reports/tables/tuned_knn_feature_addition_ablation.csv

Generated report figures are written locally to reports/figures/, including ROC curves, threshold sweeps, confusion matrices, EDA plots, feature importance, performance summaries, ablation results, and the methodology diagram.

Models

ID	Pipeline	Source
P1	Logistic Regression	Nidal
P2	Random Forest	Nidal
P3	Gradient Boosting	Nidal
P4	K-Nearest Neighbours	Thomas
P5	XGBoost	Thomas
P6	K-Means risk classifier	Talhah
P7	Tuned K-Nearest Neighbours	Zoe
P8	Gaussian Naive Bayes	Group
P9	Linear Regression score baseline	Group

P5 is skipped if XGBoost is not installed. make install installs the advanced dependency set needed for the full comparison.

Repository Layout

.
|-- data/raw/                 Local OULAD CSVs, not committed
|-- data/processed/           Derived OULAD feature tables
|-- notebooks/                Group reference notebook and individual notebooks
|-- reports/figures/          Generated report figures
|-- reports/tables/           Generated metric and ablation tables
|-- resources/                Project brief PDFs
|-- scripts/                  Command-line workflow entry points
`-- src/                      Reusable dataset, pipeline, evaluation, and reporting code

Code Overview

• src/dataset.py loads OULAD tables and builds leakage-safe cutoff feature tables.
• src/pipelines.py defines the nine registered model pipelines.
• src/evaluation.py runs model comparison, cross-validation summaries, threshold sweeps, and ablations.
• src/feature_ablation.py contains feature-block ablation helpers.
• src/reporting.py creates the report figures.
• scripts/run_pipeline.py is the entry point behind make run.
• scripts/make_plots.py is the entry point behind make plots.

License

The project code is licensed under the GNU General Public License v3.0. See LICENSE.

The committed data/processed/ tables are derived from OULAD and remain subject to OULAD's CC BY 4.0 attribution terms.

Notes For Contributors

• Treat reports/tables/ and reports/figures/ as generated outputs.
• Keep raw OULAD data and ad hoc row-level derived artifacts out of git.
• Use the Makefile workflow as the source of truth for reproducible group results.
• Keep individual work in notebooks/individual/; the shared pipeline should live in src/ and scripts/.