explainiverse 0.1.0a1__py3-none-any.whl → 0.1.1a1__py3-none-any.whl

explainiverse/engine/suite.py

@@ -0,0 +1,143 @@
+# src/explainiverse/engine/suite.py
+
+from explainiverse.core.explanation import Explanation
+from explainiverse.explainers.attribution.lime_wrapper import LimeExplainer
+from explainiverse.explainers.attribution.shap_wrapper import ShapExplainer
+from explainiverse.evaluation.metrics import compute_roar
+from sklearn.metrics import accuracy_score
+from sklearn.linear_model import LogisticRegression
+
+class ExplanationSuite:
+    """
+    Runs multiple explainers on a single instance and compares their outputs.
+    """
+
+    def __init__(self, model, explainer_configs, data_meta=None):
+        """
+        Args:
+            model: a model adapter (e.g., SklearnAdapter)
+            explainer_configs: list of (name, kwargs) tuples for explainers
+            data_meta: optional metadata about the task, scope, or preference
+        """
+        self.model = model
+        self.configs = explainer_configs
+        self.data_meta = data_meta or {}
+        self.explanations = {}
+
+    def run(self, instance):
+        """
+        Run all configured explainers on a single instance.
+        """
+        for name, params in self.configs:
+            explainer = self._load_explainer(name, **params)
+            explanation = explainer.explain(instance)
+            self.explanations[name] = explanation
+        return self.explanations
+
+    def compare(self):
+        """
+        Print attribution scores side-by-side.
+        """
+        keys = set()
+        for explanation in self.explanations.values():
+            keys.update(explanation.explanation_data.get("feature_attributions", {}).keys())
+
+        print("\nSide-by-Side Comparison:")
+        for key in sorted(keys):
+            row = [f"{key}"]
+            for name in self.explanations:
+                value = self.explanations[name].explanation_data.get("feature_attributions", {}).get(key, "—")
+                row.append(f"{name}: {value:.4f}" if isinstance(value, float) else f"{name}: {value}")
+            print(" | ".join(row))
+
+    def suggest_best(self):
+        """
+        Suggest the best explainer based on model type, output structure, and task metadata.
+        """
+        if "task" in self.data_meta:
+            task = self.data_meta["task"]
+        else:
+            task = "unknown"
+
+        model = self.model.model
+
+        # 1. Regression: SHAP preferred due to consistent output
+        if task == "regression":
+            return "shap"
+
+        # 2. Model with `predict_proba` → SHAP handles probabilistic outputs well
+        if hasattr(model, "predict_proba"):
+            try:
+                output = self.model.predict([[0] * model.n_features_in_])
+                if output.shape[1] > 2:
+                    return "shap"  # Multi-class, SHAP more stable
+                else:
+                    return "lime"  # Binary, both are okay
+            except Exception:
+                return "shap"
+
+        # 3. Tree-based models → prefer SHAP (TreeSHAP if available)
+        if "tree" in str(type(model)).lower():
+            return "shap"
+
+        # 4. Default fallback
+        return "lime"
+
+    def _load_explainer(self, name, **kwargs):
+        if name == "lime":
+            return LimeExplainer(model=self.model, **kwargs)
+        elif name == "shap":
+            return ShapExplainer(model=self.model, **kwargs)
+        else:
+            raise ValueError(f"Unknown explainer: {name}")
+        
+
+
+    def evaluate_roar(
+        self,
+        X_train,
+        y_train,
+        X_test,
+        y_test,
+        top_k: int = 2,
+        model_class=None,
+        model_kwargs: dict = None
+    ):
+        """
+        Evaluate each explainer using ROAR (Remove And Retrain).
+        
+        Args:
+            X_train, y_train: training data
+            X_test, y_test: test data
+            top_k: number of features to mask
+            model_class: model constructor with .fit() and .predict() (default: same as current model)
+            model_kwargs: optional keyword args for new model instance
+
+        Returns:
+            Dict of {explainer_name: accuracy drop (baseline - retrained)}
+        """
+        from explainiverse.evaluation.metrics import compute_roar
+
+        model_kwargs = model_kwargs or {}
+
+        # Default to type(self.model.model) if not provided
+        if model_class is None:
+            model_class = type(self.model.model)
+
+        roar_scores = {}
+
+        for name, explanation in self.explanations.items():
+            print(f"[ROAR] Evaluating explainer: {name}")
+            roar = compute_roar(
+                model_class=model_class,
+                X_train=X_train,
+                y_train=y_train,
+                X_test=X_test,
+                y_test=y_test,
+                explanations=[explanation],  # single-instance for now
+                top_k=top_k,
+                model_kwargs=model_kwargs
+            )
+            roar_scores[name] = roar
+
+        return roar_scores

