domains / data / shap-model-explanation / shap

shap

Skill card

combined

The K-Dense-AI copy is a rigorous, version-pinned procedure for SHAP 0.52.0 that includes operating rules, additivity validation, and security constraints. The other three copies (Vibe-Skills, medical-research-skills, OpenClaw-Medical-Skills) are nearly identical to each other and provide a broader, more general guide with specific workflows for debugging, feature engineering, model comparison, and fairness analysis that the K-Dense copy lacks. Because the K-Dense copy is a specialized, high-fidelity version of the core procedure while the others add distinct workflow steps, crowning one would hide the other's material steps.

Repositories

Other copies

Combined skill

---
name: shap
description: Explain and audit machine-learning predictions with SHAP. Use for selecting explainers, computing attributions, and producing visualizations or fairness analyses.
---

# SHAP

Use SHAP to describe how a fitted predictive model maps inputs to outputs. Work from the modern `shap.Explanation` API, make the explained output and background distribution explicit, and validate every explanation before interpreting it.

## Operating Rules
1. Explain a fixed, evaluated model; do not use SHAP as a substitute for predictive validation.
2. Use held-out or clearly labeled analysis rows for explanations. Choose background rows only from an appropriate training or reference population.
3. State the explained output: regression value, raw margin, probability, log loss, logit, or another model method.
4. Prefer `shap.Explanation` objects and `explainer(X)`. Preserve output indexes and baselines explicitly.
5. For multi-output models, select one output before using tabular plots: `explanation[..., output_index]`.
6. Check `base_values + values.sum(...)` against the exact model output being explained.
7. Treat SHAP as a description of model behavior under a masking/background choice. It does not establish causality, fairness, recourse, or scientific mechanism.
8. Never silence an additivity failure until input shape, preprocessing, model version, output space, and row ordering have been checked.
9. Do not load untrusted pickle, joblib, model, or explainer artifacts.

## Standard Workflow

### 1. Define the explanation target
Record the model version, exact callable, output name/index, evaluation rows, background population, and masker/explainer algorithm.

### 2. Select an explainer and masker
- **Tree-based model**: Use `shap.TreeExplainer`.
- **Deep neural network**: Use `shap.DeepExplainer` or `shap.GradientExplainer`.
- **Linear model**: Use `shap.LinearExplainer`.
- **Black-box model**: Use `shap.KernelExplainer`.
- **Unsure**: Use `shap.Explainer` for automatic dispatch.

### 3. Compute a modern `Explanation`
```python
import shap
explainer = shap.Explainer(model, masker)
explanation = explainer(X_test)
```

### 4. Visualize Results
- **Global**: `shap.plots.beeswarm(explanation)` or `shap.plots.bar(explanation)`.
- **Individual**: `shap.plots.waterfall(explanation[0])` or `shap.plots.force(explanation[0])`.
- **Feature Relationships**: `shap.plots.scatter(explanation[:, "Feature_Name"])`.

### 5. Advanced Workflows
- **Model Debugging**: Identify prediction errors, explain misclassified samples, and check for data leakage via unexpected feature importance.
- **Feature Engineering**: Identify nonlinear relationships and interactions to guide new feature creation.
- **Model Comparison**: Compare global feature importance and consistency across multiple models.
- **Fairness and Bias**: Compare feature importance across demographic groups to detect bias.