predictive_analysis/README.md

# 🎓 Student Success Prediction Dashboard

A beautiful Streamlit application that predicts student academic outcomes (Graduate, Dropout, or Enrolled) using a Random Forest model trained on 36 features including academic performance, demographics, and economic indicators.

## 🚀 Quick Start

### 1. Train and Save the Model

First, run the training script to create the pickle files:

```bash
python train_and_save_model.py
```

This will create:
- `random_forest_model.pkl` - The trained Random Forest model
- `preprocessing_info.pkl` - Preprocessing pipeline information
- `feature_names.pkl` - Feature names for consistency

### 2. Install Dependencies

```bash
pip install -r requirements.txt
```

### 3. Launch the Dashboard

```bash
streamlit run app.py
```

The dashboard will open in your browser at `http://localhost:8501`

## 📊 Model Performance

- **Algorithm:** Random Forest Classifier (n_estimators=100)
- **Training Accuracy:** 100%
- **Test Accuracy:** 93.84%
- **Features:** 36 student characteristics
- **Classes:** Graduate (50%), Dropout (32%), Enrolled (17%)

## 🎯 Features

### Complete Input Form
- **Personal Information:** Marital status, gender, age, nationality
- **Academic Background:** Application details, course, previous qualifications
- **Family Background:** Parents' education and occupation
- **Financial & Social:** Scholarships, debts, special needs status
- **Academic Performance:** 1st and 2nd semester curricular units and grades
- **Economic Indicators:** Unemployment rate, inflation rate, GDP

### Beautiful Interface
- **Responsive Design:** Clean, professional layout with custom CSS
- **Interactive Widgets:** User-friendly dropdowns with human-readable labels
- **Real-time Predictions:** Instant results with confidence scores
- **Visual Analytics:** Interactive charts showing prediction probabilities
- **Model Insights:** Performance metrics and key factors display

### Accurate Preprocessing
- **Exact Pipeline Match:** Preprocessing mirrors the training notebook exactly
- **One-hot Encoding:** Categorical variables properly encoded
- **Feature Consistency:** Ensures all 105+ features match training data
- **Input Validation:** Handles missing features and maintains column order

## 🔧 Technical Details

### Data Pipeline
1. **Data Loading:** Reads from `./data/data.csv`
2. **Column Cleaning:** Removes apostrophes, fixes typos (Nacionality → Nationality)
3. **Target Encoding:** Maps Dropout=0, Enrolled=1, Graduate=2
4. **One-hot Encoding:** Converts categorical features to binary columns
5. **Feature Alignment:** Ensures prediction input matches training features

### Model Architecture
- **Random Forest** with 100 estimators
- **No scaling required** (tree-based model)
- **Train/Test Split:** 70/30 with random_state=42
- **Cross-validation:** 5-fold validation during training

### User Experience Enhancements
- **Human-readable Labels:** Maps numeric codes to descriptive text
- **Smart Defaults:** Pre-filled with typical student values
- **Interactive Sliders:** Easy input for numeric values
- **Color-coded Results:** Green for Graduate, Red for Dropout, Yellow for Enrolled
- **Confidence Display:** Shows probability scores for all three outcomes

## 📁 Project Structure

```
predictive_analysis/
├── data/
│   └── data.csv                    # Original dataset (4,424 students)
├── src/                            # Source code modules
│   ├── config/                     # Configuration files
│   │   ├── __init__.py
│   │   ├── theme.py               # Rose Pine theme and constants
│   │   └── mappings.py            # Feature mappings and presets
│   ├── utils/                     # Utility functions
│   │   ├── __init__.py
│   │   └── model_utils.py         # Model loading and preprocessing
│   ├── components/                # UI components
│   │   ├── __init__.py
│   │   ├── form_components.py     # Input form sections
│   │   └── prediction_components.py # Results and charts
│   └── __init__.py
├── predictive_analysis.ipynb      # Original analysis notebook
├── train_and_save_model.py        # Model training and pickle export
├── streamlit_app.py               # Legacy monolithic app (deprecated)
├── app.py                         # New modular main application
├── requirements.txt               # Python dependencies
├── random_forest_model.pkl        # Trained model (generated)
├── preprocessing_info.pkl         # Preprocessing pipeline (generated)
├── feature_names.pkl              # Feature list (generated)
└── README.md                      # This file
```

## 🎨 Dashboard Screenshots

The dashboard features:
- **Sidebar Input Form:** All 36 features organized by category
- **Main Prediction Area:** Large, colorful prediction display
- **Probability Charts:** Interactive bar charts and radar plots
- **Model Information:** Performance metrics and key insights
- **Responsive Design:** Works on desktop and mobile devices

## 🔍 Key Features Explained

### Categorical Mappings
- **Marital Status:** Single, Married, Divorced, etc.
- **Application Mode:** Various admission pathways
- **Course:** Animation, Engineering, Management, etc.
- **Qualifications:** Education levels from basic to doctorate
- **Occupations:** Professional categories for parents

### Academic Performance Tracking
- **Curricular Units:** Credits, enrollments, evaluations, approvals
- **Grades:** Average performance in 1st and 2nd semesters
- **Without Evaluations:** Units not evaluated

### Economic Context
- **Unemployment Rate:** Regional economic indicator
- **Inflation Rate:** Economic stability measure
- **GDP:** Overall economic performance

## 🚀 Deployment Options

### Local Development
```bash
streamlit run streamlit_app.py
```

### Streamlit Cloud
1. Push code to GitHub
2. Connect repository to Streamlit Cloud
3. Deploy with automatic requirements detection

### Docker
```dockerfile
FROM python:3.9-slim
COPY . /app
WORKDIR /app
RUN pip install -r requirements.txt
EXPOSE 8501
CMD ["streamlit", "run", "streamlit_app.py"]
```

## 🛠️ Customization

### Adding New Features
1. Update `train_and_save_model.py` with new preprocessing
2. Modify `streamlit_app.py` input form
3. Ensure feature alignment in `preprocess_input()`

### Styling Changes
- Modify CSS in the `st.markdown()` sections
- Update color schemes in `color_discrete_map`
- Adjust layout in column configurations

### Model Improvements
- Tune hyperparameters in `RandomForestClassifier()`
- Add feature selection or engineering
- Implement cross-validation strategies

## 📊 Model Validation

The model achieves excellent performance:
- **ROC AUC:** 0.98 (nearly perfect discrimination)
- **Precision:** Graduate 95%, Dropout 92%
- **Recall:** Graduate 95%, Dropout 93%
- **F1-Score:** Balanced across all classes

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

## 📄 License

This project is open source and available under the MIT License.

## 🙏 Acknowledgments

- Dataset from UCI Machine Learning Repository
- Built with Streamlit, scikit-learn, and Plotly
- Inspired by educational data mining research