shap_enhanced.tools.visulization

SHAP Visualization Utilities

Overview

This module provides a set of clean, publication-ready visualization utilities for comparing SHAP attributions against ground-truth or across multiple explainers. The visualizations support both sequential (2D) and tabular (1D) input formats and offer multiple views such as bar plots, 3D surface plots, and 3D bar plots.

The focus is on clarity, aesthetics, and comparability, making the tools well-suited for research papers, presentations, and internal model audits.

Key Functions

  • plot_mse_pearson: Bar chart comparing MSE and Pearson correlation of each explainer vs ground-truth SHAP.

  • plot_3d_surface: Side-by-side 3D surface plots for ground-truth and predicted SHAP values over time and features.

  • plot_3d_bars: Paired 3D bar plots for SHAP values, visually appealing and easy to compare height/direction.

  • plot_feature_comparison: Side-by-side bar plots for SHAP values from different explainers (1D/tabular inputs only).

Customization

  • Color maps: Most functions support custom colormaps via cmap (default: ‘viridis’).

  • Saving: All plots can be saved using the save argument (PDF/PNG via matplotlib).

  • Interactivity: Plots are shown by default, but this can be toggled with show=False.

Use Case

These tools are especially useful for: - Benchmarking explainers on synthetic datasets. - Visualizing time-series explanations (e.g., SHAP over (T, F) inputs). - Comparing surrogate vs exact SHAP explainers. - Producing clean visuals for publications and reports.

Example

plot_mse_pearson(mse_dict, pearson_dict, save="comparison.pdf")

plot_3d_surface(gt_shap, shap_outputs, seq_len=10, n_features=5)

plot_feature_comparison(gt_tab, shap_dict_tabular)

Functions

plot_3d_bars(shap_gt, shap_models, seq_len, ...)

Visual comparison of SHAP values using 3D bar plots for ground-truth and explainer outputs.

plot_3d_surface(shap_gt, shap_models, ...[, ...])

Generate side-by-side 3D surface plots for SHAP values from ground-truth and explainers.

plot_feature_comparison(shap_gt, shap_models)

Plot bar charts comparing 1D/tabular SHAP attributions across explainers and ground truth.

plot_mse_pearson(results, pearson_results[, ...])

Plot comparison of Mean Squared Error and Pearson Correlation across SHAP explainers.
shap_enhanced.tools.visulization.plot_3d_bars(shap_gt, shap_models, seq_len, n_features, save=None, bar_alpha=0.88, bar_color='#3498db', show=True)[source]

Visual comparison of SHAP values using 3D bar plots for ground-truth and explainer outputs.

Emphasizes direction and magnitude using colored bars over (T, F) space.

Parameters:

  • shap_gt (np.ndarray) – Ground-truth SHAP values.

  • shap_models (dict) – Dictionary mapping explainer names to SHAP arrays.

  • seq_len (int) – Length of the sequence (T).

  • n_features (int) – Number of input features (F).

  • save (str) – Optional path to save the plot.

  • bar_alpha (float) – Transparency of bars (default: 0.88).

  • bar_color (str) – Hex color string for positive bars.

  • show (bool) – Whether to display the figure.

shap_enhanced.tools.visulization.plot_3d_surface(shap_gt, shap_models, seq_len, n_features, save=None, cmap='viridis', vlim=None, show=True)[source]

Generate side-by-side 3D surface plots for SHAP values from ground-truth and explainers.

Used for comparing SHAP explanations on sequential (T, F) inputs with rich spatial structure.

Parameters:

  • shap_gt (np.ndarray) – Ground-truth SHAP array (T, F) or (1, T, F).

  • shap_models (dict) – Dictionary mapping explainer names to SHAP arrays.

  • seq_len (int) – Sequence length (T).

  • n_features (int) – Number of input features (F).

  • save (str) – Optional filename to save the figure.

  • cmap (str) – Colormap for surface shading.

  • vlim (tuple) – Optional tuple of (vmin, vmax) for shared Z-axis scaling.

  • show (bool) – Whether to display the figure.

shap_enhanced.tools.visulization.plot_feature_comparison(shap_gt, shap_models, feature_names=None, save=None)[source]

Plot bar charts comparing 1D/tabular SHAP attributions across explainers and ground truth.

Parameters:

  • shap_gt (np.ndarray) – Ground-truth SHAP values (1D).

  • shap_models (dict) – Dictionary of SHAP arrays from different explainers.

  • feature_names (list) – Optional list of feature names.

  • save (str) – Optional path to save the plot.

shap_enhanced.tools.visulization.plot_mse_pearson(results, pearson_results, save=None, bar_threshold=4, cmap='viridis', show=True)[source]

Plot comparison of Mean Squared Error and Pearson Correlation across SHAP explainers.

Generates side-by-side bar charts to compare each explainer’s SHAP attributions to ground-truth values.

Parameters:

  • results (dict) – Dictionary mapping explainer names to MSE values.

  • pearson_results (dict) – Dictionary mapping explainer names to Pearson correlation scores.

  • save (str) – Optional filename to save the figure (PDF/PNG).

  • bar_threshold (int) – Orientation switches to horizontal if number of bars exceeds this threshold.

  • cmap (str) – Colormap name for value encoding (default: “viridis”).

  • show (bool) – Whether to display the plot.