alterlab-shap
Model interpretability and explainability with SHAP (SHapley Additive exPlanations) — feature importance and plots (waterfall, beeswarm, bar, scatter, force, heatmap). Use when explaining ML model predictions, computing feature importance, debugging models, analyzing bias or fair
Install
npx skills add https://github.com/AlterLab-IEU/AlterLab-Academic-Skills/tree/main/skills/data-science/alterlab-shap
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install alterlab-ieu-alterlab-academic-skills@llmmart
git clone https://github.com/AlterLab-IEU/AlterLab-Academic-Skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole alterlab-ieu/alterlab-academic-skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
SHAP (SHapley Additive exPlanations)
Overview
SHAP is a unified approach to explain machine learning model outputs using Shapley values from cooperative game theory. This skill provides comprehensive guidance for:
- Computing SHAP values for any model type
- Creating visualizations to understand feature importance
- Debugging and validating model behavior
- Analyzing fairness and bias
- Implementing explainable AI in production
SHAP works with all model types: tree-based models (XGBoost, LightGBM, CatBoost, Random Forest), deep learning models (TensorFlow, PyTorch, Keras), linear models, and black-box models.
When to Use This Skill
Trigger this skill when users ask about:
- "Explain which features are most important in my model"
- "Generate SHAP plots" (waterfall, beeswarm, bar, scatter, force, heatmap, etc.)
- "Why did my model make this prediction?"
- "Calculate SHAP values for my model"
- "Visualize feature importance using SHAP"
- "Debug my model's behavior" or "validate my model"
- "Check my model for bias" or "analyze fairness"
- "Compare feature importance across models"
- "Implement explainable AI" or "add explanations to my model"
- "Understand feature interactions"
- "Create model interpretation dashboard"
Does NOT Trigger
| Scenario | Use Instead |
|---|---|
| Profiling a raw dataset (distributions, missingness, correlations) before any model exists | alterlab-eda |
| Building, cross-validating, or tuning the model itself | alterlab-scikit-learn |
| Estimating the causal effect of an intervention (SHAP describes model associations, not causes) | alterlab-causal-inference |
Hand-off rule. When the request matches a row above, open your answer by naming that skill by its exact id (for example alterlab-eda) and saying in one line why it fits better, then stop applying this skill's procedure. Name it even when you also need to ask for missing input. If only part of the request is out of scope, name the skill for that part and do only the in-scope part. A brief general pointer is fine; the named skill does the work.
Quick Start Guide
Step 1: Select the Right Explainer
Decision Tree:
Tree-based model? (XGBoost, LightGBM, CatBoost, Random Forest, Gradient Boosting)
- Use
shap.TreeExplainer(fast, exact)
- Use
Deep neural network? (TensorFlow, PyTorch, Keras, CNNs, RNNs, Transformers)
- Use
shap.DeepExplainerorshap.GradientExplainer
- Use
Linear model? (Linear/Logistic Regression, GLMs)
- Use
shap.LinearExplainer(extremely fast)
- Use
Any other model? (SVMs, custom functions, black-box models)
- Use
shap.KernelExplainer(model-agnostic but slower)
- Use
Unsure?
- Use
shap.Explainer(automatically selects best algorithm)
- Use
See references/explainers.md for detailed information on all explainer types.
Step 2: Compute SHAP Values
import shap
# Example with tree-based model (XGBoost)
import xgboost as xgb
# Train model
model = xgb.XGBClassifier().fit(X_train, y_train)
# Create explainer
explainer = shap.TreeExplainer(model)
# Compute SHAP values
shap_values = explainer(X_test)
# The shap_values object contains:
# - values: SHAP values (feature attributions)
# - base_values: Expected model output (baseline)
# - data: Original feature values
Step 3: Visualize Results
For Global Understanding (entire dataset):
# Beeswarm plot - shows feature importance with value distributions
shap.plots.beeswarm(shap_values, max_display=15)
# Bar plot - clean summary of feature importance
shap.plots.bar(shap_values)
For Individual Predictions:
# Waterfall plot - detailed breakdown of single prediction
shap.plots.waterfall(shap_values[0])
# Force plot - additive force visualization
shap.plots.force(shap_values[0])
For Feature Relationships:
# Scatter plot - feature-prediction relationship
shap.plots.scatter(shap_values[:, "Feature_Name"])
# Colored by another feature to show interactions
shap.plots.scatter(shap_values[:, "Age"], color=shap_values[:, "Education"])
See references/plots.md for comprehensive guide on all plot types.
Core Workflows
This skill supports several common workflows. Choose the workflow that matches the current task.
Workflow 1: Basic Model Explanation
Goal: Understand what drives model predictions
Steps:
- Train model and create appropriate explainer
- Compute SHAP values for test set
- Generate global importance plots (beeswarm or bar)
- Examine top feature relationships (scatter plots)
- Explain specific predictions (waterfall plots)
Example:
# Step 1-2: Setup
explainer = shap.TreeExplainer(model)
shap_values = explainer(X_test)
# Step 3: Global importance
shap.plots.beeswarm(shap_values)
# Step 4: Feature relationships
shap.plots.scatter(shap_values[:, "Most_Important_Feature"])
# Step 5: Individual explanation
shap.plots.waterfall(shap_values[0])
Workflow 2: Model Debugging
Goal: Identify and fix model issues
Steps:
- Compute SHAP values
- Identify prediction errors
- Explain misclassified samples
- Check for unexpected feature importance (data leakage)
- Validate feature relationships make sense
- Check feature interactions
See references/workflows.md for detailed debugging workflow.
Workflow 3: Feature Engineering
Goal: Use SHAP insights to improve features
Steps:
- Compute SHAP values for baseline model
- Identify nonlinear relationships (candidates for transformation)
- Identify feature interactions (candidates for interaction terms)
- Engineer new features
- Retrain and compare SHAP values
- Validate improvements
See references/workflows.md for detailed feature engineering workflow.
Workflow 4: Model Comparison
Goal: Compare multiple models to select best interpretable option
Steps:
- Train multiple models
- Compute SHAP values for each
- Compare global feature importance
- Check consistency of feature rankings
- Analyze specific predictions across models
- Select based on accuracy, interpretability, and consistency
See references/workflows.md for detailed model comparison workflow.
Workflow 5: Fairness and Bias Analysis
Goal: Detect and analyze model bias across demographic groups
Steps:
- Identify protected attributes (gender, race, age, etc.)
- Compute SHAP values
- Compare feature importance across groups
- Check protected attribute SHAP importance
- Identify proxy features
- Implement mitigation strategies if bias found
See references/workflows.md for detailed fairness analysis workflow.
Workflow 6: Production Deployment
Goal: Integrate SHAP explanations into production systems
Steps:
- Train and save model
- Create and save explainer
- Build explanation service
- Create API endpoints for predictions with explanations
- Implement caching and optimization
- Monitor explanation quality
See references/workflows.md for detailed production deployment workflow.
Key Concepts
SHAP Values
Definition: SHAP values quantify each feature's contribution to a prediction, measured as the deviation from the expected model output (baseline).
Properties:
- Additivity: SHAP values sum to difference between prediction and baseline
- Fairness: Based on Shapley values from game theory
- Consistency: If a feature becomes more important, its SHAP value increases
Interpretation:
- Positive SHAP value → Feature pushes prediction higher
- Negative SHAP value → Feature pushes prediction lower
- Magnitude → Strength of feature's impact
- Sum of SHAP values → Total prediction change from baseline
Example:
Baseline (expected value): 0.30
Feature contributions (SHAP values):
Age: +0.15
Income: +0.10
Education: -0.05
Final prediction: 0.30 + 0.15 + 0.10 - 0.05 = 0.50
Background Data / Baseline
Purpose: Represents "typical" input to establish baseline expectations
Selection:
- Random sample from training data (50-1000 samples)
- Or use kmeans to select representative samples
- For DeepExplainer/KernelExplainer: 100-1000 samples balances accuracy and speed
Impact: Baseline affects SHAP value magnitudes but not relative importance
Model Output Types
Critical Consideration: Understand what your model outputs
- Raw output: For regression or tree margins
- Probability: For classification probability
- Log-odds: For logistic regression (before sigmoid)
Example: XGBoost classifiers explain margin output (log-odds) by default. To explain probabilities, use model_output="probability" in TreeExplainer.
Common Patterns
Pattern 1: Complete Model Analysis
# 1. Setup
explainer = shap.TreeExplainer(model)
shap_values = explainer(X_test)
# 2. Global importance
shap.plots.beeswarm(shap_values)
shap.plots.bar(shap_values)
# 3. Top feature relationships
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. Example predictions
for i in range(5):
shap.plots.waterfall(shap_values[i])
Pattern 2: Cohort Comparison
# Define cohorts
cohort1_mask = X_test['Group'] == 'A'
cohort2_mask = X_test['Group'] == 'B'
# Compare feature importance
shap.plots.bar({
"Group A": shap_values[cohort1_mask],
"Group B": shap_values[cohort2_mask]
})
Pattern 3: Debugging Errors
# Find errors
errors = model.predict(X_test) != y_test
error_indices = np.where(errors)[0]
# Explain errors
for idx in error_indices[:5]:
print(f"Sample {idx}:")
shap.plots.waterfall(shap_values[idx])
# Investigate key features
shap.plots.scatter(shap_values[:, "Suspicious_Feature"])
Performance Optimization
Speed Considerations
Explainer Speed (fastest to slowest):
LinearExplainer- Nearly instantaneousTreeExplainer- Very fastDeepExplainer- Fast for neural networksGradientExplainer- Fast for neural networksKernelExplainer- Slow (use only when necessary)PermutationExplainer- Very slow but accurate
Optimization Strategies
For Large Datasets:
# Compute SHAP for subset
shap_values = explainer(X_test[:1000])
# Or 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)
For Visualizations:
# Sample subset for plots
shap.plots.beeswarm(shap_values[:1000])
# Adjust transparency for dense plots
shap.plots.scatter(shap_values[:, "Feature"], alpha=0.3)
For Production:
# Cache explainer
import joblib
joblib.dump(explainer, 'explainer.pkl')
explainer = joblib.load('explainer.pkl')
# Pre-compute for batch predictions
# Only compute top N features for API responses
Troubleshooting
Issue: Wrong explainer choice
Problem: Using KernelExplainer for tree models (slow and unnecessary) Solution: Always use TreeExplainer for tree-based models
Issue: Insufficient background data
Problem: DeepExplainer/KernelExplainer with too few background samples Solution: Use 100-1000 representative samples
Issue: Confusing units
Problem: Interpreting log-odds as probabilities Solution: Check model output type; understand whether values are probabilities, log-odds, or raw outputs
Issue: Plots don't display
Problem: Matplotlib backend issues
Solution: Ensure backend is set correctly; use plt.show() if needed
Issue: Too many features cluttering plots
Problem: Default max_display=10 may be too many or too few
Solution: Adjust max_display parameter or use feature clustering
Issue: Slow computation
Problem: Computing SHAP for very large datasets Solution: Sample subset, use batching, or ensure using specialized explainer (not KernelExplainer)
Integration with Other Tools
- Jupyter: interactive force plots render inline; plots display with
show=True(default). For saving to file, passshow=Falsethenplt.savefig(...). - MLflow / experiment tracking: log plots with
mlflow.log_figure(plt.gcf(), "shap_beeswarm.png")and lognp.abs(shap_values.values).mean(0)per feature as metrics. Full snippet inreferences/workflows.md(MLOps integration). - Production APIs: persist model + explainer with
joblib, recompute SHAP at request time, return base value + per-feature contributions. FullExplanationServiceclass inreferences/workflows.md(Workflow 7).
Reference Documentation
Load these on demand (via Read) for depth beyond this SKILL.md:
references/explainers.md— every explainer class (constructor params, supported models, methods, perf). Load when choosing an explainer or needing exact parameters.references/plots.md— every plot function (params, use cases, plot-selection guide). Load when picking or tuning a visualization.references/workflows.md— full step-by-step workflows (debugging, feature engineering, model comparison, fairness, deep learning, production, time series, MLOps). Load for multi-step tasks.references/theory.md— Shapley-value math, axioms, computation algorithms, conditional expectations, comparisons to LIME/permutation/Gini importance. Load for theoretical questions.
Best Practices Summary
Choose the right explainer: Use specialized explainers (TreeExplainer, DeepExplainer, LinearExplainer) when possible; avoid KernelExplainer unless necessary
Start global, then go local: Begin with beeswarm/bar plots for overall understanding, then dive into waterfall/scatter plots for details
Use multiple visualizations: Different plots reveal different insights; combine global (beeswarm) + local (waterfall) + relationship (scatter) views
Select appropriate background data: Use 50-1000 representative samples from training data
Understand model output units: Know whether explaining probabilities, log-odds, or raw outputs
Validate with domain knowledge: SHAP shows model behavior; use domain expertise to interpret and validate
Optimize for performance: Sample subsets for visualization, batch for large datasets, cache explainers in production
Check for data leakage: Unexpectedly high feature importance may indicate data quality issues
Consider feature correlations: Use TreeExplainer's correlation-aware options or feature clustering for redundant features
Remember SHAP shows association, not causation: Use domain knowledge for causal interpretation
Installation
The modern API used throughout this skill — the callable explainer(X) returning an Explanation object, plus the shap.plots.* namespace — requires shap >= 0.41. The current release is 0.52 (May 2026; requires Python ≥ 3.12 and NumPy ≥ 2), with 0.53 in release candidate as of 2026-09. Pin it in a uv project:
# In a uv project (adds to pyproject.toml + uv.lock):
uv add "shap>=0.41" matplotlib
# Scratch / one-off run (ephemeral env, nothing persisted):
uv run --python ">=3.12" --with "shap>=0.41" --with matplotlib python explain.py
(uv pip install works only inside an already-activated venv; prefer uv add / uv run --with so the dependency is recorded.)
Dependencies: numpy, pandas, scikit-learn, scipy, and numba are pulled in automatically. matplotlib is optional (the shap[plots] extra), so install it explicitly as above before calling shap.plots.*.
Optional: xgboost, lightgbm, catboost, tensorflow, torch (depending on model types).
Additional Resources
- Official Documentation: https://shap.readthedocs.io/
- GitHub Repository: https://github.com/shap/shap
- Original Paper: Lundberg & Lee (2017) - "A Unified Approach to Interpreting Model Predictions"
- Nature MI Paper: Lundberg et al. (2020) - "From local explanations to global understanding with explainable AI for trees"
This skill provides comprehensive coverage of SHAP for model interpretability across all use cases and model types.
Files (alterlab-academic-skills)
-
evals
-
evals.json 2.9 KB
Loading…
-
-
references
-
explainers.md 12.8 KB
Loading… -
plots.md 16.2 KB
Loading… -
theory.md 16.6 KB
Loading… -
workflows.md 19.3 KB
Loading…
-
-
SKILL.md 17 KB
--- name: alterlab-shap description: Model interpretability and explainability with SHAP (SHapley Additive exPlanations) — feature importance and plots (waterfall, beeswarm, bar, scatter, force, heatmap). Use when explaining ML model predictions, computing feature importance, debugging models, analyzing bias or fairness, comparing models, or implementing explainable AI across tree-based models (XGBoost, LightGBM, Random Forest), deep learning (TensorFlow, PyTorch), linear models, and any black-box model. Part of the AlterLab Academic Skills suite. license: MIT allowed-tools: Read Write Edit Bash(python:*) Bash(uv:*) compatibility: No API key required. Runs locally via `uv run --python ">=3.12" --with "shap>=0.41" --with matplotlib python script.py` (no install step; the interpreter pin matters because an older default Python resolves older releases); requires shap >= 0.41 for the Explanation/`shap.plots` API (current 0.52 as of 2026-09, Python >= 3.12) plus matplotlib for plots. metadata: skill-author: AlterLab version: "1.0.1" last_updated: "2026-09-23" --- # SHAP (SHapley Additive exPlanations) ## Overview SHAP is a unified approach to explain machine learning model outputs using Shapley values from cooperative game theory. This skill provides comprehensive guidance for: - Computing SHAP values for any model type - Creating visualizations to understand feature importance - Debugging and validating model behavior - Analyzing fairness and bias - Implementing explainable AI in production SHAP works with all model types: tree-based models (XGBoost, LightGBM, CatBoost, Random Forest), deep learning models (TensorFlow, PyTorch, Keras), linear models, and black-box models. ## When to Use This Skill **Trigger this skill when users ask about**: - "Explain which features are most important in my model" - "Generate SHAP plots" (waterfall, beeswarm, bar, scatter, force, heatmap, etc.) - "Why did my model make this prediction?" - "Calculate SHAP values for my model" - "Visualize feature importance using SHAP" - "Debug my model's behavior" or "validate my model" - "Check my model for bias" or "analyze fairness" - "Compare feature importance across models" - "Implement explainable AI" or "add explanations to my model" - "Understand feature interactions" - "Create model interpretation dashboard" ### Does NOT Trigger | Scenario | Use Instead | |----------|-------------| | Profiling a raw dataset (distributions, missingness, correlations) before any model exists | `alterlab-eda` | | Building, cross-validating, or tuning the model itself | `alterlab-scikit-learn` | | Estimating the causal effect of an intervention (SHAP describes model associations, not causes) | `alterlab-causal-inference` | **Hand-off rule.** When the request matches a row above, open your answer by naming that skill by its exact id (for example `alterlab-eda`) and saying in one line why it fits better, then stop applying this skill's procedure. Name it even when you also need to ask for missing input. If only part of the request is out of scope, name the skill for that part and do only the in-scope part. A brief general pointer is fine; the named skill does the work. ## Quick Start Guide ### Step 1: Select the Right Explainer **Decision Tree**: 1. **Tree-based model?** (XGBoost, LightGBM, CatBoost, Random Forest, Gradient Boosting) - Use `shap.TreeExplainer` (fast, exact) 2. **Deep neural network?** (TensorFlow, PyTorch, Keras, CNNs, RNNs, Transformers) - Use `shap.DeepExplainer` or `shap.GradientExplainer` 3. **Linear model?** (Linear/Logistic Regression, GLMs) - Use `shap.LinearExplainer` (extremely fast) 4. **Any other model?** (SVMs, custom functions, black-box models) - Use `shap.KernelExplainer` (model-agnostic but slower) 5. **Unsure?** - Use `shap.Explainer` (automatically selects best algorithm) **See `references/explainers.md` for detailed information on all explainer types.** ### Step 2: Compute SHAP Values ```python import shap # Example with tree-based model (XGBoost) import xgboost as xgb # Train model model = xgb.XGBClassifier().fit(X_train, y_train) # Create explainer explainer = shap.TreeExplainer(model) # Compute SHAP values shap_values = explainer(X_test) # The shap_values object contains: # - values: SHAP values (feature attributions) # - base_values: Expected model output (baseline) # - data: Original feature values ``` ### Step 3: Visualize Results **For Global Understanding** (entire dataset): ```python # Beeswarm plot - shows feature importance with value distributions shap.plots.beeswarm(shap_values, max_display=15) # Bar plot - clean summary of feature importance shap.plots.bar(shap_values) ``` **For Individual Predictions**: ```python # Waterfall plot - detailed breakdown of single prediction shap.plots.waterfall(shap_values[0]) # Force plot - additive force visualization shap.plots.force(shap_values[0]) ``` **For Feature Relationships**: ```python # Scatter plot - feature-prediction relationship shap.plots.scatter(shap_values[:, "Feature_Name"]) # Colored by another feature to show interactions shap.plots.scatter(shap_values[:, "Age"], color=shap_values[:, "Education"]) ``` **See `references/plots.md` for comprehensive guide on all plot types.** ## Core Workflows This skill supports several common workflows. Choose the workflow that matches the current task. ### Workflow 1: Basic Model Explanation **Goal**: Understand what drives model predictions **Steps**: 1. Train model and create appropriate explainer 2. Compute SHAP values for test set 3. Generate global importance plots (beeswarm or bar) 4. Examine top feature relationships (scatter plots) 5. Explain specific predictions (waterfall plots) **Example**: ```python # Step 1-2: Setup explainer = shap.TreeExplainer(model) shap_values = explainer(X_test) # Step 3: Global importance shap.plots.beeswarm(shap_values) # Step 4: Feature relationships shap.plots.scatter(shap_values[:, "Most_Important_Feature"]) # Step 5: Individual explanation shap.plots.waterfall(shap_values[0]) ``` ### Workflow 2: Model Debugging **Goal**: Identify and fix model issues **Steps**: 1. Compute SHAP values 2. Identify prediction errors 3. Explain misclassified samples 4. Check for unexpected feature importance (data leakage) 5. Validate feature relationships make sense 6. Check feature interactions **See `references/workflows.md` for detailed debugging workflow.** ### Workflow 3: Feature Engineering **Goal**: Use SHAP insights to improve features **Steps**: 1. Compute SHAP values for baseline model 2. Identify nonlinear relationships (candidates for transformation) 3. Identify feature interactions (candidates for interaction terms) 4. Engineer new features 5. Retrain and compare SHAP values 6. Validate improvements **See `references/workflows.md` for detailed feature engineering workflow.** ### Workflow 4: Model Comparison **Goal**: Compare multiple models to select best interpretable option **Steps**: 1. Train multiple models 2. Compute SHAP values for each 3. Compare global feature importance 4. Check consistency of feature rankings 5. Analyze specific predictions across models 6. Select based on accuracy, interpretability, and consistency **See `references/workflows.md` for detailed model comparison workflow.** ### Workflow 5: Fairness and Bias Analysis **Goal**: Detect and analyze model bias across demographic groups **Steps**: 1. Identify protected attributes (gender, race, age, etc.) 2. Compute SHAP values 3. Compare feature importance across groups 4. Check protected attribute SHAP importance 5. Identify proxy features 6. Implement mitigation strategies if bias found **See `references/workflows.md` for detailed fairness analysis workflow.** ### Workflow 6: Production Deployment **Goal**: Integrate SHAP explanations into production systems **Steps**: 1. Train and save model 2. Create and save explainer 3. Build explanation service 4. Create API endpoints for predictions with explanations 5. Implement caching and optimization 6. Monitor explanation quality **See `references/workflows.md` for detailed production deployment workflow.** ## Key Concepts ### SHAP Values **Definition**: SHAP values quantify each feature's contribution to a prediction, measured as the deviation from the expected model output (baseline). **Properties**: - **Additivity**: SHAP values sum to difference between prediction and baseline - **Fairness**: Based on Shapley values from game theory - **Consistency**: If a feature becomes more important, its SHAP value increases **Interpretation**: - Positive SHAP value → Feature pushes prediction higher - Negative SHAP value → Feature pushes prediction lower - Magnitude → Strength of feature's impact - Sum of SHAP values → Total prediction change from baseline **Example**: ``` Baseline (expected value): 0.30 Feature contributions (SHAP values): Age: +0.15 Income: +0.10 Education: -0.05 Final prediction: 0.30 + 0.15 + 0.10 - 0.05 = 0.50 ``` ### Background Data / Baseline **Purpose**: Represents "typical" input to establish baseline expectations **Selection**: - Random sample from training data (50-1000 samples) - Or use kmeans to select representative samples - For DeepExplainer/KernelExplainer: 100-1000 samples balances accuracy and speed **Impact**: Baseline affects SHAP value magnitudes but not relative importance ### Model Output Types **Critical Consideration**: Understand what your model outputs - **Raw output**: For regression or tree margins - **Probability**: For classification probability - **Log-odds**: For logistic regression (before sigmoid) **Example**: XGBoost classifiers explain margin output (log-odds) by default. To explain probabilities, use `model_output="probability"` in TreeExplainer. ## Common Patterns ### Pattern 1: Complete Model Analysis ```python # 1. Setup explainer = shap.TreeExplainer(model) shap_values = explainer(X_test) # 2. Global importance shap.plots.beeswarm(shap_values) shap.plots.bar(shap_values) # 3. Top feature relationships 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. Example predictions for i in range(5): shap.plots.waterfall(shap_values[i]) ``` ### Pattern 2: Cohort Comparison ```python # Define cohorts cohort1_mask = X_test['Group'] == 'A' cohort2_mask = X_test['Group'] == 'B' # Compare feature importance shap.plots.bar({ "Group A": shap_values[cohort1_mask], "Group B": shap_values[cohort2_mask] }) ``` ### Pattern 3: Debugging Errors ```python # Find errors errors = model.predict(X_test) != y_test error_indices = np.where(errors)[0] # Explain errors for idx in error_indices[:5]: print(f"Sample {idx}:") shap.plots.waterfall(shap_values[idx]) # Investigate key features shap.plots.scatter(shap_values[:, "Suspicious_Feature"]) ``` ## Performance Optimization ### Speed Considerations **Explainer Speed** (fastest to slowest): 1. `LinearExplainer` - Nearly instantaneous 2. `TreeExplainer` - Very fast 3. `DeepExplainer` - Fast for neural networks 4. `GradientExplainer` - Fast for neural networks 5. `KernelExplainer` - Slow (use only when necessary) 6. `PermutationExplainer` - Very slow but accurate ### Optimization Strategies **For Large Datasets**: ```python # Compute SHAP for subset shap_values = explainer(X_test[:1000]) # Or 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) ``` **For Visualizations**: ```python # Sample subset for plots shap.plots.beeswarm(shap_values[:1000]) # Adjust transparency for dense plots shap.plots.scatter(shap_values[:, "Feature"], alpha=0.3) ``` **For Production**: ```python # Cache explainer import joblib joblib.dump(explainer, 'explainer.pkl') explainer = joblib.load('explainer.pkl') # Pre-compute for batch predictions # Only compute top N features for API responses ``` ## Troubleshooting ### Issue: Wrong explainer choice **Problem**: Using KernelExplainer for tree models (slow and unnecessary) **Solution**: Always use TreeExplainer for tree-based models ### Issue: Insufficient background data **Problem**: DeepExplainer/KernelExplainer with too few background samples **Solution**: Use 100-1000 representative samples ### Issue: Confusing units **Problem**: Interpreting log-odds as probabilities **Solution**: Check model output type; understand whether values are probabilities, log-odds, or raw outputs ### Issue: Plots don't display **Problem**: Matplotlib backend issues **Solution**: Ensure backend is set correctly; use `plt.show()` if needed ### Issue: Too many features cluttering plots **Problem**: Default max_display=10 may be too many or too few **Solution**: Adjust `max_display` parameter or use feature clustering ### Issue: Slow computation **Problem**: Computing SHAP for very large datasets **Solution**: Sample subset, use batching, or ensure using specialized explainer (not KernelExplainer) ## Integration with Other Tools - **Jupyter**: interactive force plots render inline; plots display with `show=True` (default). For saving to file, pass `show=False` then `plt.savefig(...)`. - **MLflow / experiment tracking**: log plots with `mlflow.log_figure(plt.gcf(), "shap_beeswarm.png")` and log `np.abs(shap_values.values).mean(0)` per feature as metrics. Full snippet in `references/workflows.md` (MLOps integration). - **Production APIs**: persist model + explainer with `joblib`, recompute SHAP at request time, return base value + per-feature contributions. Full `ExplanationService` class in `references/workflows.md` (Workflow 7). ## Reference Documentation Load these on demand (via Read) for depth beyond this SKILL.md: - **`references/explainers.md`** — every explainer class (constructor params, supported models, methods, perf). Load when choosing an explainer or needing exact parameters. - **`references/plots.md`** — every plot function (params, use cases, plot-selection guide). Load when picking or tuning a visualization. - **`references/workflows.md`** — full step-by-step workflows (debugging, feature engineering, model comparison, fairness, deep learning, production, time series, MLOps). Load for multi-step tasks. - **`references/theory.md`** — Shapley-value math, axioms, computation algorithms, conditional expectations, comparisons to LIME/permutation/Gini importance. Load for theoretical questions. ## Best Practices Summary 1. **Choose the right explainer**: Use specialized explainers (TreeExplainer, DeepExplainer, LinearExplainer) when possible; avoid KernelExplainer unless necessary 2. **Start global, then go local**: Begin with beeswarm/bar plots for overall understanding, then dive into waterfall/scatter plots for details 3. **Use multiple visualizations**: Different plots reveal different insights; combine global (beeswarm) + local (waterfall) + relationship (scatter) views 4. **Select appropriate background data**: Use 50-1000 representative samples from training data 5. **Understand model output units**: Know whether explaining probabilities, log-odds, or raw outputs 6. **Validate with domain knowledge**: SHAP shows model behavior; use domain expertise to interpret and validate 7. **Optimize for performance**: Sample subsets for visualization, batch for large datasets, cache explainers in production 8. **Check for data leakage**: Unexpectedly high feature importance may indicate data quality issues 9. **Consider feature correlations**: Use TreeExplainer's correlation-aware options or feature clustering for redundant features 10. **Remember SHAP shows association, not causation**: Use domain knowledge for causal interpretation ## Installation The modern API used throughout this skill — the callable `explainer(X)` returning an `Explanation` object, plus the `shap.plots.*` namespace — requires **shap >= 0.41**. The current release is **0.52** (May 2026; requires Python ≥ 3.12 and NumPy ≥ 2), with 0.53 in release candidate as of 2026-09. Pin it in a uv project: ```bash # In a uv project (adds to pyproject.toml + uv.lock): uv add "shap>=0.41" matplotlib # Scratch / one-off run (ephemeral env, nothing persisted): uv run --python ">=3.12" --with "shap>=0.41" --with matplotlib python explain.py ``` (`uv pip install` works only inside an already-activated venv; prefer `uv add` / `uv run --with` so the dependency is recorded.) **Dependencies**: numpy, pandas, scikit-learn, scipy, and numba are pulled in automatically. matplotlib is optional (the `shap[plots]` extra), so install it explicitly as above before calling `shap.plots.*`. **Optional**: xgboost, lightgbm, catboost, tensorflow, torch (depending on model types). ## Additional Resources - **Official Documentation**: https://shap.readthedocs.io/ - **GitHub Repository**: https://github.com/shap/shap - **Original Paper**: Lundberg & Lee (2017) - "A Unified Approach to Interpreting Model Predictions" - **Nature MI Paper**: Lundberg et al. (2020) - "From local explanations to global understanding with explainable AI for trees" This skill provides comprehensive coverage of SHAP for model interpretability across all use cases and model types.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.