classifier-toolkit 0.2.7__tar.gz → 0.3.1__tar.gz

{classifier_toolkit-0.2.7 → classifier_toolkit-0.3.1}/.github/workflows/docs.yml

@@ -26,4 +26,4 @@ jobs:
         run: uv sync --group docs
 
       - name: Deploy
-        run: uv run mkdocs gh-deploy --force
+        run: uv run mkdocs gh-deploy --force --cname classifier-toolkit.gh-pages.qonto.co

{classifier_toolkit-0.2.7 → classifier_toolkit-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: classifier-toolkit
-Version: 0.2.7
+Version: 0.3.1
 Project-URL: Documentation, http://classifier-toolkit.gh-pages.qonto.co/
 Author-email: "senih.yilmaz" <senih.yilmaz@qonto.com>, "jeremy.fraoua" <jeremy.fraoua@qonto.com>, "gauthier.marquand" <gauthier.marquand@qonto.com>, "arnaud.alepee" <arnaud.alepee@qonto.com>
 License-File: LICENSE

classifier_toolkit-0.3.1/classifier_toolkit/explainability/__init__.py

@@ -0,0 +1,41 @@
+"""Model explainability public API with lazy imports.
+
+Exposes SHAP-based global, local, and interaction explanations for tree
+models, mirroring the paylater production explainability workflow.
+"""
+
+import logging
+from importlib import import_module
+from typing import Any
+
+logging.getLogger("classifier_toolkit.explainability").addHandler(logging.NullHandler())
+
+_EXPORTS: dict[str, str] = {
+    "ExplainabilityError": "classifier_toolkit.explainability.base",
+    "ShapResult": "classifier_toolkit.explainability.base",
+    "TreeSHAPExplainer": "classifier_toolkit.explainability.tree_explainer",
+    "plot_summary": "classifier_toolkit.explainability.plots",
+    "plot_waterfall": "classifier_toolkit.explainability.plots",
+    "plot_shap_dependence_grid": "classifier_toolkit.explainability.plots",
+    "compute_shap_interaction_values": "classifier_toolkit.explainability.interactions",
+    "analyze_shap_interactions": "classifier_toolkit.explainability.interactions",
+    "plot_top_shap_interactions": "classifier_toolkit.explainability.interactions",
+    "MisclassificationAnalyzer": "classifier_toolkit.explainability.misclassification",
+    "ExplainabilityToolkit": "classifier_toolkit.explainability.toolkit",
+}
+
+__all__ = list(_EXPORTS.keys())
+
+
+def __getattr__(name: str) -> Any:  # pragma: no cover
+    module_path = _EXPORTS.get(name)
+    if module_path is None:
+        raise AttributeError(
+            f"module 'classifier_toolkit.explainability' has no attribute '{name}'"
+        )
+    module = import_module(module_path)
+    return getattr(module, name)
+
+
+def __dir__():  # pragma: no cover
+    return sorted(list(globals().keys()) + __all__)

classifier_toolkit-0.3.1/classifier_toolkit/explainability/base.py

@@ -0,0 +1,60 @@
+"""Base types and exceptions for model explainability."""
+
+from dataclasses import dataclass
+from typing import Any, Optional, Union
+
+import numpy as np
+import pandas as pd
+
+
+class ExplainabilityError(Exception):
+    """Base exception for explainability errors."""
+
+
+@dataclass
+class ShapResult:
+    """Container for SHAP explanation output.
+
+    Attributes
+    ----------
+    values : np.ndarray
+        SHAP values with shape ``(n_samples, n_features)`` for binary
+        classification, or ``(n_samples, n_features, n_classes)`` for
+        multiclass models.
+    data : Union[pd.DataFrame, np.ndarray]
+        Feature matrix that was explained.
+    feature_names : List[str]
+        Names of the explained features.
+    base_values : Optional[np.ndarray]
+        Expected model output (SHAP base value) per sample.
+    explainer : Any
+        Underlying SHAP explainer instance (for waterfall / interaction reuse).
+    """
+
+    values: np.ndarray
+    data: Union[pd.DataFrame, np.ndarray]
+    feature_names: list[str]
+    base_values: Optional[np.ndarray] = None
+    explainer: Any = None
+
+    @property
+    def n_samples(self) -> int:
+        return int(self.values.shape[0])
+
+    @property
+    def n_features(self) -> int:
+        if self.values.ndim == 2:
+            return int(self.values.shape[1])
+        return int(self.values.shape[1])
+
+    def values_for_class(self, class_index: int = -1) -> np.ndarray:
+        """Return a 2D SHAP matrix for plotting (positive class by default)."""
+        if self.values.ndim == 3:
+            return self.values[..., class_index]
+        return self.values
+
+    def mean_abs_importance(self) -> pd.Series:
+        """Mean absolute SHAP value per feature (global importance)."""
+        values = self.values_for_class()
+        importance = np.abs(values).mean(axis=0)
+        return pd.Series(importance, index=self.feature_names, name="mean_abs_shap")

classifier_toolkit-0.3.1/classifier_toolkit/explainability/interactions.py

@@ -0,0 +1,138 @@
+"""SHAP interaction analysis and plotting."""
+
+import math
+from collections.abc import Sequence
+from typing import Union
+
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+import shap
+
+
+def _normalize_shap_array(values, class_index: int = -1) -> np.ndarray:
+    """Convert list-shaped multiclass SHAP output to a single 2D/3D array."""
+    if isinstance(values, list):
+        return np.asarray(values[class_index])
+    return np.asarray(values)
+
+
+def compute_shap_interaction_values(
+    model, X: pd.DataFrame, feature_names: Sequence[str], class_index: int = -1
+) -> np.ndarray:
+    """Compute SHAP interaction values for tree models."""
+    raw = shap.TreeExplainer(model).shap_interaction_values(X[feature_names])
+    return _normalize_shap_array(raw, class_index=class_index)
+
+
+def analyze_shap_interactions(
+    model,
+    X_test: pd.DataFrame,
+    feature_names: Sequence[str],
+    shap_values: np.ndarray,
+    n_important_features: int = 2,
+) -> plt.Figure:
+    """Grid of main effects (diagonal) and pairwise interactions (off-diagonal)."""
+    interaction_values = compute_shap_interaction_values(model, X_test, feature_names)
+
+    important_features = list(feature_names)[:n_important_features]
+    n_features = len(important_features)
+
+    fig, axes = plt.subplots(
+        n_features, n_features, figsize=(10 * n_features, 10 * n_features)
+    )
+
+    if n_features == 1:
+        axes = np.array([[axes]])
+
+    feature_list = list(feature_names)
+    for i in range(n_features):
+        for j in range(n_features):
+            feature_i = important_features[i]
+            feature_j = important_features[j]
+            idx_i = feature_list.index(feature_i)
+            idx_j = feature_list.index(feature_j)
+            plt.sca(axes[i, j])
+
+            if i == j:
+                shap.dependence_plot(
+                    ind=idx_i,
+                    shap_values=shap_values,
+                    features=X_test[feature_list],
+                    feature_names=feature_list,
+                    ax=axes[i, j],
+                    show=False,
+                )
+                axes[i, j].set_title(f"Main effect: {feature_i}")
+            else:
+                shap.dependence_plot(
+                    (idx_i, idx_j),
+                    interaction_values,
+                    X_test[feature_list],
+                    feature_names=feature_list,
+                    ax=axes[i, j],
+                    show=False,
+                )
+                axes[i, j].set_title(f"Interaction: {feature_i} × {feature_j}")  # noqa: RUF001
+
+    plt.tight_layout()
+    plt.subplots_adjust(top=0.9)
+    fig.suptitle("Main Effects and Interactions Analysis", fontsize=16)
+    return fig
+
+
+def plot_top_shap_interactions(
+    model,
+    X_test: Union[pd.DataFrame, np.ndarray],
+    feature_names: Sequence[str],
+    n_top_interactions: int = 9,
+) -> plt.Figure:
+    """Plot the strongest feature interactions by mean absolute SHAP interaction."""
+    if not isinstance(X_test, pd.DataFrame):
+        X_test = pd.DataFrame(X_test, columns=list(feature_names))
+
+    interaction_values = compute_shap_interaction_values(model, X_test, feature_names)
+
+    interaction_strength = np.abs(interaction_values).mean(axis=0)
+    np.fill_diagonal(interaction_strength, 0)
+
+    flat_indices = np.argsort(interaction_strength.flatten())[-n_top_interactions:]
+    feature_pairs: list[tuple] = []
+    names = list(feature_names)
+
+    for flat_idx in flat_indices[::-1]:
+        i, j = np.unravel_index(flat_idx, interaction_strength.shape)
+        if i < j:
+            feature_pairs.append((names[i], names[j], interaction_strength[i, j]))
+        else:
+            feature_pairs.append((names[j], names[i], interaction_strength[i, j]))
+
+    n_cols = 2
+    n_rows = math.ceil(len(feature_pairs) / n_cols)
+    fig, axes = plt.subplots(n_rows, n_cols, figsize=(18, 6 * n_rows))
+
+    if n_rows == 1:
+        axes = np.array([axes])
+    axes_flat = axes.flatten()
+
+    for i, (feature1, feature2, strength) in enumerate(feature_pairs):
+        ax = axes_flat[i]
+        idx1 = names.index(feature1)
+        idx2 = names.index(feature2)
+        plt.sca(ax)
+        shap.dependence_plot(
+            (idx1, idx2),
+            interaction_values,
+            X_test[names],
+            feature_names=names,
+            ax=ax,
+            show=False,
+        )
+        ax.set_title(f"#{i + 1}: {feature1} × {feature2}\nStrength: {strength:.4f}")  # noqa: RUF001
+
+    for i in range(len(feature_pairs), n_rows * n_cols):
+        axes_flat[i].set_visible(False)
+
+    fig.suptitle("Top Feature Interactions by SHAP Strength", fontsize=16, y=1.02)
+    plt.tight_layout()
+    return fig

classifier_toolkit-0.3.1/classifier_toolkit/explainability/misclassification.py

@@ -0,0 +1,107 @@
+"""Misclassification analysis with per-observation SHAP waterfalls."""
+
+from collections.abc import Sequence
+from typing import Literal, Optional, Union
+
+import numpy as np
+import pandas as pd
+
+from classifier_toolkit.explainability.base import ExplainabilityError
+from classifier_toolkit.explainability.plots import plot_waterfall
+from classifier_toolkit.explainability.tree_explainer import TreeSHAPExplainer
+
+Quadrant = Literal[
+    "false_negative",
+    "false_positive",
+    "true_positive",
+    "true_negative",
+]
+
+_QUADRANT_FILTERS: dict[Quadrant, tuple] = {
+    "false_negative": ("y_pred", False, "y_true", True),
+    "false_positive": ("y_pred", True, "y_true", False),
+    "true_positive": ("y_pred", True, "y_true", True),
+    "true_negative": ("y_pred", False, "y_true", False),
+}
+
+_QUADRANT_SORT: dict[Quadrant, tuple] = {
+    "false_negative": ("y_pred_proba", True),
+    "false_positive": ("y_pred_proba", False),
+    "true_positive": ("y_pred_proba", False),
+    "true_negative": ("y_pred_proba", True),
+}
+
+
+class MisclassificationAnalyzer:
+    """Filter confusion-matrix quadrants and explain individual predictions.
+
+    Mirrors the bin-analysis workflow from the paylater explainability
+    notebook (false negatives, false positives, true positives, true negatives).
+    """
+
+    def __init__(
+        self,
+        model,
+        explainer: TreeSHAPExplainer,
+        feature_names: Sequence[str],
+        threshold: float = 0.5,
+    ) -> None:
+        self.model = model
+        self.explainer = explainer
+        self.feature_names = list(feature_names)
+        self.threshold = threshold
+
+    def build_prediction_frame(
+        self,
+        X: pd.DataFrame,
+        y_true: Union[pd.Series, np.ndarray],
+        extra_columns: Optional[pd.DataFrame] = None,
+    ) -> pd.DataFrame:
+        """Attach true labels, predicted probabilities, and binary predictions."""
+        df = X[self.feature_names].copy()
+        if extra_columns is not None:
+            for col in extra_columns.columns:
+                df[col] = extra_columns[col].values
+        df["y_true"] = np.asarray(y_true)
+        proba = self.model.predict_proba(df[self.feature_names])[:, 1]
+        df["y_pred_proba"] = proba
+        df["y_pred"] = (proba > self.threshold).astype(int)
+        return df
+
+    def filter_quadrant(
+        self,
+        df: pd.DataFrame,
+        quadrant: Quadrant,
+    ) -> pd.DataFrame:
+        """Return rows for a confusion-matrix quadrant, sorted by probability."""
+        if quadrant not in _QUADRANT_FILTERS:
+            raise ExplainabilityError(f"Unknown quadrant: {quadrant}")
+
+        pred_col, pred_val, true_col, true_val = _QUADRANT_FILTERS[quadrant]
+        mask = (df[pred_col] == pred_val) & (df[true_col] == true_val)
+        sort_col, ascending = _QUADRANT_SORT[quadrant]
+        return df.loc[mask].sort_values(by=sort_col, ascending=ascending)
+
+    def explain_row(self, row: Union[pd.Series, pd.DataFrame]):
+        """SHAP explanation object for one observation (waterfall-ready)."""
+        if isinstance(row, pd.Series):
+            row = row.to_frame().T
+        if len(row) != 1:
+            raise ExplainabilityError("explain_row expects a single observation.")
+        return self.explainer.explain_observation(row[self.feature_names])
+
+    def plot_waterfall_for_row(
+        self,
+        row: Union[pd.Series, pd.DataFrame],
+        max_display: int = 15,
+        show: bool = True,
+    ) -> None:
+        """Waterfall plot for one observation."""
+        plot_waterfall(self.explain_row(row), max_display=max_display, show=show)
+
+    def quadrant_counts(self, df: pd.DataFrame) -> pd.Series:
+        """Count rows in each confusion-matrix quadrant."""
+        counts = {}
+        for quadrant in _QUADRANT_FILTERS:
+            counts[quadrant] = len(self.filter_quadrant(df, quadrant))
+        return pd.Series(counts, name="count")

classifier_toolkit-0.3.1/classifier_toolkit/explainability/plots.py

@@ -0,0 +1,140 @@
+"""SHAP plotting helpers."""
+
+import math
+from collections.abc import Sequence
+from typing import Optional, Union
+
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+import shap
+
+from classifier_toolkit.explainability.base import ShapResult
+
+
+def plot_summary(
+    shap_result: ShapResult,
+    max_display: int = 20,
+    show: bool = True,
+) -> None:
+    """Beeswarm summary plot for global feature importance."""
+    shap.summary_plot(
+        shap_result.values_for_class(),
+        shap_result.data,
+        feature_names=shap_result.feature_names,
+        max_display=max_display,
+        show=show,
+    )
+
+
+def plot_waterfall(
+    explanation,
+    max_display: int = 15,
+    show: bool = True,
+) -> None:
+    """Waterfall plot for a single observation SHAP explanation."""
+    shap.plots.waterfall(explanation, max_display=max_display, show=show)
+
+
+def plot_shap_dependence_grid(
+    feature_list: Union[str, Sequence[str]],
+    shap_values: Union[np.ndarray, pd.DataFrame],
+    X_test: pd.DataFrame,
+    feature_names: Optional[Sequence[str]] = None,
+    n_cols: int = 2,
+    overall_title: str = "Feature Impact Analysis using SHAP",
+    is_categorical: bool = False,
+    show: bool = False,
+) -> Optional[plt.Figure]:
+    """Plot SHAP dependence plots for a list of features in a grid layout.
+
+    Ported from the paylater production workflow to provide the same
+    grid-layout dependence analysis inside classifier_toolkit.
+    """
+    if isinstance(feature_list, str):
+        feature_list = [feature_list]
+    feature_list = list(feature_list)
+
+    if len(feature_list) == 0:
+        return None
+
+    if feature_names is None:
+        feature_names = list(X_test.columns)
+    feature_names = list(feature_names)
+
+    missing = [f for f in feature_list if f not in feature_names]
+    if missing:
+        raise ValueError(
+            f"The following features are not in feature_names: {missing}. "
+            f"Available features: {feature_names}"
+        )
+
+    n_features = len(feature_list)
+    n_rows = math.ceil(n_features / n_cols)
+
+    fig, axes = plt.subplots(n_rows, n_cols, figsize=(18, 6 * n_rows))
+
+    if n_rows * n_cols == 1:
+        axes_flat = [axes]
+    elif n_rows == 1:
+        axes_flat = list(axes)
+    else:
+        axes_flat = list(axes.flatten())
+
+    if not is_categorical:
+        for i, feature in enumerate(feature_list):
+            ax = axes_flat[i]
+            try:
+                shap.dependence_plot(
+                    ind=feature,
+                    shap_values=shap_values,
+                    features=X_test[feature_names],
+                    feature_names=feature_names,
+                    ax=ax,
+                    show=False,
+                )
+                ax.set_title(f"SHAP Dependence: {feature}")
+            except Exception as exc:  # pragma: no cover - plotting edge cases
+                ax.text(
+                    0.5,
+                    0.5,
+                    f"Error plotting\n{feature}\n{exc}",
+                    ha="center",
+                    va="center",
+                    transform=ax.transAxes,
+                )
+    else:
+        for i, feature in enumerate(feature_list):
+            row = i // n_cols
+            col = i % n_cols
+            feature_idx = feature_names.index(feature)
+            ax = axes[row, col] if n_rows > 1 else axes_flat[i]
+            try:
+                shap.dependence_plot(
+                    feature_idx,
+                    shap_values,
+                    X_test,
+                    title=f"Dependence: {feature}",
+                    ax=ax,
+                    show=False,
+                    interaction_index=None,
+                )
+            except Exception as exc:  # pragma: no cover
+                ax.text(
+                    0.5,
+                    0.5,
+                    f"Error plotting\n{feature}\n{exc}",
+                    ha="center",
+                    va="center",
+                    transform=ax.transAxes,
+                )
+
+    if n_rows * n_cols > 1:
+        for i in range(n_features, n_rows * n_cols):
+            axes_flat[i].set_visible(False)
+
+    fig.suptitle(overall_title, fontsize=16, y=1.02)
+    plt.tight_layout()
+    if show:
+        plt.show()
+    return fig

classifier_toolkit-0.3.1/classifier_toolkit/explainability/toolkit.py

@@ -0,0 +1,137 @@
+"""High-level explainability orchestrator."""
+
+from collections.abc import Sequence
+from typing import Optional, Union
+
+import numpy as np
+import pandas as pd
+
+from classifier_toolkit.explainability.base import ShapResult
+from classifier_toolkit.explainability.interactions import (
+    analyze_shap_interactions,
+    plot_top_shap_interactions,
+)
+from classifier_toolkit.explainability.misclassification import (
+    MisclassificationAnalyzer,
+)
+from classifier_toolkit.explainability.plots import (
+    plot_shap_dependence_grid,
+    plot_summary,
+)
+from classifier_toolkit.explainability.tree_explainer import TreeSHAPExplainer
+
+
+class ExplainabilityToolkit:
+    """Orchestrate the standard SHAP explainability workflow.
+
+      Combines global summaries, dependence grids, interaction analysis, and
+    misclassification waterfalls behind a single entry point.
+    """
+
+    def __init__(
+        self,
+        model,
+        feature_names: Sequence[str],
+        numerical_features: Optional[Sequence[str]] = None,
+        categorical_features: Optional[Sequence[str]] = None,
+        cat_features: Optional[list[str]] = None,
+        threshold: float = 0.5,
+    ) -> None:
+        self.model = model
+        self.feature_names = list(feature_names)
+        self.numerical_features = list(numerical_features or [])
+        self.categorical_features = list(categorical_features or [])
+        self.explainer = TreeSHAPExplainer(
+            model,
+            cat_features=cat_features or categorical_features,
+            feature_names=self.feature_names,
+        )
+        self.threshold = threshold
+        self.shap_result_: Optional[ShapResult] = None
+
+    def compute_shap(
+        self,
+        X: pd.DataFrame,
+        y: Optional[Union[pd.Series, np.ndarray]] = None,
+    ) -> ShapResult:
+        """Compute and cache SHAP values for a feature matrix."""
+        self.shap_result_ = self.explainer.explain(X[self.feature_names], y=y)
+        return self.shap_result_
+
+    def plot_global_summary(self, max_display: int = 20, show: bool = True) -> None:
+        """Beeswarm summary plot from cached SHAP values."""
+        if self.shap_result_ is None:
+            raise ValueError("Call compute_shap() first.")
+        plot_summary(self.shap_result_, max_display=max_display, show=show)
+
+    def plot_numerical_dependence(self, show: bool = False):
+        """Dependence grid for numerical features."""
+        if self.shap_result_ is None:
+            raise ValueError("Call compute_shap() first.")
+        if not self.numerical_features:
+            return None
+        n_num = len(self.numerical_features)
+        values_2d = self.shap_result_.values_for_class()
+        shap_subset = values_2d[:, :n_num]
+        X_num = self.shap_result_.data[self.numerical_features]
+        return plot_shap_dependence_grid(
+            feature_list=self.numerical_features,
+            shap_values=shap_subset,
+            X_test=X_num,
+            feature_names=self.numerical_features,
+            overall_title="Numerical Feature Impact (SHAP)",
+            show=show,
+        )
+
+    def plot_categorical_dependence(self, show: bool = False):
+        """Dependence grid for categorical features."""
+        if self.shap_result_ is None:
+            raise ValueError("Call compute_shap() first.")
+        if not self.categorical_features:
+            return None
+        n_num = len(self.numerical_features)
+        values_2d = self.shap_result_.values_for_class()
+        shap_cat = values_2d[:, n_num:]
+        X_cat = self.shap_result_.data[self.categorical_features]
+        return plot_shap_dependence_grid(
+            feature_list=self.categorical_features,
+            shap_values=shap_cat,
+            X_test=X_cat,
+            feature_names=self.categorical_features,
+            is_categorical=True,
+            overall_title="Categorical Feature Impact (SHAP)",
+            show=show,
+        )
+
+    def plot_interaction_grid(self, n_important_features: int = 2):
+        """Main-effect / interaction grid for top features."""
+        if self.shap_result_ is None:
+            raise ValueError("Call compute_shap() first.")
+        X = self.shap_result_.data
+        return analyze_shap_interactions(
+            self.model,
+            X,
+            self.feature_names,
+            self.shap_result_.values_for_class(),
+            n_important_features=n_important_features,
+        )
+
+    def plot_top_interactions(self, n_top_interactions: int = 5):
+        """Top pairwise SHAP interactions."""
+        if self.shap_result_ is None:
+            raise ValueError("Call compute_shap() first.")
+        return plot_top_shap_interactions(
+            self.model,
+            self.shap_result_.data,
+            self.feature_names,
+            n_top_interactions=n_top_interactions,
+        )
+
+    def misclassification_analyzer(self) -> MisclassificationAnalyzer:
+        """Analyzer for confusion-matrix quadrant waterfalls."""
+        return MisclassificationAnalyzer(
+            model=self.model,
+            explainer=self.explainer,
+            feature_names=self.feature_names,
+            threshold=self.threshold,
+        )