Skip to content

v0.2.0

Release Date: 2025-03-14

Major feature release adding TreeSHAP and LinearSHAP explainers, comprehensive documentation, and CI infrastructure.

Breaking Changes

Masker Interface Change

The Masker.Mask() method now returns ([]float64, error) instead of []float64. Previously, dimension mismatches caused panics; now they return descriptive errors.

Before (v0.1.0):

result := masker.Mask(instance, mask)  // panics on mismatch

After (v0.2.0):

result, err := masker.Mask(instance, mask)
if err != nil {
    // Handle ErrInstanceFeatureMismatch, ErrMaskFeatureMismatch, etc.
}

Migration: Add error handling to all Mask() and MaskWithBackground() calls.

New Features

TreeSHAP Explainer

Exact SHAP values for tree ensemble models in O(TLD²) time—40-100x faster than permutation methods.

  • XGBoost support: Load JSON models via tree.LoadXGBoostModel()
  • LightGBM support: Load JSON models via tree.LoadLightGBMModel()
  • Python SHAP equivalence: Validated against Python SHAP library
import "github.com/plexusone/shap-go/explainer/tree"

ensemble, _ := tree.LoadXGBoostModel("model.json")
explainer, _ := tree.New(ensemble)
explanation, _ := explainer.Explain(ctx, instance)

LinearSHAP Explainer

Exact closed-form SHAP values for linear models using the analytical solution: SHAP[i] = coef[i] * (x[i] - E[X[i]])

  • O(d) complexity where d is number of features
  • Support for linear regression and logistic regression
import "github.com/plexusone/shap-go/explainer/linear"

explainer, _ := linear.New(coefficients, intercept, backgroundMeans)
explanation, _ := explainer.Explain(ctx, instance)

New Examples

  • examples/treeshap/: TreeSHAP with XGBoost/LightGBM models
  • examples/linearshap/: LinearSHAP for linear regression
  • examples/sampling/: SamplingSHAP Monte Carlo approximation
  • examples/batch/: Batch processing multiple instances
  • examples/visualization/: ChartIR output generation

Documentation

  • MkDocs site: Comprehensive documentation at /docs/
  • Explainer guides: Detailed guides for each explainer type
  • Model integration: XGBoost, LightGBM, ONNX integration docs
  • API reference: Complete API documentation
  • Benchmarks: Performance comparisons

Infrastructure

  • CI/CD: GitHub Actions workflows for testing, linting, and docs deployment
  • Multi-version testing: Go 1.21, 1.22, 1.23 matrix
  • Python equivalence tests: Automated validation against Python SHAP
  • Makefile: Convenient targets for test, lint, and testdata generation

Bug Fixes

  • Resolve CI lint errors (gofmt, gosec)

Installation

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

Upgrade Guide

  1. Update import: go get github.com/plexusone/shap-go@v0.2.0
  2. Add error handling to Masker.Mask() calls (breaking change)
  3. Consider migrating to TreeSHAP for tree models (40-100x faster)
  4. Consider migrating to LinearSHAP for linear models (exact, O(d))