SHAP (SHapley Additive exPlanations)

Présentation générale

SHAP est une approche unifiée pour expliquer les prédictions des modèles de machine learning en utilisant les valeurs de Shapley issues de la théorie des jeux coopératifs. Cette compétence offre des conseils complets pour :

• Calculer les valeurs SHAP pour n'importe quel type de modèle
• Créer des visualisations pour comprendre l'importance des features
• Déboguer et valider le comportement du modèle
• Analyser l'équité et les biais
• Implémenter l'IA explicable en production

SHAP fonctionne avec tous les types de modèles : les modèles arborescents (XGBoost, LightGBM, CatBoost, Random Forest), les modèles d'apprentissage profond (TensorFlow, PyTorch, Keras), les modèles linéaires et les modèles boîte noire.

Quand utiliser cette compétence

Activez cette compétence quand les utilisateurs posent des questions sur :

• « Explique quelles features sont les plus importantes dans mon modèle »
• « Génère des graphiques SHAP » (waterfall, beeswarm, bar, scatter, force, heatmap, etc.)
• « Pourquoi mon modèle a-t-il fait cette prédiction ? »
• « Calcule les valeurs SHAP pour mon modèle »
• « Visualise l'importance des features avec SHAP »
• « Déboguez le comportement de mon modèle » ou « valide mon modèle »
• « Vérifie mon modèle pour les biais » ou « analyse l'équité »
• « Compare l'importance des features entre les modèles »
• « Implémente l'IA explicable » ou « ajoute des explications à mon modèle »
• « Comprendre les interactions entre features »
• « Crée un tableau de bord d'interprétation du modèle »

Guide de démarrage rapide

Étape 1 : Sélectionner le bon explainer

Arbre de décision :

1. Modèle arborescent ? (XGBoost, LightGBM, CatBoost, Random Forest, Gradient Boosting)

   • Utilise shap.TreeExplainer (rapide, exact)

2. Réseau de neurones profond ? (TensorFlow, PyTorch, Keras, CNNs, RNNs, Transformers)

   • Utilise shap.DeepExplainer ou shap.GradientExplainer

3. Modèle linéaire ? (Linear/Logistic Regression, GLMs)

   • Utilise shap.LinearExplainer (extrêmement rapide)

4. Tout autre modèle ? (SVMs, fonctions personnalisées, modèles boîte noire)

   • Utilise shap.KernelExplainer (modèle-agnostique mais plus lent)

5. Incertain ?

   • Utilise shap.Explainer (sélectionne automatiquement le meilleur algorithme)

Consulte references/explainers.md pour des informations détaillées sur tous les types d'explainers.

Étape 2 : Calculer les valeurs SHAP

import shap

# Exemple avec un modèle arborescent (XGBoost)
import xgboost as xgb

# Entraîner le modèle
model = xgb.XGBClassifier().fit(X_train, y_train)

# Créer l'explainer
explainer = shap.TreeExplainer(model)

# Calculer les valeurs SHAP
shap_values = explainer(X_test)

# L'objet shap_values contient :
# - values: valeurs SHAP (attributions de features)
# - base_values: résultat attendu du modèle (baseline)
# - data: valeurs originales des features

Étape 3 : Visualiser les résultats

Pour la compréhension globale (ensemble de données entier) :

# Graphique beeswarm - affiche l'importance des features avec distributions des valeurs
shap.plots.beeswarm(shap_values, max_display=15)

# Graphique en barres - résumé propre de l'importance des features
shap.plots.bar(shap_values)

Pour les prédictions individuelles :

# Graphique waterfall - ventilation détaillée d'une seule prédiction
shap.plots.waterfall(shap_values[0])

# Graphique force - visualisation de la force additive
shap.plots.force(shap_values[0])

Pour les relations entre features :

# Graphique scatter - relation feature-prédiction
shap.plots.scatter(shap_values[:, "Feature_Name"])

# Colorié par une autre feature pour montrer les interactions
shap.plots.scatter(shap_values[:, "Age"], color=shap_values[:, "Education"])

Consulte references/plots.md pour un guide complet de tous les types de graphiques.

Workflows principaux

