mjpsm/test-score-predictor

Test Score Predictor (XGBoost)

This model predicts final test scores for students based on previous performance and study habits.
It was trained on a synthetic dataset of 1,000 rows generated to reflect average realism (balanced distribution of student profiles).

---

📊 Input Features

The model expects the following features:

• previous_test_score → Student’s most recent test score (0–100)
• motivation_level → Self-reported motivation (1–10)
• self_confidence → Confidence in academic ability (1–10)
• study_environment_quality → Quality of study environment (1–10, quiet & focused = higher)
• time_management_skill → Time management ability (1–10)
• last_minute_cram_hours → Hours crammed the night before the test (0–12)

---

🎯 Output

• Predicted final test score (0–100)
• Can also be mapped to a letter grade (A–F)

Score Range	Grade
90–100	A
80–89	B
70–79	C
60–69	D
< 60	F

---

🛠️ Usage

1. Install dependencies

pip install xgboost scikit-learn pandas joblib huggingface_hub
import joblib
import pandas as pd
from huggingface_hub import hf_hub_download

# Download model file from Hugging Face repo
model_path = hf_hub_download(
    repo_id="mjpsm/test-score-predictor",
    filename="xgb_test_score_model.pkl"
)

# Load the model
model = joblib.load(model_path)

# Example student
student = pd.DataFrame([{
    "previous_test_score": 72,
    "motivation_level": 8,
    "self_confidence": 7,
    "study_environment_quality": 6,
    "time_management_skill": 5,
    "last_minute_cram_hours": 3
}])

# Predict final score
prediction = model.predict(student)[0]
print(f"Predicted final test score: {prediction:.2f}")

📈 Training

• Algorithm: XGBoost Regressor
• Dataset: 1,000 rows synthetic (realistic student performance simulation)

Metrics on test set:

• MSE: ~38.25
• R²: ~0.79

📌 Notes

• Predictions are continuous values, so results may slightly exceed 100 — clamp to [0, 100] if needed.
• The dataset reflects average realism: some students improve, some decline, depending on habits and prior scores.