🏥 MedTriage AI - Medical Disease Classification System

Un système d'intelligence artificielle basé sur l'apprentissage automatique pour la classification des maladies à partir des symptômes et du profil patient.

📋 Table des matières

• Aperçu
• Architecture
• Installation
• Structure du projet
• Utilisation
• Pipeline de données
• Modèle et performances
• Configuration
• Résultats et visualisations
• Licence

🎯 Aperçu

MedTriage AI est une application d'apprentissage automatique conçue pour :

• Prédire les maladies à partir des symptômes et profils patients
• Analyser l'importance des features cliniques
• Évaluer la performance du modèle avec des métriques détaillées
• Expliquer les prédictions du modèle

Caractéristiques principales

✅ Pipeline complet : chargement → nettoyage → ingénierie des features → entraînement → évaluation
✅ Modèle robuste : Random Forest Classifier avec validation croisée
✅ Visualisations : matrice de confusion, importance des features, courbe ROC
✅ Interprétabilité : explicabilité des prédictions et statistiques du modèle
✅ Code modulaire : architecture orientée objet, facilement extensible

🏗️ Architecture

MedTriage AI/
├── main.py                              # Point d'entrée principal du pipeline
├── requirements.txt                     # Dépendances du projet
├── README.md                            # Cette documentation
│
├── data/
│   ├── raw/                             # Données brutes
│   │   └── Disease_symptom_and_patient_profile_dataset.csv
│   └── processed/                       # Données nettoyées et prétraitées
│       └── processed_dataset.csv
│
├── src/
│   ├── __pycache__/                     # Cache Python
│   ├── config.py                        # Configuration centralisée
│   ├── dataset.py                       # Chargement et nettoyage des données
│   ├── features.py                      # Ingénierie des features
│   ├── trainer.py                       # Entraînement du modèle
│   ├── evaluate.py                      # Évaluation et métriques
│   └── explain.py                       # Interprétabilité du modèle
│
└── results/
    ├── model.pkl                        # Modèle entraîné
    └── figures/
        └── metrics/                     # Visualisations et rapports
            ├── confusion_matrix.png
            ├── feature_importance.png
            ├── feature_importance_detailed.png
            ├── roc_curve.png
            └── metrics_report.txt

💻 Installation

Prérequis

• Python 3.9+
• pip ou conda
• Git (optionnel)

Étapes d'installation

1. Cloner le dépôt (ou télécharger les fichiers)

   git clone <repository-url>
   cd "MedTriage AI"

2. Créer un environnement virtuel

   python -m venv .venv

3. Activer l'environnement virtuel

   Windows:

   .venv\Scripts\Activate.ps1

   macOS/Linux:

   source .venv/bin/activate

4. Installer les dépendances

   pip install -r requirements.txt

📁 Structure du projet

Fichiers principaux

main.py - Pipeline principal

Orchestre l'ensemble du flux de travail :

• Charge et prépare les données
• Entraîne le modèle
• Évalue les performances
• Génère les visualisations
• Sauvegarde le modèle

src/config.py - Configuration centralisée

• Chemins des répertoires (données, résultats, modèles)
• Colonnes du dataset
• Hyperparamètres du modèle
• Paramètres d'entraînement

src/dataset.py - Gestion des données

Fonctions principales :

• load_raw_data() : charge le CSV brut
• clean_dataframe() : nettoie et uniformise les données
• save_processed_data() : enregistre les données traitées
• DatasetPreprocessor : classe d'orchestration

Transformations appliquées :

• Suppression des doublons
• Nettoyage des espaces superflus
• Conversion des types numériques
• Gestion des valeurs manquantes
• Validation des colonnes essentielles

src/features.py - Ingénierie des features

Classe FeatureEngineer :

• encode_categorical() : encodage des variables catégoriques
• scale_features() : normalisation StandardScaler
• create_features() : création de nouvelles features
• fit_transform() : pipeline complet

Features créées :

• respiratory_issues : combinaison de symptômes respiratoires (Toux, Dyspnée)
• age_group : catégorisation d'âge (enfant, jeune adulte, adulte, senior, âgé)