explainiverse/evaluation/metrics.py

@@ -0,0 +1,233 @@
+import numpy as np
+from explainiverse.core.explanation import Explanation
+from sklearn.metrics import accuracy_score
+import copy
+
+
+def compute_aopc(
+    model,
+    instance: np.ndarray,
+    explanation: Explanation,
+    num_steps: int = 10,
+    baseline_value: float = 0.0
+) -> float:
+    """
+    Computes Area Over the Perturbation Curve (AOPC) by iteratively removing top features.
+
+    Args:
+        model: wrapped model with .predict() method
+        instance: input sample (1D array)
+        explanation: Explanation object
+        num_steps: number of top features to remove
+        baseline_value: value to replace removed features with (e.g., 0, mean)
+
+    Returns:
+        AOPC score (higher means explanation is more faithful)
+    """
+    base_pred = model.predict(instance.reshape(1, -1))[0]
+    attributions = explanation.explanation_data.get("feature_attributions", {})
+
+    if not attributions:
+        raise ValueError("No feature attributions found in explanation.")
+
+    # Sort features by abs importance
+    sorted_features = sorted(
+        attributions.items(),
+        key=lambda x: abs(x[1]),
+        reverse=True
+    )
+
+    # Try to map feature names to indices
+    feature_indices = []
+    for i, (fname, _) in enumerate(sorted_features):
+        try:
+            idx = explanation.feature_names.index(fname)
+        except Exception:
+            idx = i  # fallback: assume order
+        feature_indices.append(idx)
+
+    deltas = []
+    modified = instance.copy()
+
+    for i in range(min(num_steps, len(feature_indices))):
+        idx = feature_indices[i]
+        modified[idx] = baseline_value
+        new_pred = model.predict(modified.reshape(1, -1))[0]
+        delta = abs(base_pred - new_pred)
+        deltas.append(delta)
+
+    return np.mean(deltas)
+
+
+def compute_batch_aopc(
+    model,
+    X: np.ndarray,
+    explanations: dict,
+    num_steps: int = 10,
+    baseline_value: float = 0.0
+) -> dict:
+    """
+    Compute average AOPC for multiple explainers over a batch of instances.
+
+    Args:
+        model: wrapped model
+        X: 2D input array
+        explanations: dict of {explainer_name: list of Explanation objects}
+        num_steps: number of top features to remove
+        baseline_value: value to replace features with
+
+    Returns:
+        Dict of {explainer_name: mean AOPC score}
+    """
+    results = {}
+
+    for explainer_name, expl_list in explanations.items():
+        scores = []
+        for i, exp in enumerate(expl_list):
+            instance = X[i]
+            score = compute_aopc(model, instance, exp, num_steps, baseline_value)
+            scores.append(score)
+        results[explainer_name] = np.mean(scores)
+
+    return results
+
+
+def compute_roar(
+    model_class,
+    X_train: np.ndarray,
+    y_train: np.ndarray,
+    X_test: np.ndarray,
+    y_test: np.ndarray,
+    explanations: list,
+    top_k: int = 3,
+    baseline_value: float = 0.0,
+    model_kwargs: dict = None
+) -> float:
+    """
+    Compute ROAR (Remove And Retrain) using top-k important features from explanations.
+
+    Args:
+        model_class: uninstantiated model class (e.g. LogisticRegression)
+        X_train: full training data
+        y_train: training labels
+        X_test: test features
+        y_test: test labels
+        explanations: list of Explanation objects (one per train instance)
+        top_k: number of top features to remove
+        baseline_value: what to set removed features to
+        model_kwargs: optional kwargs to pass to model_class
+
+    Returns:
+        Accuracy drop (baseline_acc - retrained_acc)
+    """
+    model_kwargs = model_kwargs or {}
+
+    # Baseline model
+    baseline_model = model_class(**model_kwargs)
+    baseline_model.fit(X_train, y_train)
+    baseline_preds = baseline_model.predict(X_test)
+    baseline_acc = accuracy_score(y_test, baseline_preds)
+
+    # Compute top-k feature indices from attributions (use mode)
+    feature_counts = {}
+    for exp in explanations:
+        for fname, val in sorted(exp.explanation_data["feature_attributions"].items(), key=lambda x: abs(x[1]), reverse=True)[:top_k]:
+            try:
+                idx = exp.feature_names.index(fname)
+                feature_counts[idx] = feature_counts.get(idx, 0) + 1
+            except:
+                continue
+
+    top_features = sorted(feature_counts.items(), key=lambda x: x[1], reverse=True)[:top_k]
+    top_feature_indices = [idx for idx, _ in top_features]
+
+    # Remove top-k from training and test data
+    X_train_mod = copy.deepcopy(X_train)
+    X_test_mod = copy.deepcopy(X_test)
+    
+    # Prepare feature-wise baselines
+    # Compute or assign feature-wise baseline values
+    if not isinstance(
+    baseline_value,
+        (str, float, int, np.number, np.ndarray)
+    ) and not callable(baseline_value):
+        raise ValueError(f"Invalid baseline_value type: {type(baseline_value)}")
+    
+    if isinstance(baseline_value, str):
+        if baseline_value == "mean":
+            feature_baseline = np.mean(X_train, axis=0)
+        elif baseline_value == "median":
+            feature_baseline = np.median(X_train, axis=0)
+        else:
+            raise ValueError(f"Unsupported string baseline: {baseline_value}")
+    elif callable(baseline_value):
+        feature_baseline = baseline_value(X_train)
+    elif isinstance(baseline_value, np.ndarray):
+        if baseline_value.shape != (X_train.shape[1],):
+            raise ValueError("baseline_value ndarray must match number of features")
+        feature_baseline = baseline_value
+    elif isinstance(baseline_value, (float, int, np.number)):
+        feature_baseline = np.full(X_train.shape[1], baseline_value)
+    else:
+        raise ValueError(f"Invalid baseline_value type: {type(baseline_value)}")
+    
+    for idx in top_feature_indices:
+        X_train_mod[:, idx] = feature_baseline[idx]
+        X_test_mod[:, idx] = feature_baseline[idx]
+        # X_train_mod[:, idx] = baseline_value
+        # X_test_mod[:, idx] = baseline_value
+
+    # Retrain and evaluate
+    retrained_model = model_class(**model_kwargs)
+    retrained_model.fit(X_train_mod, y_train)
+    retrained_preds = retrained_model.predict(X_test_mod)
+    retrained_acc = accuracy_score(y_test, retrained_preds)
+
+    return baseline_acc - retrained_acc
+
+
+def compute_roar_curve(
+    model_class,
+    X_train,
+    y_train,
+    X_test,
+    y_test,
+    explanations,
+    max_k=5,
+    baseline_value="mean",
+    model_kwargs=None
+) -> dict:
+    """
+    Compute ROAR accuracy drops across a range of top-k features removed.
+
+    Args:
+        model_class: model type (e.g. LogisticRegression)
+        X_train, y_train, X_test, y_test: full dataset
+        explanations: list of Explanation objects
+        max_k: maximum top-k to try
+        baseline_value: string, scalar, ndarray, or callable
+        model_kwargs: passed to model class
+
+    Returns:
+        Dict of {k: accuracy drop} for k in 1..max_k
+    """
+    from copy import deepcopy
+
+    model_kwargs = model_kwargs or {}
+    curve = {}
+
+    for k in range(1, max_k + 1):
+        acc_drop = compute_roar(
+            model_class=model_class,
+            X_train=deepcopy(X_train),
+            y_train=deepcopy(y_train),
+            X_test=deepcopy(X_test),
+            y_test=deepcopy(y_test),
+            explanations=deepcopy(explanations),
+            top_k=k,
+            baseline_value=baseline_value,
+            model_kwargs=deepcopy(model_kwargs)
+        )
+        curve[k] = acc_drop
+
+    return curve

