Shap

SHAP (SHapley Additive exPlanations)

Visão Geral

SHAP é uma abordagem unificada para explicar saídas de modelos de machine learning usando valores de Shapley da teoria dos jogos cooperativos. Essa skill oferece orientação abrangente para:

• Computar valores SHAP para qualquer tipo de modelo
• Criar visualizações para entender importância de features
• Depurar e validar comportamento de modelos
• Analisar justiça e vieses
• Implementar IA explicável em produção

SHAP funciona com todos os tipos de modelos: modelos baseados em árvores (XGBoost, LightGBM, CatBoost, Random Forest), modelos de deep learning (TensorFlow, PyTorch, Keras), modelos lineares e modelos black-box.

Quando Usar Essa Skill

Ative essa skill quando usuários perguntarem sobre:

• "Explique quais features são mais importantes no meu modelo"
• "Gere plots SHAP" (waterfall, beeswarm, bar, scatter, force, heatmap, etc.)
• "Por que meu modelo fez essa predição?"
• "Calcule valores SHAP para meu modelo"
• "Visualize importância de features usando SHAP"
• "Depure o comportamento do meu modelo" ou "valide meu modelo"
• "Verifique vieses no meu modelo" ou "analise justiça"
• "Compare importância de features entre modelos"
• "Implemente IA explicável" ou "adicione explicações ao meu modelo"
• "Entenda interações de features"
• "Crie dashboard de interpretação de modelos"

Guia de Início Rápido

Passo 1: Selecione o Explainer Correto

Árvore de Decisão:

1. Modelo baseado em árvores? (XGBoost, LightGBM, CatBoost, Random Forest, Gradient Boosting)

   • Use shap.TreeExplainer (rápido, exato)

2. Rede neural profunda? (TensorFlow, PyTorch, Keras, CNNs, RNNs, Transformers)

   • Use shap.DeepExplainer ou shap.GradientExplainer

3. Modelo linear? (Linear/Logistic Regression, GLMs)

   • Use shap.LinearExplainer (extremamente rápido)

4. Qualquer outro modelo? (SVMs, funções customizadas, modelos black-box)

   • Use shap.KernelExplainer (agnóstico de modelo, mas mais lento)

5. Incerto?

   • Use shap.Explainer (seleciona automaticamente o melhor algoritmo)

Veja references/explainers.md para informações detalhadas sobre todos os tipos de explainers.

Passo 2: Compute Valores SHAP

import shap

# Exemplo com modelo baseado em árvores (XGBoost)
import xgboost as xgb

# Treine o modelo
model = xgb.XGBClassifier().fit(X_train, y_train)

# Crie o explainer
explainer = shap.TreeExplainer(model)

# Compute valores SHAP
shap_values = explainer(X_test)

# O objeto shap_values contém:
# - values: valores SHAP (atribuições de features)
# - base_values: saída esperada do modelo (baseline)
# - data: valores originais das features

Passo 3: Visualize Resultados

Para Entendimento Global (dataset inteiro):

# Plot beeswarm - mostra importância de features com distribuições de valores
shap.plots.beeswarm(shap_values, max_display=15)

# Plot bar - resumo limpo de importância de features
shap.plots.bar(shap_values)

Para Predições Individuais:

# Plot waterfall - decomposição detalhada de uma predição
shap.plots.waterfall(shap_values[0])

# Plot force - visualização de força aditiva
shap.plots.force(shap_values[0])

Para Relações de Features:

# Plot scatter - relação feature-predição
shap.plots.scatter(shap_values[:, "Feature_Name"])

# Colorido por outra feature para mostrar interações
shap.plots.scatter(shap_values[:, "Age"], color=shap_values[:, "Education"])

Veja references/plots.md para guia abrangente sobre todos os tipos de plots.

Workflows Principais

Essa skill suporta vários workflows comuns. Escolha o workflow que corresponde à tarefa atual.

Workflow 1: Explicação Básica de Modelo

Objetivo: Entender o que direciona predições de modelo

Passos:

1. Treine modelo e crie explainer apropriado
2. Compute valores SHAP para conjunto de teste
3. Gere plots de importância global (beeswarm ou bar)
4. Examine relações das top features (scatter plots)
5. Explique predições específicas (waterfall plots)

Exemplo:

# Passos 1-2: Setup
explainer = shap.TreeExplainer(model)
shap_values = explainer(X_test)

