Usual plots

The shap.plots-equivalent figures. Each function accepts SHAP values as an Explanation-like object, a NumPy array, or a pandas DataFrame, plus an optional typed config (see Configuration).

bar

Global feature-importance bar plot (shap.plots.bar equivalent).

bar

bar(
    values: ExplanationLike | ArrayLike | object,
    *,
    base_values: object = None,
    data: ArrayLike | None = None,
    feature_names: Sequence[str] | None = None,
    output_index: int | None = None,
    config: BarConfig | None = None,
) -> Figure

Render a feature-importance bar plot as a Plotly figure.

For a multi-sample explanation, bars encode the mean absolute SHAP value per feature. For a single instance, bars encode the signed contributions and are colored red (positive) or blue (negative), matching shap.

Parameters:

Name	Type	Description	Default
values	ExplanationLike | ArrayLike | object	SHAP values as an Explanation-like object, numpy array or DataFrame.	required
base_values	object	Forwarded to :func:shaply.explanation.to_explanation.	None
data	object	Forwarded to :func:shaply.explanation.to_explanation.	None
feature_names	object	Forwarded to :func:shaply.explanation.to_explanation.	None
output_index	object	Forwarded to :func:shaply.explanation.to_explanation.	None
config	BarConfig | None	Optional :class:~shaply.config.BarConfig; defaults are used otherwise.	None

Returns:

Type	Description
Figure	The bar figure.

Source code in src/shaply/plots/usual/bar.py

def bar(
    values: ExplanationLike | npt.ArrayLike | object,
    *,
    base_values: object = None,
    data: npt.ArrayLike | None = None,
    feature_names: Sequence[str] | None = None,
    output_index: int | None = None,
    config: BarConfig | None = None,
) -> go.Figure:
    """Render a feature-importance bar plot as a Plotly figure.

    For a multi-sample explanation, bars encode the mean absolute SHAP value
    per feature. For a single instance, bars encode the signed contributions
    and are colored red (positive) or blue (negative), matching ``shap``.

    Parameters
    ----------
    values
        SHAP values as an ``Explanation``-like object, numpy array or DataFrame.
    base_values, data, feature_names, output_index
        Forwarded to :func:`shaply.explanation.to_explanation`.
    config
        Optional :class:`~shaply.config.BarConfig`; defaults are used otherwise.

    Returns
    -------
    plotly.graph_objects.Figure
        The bar figure.
    """
    explanation = to_explanation(
        values,
        base_values=base_values,
        data=data,
        feature_names=feature_names,
        output_index=output_index,
    )
    cfg = config or BarConfig()
    return _build_bar(explanation, cfg)

beeswarm

Beeswarm summary plot (shap.plots.beeswarm equivalent).

beeswarm

beeswarm(
    values: ExplanationLike | ArrayLike | object,
    *,
    base_values: object = None,
    data: ArrayLike | None = None,
    feature_names: Sequence[str] | None = None,
    output_index: int | None = None,
    config: BeeswarmConfig | None = None,
) -> Figure

Render a beeswarm summary plot as a Plotly figure.

Each point is one sample's SHAP value for a feature, spread vertically by local density and colored by the (normalized) feature value.

Parameters:

Name	Type	Description	Default
values	ExplanationLike | ArrayLike | object	SHAP values as an Explanation-like object, numpy array or DataFrame.	required
base_values	object	Forwarded to :func:shaply.explanation.to_explanation.	None
data	object	Forwarded to :func:shaply.explanation.to_explanation.	None
feature_names	object	Forwarded to :func:shaply.explanation.to_explanation.	None
output_index	object	Forwarded to :func:shaply.explanation.to_explanation.	None
config	BeeswarmConfig | None	Optional :class:~shaply.config.BeeswarmConfig.	None

Returns:

Type	Description
Figure	The beeswarm figure.

Source code in src/shaply/plots/usual/beeswarm.py

