shap.plots.decision

shap.plots.decision(base_value: float | ndarray, shap_values: ndarray, features: ndarray | Series | DataFrame | list | None = None, feature_names=None, feature_order='importance', feature_display_range=None, highlight=None, link='identity', plot_color=None, axis_color='#333333', y_demarc_color='#333333', alpha=None, color_bar=True, auto_size_plot=True, title=None, xlim=None, show=True, return_objects=False, ignore_warnings=False, new_base_value=None, legend_labels=None, legend_location='best') → DecisionPlotResult | None

Visualize model decisions using cumulative SHAP values.

Each plotted line explains a single model prediction. If a single prediction is plotted, feature values will be printed in the plot (if supplied). If multiple predictions are plotted together, feature values will not be printed. Plotting too many predictions together will make the plot unintelligible.

Parameters:

base_valuefloat or numpy.ndarray

This is the reference value that the feature contributions start from. Usually, this is explainer.expected_value.

shap_valuesnumpy.ndarray

Matrix of SHAP values (# features) or (# samples x # features) from explainer.shap_values(). Or cube of SHAP interaction values (# samples x # features x # features) from explainer.shap_interaction_values().

featuresnumpy.array or pandas.Series or pandas.DataFrame or numpy.ndarray or list

Matrix of feature values (# features) or (# samples x # features). This provides the values of all the features and, optionally, the feature names.

feature_nameslist or numpy.ndarray

List of feature names (# features). If None, names may be derived from the features argument if a Pandas object is provided. Otherwise, numeric feature names will be generated.

feature_orderstr or None or list or numpy.ndarray

Any of “importance” (the default), “hclust” (hierarchical clustering), None, or a list/array of indices.

feature_display_range: slice or range

The slice or range of features to plot after ordering features by feature_order. A step of 1 or None will display the features in ascending order. A step of -1 will display the features in descending order. If feature_display_range=None, slice(-1, -21, -1) is used (i.e. show the last 20 features in descending order). If shap_values contains interaction values, the number of features is automatically expanded to include all possible interactions: N(N + 1)/2 where N = shap_values.shape[1].

highlightAny

Specify which observations to draw in a different line style. All numpy indexing methods are supported. For example, list of integer indices, or a bool array.

linkstr

Use “identity” or “logit” to specify the transformation used for the x-axis. The “logit” link transforms log-odds into probabilities.

plot_colorstr or matplotlib.colors.ColorMap

Color spectrum used to draw the plot lines. If str, a registered matplotlib color name is assumed.

axis_colorstr or int

Color used to draw plot axes.

y_demarc_colorstr or int

Color used to draw feature demarcation lines on the y-axis.

alphafloat

Alpha blending value in [0, 1] used to draw plot lines.

color_barbool

Whether to draw the color bar (legend).

auto_size_plotbool

Whether to automatically size the matplotlib plot to fit the number of features displayed. If False, specify the plot size using matplotlib before calling this function.

titlestr

Title of the plot.

xlim: tuple[float, float]

The extents of the x-axis (e.g. (-1.0, 1.0)). If not specified, the limits are determined by the maximum/minimum predictions centered around base_value when link="identity". When link="logit", the x-axis extents are (0, 1) centered at 0.5. xlim values are not transformed by the link function. This argument is provided to simplify producing multiple plots on the same scale for comparison.

showbool

Whether matplotlib.pyplot.show() is called before returning. Setting this to False allows the plot to be customized further after it has been created.

return_objectsbool

Whether to return a DecisionPlotResult object containing various plotting features. This can be used to generate multiple decision plots using the same feature ordering and scale.

ignore_warningsbool

Plotting many data points or too many features at a time may be slow, or may create very large plots. Set this argument to True to override hard-coded limits that prevent plotting large amounts of data.

new_base_valuefloat

SHAP values are relative to a base value. By default, this base value is the expected value of the model’s raw predictions. Use new_base_value to shift the base value to an arbitrary value (e.g. the cutoff point for a binary classification task).

legend_labelslist of str

List of legend labels. If None, legend will not be shown.

legend_locationstr

Legend location. Any of “best”, “upper right”, “upper left”, “lower left”, “lower right”, “right”, “center left”, “center right”, “lower center”, “upper center”, “center”.

Returns:

DecisionPlotResult or None

Returns a DecisionPlotResult object if return_objects=True. Returns None otherwise (the default).

Examples

Plot two decision plots using the same feature order and x-axis.

>>> range1, range2 = range(20), range(20, 40)
>>> r = decision_plot(base, shap_values[range1], features[range1], return_objects=True)
>>> decision_plot(base, shap_values[range2], features[range2], feature_order=r.feature_idx, xlim=r.xlim)

See more decision plot examples here.