| ---
|
| license: mit
|
| language:
|
| - en
|
| tags:
|
| - tabular-regression
|
| - student-performance
|
| - education
|
| - scikit-learn
|
| - random-forest
|
| datasets:
|
| - larsen0966/student-performance-data-set
|
| metrics:
|
| - mae
|
| - rmse
|
| - r2
|
| model-index:
|
| - name: Student Performance Predictor
|
| results:
|
| - task:
|
| type: tabular-regression
|
| name: Student Grade Prediction
|
| dataset:
|
| name: Student Performance Data Set
|
| type: tabular
|
| metrics:
|
| - type: mae
|
| value: 2.0
|
| name: Mean Absolute Error
|
| - type: rmse
|
| value: 2.8
|
| name: Root Mean Squared Error
|
| - type: r2
|
| value: 0.25
|
| name: R² Score
|
| ---
|
|
|
| # 🎓 Student Performance Predictor
|
|
|
| ## Model Description
|
|
|
| Модель для предсказания академической успеваемости студентов (финальной оценки G3) на основе демографических, социальных и поведенческих факторов. Обучена на данных португальских школ с использованием Random Forest Regressor.
|
|
|
| - **Developed by:** SergeyR256
|
| - **Model type:** Random Forest Regressor
|
| - **Framework:** scikit-learn 1.5.2
|
| - **License:** MIT
|
|
|
| ## Intended Use
|
|
|
| ### Primary Use
|
| Предсказание финальной оценки студента по 20-балльной шкале для:
|
| - Выявления студентов в зоне риска
|
| - Планирования образовательных интервенций
|
| - Исследования факторов, влияющих на успеваемость
|
|
|
| ### Out-of-Scope Use
|
| - Не использовать для принятия окончательных решений об отчислении
|
| - Не применять к студентам младше 15 или старше 22 лет
|
| - Не использовать за пределами португальской образовательной системы без дополнительной валидации
|
|
|
| ## Training Data
|
|
|
| ### Data Description
|
| - **Source:** UCI Machine Learning Repository
|
| - **Authors:** P. Cortez and A. Silva (2008)
|
| - **Samples:** 649 студентов
|
| - **Features:** 30 признаков + 7 engineered features
|
|
|
| ### Feature Categories
|
| | Category | Features |
|
| |----------|----------|
|
| | Demographics | age, sex, address, famsize, Pstatus |
|
| | Family | Medu, Fedu, Mjob, Fjob, guardian, famrel |
|
| | School | school, studytime, traveltime, failures, absences, reason |
|
| | Support | schoolsup, famsup, paid, activities, nursery, higher, internet |
|
| | Lifestyle | freetime, goout, Dalc, Walc, health, romantic |
|
|
|
| ### Target Variable
|
| - **G3:** Final grade (0-20 scale)
|
| - **Note:** G1 and G2 (interim grades) were excluded to avoid data leakage
|
|
|
| ### Data Splits
|
| | Split | Samples | Percentage |
|
| |-------|---------|------------|
|
| | Train | 519 | 80% |
|
| | Test | 130 | 20% |
|
|
|
| ## Training Procedure
|
|
|
| ### Preprocessing
|
| - **Numeric features:** Median imputation + StandardScaler
|
| - **Nominal features:** Most frequent imputation + OneHotEncoder
|
| - **Ordinal features:** Most frequent imputation + OrdinalEncoder
|
|
|
| ### Feature Engineering
|
| ```python
|
| df['total_alcohol'] = df['Dalc'] + df['Walc']
|
| df['parent_edu_avg'] = (df['Medu'] + df['Fedu']) / 2
|
| df['goout_studytime_ratio'] = df['goout'] / (df['studytime'] + 1)
|
| df['alcohol_study_interaction'] = df['total_alcohol'] * df['studytime']
|
| df['failures_squared'] = df['failures'] ** 2
|
| df['age_squared'] = df['age'] ** 2
|
| df['health_freetime_ratio'] = df['health'] / (df['freetime'] + 1)
|
| ```
|
|
|
| ### Hyperparameters
|
| Grid search with 5-fold cross-validation:
|
|
|
| | Parameter | Search Space | Best Value
|
| |--|--|--
|
| | n_estimators | 100-500 | 300
|
| | max_depth | 10-25 | 20
|
| | min_samples_split 2-10 | 5
|
| | min_samples_leaf | 1-4 | 2
|
| | max_features | sqrt, log2, 0.5 | sqrt
|
|
|
| ## Training Script
|
| The complete training pipeline is available in the [GitHub repository](https://github.com/Reactivity512/student-performance-prediction) and [Jupyter notebook](https://github.com/Reactivity512/student-performance-prediction/blob/main/notebooks/01_eda_and_training.ipynb).
|
|
|
| ## Evaluation Results
|
| Test Set Metrics
|
|
|
| | Metric | Value | Interpretation
|
| |--|--|--
|
| | MAE | 2.0 балла | Средняя ошибка в 2 балла из 20
|
| | RMSE | 2.8 балла | Большие ошибки штрафуются сильнее
|
| | R² | 0.25 | Модель объясняет 25% вариации
|
|
|
| ### Cross-Validation
|
|
|
| * 5-fold CV MAE: 1.97 ± 0.12 балла
|
| * Stability: Низкая вариация указывает на стабильность модели
|
|
|
| ### 📝 Категории оценок
|
|
|
| | Баллы | Категория | Эмодзи |
|
| |-------|-----------|--------|
|
| | 0-7 | Неудовлетворительно | 🔴 |
|
| | 8-9 | Ниже среднего | 🟠 |
|
| | 10-11 | Средне | 🟡 |
|
| | 12-13 | Хорошо | 🟢 |
|
| | 14-15 | Очень хорошо | 🔵 |
|
| | 16-20 | Отлично | 🟣 |
|
|
|
| ### Error Analysis by Grade Range
|
|
|
| | Actual Grade Range | Count | Mean Absolute Error
|
| |--|--|--
|
| | 0-8 | 15 | 3.2
|
| | 9-10 | 28 | 2.5
|
| | 11-12 | 35 | 2.1
|
| | 13-14 | 30 | 1.8
|
| | 15-16 | 15 | 2.0
|
| | 17-20 | 7 | 2.8
|
|
|
| `Note: Model performs better on middle-range grades, struggles with extremes`
|
|
|
| ### Limitations and Biases
|
|
|
| Known Limitations
|
| * Regional Specificity: Trained only on Portuguese schools, may not generalize to other educational systems
|
| * Grade Range: Predictions bounded to [0, 20], but model may extrapolate poorly at extremes
|
| * Temporal Validity: Data from 2008, may not reflect current educational context
|
| * Missing G1/G2: Excluding interim grades makes prediction harder but more useful
|
|
|
| ## How to Use
|
|
|
| ### Load the Model
|
|
|
| ```py
|
| import joblib
|
|
|
| # Load from local file
|
| model = joblib.load('path/to/model.joblib')
|
| ```
|
|
|
| ### Make a Prediction
|
|
|
| ```py
|
| import pandas as pd
|
|
|
| # Example input
|
| input_data = {
|
| 'age': 18, 'Medu': 3, 'Fedu': 2, 'traveltime': 2,
|
| 'studytime': 2, 'failures': 0, 'famrel': 4, 'freetime': 3,
|
| 'goout': 3, 'Dalc': 1, 'Walc': 2, 'health': 5, 'absences': 4,
|
| 'school': 'GP', 'sex': 'F', 'address': 'U', 'famsize': 'GT3',
|
| 'Pstatus': 'T', 'Mjob': 'teacher', 'Fjob': 'other',
|
| 'reason': 'course', 'guardian': 'mother', 'schoolsup': 'no',
|
| 'famsup': 'yes', 'paid': 'no', 'activities': 'yes',
|
| 'nursery': 'yes', 'higher': 'yes', 'internet': 'yes',
|
| 'romantic': 'no'
|
| }
|
|
|
| # Predict
|
| input_df = pd.DataFrame([input_data])
|
| prediction = model.predict(input_df)[0]
|
| print(f"Predicted grade: {prediction:.2f}/20")
|
| ```
|
|
|
| ### API Deployment
|
|
|
| ```py
|
| # FastAPI example
|
| from fastapi import FastAPI
|
| import joblib
|
|
|
| app = FastAPI()
|
| model = joblib.load('best_model_random_forest.joblib')
|
|
|
| @app.post("/predict")
|
| async def predict(data: dict):
|
| import pandas as pd
|
| df = pd.DataFrame([data])
|
| prediction = model.predict(df)[0]
|
| return {"predicted_grade": round(float(prediction), 2)}
|
| ```
|
|
|
| ## 📚 Источник данных
|
|
|
| Модель обучена на [Student Performance Data Set](https://archive.ics.uci.edu/ml/datasets/student+performance) из UCI Machine Learning Repository.
|
|
|
| **Авторы датасета:** P. Cortez and A. Silva, 2008
|
|
|
| **Описание:** Данные о успеваемости учащихся двух португальских школ по предмету "Португальский язык".
|
|
|
| ## Resources
|
|
|
| * 📓 Jupyter Notebook: [Training and Analysis](https://github.com/Reactivity512/student-performance-prediction/blob/main/notebooks/01_eda_and_training.ipynb)
|
| * 📂 GitHub Repository: [Full Project](https://github.com/Reactivity512/student-performance-prediction)
|
|
|
| ## 👤 Contact
|
|
|
| SergeyR256
|
|
|
| * GitHub: https://github.com/Reactivity512
|
| * Hugging Face: https://huggingface.co/SergeyR256
|
|
|
