shaply 1.0.0__py3-none-any.whl

shaply/__init__.py

@@ -0,0 +1,110 @@
+"""shaply - usual SHAP explainability figures rendered as Plotly charts.
+
+The public API mirrors the familiar ``shap.plots`` entry points but returns
+:class:`plotly.graph_objects.Figure` objects instead of matplotlib axes::
+
+    import shaply
+
+    fig = shaply.beeswarm(shap_values)   # a shap.Explanation, ndarray or DataFrame
+    fig.show()
+
+Every plotting function accepts a ``shap.Explanation``-like object, a numpy
+array of SHAP values, or a :class:`pandas.DataFrame`, and an optional typed
+config object from :mod:`shaply.config`.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from shaply.config import (
+    BarConfig,
+    BeeswarmConfig,
+    BeeswarmRangesConfig,
+    DecisionConfig,
+    ErrorAnalysisConfig,
+    ExplanationArchetypesConfig,
+    FeatureClusteringConfig,
+    ForceConfig,
+    HeatmapConfig,
+    ImportanceByCohortConfig,
+    ImportanceCIConfig,
+    InteractionHeatmapConfig,
+    MonotonicityConfig,
+    ResponseCurveConfig,
+    ScatterConfig,
+    ShapSurfaceConfig,
+    WaterfallConfig,
+)
+from shaply.enums import ColorScale, FeatureOrdering, PlotType
+from shaply.explanation import Explanation, to_explanation
+from shaply.interaction import InteractionValues, to_interaction_values
+from shaply.plots import (
+    bar,
+    beeswarm,
+    beeswarm_ranges,
+    decision,
+    error_analysis,
+    explanation_archetypes,
+    feature_clustering,
+    force,
+    heatmap,
+    importance_by_cohort,
+    importance_ci,
+    interaction_heatmap,
+    monotonicity_check,
+    response_curve,
+    scatter,
+    shap_surface,
+    waterfall,
+)
+
+try:
+    __version__ = version("shaply")
+except PackageNotFoundError:  # pragma: no cover - only during local dev without install
+    __version__ = "0.0.0"
+
+__all__ = [
+    "BarConfig",
+    "BeeswarmConfig",
+    "BeeswarmRangesConfig",
+    "ColorScale",
+    "DecisionConfig",
+    "ErrorAnalysisConfig",
+    "Explanation",
+    "ExplanationArchetypesConfig",
+    "FeatureClusteringConfig",
+    "FeatureOrdering",
+    "ForceConfig",
+    "HeatmapConfig",
+    "ImportanceByCohortConfig",
+    "ImportanceCIConfig",
+    "InteractionHeatmapConfig",
+    "InteractionValues",
+    "MonotonicityConfig",
+    "PlotType",
+    "ResponseCurveConfig",
+    "ScatterConfig",
+    "ShapSurfaceConfig",
+    "WaterfallConfig",
+    "__version__",
+    "bar",
+    "beeswarm",
+    "beeswarm_ranges",
+    "decision",
+    "error_analysis",
+    "explanation_archetypes",
+    "feature_clustering",
+    "force",
+    "heatmap",
+    "importance_by_cohort",
+    "importance_ci",
+    "interaction_heatmap",
+    "monotonicity_check",
+    "response_curve",
+    "scatter",
+    "shap_surface",
+    "to_explanation",
+    "to_interaction_values",
+    "waterfall",
+]

shaply/colors.py

@@ -0,0 +1,96 @@
+"""Color utilities reproducing SHAP's visual language for Plotly figures.
+
+SHAP relies on a red/blue diverging scheme where blue encodes low feature
+values and red encodes high ones. The exact anchor colors used here match the
+defaults shipped by the ``shap`` package so figures feel familiar to its users.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+from shaply.enums import ColorScale
+
+#: Canonical SHAP accent colors.
+SHAP_RED: Final = "#ff0d57"
+SHAP_BLUE: Final = "#008bff"
+SHAP_GRAY: Final = "#777777"
+
+#: Plotly colorscale definitions as ``(position, css_color)`` stops.
+_ColorStop = tuple[float, str]
+Colorscale = list[_ColorStop]
+
+_RED_BLUE: Final[Colorscale] = [
+    (0.0, SHAP_BLUE),
+    (0.5, "#c6b7d6"),
+    (1.0, SHAP_RED),
+]
+
+_COOLWARM: Final[Colorscale] = [
+    (0.0, "#3b4cc0"),
+    (0.5, "#dddddd"),
+    (1.0, "#b40426"),
+]
+
+#: Sequential white->red scale for non-negative magnitudes (e.g. |interaction|).
+_REDS: Final[Colorscale] = [
+    (0.0, "#fff5f0"),
+    (0.5, "#fca082"),
+    (1.0, SHAP_RED),
+]
+
+_SCALE_REGISTRY: Final[dict[ColorScale, Colorscale | str]] = {
+    ColorScale.RED_BLUE: _RED_BLUE,
+    ColorScale.COOLWARM: _COOLWARM,
+    ColorScale.REDS: _REDS,
+    ColorScale.VIRIDIS: "Viridis",
+    ColorScale.PLASMA: "Plasma",
+}
+
+
+def resolve_colorscale(scale: ColorScale) -> Colorscale | str:
+    """Return the Plotly-compatible colorscale for a :class:`ColorScale`.
+
+    Parameters
+    ----------
+    scale
+        The named color scale to resolve.
+
+    Returns
+    -------
+    list of tuple or str
+        Either an explicit list of ``(position, color)`` stops or the name of a
+        built-in Plotly colorscale.
+    """
+    return _SCALE_REGISTRY[scale]
+
+
+def sample_scale(scale: ColorScale, positions: list[float]) -> list[str]:
+    """Sample a color scale at ``positions`` in ``[0, 1]``.
+
+    Parameters
+    ----------
+    scale
+        The named color scale to sample.
+    positions
+        Fractions in ``[0, 1]`` at which to read the scale.
+
+    Returns
+    -------
+    list of str
+        One CSS ``rgb(...)`` color per requested position.
+    """
+    from plotly.colors import sample_colorscale
+
+    resolved = resolve_colorscale(scale)
+    colorscale = resolved if isinstance(resolved, str) else [list(stop) for stop in resolved]
+    return list(sample_colorscale(colorscale, positions, colortype="rgb"))
+
+
+def signed_color(value: float) -> str:
+    """Return the SHAP accent color matching the sign of ``value``.
+
+    Positive contributions map to red, negative ones to blue, matching the
+    waterfall and force conventions of ``shap``.
+    """
+    return SHAP_RED if value >= 0 else SHAP_BLUE

