shap-analyzer 0.1.3__tar.gz

shap_analyzer-0.1.3/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: shap_analyzer
+Version: 0.1.3
+Summary: A lightweight wrapper for quick SHAP model explainability analysis.
+Author-email: Abu Saad <abusaadd44@gmail.com>
+Requires-Python: >=3.8
+Requires-Dist: shap>=0.42.0
+Requires-Dist: pandas>=1.5.0
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: matplotlib>=3.5.0

shap_analyzer-0.1.3/pyproject.toml

@@ -0,0 +1,16 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "shap_analyzer"
+version = "0.1.3"
+description = "A lightweight wrapper for quick SHAP model explainability analysis."
+authors = [{ name = "Abu Saad", email = "abusaadd44@gmail.com" }]
+dependencies = [
+    "shap>=0.42.0",
+    "pandas>=1.5.0",
+    "numpy>=1.21.0",
+    "matplotlib>=3.5.0"
+]
+requires-python = ">=3.8"

shap_analyzer-0.1.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

shap_analyzer-0.1.3/shap_analyzer/__init__.py

@@ -0,0 +1,26 @@
+# 
+
+"""
+SHAP Analyzer Package Initializer
+"""
+
+from .core import ModelExplainer, analyze
+from .visualizer import (
+    plot_bar,
+    plot_decision,
+    plot_dependence,
+    plot_heatmap,
+    plot_local,
+    plot_summary,
+)
+
+__all__ = [
+    "ModelExplainer", 
+    "analyze",
+    "plot_summary", 
+    "plot_bar", 
+    "plot_local", 
+    "plot_dependence", 
+    "plot_heatmap", 
+    "plot_decision"
+]

shap_analyzer-0.1.3/shap_analyzer/core.py

