Advanced plots

Diagnostics and analyses that go beyond the standard shap figures.

beeswarm_ranges

Combined beeswarm + feature-value-ranges figure.

The left panel is the usual SHAP beeswarm (impact on the model output); the right panel shows, on a shared feature axis, the real distribution of each feature's values as a horizontal density silhouette with an inner box. The silhouette is colored with the same low-to-high scale as the beeswarm dots, so a glance at the color already says which end is "low" and which is "high". Because raw features live on very different scales, each silhouette is min-max normalized for geometry while the true min/max are annotated at its ends - so an engineer reads the impact, the operating range, and the value scale on the same line.

beeswarm_ranges

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

Render a beeswarm alongside each feature's real value distribution.

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	BeeswarmRangesConfig | None	Optional :class:~shaply.config.BeeswarmRangesConfig.	None

Returns:

Type	Description
Figure	The two-panel figure.

Raises:

Type	Description
ValueError	If feature values (data) were not provided; the right panel needs the real feature values.

Source code in src/shaply/plots/advanced/beeswarm_ranges.py

def beeswarm_ranges(
    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: BeeswarmRangesConfig | None = None,
) -> go.Figure:
    """Render a beeswarm alongside each feature's real value distribution.

    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.BeeswarmRangesConfig`.

    Returns
    -------
    plotly.graph_objects.Figure
        The two-panel figure.

    Raises
    ------
    ValueError
        If feature values (``data``) were not provided; the right panel needs
        the real feature values.
    """
    explanation = to_explanation(
        values,
        base_values=base_values,
        data=data,
        feature_names=feature_names,
        output_index=output_index,
    )
    if explanation.data is None:
        msg = "beeswarm_ranges requires feature values; pass data=... or a shap.Explanation."
        raise ValueError(msg)
    cfg = config or BeeswarmRangesConfig()
    return _build(explanation, cfg)

error_analysis

Error-analysis plot: which features drive the model's mistakes.

Splits the instances into a correct and an error cohort and compares the mean SHAP value of each feature between them, ordered by the size of the gap. Features with a large gap are the ones the model relies on differently when it is wrong - usually the most profitable place to look in an industrial setting.

error_analysis

error_analysis(
    values: ExplanationLike | ArrayLike | object,
    *,
    errors: ArrayLike | None = None,
    y_true: ArrayLike | None = None,
    y_pred: ArrayLike | None = None,
    base_values: object = None,
    data: ArrayLike | None = None,
    feature_names: Sequence[str] | None = None,
    output_index: int | None = None,
    config: ErrorAnalysisConfig | None = None,
) -> Figure

Compare mean SHAP values between correct and mis-predicted instances.

Provide the error cohort either directly via errors (a boolean mask, True for mistakes) or via y_true and y_pred (mismatch defines an error).

Parameters:

Name	Type	Description	Default
values	ExplanationLike | ArrayLike | object	SHAP values as an Explanation-like object, numpy array or DataFrame.	required
errors	ArrayLike | None	Boolean mask, True where the model was wrong.	None
y_true	ArrayLike | None	Ground-truth and predicted labels; an error is y_true != y_pred.	None
y_pred	ArrayLike | None	Ground-truth and predicted labels; an error is y_true != y_pred.	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	ErrorAnalysisConfig | None	Optional :class:~shaply.config.ErrorAnalysisConfig.	None

Returns:

Type	Description
Figure	The error-analysis figure.

Raises:

Type	Description
ValueError	If the error cohort is under-specified, mis-sized, or empty/complete.

Source code in src/shaply/plots/advanced/error_analysis.py