def beeswarm(
    values: ExplanationLike | npt.ArrayLike | object,
    *,
    base_values: object = None,
    data: npt.ArrayLike | None = None,
    feature_names: Sequence[str] | None = None,
    output_index: int | None = None,
    config: BeeswarmConfig | None = None,
) -> go.Figure:
    """Render a beeswarm summary plot as a Plotly figure.

    Each point is one sample's SHAP value for a feature, spread vertically by
    local density and colored by the (normalized) feature value.

    Parameters
    ----------
    values
        SHAP values as an ``Explanation``-like object, numpy array or DataFrame.
    base_values, data, feature_names, output_index
        Forwarded to :func:`shaply.explanation.to_explanation`.
    config
        Optional :class:`~shaply.config.BeeswarmConfig`.

    Returns
    -------
    plotly.graph_objects.Figure
        The beeswarm figure.
    """
    explanation = to_explanation(
        values,
        base_values=base_values,
        data=data,
        feature_names=feature_names,
        output_index=output_index,
    )
    cfg = config or BeeswarmConfig()
    return _build_beeswarm(explanation, cfg)

beeswarm_scatter

beeswarm_scatter(
    explanation: Explanation,
    order: IntArray,
    color_scale: ColorScale,
    *,
    point_size: float,
    opacity: float,
    jitter: float,
    show_colorbar: bool = True,
) -> Scatter

Build the beeswarm scatter trace for features given in display order.

order lists feature indices bottom-to-top; each feature's samples are plotted at y = row (+ density offset) with x the SHAP value and the color encoding the (normalized) feature value.

Parameters:

Name	Type	Description	Default
explanation	Explanation	The explanation to render.	required
order	IntArray	Feature indices in display order (bottom row first).	required
color_scale	ColorScale	Color scale encoding feature values.	required
point_size	float	Marker size, marker opacity and vertical density spread.	required
opacity	float	Marker size, marker opacity and vertical density spread.	required
jitter	float	Marker size, marker opacity and vertical density spread.	required
show_colorbar	bool	Whether to attach the shared Low/High colorbar to the trace.	True

Returns:

Type	Description
Scatter	The assembled scatter trace.

Source code in src/shaply/plots/usual/beeswarm.py

def beeswarm_scatter(
    explanation: Explanation,
    order: IntArray,
    color_scale: ColorScale,
    *,
    point_size: float,
    opacity: float,
    jitter: float,
    show_colorbar: bool = True,
) -> go.Scatter:
    """Build the beeswarm scatter trace for features given in display order.

    ``order`` lists feature indices bottom-to-top; each feature's samples are
    plotted at ``y = row (+ density offset)`` with ``x`` the SHAP value and the
    color encoding the (normalized) feature value.

    Parameters
    ----------
    explanation
        The explanation to render.
    order
        Feature indices in display order (bottom row first).
    color_scale
        Color scale encoding feature values.
    point_size, opacity, jitter
        Marker size, marker opacity and vertical density spread.
    show_colorbar
        Whether to attach the shared Low/High colorbar to the trace.

    Returns
    -------
    plotly.graph_objects.Scatter
        The assembled scatter trace.
    """
    has_color = explanation.data is not None
    xs: list[FloatArray] = []
    ys: list[FloatArray] = []
    colors: list[FloatArray] = []
    customdata: list[FloatArray] = []

    for row, feature_idx in enumerate(order):
        shap_col = explanation.values[:, feature_idx]
        offsets = _density_offsets(shap_col, jitter)
        xs.append(shap_col)
        ys.append(np.full_like(shap_col, row) + offsets)
        if has_color and explanation.data is not None:
            raw = explanation.data[:, feature_idx]
            normalized = _normalize_feature(raw)
            colors.append(normalized if normalized is not None else np.full_like(raw, 0.5))
            customdata.append(raw)

    marker: dict[str, object] = {"size": point_size, "opacity": opacity}
    if has_color:
        marker.update(
            {
                "color": np.concatenate(colors),
                "colorscale": resolve_colorscale(color_scale),
                "cmin": 0.0,
                "cmax": 1.0,
            }
        )
        if show_colorbar:
            marker["colorbar"] = {
                "title": {"text": "Feature value", "side": "right"},
                "tickmode": "array",
                "tickvals": [0.0, 1.0],
                "ticktext": ["Low", "High"],
            }
        hovertemplate = "SHAP %{x:.4f}<br>value %{customdata:.4g}<extra></extra>"
        custom = np.concatenate(customdata)
    else:
        marker["color"] = SHAP_GRAY
        hovertemplate = "SHAP %{x:.4f}<extra></extra>"
        custom = None

    return go.Scatter(
        x=np.concatenate(xs),
        y=np.concatenate(ys),
        mode="markers",
        marker=marker,
        customdata=custom,
        hovertemplate=hovertemplate,
    )