src/trainer.py - Entraînement du modèle

Classe ModelTrainer :

• prepare_data() : préparation des données d'entraînement/test
• train() : entraînement avec validation croisée (5-fold)
• predict() : prédictions classiques
• predict_proba() : prédictions avec probabilités
• get_feature_importance() : importance des features
• save_model() / load_model() : persistance du modèle

Modèle utilisé :

• Random Forest Classifier
• 100 arbres (estimateurs)
• Profondeur max : 10
• Stratification : test/train 80/20

src/evaluate.py - Évaluation et métriques

Classe ModelEvaluator :

• evaluate() : calcul des métriques (Accuracy, Precision, Recall, F1)
• plot_confusion_matrix() : visualisation heatmap
• plot_feature_importance() : top N features
• plot_roc_curve() : courbe ROC pour classification binaire
• save_metrics_report() : rapport texte des performances

Métriques calculées :

• Accuracy (précision globale)
• Precision (TP / (TP + FP))
• Recall (TP / (TP + FN))
• F1-Score (moyenne harmonique)
• AUC-ROC (pour binaire)

src/explain.py - Interprétabilité

Classe ModelExplainer :

• get_feature_importance() : importance des features triées
• explain_prediction() : explication d'une prédiction unique
• plot_feature_importance_detailed() : graphique coloré top N
• feature_importance_summary() : affichage console
• get_decision_path_stats() : statistiques du modèle

🚀 Utilisation

Exécution simple

python main.py

Cela lancera le pipeline complet :

1. Chargement et nettoyage des données
2. Entraînement du modèle
3. Évaluation et génération de visualisations
4. Sauvegarde du modèle et rapports

Utilisation dans du code personnalisé

from src.dataset import DatasetPreprocessor
from src.trainer import ModelTrainer
from src.evaluate import ModelEvaluator
from src.explain import ModelExplainer

# Étape 1 : Préparation des données
preproc = DatasetPreprocessor()
df = preproc.run()

# Étape 2 : Entraînement
trainer = ModelTrainer()
X_train, X_test, y_train, y_test = trainer.prepare_data(df)
model = trainer.train()

# Étape 3 : Évaluation
evaluator = ModelEvaluator(model, X_test, y_test)
metrics = evaluator.evaluate()
evaluator.plot_confusion_matrix()

# Étape 4 : Explications
explainer = ModelExplainer(model, X_train, list(X_train.columns))
explainer.feature_importance_summary()

Charger un modèle entraîné

from src.trainer import ModelTrainer

trainer = ModelTrainer()
trainer.load_model()

# Faire des prédictions
predictions = trainer.predict(X_new)
probabilities = trainer.predict_proba(X_new)

🔄 Pipeline de données

Flux de traitement

Dataset brut (CSV)
        ↓
  [Chargement]
        ↓
  [Nettoyage]
   - Dédoublonnage
   - Normalisation texte
   - Conversion types
   - Gestion NaN
        ↓
  [Ingénierie Features]
   - Encodage variables catégoriques
   - Création features dérivées
   - Normalisation (StandardScaler)
        ↓
  [Train/Test Split 80/20]
        ↓
   [Modèle ML]
        ↓
  [Évaluation + Visualisations]

Colonnes utilisées

Features symptomatiques :

• Fever (Fièvre)
• Cough (Toux)
• Fatigue
• Difficulty Breathing (Dyspnée)

Features profil patient :

• Age (Âge)
• Gender (Genre)
• Blood Pressure (Tension artérielle)
• Cholesterol Level (Taux de cholestérol)

Cible :

• Outcome Variable (Résultat : Positive/Negative)

Colonne contextuelle :

• Disease (Maladie diagnostiquée)

📊 Modèle et performances

Modèle choisi

Random Forest Classifier

• Pourquoi ? Robustesse, gestion des non-linéarités, interprétabilité des features
• Hyperparamètres :
  • n_estimators : 100 arbres
  • max_depth : 10 (limitation de la profondeur)
  • min_samples_split : 5
  • min_samples_leaf : 2
  • random_state : 42 (reproductibilité)