shaply/config.py

@@ -0,0 +1,241 @@
+"""Public, validated plot configuration models (pydantic v2).
+
+These are the external data models users can pass to tune figures. They are
+deliberately kept separate from the internal :mod:`shaply.explanation`
+dataclasses: pydantic validates and normalizes user input, dataclasses carry
+already-trusted internal state.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from shaply.enums import ColorScale, FeatureOrdering
+
+_DEFAULT_TEMPLATE = "plotly_white"
+
+
+class BasePlotConfig(BaseModel):
+    """Options shared by every ``shaply`` figure."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    title: str | None = Field(default=None, description="Figure title.")
+    width: int | None = Field(default=None, gt=0, description="Figure width in pixels.")
+    height: int | None = Field(default=None, gt=0, description="Figure height in pixels.")
+    template: str = Field(default=_DEFAULT_TEMPLATE, description="Plotly layout template.")
+    show_grid: bool = Field(default=True, description="Whether to draw axis gridlines.")
+
+
+class BarConfig(BasePlotConfig):
+    """Configuration for the global feature-importance bar plot."""
+
+    max_display: int = Field(default=10, gt=0, description="Max features to display.")
+    ordering: FeatureOrdering = Field(
+        default=FeatureOrdering.IMPORTANCE,
+        description="How to order features along the axis.",
+    )
+    show_values: bool = Field(default=True, description="Annotate each bar with its numeric value.")
+
+
+class BeeswarmConfig(BasePlotConfig):
+    """Configuration for the beeswarm (summary) plot."""
+
+    max_display: int = Field(default=10, gt=0, description="Max features to display.")
+    ordering: FeatureOrdering = Field(
+        default=FeatureOrdering.IMPORTANCE,
+        description="How to order features along the axis.",
+    )
+    color_scale: ColorScale = Field(
+        default=ColorScale.RED_BLUE,
+        description="Color scale encoding feature values.",
+    )
+    point_size: float = Field(default=5.0, gt=0, description="Marker size in pixels.")
+    jitter: float = Field(
+        default=0.35, ge=0.0, le=1.0, description="Vertical spread of overlapping points."
+    )
+    opacity: float = Field(default=0.8, gt=0.0, le=1.0, description="Marker opacity.")
+
+
+class BeeswarmRangesConfig(BeeswarmConfig):
+    """Configuration for the combined beeswarm + feature-value-ranges figure.
+
+    Extends :class:`BeeswarmConfig` with the options controlling the right-hand
+    panel that shows the real distribution (violin + box) of each feature's
+    values.
+    """
+
+    impact_panel_ratio: float = Field(
+        default=0.62,
+        gt=0.2,
+        lt=0.9,
+        description="Fraction of width given to the left (SHAP impact) panel.",
+    )
+    show_value_labels: bool = Field(
+        default=True,
+        description="Annotate each feature row with its real min and max value.",
+    )
+
+
+class WaterfallConfig(BasePlotConfig):
+    """Configuration for the single-prediction waterfall plot."""
+
+    max_display: int = Field(default=10, gt=0, description="Max features to display.")
+    show_values: bool = Field(default=True, description="Annotate each step with its contribution.")
+
+
+class ScatterConfig(BasePlotConfig):
+    """Configuration for the dependence / scatter plot."""
+
+    color_scale: ColorScale = Field(
+        default=ColorScale.RED_BLUE,
+        description="Color scale used when coloring by an interaction feature.",
+    )
+    point_size: float = Field(default=6.0, gt=0, description="Marker size in pixels.")
+    opacity: float = Field(default=0.8, gt=0.0, le=1.0, description="Marker opacity.")
+
+
+class HeatmapConfig(BasePlotConfig):
+    """Configuration for the instances-by-features heatmap."""
+
+    max_display: int = Field(default=10, gt=0, description="Max features to display.")
+    ordering: FeatureOrdering = Field(
+        default=FeatureOrdering.IMPORTANCE,
+        description="How to order features along the axis.",
+    )
+    color_scale: ColorScale = Field(
+        default=ColorScale.RED_BLUE,
+        description="Color scale encoding SHAP values.",
+    )
+
+
+class ResponseCurveConfig(BasePlotConfig):
+    """Configuration for the response-curve plot (smoothed effect + thresholds)."""
+
+    n_bins: int = Field(default=20, gt=2, description="Number of bins used to smooth.")
+    quantile_bins: bool = Field(
+        default=True,
+        description="Use equal-count quantile bins (stable) instead of equal-width.",
+    )
+    band: bool = Field(default=True, description="Draw a +/-1 std spread band.")
+    show_points: bool = Field(default=True, description="Overlay the raw scatter points.")
+    point_opacity: float = Field(default=0.25, gt=0.0, le=1.0, description="Raw point opacity.")
+    show_thresholds: bool = Field(
+        default=True, description="Mark the values where the mean effect crosses zero."
+    )
+
+
+class InteractionHeatmapConfig(BasePlotConfig):
+    """Configuration for the pairwise SHAP-interaction heatmap."""
+
+    max_display: int = Field(default=10, gt=0, description="Max features to display.")
+    color_scale: ColorScale = Field(
+        default=ColorScale.REDS,
+        description="Sequential color scale encoding interaction magnitude.",
+    )
+    show_diagonal: bool = Field(
+        default=False,
+        description="Keep the diagonal (main effects); hidden by default to reveal interactions.",
+    )
+    show_values: bool = Field(default=False, description="Annotate each cell with its value.")
+
+
+class ErrorAnalysisConfig(BasePlotConfig):
+    """Configuration for the error-analysis plot (SHAP drivers of errors)."""
+
+    max_display: int = Field(default=10, gt=0, description="Max features to display.")
+    show_values: bool = Field(default=True, description="Annotate each bar with its value.")
+
+
+class ShapSurfaceConfig(BasePlotConfig):
+    """Configuration for the 2D SHAP interaction surface."""
+
+    n_bins: int = Field(default=20, gt=2, description="Grid resolution per axis.")
+    color_scale: ColorScale = Field(
+        default=ColorScale.RED_BLUE,
+        description="Diverging color scale encoding the mean SHAP value.",
+    )
+    contour: bool = Field(default=False, description="Render smooth contours instead of a heatmap.")
+
+
+class ImportanceByCohortConfig(BasePlotConfig):
+    """Configuration for the cohort-wise importance plot."""
+
+    max_display: int = Field(default=10, gt=0, description="Max features to display.")
+    ordering: FeatureOrdering = Field(
+        default=FeatureOrdering.IMPORTANCE,
+        description="How to order features (by overall importance across cohorts).",
+    )
+    n_cohorts: int = Field(
+        default=3, gt=1, description="Number of quantile cohorts when splitting by a feature."
+    )
+
+
+class FeatureClusteringConfig(BasePlotConfig):
+    """Configuration for the SHAP-similarity feature-clustering heatmap."""
+
+    color_scale: ColorScale = Field(
+        default=ColorScale.RED_BLUE,
+        description="Diverging color scale encoding SHAP correlation.",
+    )
+    show_values: bool = Field(default=False, description="Annotate each cell with its value.")
+
+
+class ExplanationArchetypesConfig(BasePlotConfig):
+    """Configuration for the SHAP-profile archetypes plot."""
+
+    n_clusters: int = Field(default=4, gt=1, description="Number of archetypes to extract.")
+    max_display: int = Field(default=10, gt=0, description="Max features to display.")
+    ordering: FeatureOrdering = Field(
+        default=FeatureOrdering.IMPORTANCE,
+        description="How to order features along the axis.",
+    )
+    color_scale: ColorScale = Field(
+        default=ColorScale.RED_BLUE,
+        description="Diverging color scale encoding each archetype's mean SHAP.",
+    )
+    random_state: int = Field(default=0, description="Seed for the k-means clustering.")
+
+
+class ImportanceCIConfig(BasePlotConfig):
+    """Configuration for the bootstrap importance plot with confidence intervals."""
+
+    max_display: int = Field(default=10, gt=0, description="Max features to display.")
+    ordering: FeatureOrdering = Field(
+        default=FeatureOrdering.IMPORTANCE,
+        description="How to order features along the axis.",
+    )
+    n_boot: int = Field(default=1000, gt=10, description="Number of bootstrap resamples.")
+    ci: float = Field(default=0.95, gt=0.0, lt=1.0, description="Confidence level.")
+    random_state: int = Field(default=0, description="Seed for the bootstrap resampling.")
+
+
+class MonotonicityConfig(BasePlotConfig):
+    """Configuration for the monotonicity-check plot."""
+
+    max_display: int = Field(default=10, gt=0, description="Max features to display.")
+
+
+class ForceConfig(BasePlotConfig):
+    """Configuration for the single-prediction force plot."""
+
+    max_display: int = Field(default=10, gt=0, description="Max features to display.")
+    show_values: bool = Field(
+        default=True, description="Annotate each segment with its contribution."
+    )
+
+
+class DecisionConfig(BasePlotConfig):
+    """Configuration for the decision plot."""
+
+    max_display: int = Field(default=10, gt=0, description="Max features to display.")
+    ordering: FeatureOrdering = Field(
+        default=FeatureOrdering.IMPORTANCE,
+        description="How to order features along the axis.",
+    )
+    color_scale: ColorScale = Field(
+        default=ColorScale.RED_BLUE,
+        description="Color scale encoding each instance's predicted output.",
+    )
+    line_width: float = Field(default=1.5, gt=0, description="Line width in pixels.")
+    opacity: float = Field(default=0.8, gt=0.0, le=1.0, description="Line opacity.")