waterfall

Waterfall plot for a single prediction (shap.plots.waterfall equivalent).

waterfall

waterfall(
    values: ExplanationLike | ArrayLike | object,
    *,
    base_values: object = None,
    data: ArrayLike | None = None,
    feature_names: Sequence[str] | None = None,
    output_index: int | None = None,
    sample_index: int = 0,
    config: WaterfallConfig | None = None,
) -> Figure

Render a waterfall plot explaining a single prediction.

The plot starts at the model's expected value E[f(x)] and adds each feature's contribution to reach the prediction f(x).

Parameters:

Name	Type	Description	Default
values	ExplanationLike | ArrayLike | object	SHAP values as an Explanation-like object, numpy array or DataFrame.	required
base_values	object	Forwarded to :func:shaply.explanation.to_explanation.	None
data	object	Forwarded to :func:shaply.explanation.to_explanation.	None
feature_names	object	Forwarded to :func:shaply.explanation.to_explanation.	None
output_index	object	Forwarded to :func:shaply.explanation.to_explanation.	None
sample_index	int	Index of the instance to explain when the input holds several samples.	0
config	WaterfallConfig | None	Optional :class:~shaply.config.WaterfallConfig.	None

Returns:

Type	Description
Figure	The waterfall figure.

Source code in src/shaply/plots/usual/waterfall.py

def waterfall(
    values: ExplanationLike | npt.ArrayLike | object,
    *,
    base_values: object = None,
    data: npt.ArrayLike | None = None,
    feature_names: Sequence[str] | None = None,
    output_index: int | None = None,
    sample_index: int = 0,
    config: WaterfallConfig | None = None,
) -> go.Figure:
    """Render a waterfall plot explaining a single prediction.

    The plot starts at the model's expected value ``E[f(x)]`` and adds each
    feature's contribution to reach the prediction ``f(x)``.

    Parameters
    ----------
    values
        SHAP values as an ``Explanation``-like object, numpy array or DataFrame.
    base_values, data, feature_names, output_index
        Forwarded to :func:`shaply.explanation.to_explanation`.
    sample_index
        Index of the instance to explain when the input holds several samples.
    config
        Optional :class:`~shaply.config.WaterfallConfig`.

    Returns
    -------
    plotly.graph_objects.Figure
        The waterfall figure.
    """
    explanation = to_explanation(
        values,
        base_values=base_values,
        data=data,
        feature_names=feature_names,
        output_index=output_index,
    )
    single = explanation.select_sample(sample_index)
    cfg = config or WaterfallConfig()
    return _build_waterfall(single, cfg)

scatter

Dependence / scatter plot (shap.plots.scatter equivalent).

scatter

scatter(
    values: ExplanationLike | ArrayLike | object,
    feature: str | int,
    *,
    color_feature: str | int | None = None,
    base_values: object = None,
    data: ArrayLike | None = None,
    feature_names: Sequence[str] | None = None,
    output_index: int | None = None,
    config: ScatterConfig | None = None,
) -> Figure

Render a SHAP dependence plot for a single feature.

The x-axis is the feature's value, the y-axis its SHAP value. Points may be colored by a second (interaction) feature.

Parameters:

Name	Type	Description	Default
values	ExplanationLike | ArrayLike | object	SHAP values as an Explanation-like object, numpy array or DataFrame.	required
feature	str | int	Name or index of the feature to place on the axes.	required
color_feature	str | int | None	Optional name or index of an interaction feature used for coloring.	None
base_values	object	Forwarded to :func:shaply.explanation.to_explanation.	None
data	object	Forwarded to :func:shaply.explanation.to_explanation.	None
feature_names	object	Forwarded to :func:shaply.explanation.to_explanation.	None
output_index	object	Forwarded to :func:shaply.explanation.to_explanation.	None
config	ScatterConfig | None	Optional :class:~shaply.config.ScatterConfig.	None

Returns:

Type	Description
Figure	The dependence figure.

Raises:

Type	Description
ValueError	If feature values (data) were not provided.

Source code in src/shaply/plots/usual/scatter.py