# Passo 3: Importância global
shap.plots.beeswarm(shap_values)

# Passo 4: Relações de features
shap.plots.scatter(shap_values[:, "Most_Important_Feature"])

# Passo 5: Explicação individual
shap.plots.waterfall(shap_values[0])

Workflow 2: Depuração de Modelo

Objetivo: Identificar e corrigir problemas de modelo

Passos:

1. Compute valores SHAP
2. Identifique erros de predição
3. Explique amostras mal classificadas
4. Verifique importância de features inesperada (vazamento de dados)
5. Valide se relações de features fazem sentido
6. Verifique interações de features

Veja references/workflows.md para workflow de depuração detalhado.

Workflow 3: Engenharia de Features

Objetivo: Use insights SHAP para melhorar features

Passos:

1. Compute valores SHAP para modelo base
2. Identifique relações não-lineares (candidatas para transformação)
3. Identifique interações de features (candidatas para termos de interação)
4. Engenharie novas features
5. Retreine e compare valores SHAP
6. Valide melhorias

Veja references/workflows.md para workflow de engenharia de features detalhado.

Workflow 4: Comparação de Modelos

Objetivo: Compare múltiplos modelos para selecionar a melhor opção interpretável

Passos:

1. Treine múltiplos modelos
2. Compute valores SHAP para cada um
3. Compare importância global de features
4. Verifique consistência de rankings de features
5. Analise predições específicas entre modelos
6. Selecione com base em acurácia, interpretabilidade e consistência

Veja references/workflows.md para workflow de comparação de modelos detalhado.

Workflow 5: Análise de Justiça e Viés

Objetivo: Detecte e analise vieses de modelo entre grupos demográficos

Passos:

1. Identifique atributos protegidos (gênero, raça, idade, etc.)
2. Compute valores SHAP
3. Compare importância de features entre grupos
4. Verifique importância SHAP de atributos protegidos
5. Identifique features proxy
6. Implemente estratégias de mitigação se viés encontrado

Veja references/workflows.md para workflow de análise de justiça detalhado.

Workflow 6: Deployment em Produção

Objetivo: Integre explicações SHAP em sistemas em produção

Passos:

1. Treine e salve modelo
2. Crie e salve explainer
3. Construa serviço de explicação
4. Crie endpoints de API para predições com explicações
5. Implemente cache e otimização
6. Monitore qualidade de explicações

Veja references/workflows.md para workflow de deployment em produção detalhado.

Conceitos-Chave

Valores SHAP

Definição: Valores SHAP quantificam a contribuição de cada feature para uma predição, medida como desvio da saída esperada do modelo (baseline).

Propriedades:

• Aditividade: Valores SHAP somam à diferença entre predição e baseline
• Justiça: Baseado em valores de Shapley da teoria dos jogos
• Consistência: Se uma feature fica mais importante, seu valor SHAP aumenta

Interpretação:

• Valor SHAP positivo → Feature empurra predição para cima
• Valor SHAP negativo → Feature empurra predição para baixo
• Magnitude → Força do impacto da feature
• Soma de valores SHAP → Mudança total de predição a partir do baseline

Exemplo:

Baseline (valor esperado): 0.30
Contribuições de features (valores SHAP):
  Age: +0.15
  Income: +0.10
  Education: -0.05
Predição final: 0.30 + 0.15 + 0.10 - 0.05 = 0.50

Background Data / Baseline

Propósito: Representa entrada "típica" para estabelecer expectativas baseline

Seleção:

• Amostra aleatória dos dados de treinamento (50-1000 amostras)
• Ou use kmeans para selecionar amostras representativas
• Para DeepExplainer/KernelExplainer: 100-1000 amostras equilibra acurácia e velocidade

Impacto: Baseline afeta magnitudes de valores SHAP, mas não importância relativa

Tipos de Saída de Modelo

Consideração Crítica: Entenda o que seu modelo produz

• Saída bruta: Para regressão ou tree margins
• Probabilidade: Para probabilidade de classificação
• Log-odds: Para regressão logística (antes de sigmoid)

Exemplo: Classificadores XGBoost explicam saída de margin (log-odds) por padrão. Para explicar probabilidades, use model_output="probability" em TreeExplainer.

Padrões Comuns

Padrão 1: Análise Completa de Modelo

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

# 2. Importância global
shap.plots.beeswarm(shap_values)
shap.plots.bar(shap_values)