@@ -0,0 +1,252 @@
+# # """
+# # Core analysis engine wrapping SHAP explainers.
+# # """
+
+# # from typing import Union, Optional
+# # import pandas as pd
+# # import numpy as np
+# # import shap
+
+
+# # class ModelExplainer:
+# #     """
+# #     Main wrapper class for initializing SHAP analysis on trained models.
+# #     """
+
+# #     def __init__(self, model, X_data: pd.DataFrame, sample_size: Optional[int] = None):
+# #         """
+# #         Parameters
+# #         ----------
+# #         model : object
+# #             Trained Machine Learning model (Scikit-Learn, XGBoost, LightGBM, etc.).
+# #         X_data : pd.DataFrame
+# #             Dataset used for generating explanations.
+# #         sample_size : int, optional
+# #             If provided, subsamples X_data for faster computation on large datasets.
+# #         """
+# #         self.model = model
+# #         self.feature_names = list(X_data.columns)
+
+# #         if sample_size and sample_size < len(X_data):
+# #             self.X_data = X_data.sample(n=sample_size, random_state=42)
+# #         else:
+# #             self.X_data = X_data.copy()
+
+# #         # Automatically picks the best explainer (TreeExplainer, LinearExplainer, etc.)
+# #         self.explainer = shap.Explainer(self.model, self.X_data)
+# #         self.shap_values = self.explainer(self.X_data)
+
+# #     def get_feature_importance(self) -> pd.DataFrame:
+# #         """
+# #         Calculates global feature importance based on mean absolute SHAP values.
+
+# #         Returns
+# #         -------
+# #         pd.DataFrame
+# #             DataFrame with 'feature' and 'mean_shap_value' sorted in descending order.
+# #         """
+# #         # Multi-class output handling
+# #         if len(self.shap_values.values.shape) == 3:
+# #             vals = np.abs(self.shap_values.values).mean(axis=(0, 2))
+# #         else:
+# #             vals = np.abs(self.shap_values.values).mean(axis=0)
+
+# #         df = pd.DataFrame({
+# #             'feature': self.feature_names,
+# #             'mean_shap_value': vals
+# #         })
+# #         return df.sort_values(by='mean_shap_value', ascending=False).reset_index(drop=True)
+
+# #     def get_instance_explanation(self, index: int) -> pd.DataFrame:
+# #         """
+# #         Extracts feature contributions for a single observation/row.
+
+# #         Parameters
+# #         ----------
+# #         index : int
+# #             Row index position in X_data.
+
+# #         Returns
+# #         -------
+# #         pd.DataFrame
+# #             DataFrame containing feature names, raw values, and instance SHAP impact.
+# #         """
+# #         if index < 0 or index >= len(self.X_data):
+# #             raise IndexError(f"Index {index} is out of bounds for data length {len(self.X_data)}")
+
+# #         single_shap = self.shap_values.values[index]
+# #         single_val = self.X_data.iloc[index].values
+
+# #         # If multi-class, select first class for simplicity
+# #         if len(single_shap.shape) > 1:
+# #             single_shap = single_shap[:, 0]
+
+# #         df = pd.DataFrame({
+# #             'feature': self.feature_names,
+# #             'feature_value': single_val,
+# #             'shap_impact': single_shap
+# #         })
+# #         return df.sort_values(by='shap_impact', key=abs, ascending=False).reset_index(drop=True)
+
+# from typing import Optional
+# import pandas as pd
+# import numpy as np
+# import shap
+
+
+# class ModelExplainer:
+#     def __init__(self, model, X_data: pd.DataFrame, sample_size: Optional[int] = None):
+#         self.model = model
+#         self.feature_names = list(X_data.columns)
+
+#         if sample_size and sample_size < len(X_data):
+#             self.X_data = X_data.sample(n=sample_size, random_state=42)
+#         else:
+#             self.X_data = X_data.copy()
+
+#         self.explainer = shap.Explainer(self.model, self.X_data)
+#         raw_shap = self.explainer(self.X_data)
+
+#         # Fix: For classification models (3D matrix [samples, features, classes]), select Class 1
+#         if len(raw_shap.shape) == 3:
+#             self.shap_values = raw_shap[:, :, 1]
+#         else:
+#             self.shap_values = raw_shap
+
+#     def get_feature_importance(self) -> pd.DataFrame:
+#         vals = np.abs(self.shap_values.values).mean(axis=0)
+#         return pd.DataFrame({
+#             'feature': self.feature_names,
+#             'mean_shap_value': vals
+#         }).sort_values(by='mean_shap_value', ascending=False).reset_index(drop=True)
+
+
+
+#     def get_instance_explanation(self, index: int) -> pd.DataFrame:
+#         if index < 0 or index >= len(self.X_data):
+#             raise IndexError(f"Index {index} out of bounds.")
+
+#         return pd.DataFrame({
+#             'feature': self.feature_names,
+#             'feature_value': self.X_data.iloc[index].values,
+#             'shap_impact': self.shap_values.values[index]
+#         }).sort_values(by='shap_impact', key=abs, ascending=False).reset_index(drop=True)
+
+#     def get_top_drivers(self, index: int, top_n: int = 3) -> dict:
+#         df = self.get_instance_explanation(index)
+        
+#         # 1. Filter and sort positive drivers (largest positive impacts first)
+#         pos_drivers = (
+#             df[df['shap_impact'] > 0]
+#             .sort_values(by='shap_impact', ascending=False)
+#             .head(top_n)
+#         )
+        
+#         # 2. Filter and sort negative drivers (most negative impacts first)
+#         neg_drivers = (
+#             df[df['shap_impact'] < 0]
+#             .sort_values(by='shap_impact', ascending=True)
+#             .head(top_n)
+#         )
+        
+#         # 3. Missing Return Block
+#         return {
+#             "positive_drivers": pos_drivers[['feature', 'feature_value', 'shap_impact']].to_dict(orient='records'),
+#             "negative_drivers": neg_drivers[['feature', 'feature_value', 'shap_impact']].to_dict(orient='records')
+#         }
+
+"""
+Core explainability module for shap_analyzer.
+"""
+
+from typing import Optional
+import pandas as pd
+import numpy as np
+import shap
+
+
+class ModelExplainer:
+    def __init__(
+        self, 
+        model, 
+        X_data: pd.DataFrame, 
+        sample_size: Optional[int] = None,
+        class_index: int = 1
+    ):
+        self.model = model
+        self.class_index = class_index
+        self.feature_names = list(X_data.columns)
+
+        if sample_size and sample_size < len(X_data):
+            self.X_data = X_data.sample(n=sample_size, random_state=42)
+        else:
+            self.X_data = X_data.copy()
+
+        self.explainer = shap.Explainer(self.model, self.X_data)
+        raw_shap = self.explainer(self.X_data)
+
+        # Handle 3D SHAP outputs (multi-class or binary classification)
+        if len(raw_shap.shape) == 3:
+            num_classes = raw_shap.shape[2]
+            if self.class_index < 0 or self.class_index >= num_classes:
+                raise ValueError(
+                    f"class_index={self.class_index} is out of bounds. "
+                    f"This model has {num_classes} classes (indexes 0 to {num_classes - 1})."
+                )
+            self.shap_values = raw_shap[:, :, self.class_index]
+        else:
+            self.shap_values = raw_shap
+
+    def get_feature_importance(self) -> pd.DataFrame:
+        """Returns global feature importance sorted by mean absolute SHAP value."""
+        vals = np.abs(self.shap_values.values).mean(axis=0)
+        return pd.DataFrame({
+            'feature': self.feature_names,
+            'mean_shap_value': vals
+        }).sort_values(by='mean_shap_value', ascending=False).reset_index(drop=True)
+
+    def get_instance_explanation(self, index: int) -> pd.DataFrame:
+        """Returns local feature impacts for a specific instance row."""
+        if index < 0 or index >= len(self.X_data):
+            raise IndexError(f"Index {index} out of bounds.")
+
+        return pd.DataFrame({
+            'feature': self.feature_names,
+            'feature_value': self.X_data.iloc[index].values,
+            'shap_impact': self.shap_values.values[index]
+        }).sort_values(by='shap_impact', key=abs, ascending=False).reset_index(drop=True)
+
+    def get_top_drivers(self, index: int, top_n: int = 3) -> dict:
+        """Returns top N positive and negative features influencing a single prediction."""
+        df = self.get_instance_explanation(index)
+        
+        pos_drivers = (
+            df[df['shap_impact'] > 0]
+            .sort_values(by='shap_impact', ascending=False)
+            .head(top_n)
+        )
+        neg_drivers = (
+            df[df['shap_impact'] < 0]
+            .sort_values(by='shap_impact', ascending=True)
+            .head(top_n)
+        )
+        
+        return {
+            "positive_drivers": pos_drivers[['feature', 'feature_value', 'shap_impact']].to_dict(orient='records'),
+            "negative_drivers": neg_drivers[['feature', 'feature_value', 'shap_impact']].to_dict(orient='records')
+        }
+
+
+def analyze(
+    model, 
+    X_data: pd.DataFrame, 
+    sample_size: Optional[int] = None, 
+    class_index: int = 1
+) -> ModelExplainer:
+    """Helper function to initialize ModelExplainer directly."""
+    return ModelExplainer(
+        model, 
+        X_data, 
+        sample_size=sample_size, 
+        class_index=class_index
+    )