def scatter(
    values: ExplanationLike | npt.ArrayLike | object,
    feature: str | int,
    *,
    color_feature: str | int | None = None,
    base_values: object = None,
    data: npt.ArrayLike | None = None,
    feature_names: Sequence[str] | None = None,
    output_index: int | None = None,
    config: ScatterConfig | None = None,
) -> go.Figure:
    """Render a SHAP dependence plot for a single feature.

    The x-axis is the feature's value, the y-axis its SHAP value. Points may be
    colored by a second (interaction) feature.

    Parameters
    ----------
    values
        SHAP values as an ``Explanation``-like object, numpy array or DataFrame.
    feature
        Name or index of the feature to place on the axes.
    color_feature
        Optional name or index of an interaction feature used for coloring.
    base_values, data, feature_names, output_index
        Forwarded to :func:`shaply.explanation.to_explanation`.
    config
        Optional :class:`~shaply.config.ScatterConfig`.

    Returns
    -------
    plotly.graph_objects.Figure
        The dependence figure.

    Raises
    ------
    ValueError
        If feature values (``data``) were not provided.
    """
    explanation = to_explanation(
        values,
        base_values=base_values,
        data=data,
        feature_names=feature_names,
        output_index=output_index,
    )
    if explanation.data is None:
        msg = "scatter requires feature values; pass data=... or a shap.Explanation."
        raise ValueError(msg)
    cfg = config or ScatterConfig()
    return _build_scatter(explanation, cfg, feature, color_feature)

heatmap

Heatmap plot of SHAP values across instances (shap.plots.heatmap).

heatmap

heatmap(
    values: ExplanationLike | ArrayLike | object,
    *,
    base_values: object = None,
    data: ArrayLike | None = None,
    feature_names: Sequence[str] | None = None,
    output_index: int | None = None,
    config: HeatmapConfig | None = None,
) -> Figure

Render a heatmap of SHAP values with instances on the x-axis.

Rows are features (ordered by importance), columns are instances (ordered by their total SHAP output so similar explanations sit together).

Parameters:

Name	Type	Description	Default
values	ExplanationLike | ArrayLike | object	SHAP values as an Explanation-like object, numpy array or DataFrame.	required
base_values	object	Forwarded to :func:shaply.explanation.to_explanation.	None
data	object	Forwarded to :func:shaply.explanation.to_explanation.	None
feature_names	object	Forwarded to :func:shaply.explanation.to_explanation.	None
output_index	object	Forwarded to :func:shaply.explanation.to_explanation.	None
config	HeatmapConfig | None	Optional :class:~shaply.config.HeatmapConfig.	None

Returns:

Type	Description
Figure	The heatmap figure.

Source code in src/shaply/plots/usual/heatmap.py

def heatmap(
    values: ExplanationLike | npt.ArrayLike | object,
    *,
    base_values: object = None,
    data: npt.ArrayLike | None = None,
    feature_names: Sequence[str] | None = None,
    output_index: int | None = None,
    config: HeatmapConfig | None = None,
) -> go.Figure:
    """Render a heatmap of SHAP values with instances on the x-axis.

    Rows are features (ordered by importance), columns are instances (ordered by
    their total SHAP output so similar explanations sit together).

    Parameters
    ----------
    values
        SHAP values as an ``Explanation``-like object, numpy array or DataFrame.
    base_values, data, feature_names, output_index
        Forwarded to :func:`shaply.explanation.to_explanation`.
    config
        Optional :class:`~shaply.config.HeatmapConfig`.

    Returns
    -------
    plotly.graph_objects.Figure
        The heatmap figure.
    """
    explanation = to_explanation(
        values,
        base_values=base_values,
        data=data,
        feature_names=feature_names,
        output_index=output_index,
    )
    cfg = config or HeatmapConfig()
    return _build_heatmap(explanation, cfg)

decision

Decision plot (shap.decision_plot equivalent).

Each instance is drawn as a line that starts at the model's expected value at the bottom axis and accumulates SHAP values feature by feature going upward, so its horizontal position at the top is the prediction f(x). Lines are colored by their predicted output.

decision

decision(
    values: ExplanationLike | ArrayLike | object,
    *,
    base_values: object = None,
    data: ArrayLike | None = None,
    feature_names: Sequence[str] | None = None,
    output_index: int | None = None,
    config: DecisionConfig | None = None,
) -> Figure

