trustyai.explainers.SHAPExplainer

class trustyai.explainers.SHAPExplainer(background: ndarray | DataFrame | List[PredictionInput], link_type: LinkType | None = None, **kwargs)

“By how much did each feature contribute to the outputs?”

SHAP (SHapley Additive exPlanations) seeks to answer this question via providing SHAP values that provide an additive explanation of the model output; essentially a receipt for the model’s output. SHAP does this by finding an additive explanatory model \(g\) of the form:

\[f(x) = \phi_0 + \phi_1 x'_1 + \phi_2 x'_2 + \dots + \phi_n x'_n\]

where \(x'_1, \dots, x'_n\) are binary values that indicate whether the \(n\) th feature ispresent or absent and \(\phi_1, \dots, \phi_n\) are those features’ corresponding SHAP values. \(\phi_0\) is the fnull of the model, indicating the model’s latent output in the absence of all features; functionally, the y-intercept of the explanatory model.

What all this means is that a feature’s exact contribution to the output can be seen as its SHAP value, and the original model output can be recovered by summing up the fnull with all SHAP values.

To operate, SHAP also needs access to a background dataset, a set of representative input datapoints that captures the model’s “normal behavior”. All SHAP values are implicitly comparisons against to the background data, i.e., By how much did each feature contribute to the outputs, as compared to the background inputs?*

__init__(background: ndarray | DataFrame | List[PredictionInput], link_type: LinkType | None = None, **kwargs)

Initialize the SHAPxplainer.

Parameters:
backgroundnumpy.ndarray, pandas.DataFrame, List[PredictionInput]]

The set of background datapoints as a:

  • Numpy array of shape [n_rows, n_features]

  • Pandas DataFrame with n_rows rows and n_features columns

  • A list of TrustyAI PredictionInput

link_typeLinkType

A choice of either trustyai.explainers._ShapConfig.LinkType.IDENTITY or trustyai.explainers._ShapConfig.LinkType.LOGIT. If the model output is a probability, choosing the LOGIT link will rescale explanations into log-odds units. Otherwise, choose IDENTITY.

Keyword Arguments:
  • samples: int

    (default= None) The number of samples to use when computing SHAP values. Higher values will increase explanation accuracy, at the cost of runtime. If none, samples will equal 2048 + 2*n_features

  • seed: int

    (default= 0) The random seed to be used when generating explanations.

  • batchSize: int

    (default= 20) The number of batches passed to the PredictionProvider at once. When using Model with disable_arrow=True this parameter has no effect. If arrow=True, batch_sizes of around \(\frac{2000}{\mathtt{len(background)}}\) can produce significant performance gains.

  • trackCounterfactualsbool

    (default= False) Keep track of produced byproduct counterfactuals during SHAP run.

Returns:
SHAPResults

Object containing the results of the SHAP explanation.

Methods

__init__(background[, link_type])

Initialize the SHAPxplainer.

explain(inputs, outputs, model)

Produce a SHAP explanation.
explain(inputs: int | float | integer | inexact | ndarray | DataFrame | Series | List[Feature] | PredictionInput, outputs: int | float | integer | inexact | ndarray | DataFrame | Series | List[Output] | PredictionOutput, model: PredictionProvider | Model) → SHAPResults

Produce a SHAP explanation.

Parameters:
inputsint, float, numpy.number, List[Union[int, float, numpy.number]], numpy.ndarray, pandas.DataFrame, pandas.Series, List[Feature], or PredictionInput

The input features to the model, as a:

  • If there’s only a single input feature, an int, float, or any of the Numpy equivalents can be used.

  • A list of int, float, or any of the Numpy equivalents.

  • Numpy array of shape [1, n_features] or [n_features]

  • Pandas DataFrame with 1 row and n_features columns

  • Pandas Series with n_features rows

  • A List of TrustyAI Feature, as created by the feature() function

  • A TrustyAI PredictionInput

outputsint, float, numpy.number, List[Union[int, float, numpy.number]], numpy.ndarray, pandas.DataFrame, pandas.Series, List[Output], or PredictionOutput

The corresponding model outputs for the provided features, that is, outputs = model(input_features). These can take the form of a:

  • If there’s only a single output, an int, float, or any of the Numpy equivalents can be used.

  • A list of int, float, or any of the Numpy equivalents.

  • Numpy array of shape [1, n_outputs] or [n_outputs]

  • Pandas DataFrame with 1 row and n_outputs columns

  • Pandas Series with n_outputs rows

  • A List of TrustyAI Output, as created by the output() function

  • A TrustyAI PredictionOutput

modelPredictionProvider

The TrustyAI PredictionProvider, as generated by Model

Returns:
SHAPResults

Object containing the results of the SHAP explanation.