explainiverse-0.1.1a1.dist-info/METADATA

@@ -0,0 +1,128 @@
+Metadata-Version: 2.1
+Name: explainiverse
+Version: 0.1.1a1
+Summary: Unified, extensible explainability framework supporting LIME, SHAP, and custom adapters
+Home-page: https://github.com/jemsbhai/explainiverse
+License: MIT
+Author: Muntaser Syed
+Author-email: jemsbhai@gmail.com
+Requires-Python: >=3.10,<3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: lime (>=0.2.0.1,<0.3.0.0)
+Requires-Dist: numpy (==1.24.4)
+Requires-Dist: scikit-learn (>=1.1,<1.4)
+Requires-Dist: shap (>=0.48.0,<0.49.0)
+Requires-Dist: xgboost (>=3.0.2,<4.0.0)
+Project-URL: Repository, https://github.com/jemsbhai/explainiverse
+Description-Content-Type: text/markdown
+
+# Explainiverse
+
+**Explainiverse** is a unified, extensible, and testable Python framework for Explainable AI (XAI).  
+It offers a standardized interface for model-agnostic explainability, evaluation metrics like AOPC and ROAR, and support for multiple XAI methods out of the box.
+
+---
+
+## Features
+
+- Standardized `Explainer` API (`BaseExplainer`)
+- Support for:
+  - Local and global feature attribution
+  - Regression and classification tasks
+- Integrated explainers:
+  - **LIME** (tabular, local surrogate)
+  - **SHAP** (KernelExplainer with multi-class, regression, cohort support)
+- Evaluation metrics:
+  - **AOPC** (Area Over Perturbation Curve)
+  - **ROAR** (Remove And Retrain)
+    - Multiple `top_k` support
+    - Baseline options: `"mean"`, `"median"`, `np.ndarray`, `callable`
+    - Curve generation for ROAR vs feature importance
+- Explainability Suite:
+  - Run and compare multiple explainers
+  - Auto-suggestion based on model/task type
+- Built-in support for models: `LogisticRegression`, `RandomForest`, `SVC`, `KNN`, `XGB`, `NaiveBayes`, and more
+
+---
+
+
+## Installation
+
+From PyPI:
+
+```bash
+pip install explainiverse
+```
+
+For development use:
+
+```bash
+git clone https://github.com/jemsbhai/explainiverse.git
+cd explainiverse
+poetry install
+```
+
+---
+
+## Quick Example
+```python
+
+from explainiverse.adapters.sklearn_adapter import SklearnAdapter
+from explainiverse.explainers.attribution.lime_wrapper import LimeExplainer
+from explainiverse.engine.suite import ExplanationSuite
+
+# Wrap your model
+adapter = SklearnAdapter(your_model, class_names=["yes", "no"])
+
+# Build the suite
+suite = ExplanationSuite(
+    model=adapter,
+    explainer_configs=[
+        ("lime", {...}),
+        ("shap", {...})
+    ],
+    data_meta={"task": "classification"}
+)
+
+results = suite.run(instance)
+suite.compare()
+suite.evaluate_roar(X_train, y_train, X_test, y_test, top_k=3)
+```
+
+
+---
+
+## Running Tests
+
+All tests can be run using:
+
+```bash
+poetry run python tests/test_all.py
+```
+
+For individual component testing:
+
+```bash
+poetry run python tests/test_shap_explainer.py
+poetry run python tests/test_lime_explainer.py
+poetry run python tests/test_evaluation_metrics.py
+```
+
+---
+
+## Documentation
+
+Documentation is currently in development.  
+Until then, test files (especially `test_shap_explainer.py`) demonstrate usage and structure.
+
+---
+
+## License
+
+This project is licensed under the MIT License.
+
+

