0
# Visualization and Plotting
1

2
SHAP provides comprehensive visualization functions for understanding and communicating model explanations. All plotting functions work seamlessly with Explanation objects and support both interactive and static output formats.
3

4
## Capabilities
5

6
### Summary Visualizations
7

8
High-level overview plots showing feature importance and explanation patterns across datasets.
9

10
```python { .api }
11
def bar(shap_values, max_display=10, order=Explanation.abs, clustering=None, 
12
        clustering_cutoff=0.5, show_data="auto", ax=None, show=True):
13
    """
14
    Bar plot showing feature importance with SHAP values.
15
    
16
    Parameters:
17
    - shap_values: Explanation object, Cohorts, or dictionary of explanations
18
    - max_display: Number of top features to display (default: 10)
19
    - order: Function for sorting features (default: absolute values)
20
    - clustering: Partition tree for hierarchical clustering
21
    - show_data: Whether to show feature values in y-axis labels ("auto", True, False)
22
    - ax: Matplotlib axes object (optional)
23
    - show: Display plot immediately (bool)
24
    """
25

26
def beeswarm(shap_values, max_display=10, order=Explanation.abs.mean(0), 
27
             clustering=None, cluster_threshold=0.5, color=None, alpha=1.0, 
28
             ax=None, show=True, log_scale=False, s=16, plot_size="auto"):
29
    """
30
    Beeswarm plot showing distribution of feature impacts across samples.
31
    
32
    Each dot represents one sample's SHAP value for a feature, with position
33
    indicating impact magnitude and color showing feature value.
34
    
35
    Parameters:
36
    - shap_values: Explanation object with matrix of SHAP values
37
    - color: Colormap or color scheme for points
38
    - s: Size of scatter plot markers (default: 16)
39
    - plot_size: Control plot dimensions ("auto", float, or (width, height))
40
    - log_scale: Use logarithmic scale for SHAP values (bool)
41
    """
42

43
def violin(shap_values, features=None, feature_names=None, max_display=None,
44
           plot_type="violin", color=None, show=True, sort=True, color_bar=True,
45
           plot_size="auto", cmap=None):
46
    """
47
    Violin plot summary of SHAP value distributions across dataset.
48
    
49
    Shows density distribution of SHAP values for each feature,
50
    revealing patterns in feature importance across samples.
51
    
52
    Parameters:
53
    - plot_type: Type of plot ("violin", "layered_violin", "compact_dot")
54
    - sort: Sort features by importance (bool)
55
    - color_bar: Show color bar for feature values (bool)
56
    """
57
```
58

59
**Usage Example:**
60

61
```python
62
import shap
63

64
# Create explanations
65
explainer = shap.TreeExplainer(model)
66
shap_values = explainer(X)
67

68
# Summary visualizations
69
shap.plots.bar(shap_values)                    # Feature importance bar chart
70
shap.plots.beeswarm(shap_values)              # Feature impact distribution  
71
shap.plots.violin(shap_values, max_display=8) # Density distributions
72
```
73

74
### Individual Prediction Analysis
75

76
Detailed visualizations for understanding specific predictions and feature contributions.
77

78
```python { .api }
79
def waterfall(shap_values, max_display=10, show=True):
80
    """
81
    Waterfall chart showing additive feature contributions for single prediction.
82
    
83
    Shows how each feature pushes the prediction above or below the base value,
84
    with cumulative effect building to final prediction.
85
    
86
    Parameters:
87
    - shap_values: Single-row Explanation object only
88
    - max_display: Maximum features to show (default: 10)
89
    - show: Display plot immediately (bool)
90
    
91
    Note: Only accepts single prediction (one row of SHAP values)
92
    """
93

94
def force(base_value, shap_values=None, features=None, feature_names=None, 
95
          out_names=None, link="identity", plot_cmap="RdBu", matplotlib=False,
96
          show=True, figsize=(20, 3), contribution_threshold=0.05):
97
    """
98
    Interactive additive force layout visualization.
99
    
100
    Shows how features push prediction above/below baseline with
101
    proportional visual representation. Supports interactive JavaScript
102
    or static matplotlib output.
103
    
104
    Parameters:
105
    - base_value: Reference value or Explanation object
106
    - shap_values: SHAP values (optional if base_value is Explanation)
107
    - features: Feature values for display
108
    - link: Output transformation ("identity" or "logit")
109
    - matplotlib: Use matplotlib instead of JavaScript (default: False)
110
    - contribution_threshold: Threshold for displaying feature names (0-1)
111
    - figsize: Figure size for matplotlib output
112
    """
113

114
def decision(base_value, shap_values, features=None, feature_names=None,
115
             feature_order=None, feature_display_range=None, highlight=None,
116
             link=None, plot_color=None, axis_color="#333333", show=True):
117
    """
118
    Decision plot showing cumulative SHAP values.
119
    
120
    Traces path from base value to final prediction through
121
    cumulative feature contributions, useful for understanding
122
    prediction reasoning.
123
    
124
    Parameters:
125
    - feature_order: Order for displaying features
126
    - feature_display_range: Range of features to display
127
    - highlight: Highlight specific samples or features
128
    - plot_color: Colors for prediction paths
129
    """
130
```
131

