Skip to content

v0.4.0

Release Date: 2026-03-21

Major feature release adding four new explainers (DeepSHAP, GradientSHAP, PartitionSHAP, AdditiveSHAP), TreeSHAP interaction values, three new tree model parsers, batch explanation API, and confidence intervals.

New Explainers

DeepSHAP

Efficient SHAP values for neural networks using DeepLIFT rescale rule.

  • DeepLIFT attribution: Backpropagates importance through network layers
  • ONNX support: Works with ONNX neural network models via ActivationSession
  • Layer support: Dense, ReLU, Sigmoid, Tanh, Softmax, Add, Identity
import "github.com/plexusone/shap-go/explainer/deepshap"

// Create DeepSHAP explainer for neural network
explainer, _ := deepshap.New(activationSession, background,
    explainer.WithFeatureNames(featureNames),
)

explanation, _ := explainer.Explain(ctx, instance)

GradientSHAP

Expected Gradients method using numerical differentiation.

  • Any differentiable model: Uses finite differences for gradient estimation
  • Local smoothing: Optional noise for smoother attributions
  • Confidence intervals: Built-in uncertainty quantification
import "github.com/plexusone/shap-go/explainer/gradient"

explainer, _ := gradient.New(model, background,
    gradient.WithEpsilon(1e-4),
    gradient.WithLocalSmoothing(true),
    explainer.WithConfidenceLevel(0.95),
)

explanation, _ := explainer.Explain(ctx, instance)

PartitionSHAP

Hierarchical Owen values for feature groupings.

  • Feature hierarchies: Respect domain structure (e.g., group related features)
  • Owen values: Game-theoretic extension of Shapley for grouped features
  • Flat mode: Falls back to standard SHAP when no hierarchy provided
import "github.com/plexusone/shap-go/explainer/partition"

// Define feature hierarchy
hierarchy := &partition.Node{
    Name: "root",
    Children: []*partition.Node{
        {Name: "demographics", Indices: []int{0, 1, 2}},
        {Name: "financial", Indices: []int{3, 4, 5}},
    },
}

explainer, _ := partition.New(model, background, hierarchy,
    explainer.WithFeatureNames(featureNames),
)

AdditiveSHAP

Exact SHAP for Generalized Additive Models (GAMs).

  • O(n×b) complexity: Linear in features and background size
  • Exact values: No approximation for additive models
  • Perfect accuracy: Guaranteed local accuracy property
import "github.com/plexusone/shap-go/explainer/additive"

// Define term functions for GAM: f(x) = f1(x1) + f2(x2) + ...
termFuncs := []additive.TermFunc{
    func(x float64) float64 { return 2.0 * x },      // Linear term
    func(x float64) float64 { return x * x },        // Quadratic term
    func(x float64) float64 { return math.Sin(x) },  // Nonlinear term
}

explainer, _ := additive.New(termFuncs, background,
    explainer.WithFeatureNames(featureNames),
)

TreeSHAP Enhancements

Interaction Values

Compute pairwise feature interactions showing how features work together.

import "github.com/plexusone/shap-go/explainer/tree"

// Get interaction values (returns n×n matrix)
result, _ := explainer.ExplainInteractions(ctx, instance)

// Access interactions
interaction := result.GetInteraction(0, 1)  // Interaction between features 0 and 1
mainEffect := result.MainEffect(0)          // Main effect of feature 0

New Model Parsers

  • CatBoost: Parse CatBoost JSON models with oblivious tree support
  • LightGBM Text: Parse .txt format from model.save_model()
  • ONNX-ML TreeEnsemble: Load tree models directly from ONNX format
// CatBoost
ensemble, _ := tree.LoadCatBoostModel("model.json")

// LightGBM text format
ensemble, _ := tree.LoadLightGBMTextModel("model.txt")

// ONNX-ML TreeEnsemble
ensemble, _ := tree.ParseONNXTreeEnsembleFromBytes(onnxBytes)

Batch Explanation API

Explain multiple instances efficiently with parallel processing.

import "github.com/plexusone/shap-go/explainer"

// Parallel batch explanations
config := explainer.BatchConfig{Workers: 4}
explanations, _ := explainer.ExplainBatchParallel(ctx, exp, instances, config)

// With progress tracking
explanations, _ := explainer.ExplainBatchWithProgress(ctx, exp, instances, config,
    func(completed, total int) {
        fmt.Printf("Progress: %d/%d\n", completed, total)
    },
)

Batched Model Predictions

Optimize coalition evaluation with batched model inference.

// Enable batched predictions for faster explanation
explainer, _ := kernel.New(model, background,
    explainer.WithBatchedPredictions(true),
)

Supported in: KernelSHAP, ExactSHAP, PermutationSHAP, SamplingSHAP, PartitionSHAP

Confidence Intervals

Uncertainty bounds for sampling-based SHAP methods.

explainer, _ := sampling.New(model, background,
    explainer.WithConfidenceLevel(0.95),
    explainer.WithNumSamples(1000),
)

explanation, _ := explainer.Explain(ctx, instance)

// Access confidence intervals
if explanation.HasConfidenceIntervals() {
    ci := explanation.GetConfidenceInterval(0)
    fmt.Printf("Feature 0: %.4f [%.4f, %.4f]\n",
        explanation.SHAPValues[0], ci.Lower, ci.Upper)
}

ONNX Enhancements

ActivationSession

Capture intermediate layer activations for DeepSHAP.

import "github.com/plexusone/shap-go/model/onnx"

config := onnx.ActivationConfig{
    Config:              onnx.Config{ModelPath: "model.onnx"},
    IntermediateOutputs: []string{"dense1", "relu1", "dense2"},
}

session, _ := onnx.NewActivationSession(config)
result, _ := session.PredictWithActivations(ctx, input)
// result.Activations["dense1"] contains layer output

Graph Parsing

Parse ONNX model structure for layer-wise analysis.

graphInfo, _ := onnx.ParseGraph("model.onnx")
for _, node := range graphInfo.Nodes {
    fmt.Printf("%s: %s -> %s\n", node.Name, node.OpType, node.LayerType)
}

New Examples

  • examples/deepshap/: Neural network explanations with DeepSHAP
  • examples/gradientshap/: Gradient-based explanations
  • examples/multiclass/: Multi-class classification SHAP values
  • examples/onnx_basic/: Model-agnostic SHAP for ONNX models

All 12 examples now include expected_output.md documentation.

Documentation

  • Explainer guides: DeepSHAP, GradientSHAP, PartitionSHAP, AdditiveSHAP
  • Background data guide: Best practices for reference data selection
  • API reference: Comprehensive docs for all explainers
  • LMS presentation: Udemy-style course with 7 sections
  • Coverage badge: 80% test coverage

Installation

go get github.com/plexusone/shap-go@v0.4.0

Upgrade Guide

  1. Update import: go get github.com/plexusone/shap-go@v0.4.0
  2. New explainers available: DeepSHAP, GradientSHAP, PartitionSHAP, AdditiveSHAP
  3. Use WithBatchedPredictions(true) for faster model-agnostic explanations
  4. Use WithConfidenceLevel() for uncertainty quantification
  5. TreeSHAP now supports CatBoost, LightGBM text, and ONNX-ML models

Contributors

  • plexusone
  • Claude Opus 4.5 (AI pair programmer)