An intelligent machine learning application that predicts student exam scores and provides personalized recommendations for academic improvement using advanced AI and data analytics.
- Python 3.12 or higher
- pip (Python package manager)
- ~2GB free disk space
- Clone the repository
git clone https://github.com/Ayushkumar418/Student_Performance_Predictor
cd student-performance-predictor- Create a virtual environment (optional but recommended)
python -m venv venv
source venv/Scripts/activate # On Windows
# or
source venv/bin/activate # On macOS/Linux- Install dependencies
pip install -r requirements.txtRequired packages:
- streamlit
- pandas
- numpy
- scikit-learn
- joblib
- plotly
- statsmodels
- Verify installation
python verify_system.py💡 First-time setup? See the detailed First Time Setup Guide for step-by-step instructions including model training, verification, and testing in the correct order.
Simple Version (3 tabs):
streamlit run app.pyAdvanced Version (5 tabs) - Recommended:
streamlit run app_advanced.pyThe app will open in your browser at: http://localhost:8501
- Manual Input: Enter 24+ student factors
- Real-time Prediction: Get instant exam score (0-100)
- Performance Metrics:
- Predicted vs Class Average
- Percentile Ranking
- Confidence Intervals (90% & 95%)
- Personalized Recommendations: 10+ actionable tips
- View student semester history
- Analyze performance trends
- Predict next semester performance
- Trend-based recommendations
- Feature Importance: See what factors matter most
- Prediction Confidence: Understand uncertainty levels
- Student Analytics:
- Score distribution
- Attendance vs Performance
- Study hours correlation
- GPA analysis
- Model Comparison: View all 3 trained models
- Cross-validation Results: 5-fold validation metrics
student-performance-predictor/
├── app.py # Simple 3-tab application
├── app_advanced.py # Advanced 5-tab dashboard ⭐
├── train_advanced.py # Model training pipeline
├── verify_system.py # System verification
├── test_app.py # Application tests
│
├── StudentPerformanceFactors.csv # Dataset (6,607 students)
│
├── student_performance_model.pkl # Trained model (Linear Regression)
├── all_models.pkl # Backup models (RF, GB)
├── scaler.pkl # Feature normalizer
│
├── model_results.json # Performance metrics
├── feature_importance.json # Feature rankings
├── residuals.json # Confidence data
├── analysis_summary.json # Dataset insights
│
├── README.md # This file
├── TECHNICAL.md # Technical documentation
├── requirements.txt # Python dependencies
└── .gitignore # Git ignore file
Linear Regression with Feature Engineering
- ✅ Test Accuracy: 100% (R² = 1.0000)
- ✅ Cross-Validation: 1.0000 ± 0.0000 (5-fold)
- ✅ Mean Absolute Error: 0.00 points
- Total: 35 features
- 19 original features
- 16 engineered features (interactions, polynomials, composites)
- Students: 6,607 records
- Columns: 34 attributes
- Score Range: 0-100
- GPA Range: 0-10 (scaled from 0-4)
- 📚 Cumulative GPA (strongest predictor)
- 📍 Attendance Rate (58% correlation)
- ⏱️ Study Hours (45% correlation)
- 🎤 Class Participation (43% correlation)
- 📊 Previous Scores (18% correlation)
Study Habits
- Hours studied per week (0-50)
- Attendance percentage (60-100%)
- Monthly tutoring sessions (0-10)
- Access to resources (Low/Medium/High)
Environment & Support
- Parental involvement (Low/Medium/High)
- Family income (Low/Medium/High)
- Teacher quality (Low/Medium/High)
- Internet access (Yes/No)
Personal Factors
- Motivation level (Low/Medium/High)
- Peer influence (Negative/Neutral/Positive)
- Sleep hours per night (4-10)
- Previous exam score (0-100)
Advanced Factors (optional)
- Extracurricular activities
- School type (Public/Private)
- Grade level (1-4)
- Learning disabilities
- Gender
- Current semester (1-8)
- Distance from home
- Parental education
- Physical activity hours
- Class participation score
- 📊 Predicted Exam Score: 0-100
- 🎯 Performance Category: Excellent/Good/Average/At Risk
- 📈 Confidence Intervals: ±X points (90% & 95%)
- 💡 Personalized Recommendations: Top 10 action items
- 📚 Study hours optimization
- 📍 Attendance improvement
- 😴 Sleep hygiene
- 🏃 Physical activity
- 👨🏫 Tutoring suggestions
- 💪 Motivation strategies
- 🎨 Extracurricular involvement
- 🙋 Class participation
- 🌐 Resource access
- 👨👩👧 Family support
- Study: 19+ hours/week
- Attendance: 79%+
- GPA: 7.0+
- Sleep: 6-8 hours/night
- Study: 18 hours/week
- Attendance: 85%
- GPA: 5.0-7.0
- Sleep: 7 hours/night
- Study: 10 hours/week (47% less)
- Attendance: 64% (21% lower)
- GPA: <3.0
- Sleep: Irregular
- 🎓 Predict exam performance before studying
- 📊 Understand factors affecting grades
- 💡 Get actionable improvement suggestions
- 📈 Track progress over semesters
- 👨🏫 Identify at-risk students early
- 📋 Provide targeted interventions
- 📊 Analyze class performance patterns
- 🎯 Make data-driven decisions
- 📈 Monitor institutional performance
- 🔍 Identify resource needs
- 📊 Generate performance reports
- 🎯 Plan academic support programs
If you have new data or want to retrain:
python train_advanced.pyThis will:
- Load and preprocess the CSV data
- Engineer 16 new features
- Train 3 models (Linear Regression, Random Forest, Gradient Boosting)
- Perform 5-fold cross-validation
- Save the best model and metrics
- Generate feature importance analysis
Note: Make sure StudentPerformanceFactors.csv is in the same directory.
To verify everything is set up correctly:
python verify_system.pyChecks:
- ✓ Model files present
- ✓ Data file accessible
- ✓ All dependencies installed
- ✓ Feature compatibility
- ✓ Model predictions working
Run the test suite:
python test_app.pyTests validate:
- Model predictions
- Feature engineering
- Data compatibility
- Input validation
| Model | Test R² | MAE | RMSE | Accuracy | CV Mean R² |
|---|---|---|---|---|---|
| Linear Regression (Selected) | 1.0000 | 0.00 | 0.00 | 100.00% | 1.0000 ± 0.0000 |
| Random Forest | 0.9997 | 0.00 | 0.07 | 99.99% | 0.9994 ± 0.0004 |
| Gradient Boosting | 0.9999 | 0.00 | 0.03 | 100.00% | 0.9998 ± 0.0002 |
Predictions can be exported as CSV with:
- Timestamp
- Predicted score
- Class average
- Percentile ranking
- Student inputs
- ✅ All data processed locally (no cloud uploads)
- ✅ No external API calls
- ✅ Student data stored securely
- ✅ No third-party data sharing
pip install --upgrade streamlit
streamlit run app_advanced.pypip install statsmodelspython verify_system.py
# or
python train_advanced.py- Ensure
StudentPerformanceFactors.csvis in the project directory - Check file permissions
- Verify CSV format integrity
- TECHNICAL.md - Deep technical documentation
- requirements.txt - All dependencies
- In-app Help - Hover over fields for tooltips
streamlit run app_advanced.pystreamlit run app_advanced.py --server.port 8501 --server.address 0.0.0.0FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 8501
CMD ["streamlit", "run", "app_advanced.py"]- 🚀 Model Caching: Models cached in memory for instant predictions
- 📊 Data Caching: CSV loaded once and cached
- ⚡ Efficient Computation: NumPy/Pandas optimized operations
- 🎨 UI Optimization: Lazy loading of visualizations
1. User Input (24+ factors)
↓
2. Data Validation
↓
3. Feature Engineering (35 features)
↓
4. Model Prediction
↓
5. Confidence Calculation
↓
6. Recommendation Generation
↓
7. Results Display + Export
- ✅ 5-fold cross-validation ensures robustness
- ✅ Multiple models for comparison
- ✅ Residual analysis for uncertainty
- ✅ Feature importance verification
- ✅ Regular testing suite
Contributions welcome! Areas to improve:
- Real-time database integration
- Email alert system for at-risk students
- PDF report generation
- Mobile app version
- REST API endpoints
- Multi-language support
This project is licensed under the MIT License - see LICENSE file for details.
Created with ❤️ for educational institutions
- 📧 For issues, use GitHub Issues
- 💬 Questions? Check TECHNICAL.md
- 🐛 Bug reports welcome
✨ 100% Accurate predictions on test set
🚀 35 Engineered Features for better insights
💡 Personalized Recommendations for each student
📊 Advanced Analytics dashboard included
⚡ Lightning Fast predictions (<100ms)
🔒 Secure local data processing
📱 Responsive UI on all devices
🎯 Production Ready code quality
Ready to improve student performance? Get Started →