132
### Feature Interaction Analysis
133

134
Visualizations for understanding feature relationships and dependencies.
135

136
```python { .api }
137
def scatter(shap_values, color="#1E88E5", hist=True, axis_color="#333333",
138
            cmap=None, dot_size=16, x_jitter="auto", alpha=1.0,
139
            title=None, xmin=None, xmax=None, ymin=None, ymax=None,
140
            overlay=None, ax=None, ylabel="SHAP value", show=True):
141
    """
142
    SHAP dependence scatter plot showing feature interactions.
143
    
144
    Plots SHAP values against feature values to show how feature
145
    impacts change across different feature values. Color can represent
146
    interaction effects with other features.
147
    
148
    Parameters:
149
    - color: Fixed color or Explanation object for coloring points
150
    - hist: Show histogram along x-axis (default: True)
151
    - x_jitter: Add random jitter for discrete features ("auto" or float)
152
    - dot_size: Size of scatter points
153
    - overlay: Additional data to overlay on plot
154
    """
155

156
def partial_dependence(ind, model, data, xmin="percentile(0)", 
157
                       xmax="percentile(100)", npoints=None, ice=True,
158
                       model_expected_value=False, feature_expected_value=False,
159
                       shap_values=None, ax=None, show=True):
160
    """
161
    Partial dependence plot with Individual Conditional Expectation (ICE) curves.
162
    
163
    Shows how model output changes as target feature varies, with
164
    individual sample trajectories and average trend.
165
    
166
    Parameters:
167
    - ind: Feature index or name to analyze
168
    - model: Model function for predictions
169
    - data: Background dataset for partial dependence
170
    - ice: Show individual conditional expectation curves (bool)
171
    - npoints: Number of points along feature range
172
    - model_expected_value: Show model's expected output
173
    - feature_expected_value: Show feature's expected value
174
    """
175

176
def heatmap(shap_values, instance_order=Explanation.hclust(), 
177
            feature_values=Explanation.abs.mean(0), feature_order=None,
178
            max_display=10, cmap=None, show=True, plot_width=8, ax=None):
179
    """
180
    Heatmap showing explanation patterns across instances and features.
181
    
182
    Uses supervised clustering to reveal population substructure
183
    and feature importance patterns.
184
    
185
    Parameters:
186
    - instance_order: Function for sample ordering (default: hierarchical clustering)
187
    - feature_values: Global summary values for features  
188
    - feature_order: Custom feature ordering (optional)
189
    - cmap: Colormap for heatmap
190
    - plot_width: Width of plot in inches
191
    """
192
```
193

194
### Specialized Data Type Visualizations
195

196
Visualizations optimized for specific input types like images, text, and embeddings.
197

198
```python { .api }
199
def image(shap_values, pixel_values=None, labels=None, true_labels=None,
200
          width=20, aspect=0.2, hspace=0.2, cmap=None, vmax=None, show=True):
201
    """
202
    Visualize SHAP values for image inputs with pixel-level attributions.
203
    
204
    Overlays SHAP importance on original images using color intensity
205
    to show which pixels contribute most to predictions.
206
    
207
    Parameters:
208
    - pixel_values: Original image pixel values
209
    - labels: Predicted class labels
210
    - true_labels: Ground truth labels (optional)
211
    - width: Width of visualization in inches
212
    - aspect: Aspect ratio for subplots
213
    - hspace: Vertical spacing between subplots
214
    - vmax: Maximum value for color scale normalization
215
    """
216

217
def text(shap_values, num_starting_labels=0, grouping_threshold=0.01,
218
         separator="", xmin=None, xmax=None, cmax=None, display=True):
219
    """
220
    Interactive text explanations with token-level coloring.
221
    
222
    Colors text tokens based on SHAP importance, with intensity
223
    indicating contribution magnitude and color indicating direction.
224
    
225
    Parameters:
226
    - num_starting_labels: Number of output labels to show initially
227
    - grouping_threshold: Threshold for grouping adjacent tokens
228
    - separator: Separator between tokens in display
229
    - cmax: Maximum color intensity
230
    - display: Show interactive HTML output (bool)
231
    """
232

233
def embedding(ind, shap_values, feature_names=None, method="pca", 
234
              alpha=1.0, show=True):
235
    """
236
    2D embedding visualization of SHAP values.
237
    
238
    Projects high-dimensional SHAP values to 2D space for
239
    visualization of explanation patterns and clustering.
240
    
241
    Parameters:
242
    - ind: Feature indices to include in embedding
243
    - method: Dimensionality reduction method ("pca", "tsne")
244
    - alpha: Transparency of points (0-1)
245
    """
246
```
247