# 3. Relações das 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. Predições de exemplo
for i in range(5):
    shap.plots.waterfall(shap_values[i])

Padrão 2: Comparação de Coortes

# Defina coortes
cohort1_mask = X_test['Group'] == 'A'
cohort2_mask = X_test['Group'] == 'B'

# Compare importância de features
shap.plots.bar({
    "Group A": shap_values[cohort1_mask],
    "Group B": shap_values[cohort2_mask]
})

Padrão 3: Depurando Erros

# Encontre erros
errors = model.predict(X_test) != y_test
error_indices = np.where(errors)[0]

# Explique erros
for idx in error_indices[:5]:
    print(f"Amostra {idx}:")
    shap.plots.waterfall(shap_values[idx])

    # Investigue features suspeitas
    shap.plots.scatter(shap_values[:, "Suspicious_Feature"])

Otimização de Performance

Considerações de Velocidade

Velocidade de Explainer (mais rápido para mais lento):

1. LinearExplainer - Quase instantâneo
2. TreeExplainer - Muito rápido
3. DeepExplainer - Rápido para redes neurais
4. GradientExplainer - Rápido para redes neurais
5. KernelExplainer - Lento (use apenas quando necessário)
6. PermutationExplainer - Muito lento mas acurado

Estratégias de Otimização

Para Datasets Grandes:

# Compute SHAP para subset
shap_values = explainer(X_test[:1000])

# Ou use 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)

Para Visualizações:

# Amostra subset para plots
shap.plots.beeswarm(shap_values[:1000])

# Ajuste transparência para plots densos
shap.plots.scatter(shap_values[:, "Feature"], alpha=0.3)

Para Produção:

# Cache explainer
import joblib
joblib.dump(explainer, 'explainer.pkl')
explainer = joblib.load('explainer.pkl')

# Pre-compute para predições em batch
# Compute apenas top N features para respostas de API

Troubleshooting

Problema: Escolha errada de explainer

Problema: Usar KernelExplainer para modelos de árvore (lento e desnecessário) Solução: Sempre use TreeExplainer para modelos baseados em árvores

Problema: Background data insuficiente

Problema: DeepExplainer/KernelExplainer com pouquíssimas amostras de background Solução: Use 100-1000 amostras representativas

Problema: Unidades confusas

Problema: Interpretar log-odds como probabilidades Solução: Verifique tipo de saída do modelo; entenda se valores são probabilidades, log-odds ou saídas brutas

Problema: Plots não aparecem

Problema: Problemas de backend Matplotlib Solução: Garanta que backend está configurado corretamente; use plt.show() se necessário

Problema: Muitas features poluindo plots

Problema: max_display=10 padrão pode ser muito ou pouco Solução: Ajuste parâmetro max_display ou use clustering de features

Problema: Computação lenta

Problema: Computar SHAP para datasets muito grandes Solução: Amostra subset, use batching ou garanta uso de explainer especializado (não KernelExplainer)

Integração com Outras Ferramentas

Jupyter Notebooks

• Plots force interativos funcionam perfeitamente
• Exibição inline de plots com show=True (padrão)
• Combine com markdown para explicações narrativas

MLflow / Experiment Tracking

import mlflow

with mlflow.start_run():
    # Treine modelo
    model = train_model(X_train, y_train)

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

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

    # Log métricas de importância de 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)

Production APIs

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]))
        }

Documentação de Referência

Essa skill inclui documentação de referência abrangente organizada por tópico:

references/explainers.md

Guia completo sobre todas as classes de explainer:

• TreeExplainer - Explicações rápidas e exatas para modelos baseados em árvores
• DeepExplainer - Modelos de deep learning (TensorFlow, PyTorch)
• KernelExplainer - Agnóstico de modelo (funciona com qualquer modelo)
• LinearExplainer - Explicações rápidas para modelos lineares
• GradientExplainer - Baseado em gradientes para redes neurais
• PermutationExplainer - Exato mas lento para qualquer modelo

Inclui: Parâmetros de construtor, métodos, modelos suportados, quando usar, exemplos, considerações de performance.

references/plots.md

Guia de visualização abrangente:

• Waterfall plots - Decomposições de predições individuais
• Beeswarm plots - Importância global com distribuições de valores
• Bar plots - Resumos limpos de importância de features
• Scatter plots - Relações feature-predição e interações
• Force plots - Visualizações de força aditiva interativas
• Heatmap plots - Grades de comparação multi-amostra
• Violin plots - Alternativas focadas em distribuição
• Decision plots - Caminhos de predição multiclass