shaply/enums.py

@@ -0,0 +1,69 @@
+"""Enumerations used across ``shaply`` to keep public options explicit and typed."""
+
+from __future__ import annotations
+
+from enum import IntEnum, StrEnum
+
+
+class PlotType(StrEnum):
+    """Kind of SHAP figure that ``shaply`` can render."""
+
+    BAR = "bar"
+    BEESWARM = "beeswarm"
+    BEESWARM_RANGES = "beeswarm_ranges"
+    WATERFALL = "waterfall"
+    SCATTER = "scatter"
+    HEATMAP = "heatmap"
+    FORCE = "force"
+    DECISION = "decision"
+    RESPONSE_CURVE = "response_curve"
+    INTERACTION_HEATMAP = "interaction_heatmap"
+    ERROR_ANALYSIS = "error_analysis"
+    SHAP_SURFACE = "shap_surface"
+    IMPORTANCE_BY_COHORT = "importance_by_cohort"
+    FEATURE_CLUSTERING = "feature_clustering"
+    EXPLANATION_ARCHETYPES = "explanation_archetypes"
+    IMPORTANCE_CI = "importance_ci"
+    MONOTONICITY = "monotonicity"
+
+
+class FeatureOrdering(StrEnum):
+    """Strategy used to order features along the categorical axis of a plot.
+
+    Attributes
+    ----------
+    IMPORTANCE
+        Order by mean absolute SHAP value (most important first).
+    MAX_ABSOLUTE
+        Order by the single largest absolute SHAP value across samples.
+    ORIGINAL
+        Keep the order of ``feature_names`` as provided.
+    ALPHABETICAL
+        Order features alphabetically by name.
+    """
+
+    IMPORTANCE = "importance"
+    MAX_ABSOLUTE = "max_absolute"
+    ORIGINAL = "original"
+    ALPHABETICAL = "alphabetical"
+
+
+class ColorScale(StrEnum):
+    """Named color scales available for continuous encodings.
+
+    ``RED_BLUE`` reproduces the canonical SHAP diverging scheme
+    (blue for low feature values, red for high).
+    """
+
+    RED_BLUE = "red_blue"
+    VIRIDIS = "viridis"
+    PLASMA = "plasma"
+    COOLWARM = "coolwarm"
+    REDS = "reds"
+
+
+class SortDirection(IntEnum):
+    """Direction used when sorting numeric quantities."""
+
+    ASCENDING = 1
+    DESCENDING = -1