def error_analysis(
    values: ExplanationLike | npt.ArrayLike | object,
    *,
    errors: npt.ArrayLike | None = None,
    y_true: npt.ArrayLike | None = None,
    y_pred: npt.ArrayLike | None = None,
    base_values: object = None,
    data: npt.ArrayLike | None = None,
    feature_names: Sequence[str] | None = None,
    output_index: int | None = None,
    config: ErrorAnalysisConfig | None = None,
) -> go.Figure:
    """Compare mean SHAP values between correct and mis-predicted instances.

    Provide the error cohort either directly via ``errors`` (a boolean mask, True
    for mistakes) or via ``y_true`` and ``y_pred`` (mismatch defines an error).

    Parameters
    ----------
    values
        SHAP values as an ``Explanation``-like object, numpy array or DataFrame.
    errors
        Boolean mask, ``True`` where the model was wrong.
    y_true, y_pred
        Ground-truth and predicted labels; an error is ``y_true != y_pred``.
    base_values, data, feature_names, output_index
        Forwarded to :func:`shaply.explanation.to_explanation`.
    config
        Optional :class:`~shaply.config.ErrorAnalysisConfig`.

    Returns
    -------
    plotly.graph_objects.Figure
        The error-analysis figure.

    Raises
    ------
    ValueError
        If the error cohort is under-specified, mis-sized, or empty/complete.
    """
    explanation = to_explanation(
        values,
        base_values=base_values,
        data=data,
        feature_names=feature_names,
        output_index=output_index,
    )
    mask = _resolve_mask(explanation.n_samples, errors=errors, y_true=y_true, y_pred=y_pred)
    cfg = config or ErrorAnalysisConfig()
    return _build(explanation, cfg, mask)

explanation_archetypes

Explanation archetypes: typical SHAP-profile patterns across instances.

Clusters instances by their SHAP profile and shows each cluster's mean SHAP per feature as a heatmap row. The archetypes read as the model's recurring "reasons" - e.g. distinct failure modes or operating regimes - rather than one instance at a time.

explanation_archetypes

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

Cluster instances by SHAP profile and show each archetype's mean 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	ExplanationArchetypesConfig | None	Optional :class:~shaply.config.ExplanationArchetypesConfig.	None

Returns:

Type	Description
Figure	The archetypes heatmap.

Source code in src/shaply/plots/advanced/explanation_archetypes.py

