Class KernelSHAP<T>

java.lang.Object
smile.feature.importance.KernelSHAP<T>
Type Parameters:
T - the data type of model input objects.
All Implemented Interfaces:
Serializable, SHAP<T>
public class KernelSHAP<T> extends Object implements SHAP<T>, Serializable
Kernel SHAP (SHapley Additive exPlanations) is a model-agnostic method to approximate Shapley values using a specially-weighted local linear regression over feature coalitions.

Given an input instance x with M features and a background reference dataset B, Kernel SHAP evaluates the expected model prediction for sampled feature coalitions (where missing features are marginalized over the background dataset B) and solves a constrained weighted least squares problem that enforces the Shapley efficiency axiom: 

    sum_{j=1}^M phi_j = f(x) - E[f(z)]

References

  1. Lundberg, Scott M., and Su-In Lee. A unified approach to interpreting model predictions. NIPS, 2017.
See Also:

  • Field Details

    • DEFAULT_BACKGROUND_SAMPLES

      public static final int DEFAULT_BACKGROUND_SAMPLES
      Default maximum number of background rows when summarizing a dataset.
      See Also:

    • DEFAULT_RIDGE

      public static final double DEFAULT_RIDGE
      Default ridge regularization for numerical stability.
      See Also:

  • Method Details

    • numFeatures

      public int numFeatures()
      Returns the number of features.
      Returns:
      the number of features.

    • numOutputs

      public int numOutputs()
      Returns the number of model outputs per instance (1 for regression, k for classification).
      Returns:
      the number of model outputs.

    • baseValues

      public double[] baseValues()
      Returns the expected baseline prediction E[f(z)] over the background dataset.
      Returns:
      a copy of the baseline prediction vector.

    • options

      public KernelSHAP.Options options()
      Returns the KernelSHAP options.
      Returns:
      the options.

    • shap

      public double[] shap(DataFrame data)
      Returns the average of absolute SHAP values over a data frame.
      Parameters:
      data - the data frame.
      Returns:
      the average of absolute SHAP values.

    • shap

      public double[] shap(DataFrame data, KernelSHAP.Options options)
      Returns the average of absolute SHAP values over a data frame with custom options.
      Parameters:
      data - the data frame.
      options - the KernelSHAP options, or null to use default options.
      Returns:
      the average of absolute SHAP values.

    • shap

      public double[] shap(T rawInput)
      Description copied from interface: SHAP
      Returns the SHAP values. For regression, the length of SHAP values is same as the number of features. For classification, SHAP values are of p x k, where p is the number of features and k is the classes. The first k elements are the SHAP values of first feature over k classes, respectively. The rest features follow accordingly.
      Specified by:
      shap in interface SHAP<T>
      Parameters:
      rawInput - an instance.
      Returns:
      the SHAP values.

    • shap

      public double[] shap(T rawInput, KernelSHAP.Options options)
      Description copied from interface: SHAP
      Returns the SHAP values with custom KernelSHAP.Options (ignored by exact explainers such as TreeSHAP and linear SHAP).
      Specified by:
      shap in interface SHAP<T>
      Parameters:
      rawInput - an instance.
      options - the KernelSHAP options, or null to use default options.
      Returns:
      the SHAP values.

    • of

      public static KernelSHAP<double[]> of(double[][] background, ToDoubleFunction<double[]> predictor)
      Creates a KernelSHAP explainer for a scalar function on double[].
      Parameters:
      background - the background reference dataset.
      predictor - the scalar prediction function.
      Returns:
      the KernelSHAP explainer.

    • of

      public static KernelSHAP<double[]> of(double[][] background, ToDoubleFunction<double[]> predictor, KernelSHAP.Options options)
      Creates a KernelSHAP explainer for a scalar function on double[].
      Parameters:
      background - the background reference dataset.
      predictor - the scalar prediction function.
      options - the KernelSHAP options.
      Returns:
      the KernelSHAP explainer.

    • of

      public static KernelSHAP<double[]> of(double[][] background, double[] weights, ToDoubleFunction<double[]> predictor, KernelSHAP.Options options)
      Creates a KernelSHAP explainer for a scalar function on double[] with weighted background samples.
      Parameters:
      background - the background reference dataset.
      weights - optional background sample weights (may be null for uniform weights).
      predictor - the scalar prediction function.
      options - the KernelSHAP options.
      Returns:
      the KernelSHAP explainer.

    • of

      public static KernelSHAP<double[]> of(double[][] background, Function<double[],double[]> predictor)
      Creates a KernelSHAP explainer for a vector-valued function on double[].
      Parameters:
      background - the background reference dataset.
      predictor - the vector prediction function.
      Returns:
      the KernelSHAP explainer.

    • of

      public static KernelSHAP<double[]> of(double[][] background, Function<double[],double[]> predictor, KernelSHAP.Options options)
      Creates a KernelSHAP explainer for a vector-valued function on double[].
      Parameters:
      background - the background reference dataset.
      predictor - the vector prediction function.
      options - the KernelSHAP options.
      Returns:
      the KernelSHAP explainer.

    • of

      public static KernelSHAP<double[]> of(double[][] background, double[] weights, Function<double[],double[]> predictor, KernelSHAP.Options options)
      Creates a KernelSHAP explainer for a vector-valued function on double[] with weighted background samples.
      Parameters:
      background - the background reference dataset.
      weights - optional background sample weights (may be null for uniform weights).
      predictor - the vector prediction function.
      options - the KernelSHAP options.
      Returns:
      the KernelSHAP explainer.

    • of

      public static KernelSHAP<double[]> of(double[][] background, Regression<double[]> model)
      Creates a KernelSHAP explainer for a Regression<double[]> model.
      Parameters:
      background - the background reference dataset.
      model - the regression model.
      Returns:
      the KernelSHAP explainer.

    • of

      public static KernelSHAP<double[]> of(double[][] background, Regression<double[]> model, KernelSHAP.Options options)
      Creates a KernelSHAP explainer for a Regression<double[]> model.
      Parameters:
      background - the background reference dataset.
      model - the regression model.
      options - the KernelSHAP options.
      Returns:
      the KernelSHAP explainer.

    • of

      public static KernelSHAP<double[]> of(double[][] background, Classifier<double[]> model)
      Creates a KernelSHAP explainer for a Classifier<double[]> model. If the classifier supports soft predictions (model.isSoft()), posterior class probabilities are explained; otherwise one-hot class indicators are explained.
      Parameters:
      background - the background reference dataset.
      model - the classification model.
      Returns:
      the KernelSHAP explainer.

    • of

      public static KernelSHAP<double[]> of(double[][] background, Classifier<double[]> model, KernelSHAP.Options options)
      Creates a KernelSHAP explainer for a Classifier<double[]> model.
      Parameters:
      background - the background reference dataset.
      model - the classification model.
      options - the KernelSHAP options.
      Returns:
      the KernelSHAP explainer.

    • of

      public static KernelSHAP<Tuple> of(DataFrame background, DataFrameRegression model)
      Creates a KernelSHAP explainer for a DataFrameRegression model.
      Parameters:
      background - the background reference data frame.
      model - the DataFrame regression model.
      Returns:
      the KernelSHAP explainer.

    • of

      public static KernelSHAP<Tuple> of(DataFrame background, DataFrameRegression model, KernelSHAP.Options options)
      Creates a KernelSHAP explainer for a DataFrameRegression model.
      Parameters:
      background - the background reference data frame.
      model - the DataFrame regression model.
      options - the KernelSHAP options.
      Returns:
      the KernelSHAP explainer.

    • of

      public static KernelSHAP<Tuple> of(DataFrame background, double[] weights, DataFrameRegression model, KernelSHAP.Options options)
      Creates a KernelSHAP explainer for a DataFrameRegression model with weighted background rows.
      Parameters:
      background - the background reference data frame.
      weights - optional background sample weights (may be null for uniform weights).
      model - the DataFrame regression model.
      options - the KernelSHAP options.
      Returns:
      the KernelSHAP explainer.

    • of

      public static KernelSHAP<Tuple> of(DataFrame background, DataFrameClassifier model)
      Creates a KernelSHAP explainer for a DataFrameClassifier model.
      Parameters:
      background - the background reference data frame.
      model - the DataFrame classifier model.
      Returns:
      the KernelSHAP explainer.

    • of

      public static KernelSHAP<Tuple> of(DataFrame background, DataFrameClassifier model, KernelSHAP.Options options)
      Creates a KernelSHAP explainer for a DataFrameClassifier model.
      Parameters:
      background - the background reference data frame.
      model - the DataFrame classifier model.
      options - the KernelSHAP options.
      Returns:
      the KernelSHAP explainer.

    • of

      public static KernelSHAP<Tuple> of(DataFrame background, double[] weights, DataFrameClassifier model, KernelSHAP.Options options)
      Creates a KernelSHAP explainer for a DataFrameClassifier model with weighted background rows.
      Parameters:
      background - the background reference data frame.
      weights - optional background sample weights (may be null for uniform weights).
      model - the DataFrame classifier model.
      options - the KernelSHAP options.
      Returns:
      the KernelSHAP explainer.

    • sample

      public static DataFrame sample(DataFrame data, int maxSamples)
      Subsamples a background DataFrame to at most maxSamples representative rows using deterministic uniform stride selection (preserving RNG state).
      Parameters:
      data - the source data frame.
      maxSamples - the maximum number of background rows to retain.
      Returns:
      the subsampled data frame.

    • sample

      public static double[][] sample(double[][] data, int maxSamples)
      Subsamples a background array to at most maxSamples representative rows using deterministic uniform stride selection (preserving RNG state).
      Parameters:
      data - the source array.
      maxSamples - the maximum number of background rows to retain.
      Returns:
      the subsampled array.