Inclui: Parâmetros, casos de uso, exemplos, boas práticas, guia de seleção de plots.

references/workflows.md

Workflows detalhados e boas práticas:

• Workflow de explicação básica de modelo
• Depuração e validação de modelo
• Orientação de engenharia de features
• Comparação e seleção de modelos
• Análise de justiça e viés
• Explicação de modelos de deep learning
• Deployment em produção
• Explicação de modelos de série temporal
• Armadilhas comuns e soluções
• Técnicas avançadas
• Integração com MLOps

Inclui: Instruções passo a passo, exemplos de código, critérios de decisão, troubleshooting.

references/theory.md

Fundações teóricas:

• Valores de Shapley da teoria dos jogos
• Fórmulas matemáticas e propriedades
• Conexão com outros métodos de explicação (LIME, DeepLIFT, etc.)
• Algoritmos de computação SHAP (Tree SHAP, Kernel SHAP, etc.)
• Expectativas condicionais e seleção de baseline
• Interpretando valores SHAP
• Valores de interação
• Limitações teóricas e considerações

Inclui: Fundações matemáticas, provas, comparações, tópicos avançados.

Diretrizes de Uso

Quando carregar arquivos de referência:

• Carregue explainers.md quando usuário precisar de informações detalhadas sobre tipos específicos de explainers ou parâmetros
• Carregue plots.md quando usuário precisar de orientação detalhada de visualização ou exploração de opções de plots
• Carregue workflows.md quando usuário tiver tarefas complexas multi-etapa (depuração, análise de justiça, deployment em produção)
• Carregue theory.md quando usuário perguntar sobre fundações teóricas, valores de Shapley ou detalhes matemáticos

Abordagem padrão (sem carregar referências):

• Use esse SKILL.md para explicações básicas e início rápido
• Forneça workflows padrão e padrões comuns
• Arquivos de referência estão disponíveis se mais detalhe for necessário

Carregando referências:

# Para carregar arquivos de referência, use a ferramenta Read com caminho apropriado:
# /path/to/shap/references/explainers.md
# /path/to/shap/references/plots.md
# /path/to/shap/references/workflows.md
# /path/to/shap/references/theory.md

Resumo de Boas Práticas

1. Escolha o explainer correto: Use explainers especializados (TreeExplainer, DeepExplainer, LinearExplainer) quando possível; evite KernelExplainer a menos que necessário

2. Comece global, depois vá local: Comece com plots beeswarm/bar para entendimento geral, depois mergulhe em plots waterfall/scatter para detalhes

3. Use múltiplas visualizações: Diferentes plots revelam diferentes insights; combine vistas global (beeswarm) + local (waterfall) + relação (scatter)

4. Selecione background data apropriado: Use 50-1000 amostras representativas dos dados de treinamento

5. Entenda unidades de saída de modelo: Saiba se explicando probabilidades, log-odds ou saídas brutas

6. Valide com conhecimento de domínio: SHAP mostra comportamento de modelo; use expertise de domínio para interpretar e validar

7. Otimize para performance: Amostra subsets para visualização, batch para datasets grandes, cache explainers em produção

8. Verifique vazamento de dados: Importância de features inesperadamente alta pode indicar problemas de qualidade de dados

9. Considere correlações de features: Use opções cientes de correlação de TreeExplainer ou clustering de features para features redundantes

10. Lembre que SHAP mostra associação, não causalidade: Use conhecimento de domínio para interpretação causal

Instalação

# Instalação básica
uv pip install shap

# Com dependências de visualização
uv pip install shap matplotlib

# Versão mais recente
uv pip install -U shap

Dependências: numpy, pandas, scikit-learn, matplotlib, scipy

Opcional: xgboost, lightgbm, tensorflow, torch (dependendo dos tipos de modelo)

Recursos Adicionais

• Documentação Oficial: https://shap.readthedocs.io/
• Repositório GitHub: https://github.com/slundberg/shap
• Paper Original: Lundberg & Lee (2017) - "A Unified Approach to Interpreting Model Predictions"
• Paper Nature MI: Lundberg et al. (2020) - "From local explanations to global understanding with explainable AI for trees"

Essa skill oferece cobertura abrangente de SHAP para interpretabilidade de modelos em todos os casos de uso e tipos de modelo.