Cette compétence supporte plusieurs workflows courants. Choisis le workflow qui correspond à la tâche actuelle.

Workflow 1 : Explication de modèle basique

Objectif : Comprendre ce qui pilote les prédictions du modèle

Étapes :

1. Entraîner le modèle et créer l'explainer approprié
2. Calculer les valeurs SHAP pour l'ensemble de test
3. Générer les graphiques d'importance globale (beeswarm ou bar)
4. Examiner les relations des top features (graphiques scatter)
5. Expliquer les prédictions spécifiques (graphiques waterfall)

Exemple :

# Étapes 1-2 : Configuration
explainer = shap.TreeExplainer(model)
shap_values = explainer(X_test)

# Étape 3 : Importance globale
shap.plots.beeswarm(shap_values)

# Étape 4 : Relations entre features
shap.plots.scatter(shap_values[:, "Most_Important_Feature"])

# Étape 5 : Explication individuelle
shap.plots.waterfall(shap_values[0])

Workflow 2 : Débogage de modèle

Objectif : Identifier et corriger les problèmes du modèle

Étapes :

1. Calculer les valeurs SHAP
2. Identifier les erreurs de prédiction
3. Expliquer les échantillons mal classifiés
4. Vérifier l'importance inattendue des features (fuite de données)
5. Valider que les relations entre features ont du sens
6. Vérifier les interactions entre features

Consulte references/workflows.md pour le workflow de débogage détaillé.

Workflow 3 : Ingénierie des features

Objectif : Utiliser les insights SHAP pour améliorer les features

Étapes :