{explainiverse-0.1.0a1.dist-info → explainiverse-0.1.1a1.dist-info}/RECORD

@@ -5,11 +5,15 @@ explainiverse/adapters/sklearn_adapter.py,sha256=WQC-i4OIaR0M-AILXV5OvNo9H2JA0dV
 explainiverse/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 explainiverse/core/explainer.py,sha256=8vI_Paj1cpbhLK6GP1Ckq2SzW4FyjUgxOpuLKE12ddI,815
 explainiverse/core/explanation.py,sha256=Gxz-0lU4YVZfV1Bsrzma7uvfze127aCmqDaVK1dg-hI,905
+explainiverse/engine/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+explainiverse/engine/suite.py,sha256=brBQNCHMBobaOjSVpoBBsbo3gep9qbEcT0NSdU6SPxw,5056
+explainiverse/evaluation/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+explainiverse/evaluation/metrics.py,sha256=N_EucJ8Ud1Wa3IU6ZxzKKILF7UkQDLKEyhAvUaDHIGM,7685
 explainiverse/explainers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 explainiverse/explainers/attribution/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 explainiverse/explainers/attribution/lime_wrapper.py,sha256=hFd6tQ7uE6R3ORHTuT-w2vW9JkvFuYbEZDpGqRLRNto,2107
 explainiverse/explainers/attribution/shap_wrapper.py,sha256=yAQDZNPFbn_H0AMFhWKMEoQb8IG05Tg6oRBcWRw4CP8,2378