shap_analyzer-0.1.3/shap_analyzer/visualizer.py

@@ -0,0 +1,69 @@
+"""
+Plotting module built on top of SHAP visual outputs.
+"""
+
+import matplotlib.pyplot as plt
+import numpy as np
+import shap
+
+
+def plot_summary(explainer_obj, max_display: int = 10):
+    """Generates a SHAP beeswarm summary plot showing global feature impact."""
+    plt.figure()
+    shap.plots.beeswarm(explainer_obj.shap_values, max_display=max_display)
+    plt.tight_layout()
+    plt.show()
+
+
+def plot_bar(explainer_obj, max_display: int = 10):
+    """Generates a standard bar plot of mean absolute SHAP values."""
+    plt.figure()
+    shap.plots.bar(explainer_obj.shap_values, max_display=max_display)
+    plt.tight_layout()
+    plt.show()
+
+
+def plot_local(explainer_obj, index: int = 0):
+    """Generates a waterfall plot for explaining a specific single row prediction."""
+    plt.figure()
+    shap.plots.waterfall(explainer_obj.shap_values[index])
+    plt.tight_layout()
+    plt.show()
+
+def plot_dependence(explainer_obj, feature_name: str):
+    """
+    Shows how a single feature's value affects SHAP values 
+    and auto-colors by its strongest interacting feature.
+    """
+    plt.figure()
+    shap.plots.scatter(explainer_obj.shap_values[:, feature_name], color=explainer_obj.shap_values)
+    plt.tight_layout()
+    plt.show()
+
+
+def plot_heatmap(explainer_obj, max_display: int = 10, num_samples: int = 100):
+    """
+    Visualizes SHAP values across multiple rows simultaneously as a heatmap.
+    """
+    plt.figure()
+    shap.plots.heatmap(explainer_obj.shap_values[:num_samples], max_display=max_display)
+    plt.tight_layout()
+    plt.show()
+
+
+def plot_decision(explainer_obj, index: int = 0):
+    """
+    Shows the step-by-step decision trajectory from base value to final model prediction.
+    """
+    plt.figure()
+    expected_val = explainer_obj.explainer.expected_value
+    if isinstance(expected_val, (list, np.ndarray)):
+        expected_val = expected_val[1] if len(expected_val) > 1 else expected_val[0]
+
+    shap.decision_plot(
+        expected_val, 
+        explainer_obj.shap_values.values[index], 
+        feature_names=explainer_obj.feature_names
+    )
+    plt.tight_layout()
+    plt.show()

