Academic Performance Prediction System

A complete machine learning web application built as a final-year Computer Science project at Federal University Otuoke (FUO), Nigeria. The system predicts currently-enrolled student performance categories using a supervised Random Forest Classifier to identify academic risk early.

---

1. Project Features & Objectives

• Core Objective: Identify underperforming and "At-Risk" students before final grades are released, allowing lecturers and academic advisers to provide timely intervention.
• Target Variable: 4-class risk classification based on CGPA bands:
  • Excellent: CGPA $\ge$ 4.50 (First Class Standing)
  • Good: 3.50 $\le$ CGPA < 4.50 (Second Class Upper Standing)
  • Average: 2.40 $\le$ CGPA < 3.50 (Second Class Lower Standing)
  • At-Risk: CGPA < 2.40 (Third Class / Pass / Probation Standing)
• Input Feature Schema (Chapter 3, Section 3.4):
  1. Attendance rate (%)
  2. Study hours per week (hrs)
  3. Continuous Assessment (CA) total score (out of 30)
  4. Previous semester CGPA (0.00 - 5.00)
  5. Assignment average score (%)
  6. Test scores (average out of 30)
  7. Participation score (1 - 10)

---

2. System Architecture

The application is structured into the following layers:

DATA COLLECTION LAYER (FUO Google Form Data + Kaggle/UCI validation CSV)
        ↓
PREPROCESSING MODULE (Duplicate cleaning, medians, IQR outlier capping, scaling)
        ↓
MODEL TRAINING LAYER (Random Forest Classifier primary, Logistic Regression baseline)
        ↓
EVALUATION MODULE (Accuracy, Precision, Recall, F1, Confusion Matrix)
        ↓
PREDICTION & DASHBOARD LAYER (Web adviser forms, student self-checks, mass CSV uploads)

---

3. Project Structure

academic_prediction_system/
├── data/
│   ├── fuo_google_form_data.csv          # Authoritative training dataset
│   └── uci_kaggle_student_performance.csv # UCI Student Performance validation set
├── models/
│   ├── performance_classifier.joblib      # Saved model artifact & scaling parameters
│   └── uci_comparison_report.json        # Mapped validation comparison metrics
├── src/
│   ├── data_preprocessing.py             # Dataset cleaning, capping, scaling, and mapping
│   ├── train_model.py                    # Cross-validation, primary and baseline training
│   ├── predict.py                        # PerformancePredictor prediction class wrapper
│   └── kaggle_comparison.py              # Cross-context validation on UCI dataset
├── static/
│   ├── css/
│   │   └── style.css                     # Light/Dark mode stylesheet with responsive layout
│   └── js/
│       └── main.js                       # Deterministic client JS (Theme toggle & Chart.js)
├── templates/
│   ├── layout.html                      # Shared layout container with theme toggles
│   ├── dashboard.html                    # Analytics overview & Figure 3.2 diagram
│   ├── predict_student.html              # Adviser prediction form with recommendations
│   ├── check_performance.html            # Student projected CGPA band checker
│   ├── batch_predict.html                # Mass CSV record prediction upload center
│   └── model_reports.html                # Metrics, feature importance, confusion matrix
├── app.py                                # Main Flask server
├── requirements.txt                      # Project dependencies
└── README.md                             # Setup & run guidelines (This file)

---

4. Setup and Execution Instructions

Ensure you have Python 3.8+ installed on your system.

Step 1: Create a Virtual Environment (Recommended)

Open your terminal (PowerShell on Windows, or Bash on macOS/Linux) in the project root directory and run:

python -m venv venv

Activate the virtual environment:

• Windows (PowerShell):

  .\venv\Scripts\Activate.ps1

• macOS/Linux (Bash):

  source venv/bin/activate

Step 2: Install Dependencies

pip install -r requirements.txt

Step 3: Run Model Training & Cross-Validation

Run the training script to load and clean the raw FUO student dataset, perform 5-fold cross-validation, display comparative metrics between Random Forest and Logistic Regression, and save the model:

python src/train_model.py

This will print evaluation metrics (Accuracy, F1-score, Feature Importances, Confusion Matrix) to the console and write the model bundle to models/performance_classifier.joblib.

Step 4: Run Cross-Context Benchmarking

Compare the generalizability of the model by evaluating it against the UCI Portuguese Student Performance validation set (student-por.csv mapped to our schema):

python src/kaggle_comparison.py

This outputs a validation report comparing the model's accuracy on the FUO test set and the UCI validation set, saving details to models/uci_comparison_report.json.

Step 5: Launch the Flask Web Application

Once the model and benchmark reports are trained and saved, launch the local development server:

python app.py

• Open your browser and navigate to: http://127.0.0.1:5000/
• Fail-Loud Safety: If the model file is not present, the app will fail on startup, warning you to run training first.