-explainiverse-0.1.0a1.dist-info/LICENSE,sha256=28rbHe8rJgmUlRdxJACfq1Sj-MtCEhyHxkJedQd1ZYA,1070
-explainiverse-0.1.0a1.dist-info/METADATA,sha256=3RLsxJI-m4M3x1yWgvLRSbggI9PZvmcXYSc5FsDR5-s,2222
-explainiverse-0.1.0a1.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
-explainiverse-0.1.0a1.dist-info/RECORD,,
+explainiverse-0.1.1a1.dist-info/LICENSE,sha256=28rbHe8rJgmUlRdxJACfq1Sj-MtCEhyHxkJedQd1ZYA,1070
+explainiverse-0.1.1a1.dist-info/METADATA,sha256=rkIf7lkW6PaxJItQMdAamsOb4_DpBeVRxV0M16PrfR4,3263
+explainiverse-0.1.1a1.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+explainiverse-0.1.1a1.dist-info/RECORD,,

explainiverse-0.1.0a1.dist-info/METADATA

@@ -1,83 +0,0 @@
-Metadata-Version: 2.1
-Name: explainiverse
-Version: 0.1.0a1
-Summary: Unified, extensible explainability framework supporting LIME, SHAP, and custom adapters
-Home-page: https://github.com/jemsbhai/explainiverse
-License: MIT
-Author: Muntaser Syed
-Author-email: jemsbhai@gmail.com
-Requires-Python: >=3.10,<3.13
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Requires-Dist: lime (>=0.2.0.1,<0.3.0.0)
-Requires-Dist: numpy (==1.24.4)
-Requires-Dist: scikit-learn (>=1.1,<1.4)
-Requires-Dist: shap (>=0.48.0,<0.49.0)
-Project-URL: Repository, https://github.com/jemsbhai/explainiverse
-Description-Content-Type: text/markdown
-
-# Explainiverse
-
-Explainiverse is a unified, extensible, and testable Python framework for explainable AI (XAI).  
-It provides a consistent API and support for post-hoc explainers like LIME and SHAP, model adapters, and rigorous evaluation strategies.
-
----
-
-## Features
-
-- Standardized Explainer interface (`BaseExplainer`)
-- Support for classification, regression, and multi-class models
-- Integrated explainers:
-  - LIME (Local surrogate models)
-  - SHAP (KernelExplainer with per-class and global support)
-- Adapter layer for scikit-learn models
-- Explanation object with structured output and future extensibility for `.plot()`
-- Full unit test suite covering classification, regression, global/cohort SHAP, and adapter behavior
-
----
-
-## Installation
-
-This package will soon be available on PyPI.
-
-For development use:
-
-```bash
-git clone https://github.com/YOUR_USERNAME/explainiverse.git
-cd explainiverse
-poetry install
-```
-
----
-
-## Running Tests
-
-All tests can be run using:
-
-```bash
-poetry run python tests/test_all.py
-```
-
-For individual component testing:
-
-```bash
-poetry run python tests/test_shap_explainer.py
-poetry run python tests/test_lime_explainer.py
-```
-
----
-
-## Documentation
-
-Documentation is currently in development.  
-Until then, test files (especially `test_shap_explainer.py`) demonstrate usage and structure.
-
----
-
-## License
-
-This project is licensed under the MIT License.
-