Implement ML-Based Crowd Level Prediction

[shupandee]

🎯 Overview

This PR replaces the random crowd level generation with ML-driven predictions using the trained RandomForestRegressor model, transforming the fare estimator into an intelligent travel assistant with accurate, data-backed crowd insights.

🔗 Closes Issue

Closes #177 - Implement ML-based crowd level prediction

---

📋 Changes Made

1. Model Integration

• ✅ Added @st.cache_resource decorator to load passenger_flow_model.pkl efficiently
• ✅ Implemented graceful error handling for missing model files
• ✅ Model loads once and persists across user interactions

2. UI Enhancements

• ✅ Added hour selection slider (0-23) for time-of-day predictions
• ✅ Added day of week dropdown (Monday-Sunday) for weekday/weekend patterns
• ✅ Integrated st.metric() to display predictions for both start and end stations
• ✅ Added delta indicators showing passenger flow trends

3. Prediction Logic

• ✅ Created predict_crowd_level() function with ML model integration
• ✅ Converts station name, hour, and day into model-compatible features
• ✅ Maps numeric predictions to human-readable levels:
  • Low 🟢: < 33rd percentile
  • Moderate 🟡: 33rd-66th percentile
  • High 🔴: > 66th percentile
• ✅ Returns both crowd level and predicted passenger count

4. Code Quality

• ✅ Removed obsolete random.choice() implementation
• ✅ Added comprehensive docstrings
• ✅ Implemented type hints for better code maintainability
• ✅ Added input validation and error boundaries

---

🧪 Testing Completed

Test Case | Status | Notes
-- | -- | --
Peak hours (8-10 AM, 5-7 PM) show higher crowds | ✅ Pass | Predictions correctly identify rush hours
Weekend vs weekday differences | ✅ Pass | Weekends show lighter crowds
Station-specific variations | ✅ Pass | Different stations yield distinct results
Same inputs produce same outputs | ✅ Pass | Deterministic behavior confirmed
Model file missing error handling | ✅ Pass | Displays user-friendly warning message
UI responsiveness | ✅ Pass | Fast predictions with caching
Multiple consecutive predictions | ✅ Pass | No performance degradation
screenshots

Before:

after:

---

🔄 Breaking Changes

None - This is a pure enhancement. Existing functionality remains intact.

---

📚 Documentation Updates

• Updated README with crowd prediction feature
• Added inline code comments
• Created docstrings for new functions

---

🙏 Additional Notes

This PR demonstrates practical ML model deployment in a production Streamlit app. The implementation prioritizes:

• Performance (model caching)
• UX (responsive predictions)
• Reliability (error handling)
• Maintainability (clean code)

Special thanks to @Manjushwarofficial for guidance on this enhancement!

---

👤 Contributor Checklist

• Code follows project style guidelines
• Self-review completed
• Comments added for complex logic
• No new warnings generated
• All tests passing
• UI tested across different inputs
• Performance verified (no lag with caching)

---

Ready for review! 🚀

[github-actions]

Thanks for creating a PR for your Issue! ☺️

We'll review it as soon as possible.
In the meantime, please double-check the file changes and ensure that all commits are accurate.

If there are any unresolved review comments, feel free to resolve them 🙌🏼.