1. Calculer les valeurs SHAP pour le modèle de référence
2. Identifier les relations non linéaires (candidates à transformation)
3. Identifier les interactions entre features (candidates à termes d'interaction)
4. Concevoir de nouvelles features
5. Réentraîner et comparer les valeurs SHAP
6. Valider les améliorations

Consulte references/workflows.md pour le workflow d'ingénierie des features détaillé.

Workflow 4 : Comparaison de modèles

Objectif : Comparer plusieurs modèles pour sélectionner la meilleure option interprétable

Étapes :

1. Entraîner plusieurs modèles
2. Calculer les valeurs SHAP pour chacun
3. Comparer l'importance globale des features
4. Vérifier la cohérence des classements de features
5. Analyser les prédictions spécifiques entre modèles
6. Sélectionner selon la précision, l'interprétabilité et la cohérence

Consulte references/workflows.md pour le workflow de comparaison de modèles détaillé.

Workflow 5 : Analyse d'équité et de biais

Objectif : Détecter et analyser les biais du modèle entre groupes démographiques

Étapes :

1. Identifier les attributs protégés (genre, race, âge, etc.)
2. Calculer les valeurs SHAP
3. Comparer l'importance des features entre les groupes
4. Vérifier l'importance SHAP des attributs protégés
5. Identifier les features proxy
6. Implémenter des stratégies d'atténuation si des biais sont détectés

Consulte references/workflows.md pour le workflow d'analyse d'équité détaillé.

Workflow 6 : Déploiement en production

Objectif : Intégrer les explications SHAP dans les systèmes de production

Étapes :

1. Entraîner et sauvegarder le modèle
2. Créer et sauvegarder l'explainer
3. Construire un service d'explication
4. Créer des endpoints API pour les prédictions avec explications
5. Implémenter la mise en cache et l'optimisation
6. Monitorer la qualité des explications

Consulte references/workflows.md pour le workflow de déploiement en production détaillé.

Concepts clés

Valeurs SHAP

Définition : Les valeurs SHAP quantifient la contribution de chaque feature à une prédiction, mesurée comme la déviation par rapport au résultat attendu du modèle (baseline).

Propriétés :

• Additivité : Les valeurs SHAP s'additionnent pour la différence entre prédiction et baseline
• Équité : Basées sur les valeurs de Shapley de la théorie des jeux
• Cohérence : Si une feature devient plus importante, sa valeur SHAP augmente

Interprétation :

• Valeur SHAP positive → La feature pousse la prédiction à la hausse
• Valeur SHAP négative → La feature pousse la prédiction à la baisse
• Magnitude → Force de l'impact de la feature
• Somme des valeurs SHAP → Changement total de prédiction par rapport à la baseline

Exemple :

Baseline (valeur attendue) : 0,30
Contributions des features (valeurs SHAP) :
  Age : +0,15
  Income : +0,10
  Education : -0,05
Prédiction finale : 0,30 + 0,15 + 0,10 - 0,05 = 0,50

Données de référence / Baseline

Objectif : Représente une entrée « typique » pour établir les attentes de baseline

Sélection :

• Échantillon aléatoire des données d'entraînement (50-1000 échantillons)
• Ou utiliser kmeans pour sélectionner des échantillons représentatifs
• Pour DeepExplainer/KernelExplainer : 100-1000 échantillons pour équilibrer précision et vitesse

Impact : La baseline affecte les magnitudes des valeurs SHAP mais pas l'importance relative

Types de résultats du modèle

Considération critique : Comprendre ce que votre modèle produit

• Résultat brut : Pour la régression ou les marges arborescentes
• Probabilité : Pour la probabilité de classification
• Log-odds : Pour la régression logistique (avant sigmoid)

Exemple : Les classificateurs XGBoost expliquent la sortie de marge (log-odds) par défaut. Pour expliquer les probabilités, utilise model_output="probability" dans TreeExplainer.

Patterns courants

Pattern 1 : Analyse complète du modèle

# 1. Configuration
explainer = shap.TreeExplainer(model)
shap_values = explainer(X_test)

# 2. Importance globale
shap.plots.beeswarm(shap_values)
shap.plots.bar(shap_values)

# 3. Relations des top features
top_features = X_test.columns[np.abs(shap_values.values).mean(0).argsort()[-5:]]
for feature in top_features:
    shap.plots.scatter(shap_values[:, feature])

# 4. Exemples de prédictions
for i in range(5):
    shap.plots.waterfall(shap_values[i])

Pattern 2 : Comparaison de cohortes

# Définir les cohortes
cohort1_mask = X_test['Group'] == 'A'
cohort2_mask = X_test['Group'] == 'B'

# Comparer l'importance des features
shap.plots.bar({
    "Group A": shap_values[cohort1_mask],
    "Group B": shap_values[cohort2_mask]
})

Pattern 3 : Débogage d'erreurs

# Trouver les erreurs
errors = model.predict(X_test) != y_test
error_indices = np.where(errors)[0]

# Expliquer les erreurs
for idx in error_indices[:5]:
    print(f"Échantillon {idx}:")
    shap.plots.waterfall(shap_values[idx])

    # Enquêter sur les features clés
    shap.plots.scatter(shap_values[:, "Suspicious_Feature"])

Optimisation des performances

Considérations de vitesse

Vitesse d'Explainer (du plus rapide au plus lent) :

1. LinearExplainer - Quasi instantané
2. TreeExplainer - Très rapide
3. DeepExplainer - Rapide pour les réseaux de neurones
4. GradientExplainer - Rapide pour les réseaux de neurones
5. KernelExplainer - Lent (à utiliser uniquement si nécessaire)
6. PermutationExplainer - Très lent mais précis

Stratégies d'optimisation

Pour les grands ensembles de données :

# Calculer SHAP pour un sous-ensemble
shap_values = explainer(X_test[:1000])

# Ou utiliser le batching
batch_size = 100
all_shap_values = []
for i in range(0, len(X_test), batch_size):
    batch_shap = explainer(X_test[i:i+batch_size])
    all_shap_values.append(batch_shap)

Pour les visualisations :

# Échantillonner un sous-ensemble pour les graphiques
shap.plots.beeswarm(shap_values[:1000])

# Ajuster la transparence pour les graphiques denses
shap.plots.scatter(shap_values[:, "Feature"], alpha=0.3)

Pour la production :

# Mettre en cache l'explainer
import joblib
joblib.dump(explainer, 'explainer.pkl')
explainer = joblib.load('explainer.pkl')

# Pré-calculer pour les prédictions par lots
# Calculer uniquement les top N features pour les réponses API

Dépannage

Problème : Mauvais choix d'explainer

Symptôme : Utiliser KernelExplainer pour les modèles arborescents (lent et inutile) Solution : Toujours utiliser TreeExplainer pour les modèles arborescents

Problème : Données de référence insuffisantes

Symptôme : DeepExplainer/KernelExplainer avec trop peu d'échantillons de référence Solution : Utiliser 100-1000 échantillons représentatifs

Problème : Unités confuses

Symptôme : Interpréter les log-odds comme des probabilités Solution : Vérifier le type de résultat du modèle ; comprendre si les valeurs sont des probabilités, log-odds ou résultats bruts

Problème : Les graphiques ne s'affichent pas

Symptôme : Problèmes de backend Matplotlib Solution : S'assurer que le backend est correctement configuré ; utiliser plt.show() si nécessaire

Problème : Trop de features encombrant les graphiques

Symptôme : max_display=10 par défaut peut être trop ou trop peu Solution : Ajuster le paramètre max_display ou utiliser le clustering de features

Problème : Calcul lent

Symptôme : Calculer SHAP pour de très grands ensembles de données Solution : Échantillonner un sous-ensemble, utiliser le batching, ou s'assurer d'utiliser un explainer spécialisé (pas KernelExplainer)

Intégration avec d'autres outils

Notebooks Jupyter

• Les graphiques force interactifs fonctionnent sans problème
• Affichage des graphiques inline avec show=True (par défaut)
• Combiner avec markdown pour les explications narratives

MLflow / Experiment Tracking

import mlflow

with mlflow.start_run():
    # Entraîner le modèle
    model = train_model(X_train, y_train)

    # Calculer SHAP
    explainer = shap.TreeExplainer(model)
    shap_values = explainer(X_test)

    # Logger les graphiques
    shap.plots.beeswarm(shap_values, show=False)
    mlflow.log_figure(plt.gcf(), "shap_beeswarm.png")
    plt.close()

    # Logger les métriques d'importance des features
    mean_abs_shap = np.abs(shap_values.values).mean(axis=0)
    for feature, importance in zip(X_test.columns, mean_abs_shap):
        mlflow.log_metric(f"shap_{feature}", importance)

APIs de production

class ExplanationService:
    def __init__(self, model_path, explainer_path):
        self.model = joblib.load(model_path)
        self.explainer = joblib.load(explainer_path)

    def predict_with_explanation(self, X):
        prediction = self.model.predict(X)
        shap_values = self.explainer(X)

        return {
            'prediction': prediction[0],
            'base_value': shap_values.base_values[0],
            'feature_contributions': dict(zip(X.columns, shap_values.values[0]))
        }

Documentation de référence

Cette compétence inclut une documentation de référence complète organisée par sujet :

references/explainers.md

Guide complet de toutes les classes d'explainers :

• TreeExplainer - Explications rapides et exactes pour les modèles arborescents
• DeepExplainer - Modèles d'apprentissage profond (TensorFlow, PyTorch)
• KernelExplainer - Modèle-agnostique (fonctionne avec n'importe quel modèle)
• LinearExplainer - Explications rapides pour les modèles linéaires
• GradientExplainer - Basé sur le gradient pour les réseaux de neurones
• PermutationExplainer - Exact mais lent pour n'importe quel modèle

Inclut : paramètres du constructeur, méthodes, modèles supportés, quand utiliser, exemples, considérations de performance.

references/plots.md

Guide complet de la visualisation :

• Graphiques waterfall - Ventilations de prédictions individuelles
• Graphiques beeswarm - Importance globale avec distributions des valeurs
• Graphiques en barres - Résumés propres de l'importance des features
• Graphiques scatter - Relations feature-prédiction et interactions
• Graphiques force - Visualisations de force additive interactives
• Graphiques heatmap - Grilles de comparaison multi-échantillons
• Graphiques violin - Alternatives axées sur les distributions
• Graphiques de décision - Chemins de prédiction multiclasse

Inclut : paramètres, cas d'usage, exemples, bonnes pratiques, guide de sélection des graphiques.

references/workflows.md

Workflows détaillés et bonnes pratiques :

• Workflow d'explication de modèle basique
• Débogage et validation de modèles
• Conseils d'ingénierie des features
• Comparaison et sélection de modèles
• Analyse d'équité et de biais
• Explication de modèles d'apprentissage profond
• Déploiement en production
• Explication de modèles de séries temporelles
• Pièges courants et solutions
• Techniques avancées
• Intégration MLOps

Inclut : instructions étape par étape, exemples de code, critères de décision, dépannage.

references/theory.md

Fondations théoriques :

• Valeurs de Shapley de la théorie des jeux
• Formules mathématiques et propriétés
• Connexion avec d'autres méthodes d'explication (LIME, DeepLIFT, etc.)
• Algorithmes de calcul SHAP (Tree SHAP, Kernel SHAP, etc.)
• Attentes conditionnelles et sélection de baseline
• Interprétation des valeurs SHAP
• Valeurs d'interaction
• Limitations théoriques et considérations

Inclut : fondations mathématiques, preuves, comparaisons, sujets avancés.

Directives d'utilisation

Quand charger les fichiers de référence :

• Charger explainers.md quand l'utilisateur a besoin d'informations détaillées sur des types d'explainers spécifiques ou des paramètres
• Charger plots.md quand l'utilisateur a besoin de conseils détaillés sur la visualisation ou explore les options de graphiques
• Charger workflows.md quand l'utilisateur a des tâches complexes multi-étapes (débogage, analyse d'équité, déploiement en production)
• Charger theory.md quand l'utilisateur pose des questions sur les fondations théoriques, les valeurs de Shapley ou les détails mathématiques

Approche par défaut (sans charger les références) :

• Utiliser ce SKILL.md pour les explications basiques et le démarrage rapide
• Fournir des workflows standards et des patterns courants
• Les fichiers de référence sont disponibles si plus de détails sont nécessaires

Charger les références :

# Pour charger les fichiers de référence, utilise l'outil Read avec le chemin approprié :
# /path/to/shap/references/explainers.md
# /path/to/shap/references/plots.md
# /path/to/shap/references/workflows.md
# /path/to/shap/references/theory.md

Résumé des bonnes pratiques

1. Choisir le bon explainer : Utiliser les explainers spécialisés (TreeExplainer, DeepExplainer, LinearExplainer) quand possible ; éviter KernelExplainer sauf si nécessaire

2. Commencer global, puis local : Commencer avec les graphiques beeswarm/bar pour une compréhension globale, puis plonger dans les graphiques waterfall/scatter pour les détails

3. Utiliser plusieurs visualisations : Différents graphiques révèlent des insights différents ; combiner les vues globales (beeswarm) + locales (waterfall) + relations (scatter)

4. Sélectionner les données de référence appropriées : Utiliser 50-1000 échantillons représentatifs des données d'entraînement

5. Comprendre les unités du résultat du modèle : Savoir si on explique des probabilités, des log-odds ou des résultats bruts

6. Valider avec la connaissance du domaine : SHAP montre le comportement du modèle ; utiliser l'expertise du domaine pour interpréter et valider

7. Optimiser pour les performances : Échantillonner des sous-ensembles pour la visualisation, batch pour les grands ensembles de données, mettre en cache les explainers en production

8. Vérifier les fuites de données : Une importance de feature inattendue peut indiquer des problèmes de qualité des données

9. Considérer les corrélations entre features : Utiliser les options conscientes des corrélations de TreeExplainer ou le clustering de features pour les features redondantes

10. Se souvenir que SHAP montre l'association, pas la causalité : Utiliser la connaissance du domaine pour l'interprétation causale

Installation

# Installation basique
uv pip install shap

# Avec dépendances de visualisation
uv pip install shap matplotlib

# Dernière version
uv pip install -U shap

Dépendances : numpy, pandas, scikit-learn, matplotlib, scipy

Optionnel : xgboost, lightgbm, tensorflow, torch (selon les types de modèles)

Ressources supplémentaires

• Documentation officielle : https://shap.readthedocs.io/
• Dépôt GitHub : https://github.com/slundberg/shap
• Article original : Lundberg & Lee (2017) - « A Unified Approach to Interpreting Model Predictions »
• Article Nature MI : Lundberg et al. (2020) - « From local explanations to global understanding with explainable AI for trees »

Cette compétence offre une couverture complète de SHAP pour l'interprétabilité des modèles dans tous les cas d'usage et types de modèles.