Validation

• Stratégies : Train/Test split (80/20) + Cross-validation (5-fold)
• Metriques : Accuracy, Precision, Recall, F1-Score, AUC-ROC

Résultats typiques

Accuracy:  0.6667
Precision: 0.6714
Recall:    0.6667
F1-Score:  0.6621

Top 3 Features Importance:
  1. Age (20.6%)
  2. Cholesterol Level (16.8%)
  3. Gender (11.4%)

⚙️ Configuration

Tous les paramètres centralisés dans src/config.py :

# Hyperparamètres du modèle
MODEL_PARAMS = {
    'n_estimators': 100,        # Nombre d'arbres
    'max_depth': 10,            # Profondeur max
    'min_samples_split': 5,
    'min_samples_leaf': 2,
    'random_state': 42,
}

# Paramètres d'entraînement
RANDOM_STATE = 42              # Pour reproductibilité
TEST_SIZE = 0.2                # Proportion ensemble test
TRAIN_SIZE = 0.8               # Proportion ensemble train

Pour modifier ces paramètres, éditez src/config.py avant de lancer le pipeline.

📈 Résultats et visualisations

Les visualisations sont automatiquement générées dans results/figures/metrics/ :

1. Confusion Matrix (confusion_matrix.png)

Heatmap montrant les vrais positifs/négatifs et erreurs de classification

2. Feature Importance (feature_importance.png)

Graphique en barres horizontal des top N features les plus importantes

3. Feature Importance Détaillée (feature_importance_detailed.png)

Graphique coloré avec tous les détails des importances

4. ROC Curve (roc_curve.png)

Courbe de rendement pour problèmes de classification binaire

5. Metrics Report (metrics_report.txt)

Rapport texte résumé des performances (Accuracy, Precision, Recall, F1)

📦 Dépendances

pandas>=1.3.0           # Manipulation de données
scikit-learn>=1.0.0     # ML et prétraitement
matplotlib>=3.4.0       # Visualisations
seaborn>=0.11.0         # Visualisations avancées
joblib>=1.0.0           # Persistance de modèles
numpy>=1.21.0           # Calculs numériques

Installer via :

pip install -r requirements.txt

🛠️ Dépannage

Problème : Colonnes manquantes

ValueError: Colonnes manquantes dans le dataset

Solution : Vérifiez que le dataset CSV contient toutes les colonnes attendues définies dans config.py

Problème : Chemin du dataset incorrect

FileNotFoundError: No such file or directory

Solution : Vérifiez que le fichier Disease_symptom_and_patient_profile_dataset.csv est dans data/raw/

Problème : Import non trouvé

ModuleNotFoundError: No module named 'sklearn'

Solution : Réinstallez les dépendances : pip install -r requirements.txt

🔮 Améliorations futures

• Ajouter support pour d'autres algorithmes (XGBoost, LightGBM, Neural Networks)
• Implémenter SHAP pour explications plus détaillées
• Créer une interface web (Flask/Streamlit)
• Ajouter tests unitaires
• Pipeline de hyperparameter tuning (GridSearch, Bayesian Optimization)
• Support du déploiement Docker
• API REST pour prédictions en temps réel
• Intégration CI/CD

👥 Contribution

Les contributions sont bienvenues ! Pour contribuer :

1. Fork le projet
2. Créez une branche feature (git checkout -b feature/AmazingFeature)
3. Commit vos changements (git commit -m 'Add AmazingFeature')
4. Push vers la branche (git push origin feature/AmazingFeature)
5. Ouvrez une Pull Request

📝 Licence

Ce projet est sous licence MIT. Voir le fichier LICENSE pour plus de détails.

📧 Contact

Pour toute question ou suggestion :

• 📧 Email : support@medtriage.ai
• 🐛 Issues : [GitHub Issues]
• 💬 Discussions : [GitHub Discussions]

---

Dernière mise à jour : Février 2026
Version : 1.0.0
Statut : Production ✅