shap_analyzer-0.1.3/shap_analyzer.egg-info/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: shap_analyzer
+Version: 0.1.3
+Summary: A lightweight wrapper for quick SHAP model explainability analysis.
+Author-email: Abu Saad <abusaadd44@gmail.com>
+Requires-Python: >=3.8
+Requires-Dist: shap>=0.42.0
+Requires-Dist: pandas>=1.5.0
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: matplotlib>=3.5.0

shap_analyzer-0.1.3/shap_analyzer.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+pyproject.toml
+shap_analyzer/__init__.py
+shap_analyzer/core.py
+shap_analyzer/visualizer.py
+shap_analyzer.egg-info/PKG-INFO
+shap_analyzer.egg-info/SOURCES.txt
+shap_analyzer.egg-info/dependency_links.txt
+shap_analyzer.egg-info/requires.txt
+shap_analyzer.egg-info/top_level.txt
+tests/test_core.py

shap_analyzer-0.1.3/shap_analyzer.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

shap_analyzer-0.1.3/shap_analyzer.egg-info/requires.txt

@@ -0,0 +1,4 @@
+shap>=0.42.0
+pandas>=1.5.0
+numpy>=1.21.0
+matplotlib>=3.5.0

shap_analyzer-0.1.3/shap_analyzer.egg-info/top_level.txt

@@ -0,0 +1 @@
+shap_analyzer

shap_analyzer-0.1.3/tests/test_core.py

@@ -0,0 +1,65 @@
+import pandas as pd
+import pytest
+from sklearn.datasets import make_classification
+from sklearn.ensemble import RandomForestClassifier
+
+from shap_analyzer import analyze, ModelExplainer
+
+
+@pytest.fixture
+def binary_data_and_model():
+    X, y = make_classification(n_samples=100, n_features=4, n_classes=2, random_state=42)
+    X_df = pd.DataFrame(X, columns=[f"feat_{i}" for i in range(4)])
+    model = RandomForestClassifier(random_state=42).fit(X_df, y)
+    return model, X_df
+
+
+@pytest.fixture
+def multiclass_data_and_model():
+    X, y = make_classification(n_samples=100, n_features=4, n_classes=3, n_informative=3, random_state=42)
+    X_df = pd.DataFrame(X, columns=[f"feat_{i}" for i in range(4)])
+    model = RandomForestClassifier(random_state=42).fit(X_df, y)
+    return model, X_df
+
+
+def test_explainer_initialization(binary_data_and_model):
+    model, X_df = binary_data_and_model
+    exp = analyze(model, X_df)
+    assert isinstance(exp, ModelExplainer)
+    assert len(exp.feature_names) == 4
+
+
+def test_feature_importance(binary_data_and_model):
+    model, X_df = binary_data_and_model
+    exp = analyze(model, X_df)
+    df_imp = exp.get_feature_importance()
+    
+    assert isinstance(df_imp, pd.DataFrame)
+    assert list(df_imp.columns) == ["feature", "mean_shap_value"]
+    assert len(df_imp) == 4
+
+
+def test_top_drivers(binary_data_and_model):
+    model, X_df = binary_data_and_model
+    exp = analyze(model, X_df)
+    drivers = exp.get_top_drivers(index=0, top_n=2)
+    
+    assert "positive_drivers" in drivers
+    assert "negative_drivers" in drivers
+    assert len(drivers["positive_drivers"]) <= 2
+
+
+
+# Currently working on multiclass Models
+# def test_multiclass_handling(multiclass_data_and_model):
+#     model, X_df = multiclass_data_and_model
+#     exp = analyze(model, X_df, class_index=2)
+    
+#     assert exp.class_index == 2
+#     assert exp.shap_values.values.shape[0] == 100
+
+
+# def test_out_of_bounds_class_index(multiclass_data_and_model):
+    # model, X_df = multiclass_data_and_model
+    # with pytest.raises(ValueError):
+    #     analyze(model, X_df, class_index=99)