Render a decision plot as a Plotly figure.

Parameters:

Name	Type	Description	Default
values	ExplanationLike | ArrayLike | object	SHAP values as an Explanation-like object, numpy array or DataFrame.	required
base_values	object	Forwarded to :func:shaply.explanation.to_explanation.	None
data	object	Forwarded to :func:shaply.explanation.to_explanation.	None
feature_names	object	Forwarded to :func:shaply.explanation.to_explanation.	None
output_index	object	Forwarded to :func:shaply.explanation.to_explanation.	None
config	DecisionConfig | None	Optional :class:~shaply.config.DecisionConfig.	None

Returns:

Type	Description
Figure	The decision figure.

Source code in src/shaply/plots/usual/decision.py

def decision(
    values: ExplanationLike | npt.ArrayLike | object,
    *,
    base_values: object = None,
    data: npt.ArrayLike | None = None,
    feature_names: Sequence[str] | None = None,
    output_index: int | None = None,
    config: DecisionConfig | None = None,
) -> go.Figure:
    """Render a decision plot as a Plotly figure.

    Parameters
    ----------
    values
        SHAP values as an ``Explanation``-like object, numpy array or DataFrame.
    base_values, data, feature_names, output_index
        Forwarded to :func:`shaply.explanation.to_explanation`.
    config
        Optional :class:`~shaply.config.DecisionConfig`.

    Returns
    -------
    plotly.graph_objects.Figure
        The decision figure.
    """
    explanation = to_explanation(
        values,
        base_values=base_values,
        data=data,
        feature_names=feature_names,
        output_index=output_index,
    )
    cfg = config or DecisionConfig()
    return _build_decision(explanation, cfg)

force

Force plot for a single prediction (shap.plots.force equivalent).

Positive contributions (red) push the prediction up and negative ones (blue) push it down; the two blocks meet at f(x). The strip therefore spans [base + sum(negatives), base + sum(positives)] with the red/blue boundary at the prediction, exactly as in shap.

force

force(
    values: ExplanationLike | ArrayLike | object,
    *,
    base_values: object = None,
    data: ArrayLike | None = None,
    feature_names: Sequence[str] | None = None,
    output_index: int | None = None,
    sample_index: int = 0,
    config: ForceConfig | None = None,
) -> Figure

Render an additive force plot explaining a single prediction.

Parameters:

Name	Type	Description	Default
values	ExplanationLike | ArrayLike | object	SHAP values as an Explanation-like object, numpy array or DataFrame.	required
base_values	object	Forwarded to :func:shaply.explanation.to_explanation.	None
data	object	Forwarded to :func:shaply.explanation.to_explanation.	None
feature_names	object	Forwarded to :func:shaply.explanation.to_explanation.	None
output_index	object	Forwarded to :func:shaply.explanation.to_explanation.	None
sample_index	int	Index of the instance to explain when the input holds several samples.	0
config	ForceConfig | None	Optional :class:~shaply.config.ForceConfig.	None

Returns:

Type	Description
Figure	The force figure.

Source code in src/shaply/plots/usual/force.py

def force(
    values: ExplanationLike | npt.ArrayLike | object,
    *,
    base_values: object = None,
    data: npt.ArrayLike | None = None,
    feature_names: Sequence[str] | None = None,
    output_index: int | None = None,
    sample_index: int = 0,
    config: ForceConfig | None = None,
) -> go.Figure:
    """Render an additive force plot explaining a single prediction.

    Parameters
    ----------
    values
        SHAP values as an ``Explanation``-like object, numpy array or DataFrame.
    base_values, data, feature_names, output_index
        Forwarded to :func:`shaply.explanation.to_explanation`.
    sample_index
        Index of the instance to explain when the input holds several samples.
    config
        Optional :class:`~shaply.config.ForceConfig`.

    Returns
    -------
    plotly.graph_objects.Figure
        The force figure.
    """
    explanation = to_explanation(
        values,
        base_values=base_values,
        data=data,
        feature_names=feature_names,
        output_index=output_index,
    )
    single = explanation.select_sample(sample_index)
    cfg = config or ForceConfig()
    return _build_force(single, cfg)