def explanation_archetypes(
    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: ExplanationArchetypesConfig | None = None,
) -> go.Figure:
    """Cluster instances by SHAP profile and show each archetype's mean 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.ExplanationArchetypesConfig`.

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

feature_clustering

Feature-clustering / redundancy heatmap based on SHAP similarity.

Two features are redundant for the model when their per-sample SHAP vectors are strongly correlated: they push predictions in lockstep. This plot shows the SHAP-correlation matrix reordered by average-linkage clustering, so blocks of mutually correlated (often droppable) features stand out.

feature_clustering

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

Render a clustered heatmap of SHAP correlation between features.

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	FeatureClusteringConfig | None	Optional :class:~shaply.config.FeatureClusteringConfig.	None

Returns:

Type	Description
Figure	The clustered correlation heatmap.

Source code in src/shaply/plots/advanced/feature_clustering.py

def feature_clustering(
    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: FeatureClusteringConfig | None = None,
) -> go.Figure:
    """Render a clustered heatmap of SHAP correlation between features.

    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.FeatureClusteringConfig`.

    Returns
    -------
    plotly.graph_objects.Figure
        The clustered correlation heatmap.
    """
    explanation = to_explanation(
        values,
        base_values=base_values,
        data=data,
        feature_names=feature_names,
        output_index=output_index,
    )
    cfg = config or FeatureClusteringConfig()
    return _build(explanation, cfg)

importance_by_cohort

Cohort-wise feature importance.

Compares mean(|SHAP|) per feature across cohorts of instances, revealing that a feature can dominate in one operating regime and be negligible in another. Cohorts are given explicitly, or built by quantile-binning one feature.

importance_by_cohort

importance_by_cohort(
    values: ExplanationLike | ArrayLike | object,
    *,
    cohorts: ArrayLike | None = None,
    by_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: ImportanceByCohortConfig | None = None,
) -> Figure

Render feature importance split by cohort.

Provide the cohorts either directly via cohorts (one label per instance) or via by_feature (quantile-bin that feature into config.n_cohorts).

Parameters:

Name	Type	Description	Default
values	ExplanationLike | ArrayLike | object	SHAP values as an Explanation-like object, numpy array or DataFrame.	required
cohorts	ArrayLike | None	One cohort label per instance.	None
by_feature	str | int | None	Name or index of a feature to quantile-bin into cohorts (needs data).	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	ImportanceByCohortConfig | None	Optional :class:~shaply.config.ImportanceByCohortConfig.	None

Returns:

Type	Description
Figure	The grouped importance figure.

Raises:

Type	Description
ValueError	If neither or both cohort sources are given, or sizes mismatch.

Source code in src/shaply/plots/advanced/importance_by_cohort.py

def importance_by_cohort(
    values: ExplanationLike | npt.ArrayLike | object,
    *,
    cohorts: npt.ArrayLike | None = None,
    by_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: ImportanceByCohortConfig | None = None,
) -> go.Figure:
    """Render feature importance split by cohort.

    Provide the cohorts either directly via ``cohorts`` (one label per instance)
    or via ``by_feature`` (quantile-bin that feature into ``config.n_cohorts``).

    Parameters
    ----------
    values
        SHAP values as an ``Explanation``-like object, numpy array or DataFrame.
    cohorts
        One cohort label per instance.
    by_feature
        Name or index of a feature to quantile-bin into cohorts (needs ``data``).
    base_values, data, feature_names, output_index
        Forwarded to :func:`shaply.explanation.to_explanation`.
    config
        Optional :class:`~shaply.config.ImportanceByCohortConfig`.

    Returns
    -------
    plotly.graph_objects.Figure
        The grouped importance figure.

    Raises
    ------
    ValueError
        If neither or both cohort sources are given, or sizes mismatch.
    """
    explanation = to_explanation(
        values,
        base_values=base_values,
        data=data,
        feature_names=feature_names,
        output_index=output_index,
    )
    cfg = config or ImportanceByCohortConfig()
    labels, names = _resolve_cohorts(explanation, cohorts, by_feature, cfg)
    return _build(explanation, cfg, labels, names)

importance_ci

Global importance with bootstrap confidence intervals.

Like the bar plot, but each mean(|SHAP|) bar carries a bootstrap confidence interval over instances, so a fragile ranking (wide, overlapping intervals) is not mistaken for a robust one.

importance_ci

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

Render global feature importance with bootstrap confidence intervals.

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	ImportanceCIConfig | None	Optional :class:~shaply.config.ImportanceCIConfig.	None

Returns:

Type	Description
Figure	The importance figure with error bars.

Source code in src/shaply/plots/advanced/importance_ci.py

def importance_ci(
    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: ImportanceCIConfig | None = None,
) -> go.Figure:
    """Render global feature importance with bootstrap confidence intervals.

    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.ImportanceCIConfig`.

    Returns
    -------
    plotly.graph_objects.Figure
        The importance figure with error bars.
    """
    explanation = to_explanation(
        values,
        base_values=base_values,
        data=data,
        feature_names=feature_names,
        output_index=output_index,
    )
    cfg = config or ImportanceCIConfig()
    return _build(explanation, cfg)

interaction_heatmap

Pairwise SHAP-interaction heatmap.

Given a SHAP interaction tensor, this ranks features by total interaction strength and shows the matrix of mean absolute interaction between the top pairs. Bright off-diagonal cells flag features that act together on the prediction - the closest SHAP gets to surfacing coupled effects.

interaction_heatmap

interaction_heatmap(
    values: ArrayLike | object,
    *,
    feature_names: Sequence[str] | None = None,
    config: InteractionHeatmapConfig | None = None,
) -> Figure

Render a heatmap of mean absolute SHAP interactions between features.

Parameters:

Name	Type	Description	Default
values	ArrayLike | object	A (n_samples, n_features, n_features) interaction tensor (e.g. from shap.TreeExplainer(model).shap_interaction_values(X)) or an object exposing it as .values.	required
feature_names	Sequence[str] | None	Feature labels; inferred or generated when omitted.	None
config	InteractionHeatmapConfig | None	Optional :class:~shaply.config.InteractionHeatmapConfig.	None

Returns:

Type	Description
Figure	The interaction heatmap.

Source code in src/shaply/plots/advanced/interaction_heatmap.py

def interaction_heatmap(
    values: npt.ArrayLike | object,
    *,
    feature_names: Sequence[str] | None = None,
    config: InteractionHeatmapConfig | None = None,
) -> go.Figure:
    """Render a heatmap of mean absolute SHAP interactions between features.

    Parameters
    ----------
    values
        A ``(n_samples, n_features, n_features)`` interaction tensor (e.g. from
        ``shap.TreeExplainer(model).shap_interaction_values(X)``) or an object
        exposing it as ``.values``.
    feature_names
        Feature labels; inferred or generated when omitted.
    config
        Optional :class:`~shaply.config.InteractionHeatmapConfig`.

    Returns
    -------
    plotly.graph_objects.Figure
        The interaction heatmap.
    """
    interactions = to_interaction_values(values, feature_names=feature_names)
    cfg = config or InteractionHeatmapConfig()
    return _build(interactions, cfg)

monotonicity_check

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

Rank features by the monotonicity of their value-to-SHAP relationship.

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	MonotonicityConfig | None	Optional :class:~shaply.config.MonotonicityConfig.	None

Returns:

Type	Description
Figure	The monotonicity figure.

Raises:

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

Source code in src/shaply/plots/advanced/monotonicity.py

def monotonicity_check(
    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: MonotonicityConfig | None = None,
) -> go.Figure:
    """Rank features by the monotonicity of their value-to-SHAP relationship.

    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.MonotonicityConfig`.

    Returns
    -------
    plotly.graph_objects.Figure
        The monotonicity 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 = "monotonicity_check requires feature values; pass data=... or a shap.Explanation."
        raise ValueError(msg)
    cfg = config or MonotonicityConfig()
    return _build(explanation, cfg)

response_curve

Response-curve plot: smoothed SHAP effect of a feature with tipping points.

For a single feature this shows the smoothed mean SHAP value as a function of the feature's value, a spread band, and the values where the mean effect crosses zero (the "tipping points" where the feature switches from lowering to raising the prediction). It is an actionable, PDP/ALE-flavored read of a dependence plot.

Note: SHAP effects are associational, not causal - read a tipping point as "the value above which this feature is associated with a higher model output", not as a proven physical cause.

response_curve

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

Render the smoothed SHAP response curve of a single 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 profile.	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	ResponseCurveConfig | None	Optional :class:~shaply.config.ResponseCurveConfig.	None

Returns:

Type	Description
Figure	The response-curve figure.

Raises:

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

Source code in src/shaply/plots/advanced/response_curve.py

def response_curve(
    values: ExplanationLike | npt.ArrayLike | object,
    feature: str | int,
    *,
    base_values: object = None,
    data: npt.ArrayLike | None = None,
    feature_names: Sequence[str] | None = None,
    output_index: int | None = None,
    config: ResponseCurveConfig | None = None,
) -> go.Figure:
    """Render the smoothed SHAP response curve of a single feature.

    Parameters
    ----------
    values
        SHAP values as an ``Explanation``-like object, numpy array or DataFrame.
    feature
        Name or index of the feature to profile.
    base_values, data, feature_names, output_index
        Forwarded to :func:`shaply.explanation.to_explanation`.
    config
        Optional :class:`~shaply.config.ResponseCurveConfig`.

    Returns
    -------
    plotly.graph_objects.Figure
        The response-curve 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 = "response_curve requires feature values; pass data=... or a shap.Explanation."
        raise ValueError(msg)
    cfg = config or ResponseCurveConfig()
    return _build(explanation, cfg, feature)

scatter_ranges

Dependence scatter framed by its two axes' marginal distributions.

The center panel is a standard SHAP dependence plot for one feature: x is the feature's real value, y its SHAP value, and points are colored by the (also redundant, but helpful to the eye) feature value on the same low-to-high scale used across shaply. Around it, four marginal panels repeat each axis' distribution in two complementary shapes:

• top: a box plot of the real values, gradient-colored left-to-right.
• bottom: a density silhouette of the real values, gradient-colored.
• left: a plain gray density silhouette of the SHAP values.
• right: a plain gray box plot of the SHAP values.

Only the x-axis (real value) marginals are colored, since that color already carries meaning (low/high); the y-axis (SHAP value) marginals stay neutral.

scatter_ranges

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

Render a dependence scatter framed by its axes' marginal distributions.

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
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	ScatterRangesConfig | None	Optional :class:~shaply.config.ScatterRangesConfig.	None

Returns:

Type	Description
Figure	The framed scatter figure.

Raises:

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

Source code in src/shaply/plots/advanced/scatter_ranges.py

def scatter_ranges(
    values: ExplanationLike | npt.ArrayLike | object,
    feature: str | int,
    *,
    base_values: object = None,
    data: npt.ArrayLike | None = None,
    feature_names: Sequence[str] | None = None,
    output_index: int | None = None,
    config: ScatterRangesConfig | None = None,
) -> go.Figure:
    """Render a dependence scatter framed by its axes' marginal distributions.

    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.
    base_values, data, feature_names, output_index
        Forwarded to :func:`shaply.explanation.to_explanation`.
    config
        Optional :class:`~shaply.config.ScatterRangesConfig`.

    Returns
    -------
    plotly.graph_objects.Figure
        The framed scatter 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_ranges requires feature values; pass data=... or a shap.Explanation."
        raise ValueError(msg)
    cfg = config or ScatterRangesConfig()
    return _build(explanation, cfg, feature)

shap_surface

2D SHAP interaction surface over the plane of two features.

Bins the (feature_x, feature_y) plane and shows the mean SHAP value of one feature in each cell. Bright/dark regions expose operating regions where the feature helps or hurts the prediction, and how a second feature modulates it.

shap_surface

shap_surface(
    values: ExplanationLike | ArrayLike | object,
    feature_x: str | int,
    feature_y: str | int,
    *,
    shap_of: str | int | None = None,
    base_values: object = None,
    data: ArrayLike | None = None,
    feature_names: Sequence[str] | None = None,
    output_index: int | None = None,
    config: ShapSurfaceConfig | None = None,
) -> Figure

Render the mean SHAP surface over the plane of two features.

Parameters:

Name	Type	Description	Default
values	ExplanationLike | ArrayLike | object	SHAP values as an Explanation-like object, numpy array or DataFrame.	required
feature_x	str | int	Features spanning the horizontal and vertical axes.	required
feature_y	str | int	Features spanning the horizontal and vertical axes.	required
shap_of	str | int | None	Which feature's SHAP value to average in each cell; defaults to feature_x.	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	ShapSurfaceConfig | None	Optional :class:~shaply.config.ShapSurfaceConfig.	None

Returns:

Type	Description
Figure	The surface figure.

Raises:

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

Source code in src/shaply/plots/advanced/shap_surface.py

def shap_surface(
    values: ExplanationLike | npt.ArrayLike | object,
    feature_x: str | int,
    feature_y: str | int,
    *,
    shap_of: 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: ShapSurfaceConfig | None = None,
) -> go.Figure:
    """Render the mean SHAP surface over the plane of two features.

    Parameters
    ----------
    values
        SHAP values as an ``Explanation``-like object, numpy array or DataFrame.
    feature_x, feature_y
        Features spanning the horizontal and vertical axes.
    shap_of
        Which feature's SHAP value to average in each cell; defaults to
        ``feature_x``.
    base_values, data, feature_names, output_index
        Forwarded to :func:`shaply.explanation.to_explanation`.
    config
        Optional :class:`~shaply.config.ShapSurfaceConfig`.

    Returns
    -------
    plotly.graph_objects.Figure
        The surface 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 = "shap_surface requires feature values; pass data=... or a shap.Explanation."
        raise ValueError(msg)
    cfg = config or ShapSurfaceConfig()
    return _build(explanation, cfg, feature_x, feature_y, shap_of)