248
### Monitoring and Comparison
249

250
Visualizations for model monitoring and comparative analysis across groups or time periods.
251

252
```python { .api }
253
def monitoring(ind, shap_values, features, feature_names=None, 
254
               show=True):
255
    """
256
    Monitor model behavior over time or across batches.
257
    
258
    Tracks how feature importance and prediction patterns
259
    change across different data slices or time periods.
260
    
261
    Parameters:
262
    - ind: Time or batch indices for x-axis
263
    - features: Feature values for trend analysis
264
    """
265

266
def group_difference(shap_values, group_mask, feature_names=None, 
267
                     show=True):
268
    """
269
    Compare SHAP values between different groups or populations.
270
    
271
    Shows difference in feature importance patterns between
272
    demographic groups, time periods, or other categorical divisions.
273
    
274
    Parameters:
275
    - group_mask: Boolean mask defining group membership
276
    - feature_names: Names for features in comparison
277
    """
278

279
def benchmark(benchmark_result, show=True):
280
    """
281
    Visualize benchmark results comparing different explanation methods.
282
    
283
    Shows performance metrics and quality comparisons across
284
    different explainer algorithms.
285
    
286
    Parameters:
287
    - benchmark_result: BenchmarkResult object with comparison data
288
    """
289
```
290

291
### JavaScript Integration and Export
292

293
Functions for web integration and interactive visualization export.
294

295
```python { .api }
296
def initjs():
297
    """Initialize JavaScript environment for interactive plots in Jupyter notebooks."""
298

299
def getjs():
300
    """Get JavaScript code for SHAP visualizations (for web embedding)."""
301

302
def save_html(out_file, plot_html):
303
    """
304
    Save interactive plot HTML to file.
305
    
306
    Parameters:  
307
    - out_file: Output file path
308
    - plot_html: HTML content from interactive plot
309
    """
310
```
311

312
## Legacy Plotting Functions
313

314
SHAP maintains backward compatibility with legacy plotting function names:
315

316
```python { .api }
317
# Legacy names (still supported)
318
def bar_plot(*args, **kwargs): ...      # Use shap.plots.bar
319
def summary_plot(*args, **kwargs): ...  # Use shap.plots.beeswarm  
320
def dependence_plot(*args, **kwargs): ... # Use shap.plots.scatter
321
def force_plot(*args, **kwargs): ...    # Use shap.plots.force
322
def waterfall_plot(*args, **kwargs): ... # Use shap.plots.waterfall
323
# ... and others
324
```
325

326
## Usage Patterns
327

328
### Basic Visualization Workflow
329

330
```python
331
import shap
332

333
# Generate explanations
334
explainer = shap.TreeExplainer(model)
335
shap_values = explainer(X)
336

337
# Overview visualizations
338
shap.plots.bar(shap_values, max_display=10)       # Top features
339
shap.plots.beeswarm(shap_values, max_display=15)  # Feature distributions
340

341
# Individual prediction analysis  
342
shap.plots.waterfall(shap_values[0])              # Single prediction
343
shap.plots.force(shap_values[0])                  # Interactive force plot
344

345
# Feature interactions
346
shap.plots.scatter(shap_values[:, "feature_name"]) # Dependence plot
347
shap.plots.heatmap(shap_values[:100])             # Pattern clustering
348
```
349

350
### Customization and Styling
351

352
All plotting functions support matplotlib customization:
353

354
```python
355
import matplotlib.pyplot as plt
356

357
# Custom styling
358
plt.style.use('seaborn-v0_8')
359
fig, ax = plt.subplots(figsize=(12, 8))
360

361
# Plot with custom axes
362
shap.plots.bar(shap_values, ax=ax, show=False)
363
ax.set_title("Custom SHAP Feature Importance")
364
plt.tight_layout()
365
plt.show()
366
```
367

368
### Interactive vs Static Output
369

370
Control output format based on environment:
371

372
```python
373
# Interactive (Jupyter notebook)
374
shap.plots.force(shap_values[0])  # JavaScript interactive
375

376
# Static (matplotlib) 
377
shap.plots.force(shap_values[0], matplotlib=True)  # PNG/SVG output
378

379
# For publication
380
shap.plots.waterfall(shap_values[0], show=False)
381
plt.savefig('explanation.pdf', dpi=300, bbox_inches='tight')
382
```
383

384
### Error Handling
385

386
Common visualization errors and solutions:
387

388
- **EmptyDataError**: No SHAP values provided or empty Explanation object
389
- **DimensionError**: Incompatible shapes between SHAP values and feature data  
390
- **ImportError**: Missing matplotlib for static plots or JavaScript dependencies
391
- **TypeError**: Incorrect data types (e.g., multi-output data to single-output plot)