mirror of
https://github.com/andwati/student-retention.git
synced 2026-10-18 08:52:53 +00:00
108 lines
3.2 KiB
Markdown
108 lines
3.2 KiB
Markdown
|
|
# Student Retention Predictor
|
|
|
|
A Streamlit-based ML app for predicting student academic outcomes (Graduate/Dropout/Enrolled) using a Random Forest model. Includes role-based authentication, modular UI, customizable presets, and human-readable field mappings.
|
|
|
|
---
|
|
|
|
## Usage Instructions
|
|
|
|
### 1. Launch the Application
|
|
|
|
```bash
|
|
streamlit run app.py
|
|
```
|
|
|
|
The app will open in your browser. If model files are missing, follow the Model Training steps below.
|
|
|
|
---
|
|
|
|
### 2. Authentication & Roles
|
|
|
|
- **Login Required:** Enter your username and password to access the app.
|
|
- **Default Admin:** Username: `admin`, Password: `admin123`
|
|
- **Roles:**
|
|
- **Admin:** Full access, can manage users and export data
|
|
- **Educator:** Can export predictions
|
|
- **User:** Can view predictions only
|
|
|
|
---
|
|
|
|
### 3. Input Forms & Presets
|
|
|
|
- **Sidebar Forms:** Enter student details using dropdowns, sliders, and text fields.
|
|
- **Presets:** Use the preset selector to auto-fill fields for typical student profiles (e.g., "Typical Graduate Student").
|
|
- Presets cover academic, family background, and financial/social fields.
|
|
- **Field Mappings:** All dropdowns show human-readable names (e.g., country names, not codes), powered by the integrated data dictionary.
|
|
|
|
---
|
|
|
|
### 4. Prediction Workflow
|
|
|
|
1. **Fill in Student Data:** Complete all required fields. Use presets for convenience or enter custom values.
|
|
2. **Submit:** Click the Predict button.
|
|
3. **View Results:**
|
|
- Prediction outcome (Graduate/Dropout/Enrolled)
|
|
- Confidence score
|
|
- Personalized recommendations based on input and prediction
|
|
4. **Validation:** If input is invalid (e.g., age out of range), warnings will be shown with guidance.
|
|
|
|
---
|
|
|
|
### 5. Export & Role-Based Features
|
|
|
|
- **Export Predictions:** Available to Educator/Admin roles. Export results for further analysis.
|
|
- **Session Management:** Sessions persist for extended periods, but re-login may be required after browser refresh or timeout.
|
|
|
|
---
|
|
|
|
### 6. Model Training (If Needed)
|
|
|
|
If model files are missing or you want to retrain:
|
|
|
|
```bash
|
|
cd models
|
|
python train_and_save_model.py
|
|
```
|
|
|
|
This generates:
|
|
- `random_forest_model.pkl`
|
|
- `preprocessing_info.pkl`
|
|
- `feature_names.pkl`
|
|
|
|
---
|
|
|
|
### 7. Customization & Advanced Usage
|
|
|
|
- **Feature Changes:** Update `src/config/mappings.py` and retrain the model.
|
|
- **Presets:** Edit `PRESET_CONFIGURATIONS` in `mappings.py` to add or modify student profiles.
|
|
- **Styling:** Adjust theme in `src/config/theme.py`.
|
|
- **Authentication:** Extend roles in `src/utils/auth.py`.
|
|
|
|
---
|
|
|
|
## Project Structure
|
|
|
|
- `app.py`: Main Streamlit app
|
|
- `src/components/`: UI components (forms, prediction display)
|
|
- `src/config/`: Mappings, theme, config
|
|
- `src/utils/`: Auth, model utils
|
|
- `models/`: ML model training, serialized files
|
|
- `data/`: CSV dataset, data dictionary
|
|
- `notebook/`: Data analysis notebook
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
- **Model files missing:** Retrain using the steps above.
|
|
- **Authentication issues:** Check `users.json` for correct credentials.
|
|
- **Invalid input:** Review warnings and ensure all required fields are filled.
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
|
|
Copyright (c) 2025 Ian Andwati |