explainiverse 0.1.1a1__py3-none-any.whl → 0.2.0__py3-none-any.whl

explainiverse/evaluation/metrics.py

@@ -1,233 +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
-
+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/explainers/__init__.py

@@ -0,0 +1,38 @@
+# src/explainiverse/explainers/__init__.py
+"""
+Explainiverse Explainers - comprehensive XAI method implementations.
+
+Local Explainers (instance-level):
+- LIME: Local Interpretable Model-agnostic Explanations
+- SHAP: SHapley Additive exPlanations
+- Anchors: High-precision rule-based explanations
+- Counterfactual: Diverse counterfactual explanations
+
+Global Explainers (model-level):
+- Permutation Importance: Feature importance via permutation
+- Partial Dependence: Marginal feature effects (PDP)
+- ALE: Accumulated Local Effects (unbiased for correlated features)
+- SAGE: Shapley Additive Global importancE
+"""
+
+from explainiverse.explainers.attribution.lime_wrapper import LimeExplainer
+from explainiverse.explainers.attribution.shap_wrapper import ShapExplainer
+from explainiverse.explainers.rule_based.anchors_wrapper import AnchorsExplainer
+from explainiverse.explainers.counterfactual.dice_wrapper import CounterfactualExplainer
+from explainiverse.explainers.global_explainers.permutation_importance import PermutationImportanceExplainer
+from explainiverse.explainers.global_explainers.partial_dependence import PartialDependenceExplainer
+from explainiverse.explainers.global_explainers.ale import ALEExplainer
+from explainiverse.explainers.global_explainers.sage import SAGEExplainer
+
+__all__ = [
+    # Local explainers
+    "LimeExplainer",
+    "ShapExplainer",
+    "AnchorsExplainer",
+    "CounterfactualExplainer",
+    # Global explainers
+    "PermutationImportanceExplainer",
+    "PartialDependenceExplainer",
+    "ALEExplainer",
+    "SAGEExplainer",
+]

explainiverse/explainers/attribution/__init__.py

@@ -0,0 +1,9 @@
+# src/explainiverse/explainers/attribution/__init__.py
+"""
+Attribution-based explainers - feature importance explanations.
+"""
+
+from explainiverse.explainers.attribution.lime_wrapper import LimeExplainer
+from explainiverse.explainers.attribution.shap_wrapper import ShapExplainer
+
+__all__ = ["LimeExplainer", "ShapExplainer"]

explainiverse/explainers/attribution/lime_wrapper.py

@@ -1,63 +1,90 @@
-# src/explainiverse/explainers/attribution/lime_wrapper.py
-
-import numpy as np
-from lime.lime_tabular import LimeTabularExplainer
-
-from explainiverse.core.explainer import BaseExplainer
-from explainiverse.core.explanation import Explanation
-
-
-class LimeExplainer(BaseExplainer):
-    """
-    Wrapper for LIME that conforms to the BaseExplainer API.
-    """
-
-    def __init__(self, model, training_data, feature_names, class_names, mode="classification"):
-        """
-        Args:
-            model: A model adapter (implements .predict()).
-            training_data: The data used to initialize LIME (2D np.ndarray).
-            feature_names: List of feature names.
-            class_names: List of class names.
-            mode: 'classification' or 'regression'.
-        """
-        super().__init__(model)
-        self.feature_names = feature_names
-        self.class_names = class_names
-        self.mode = mode
-
-        self.explainer = LimeTabularExplainer(
-            training_data=training_data,
-            feature_names=feature_names,
-            class_names=class_names,
-            mode=mode
-        )
-
-    def explain(self, instance, num_features=5, top_labels=1):
-        """
-        Generate a local explanation for the given instance.
-
-        Args:
-            instance: 1D numpy array (single row)
-            num_features: Number of top features to include
-            top_labels: Number of top labels to explain
-
-        Returns:
-            Explanation object
-        """
-        lime_exp = self.explainer.explain_instance(
-            data_row=instance,
-            predict_fn=self.model.predict,
-            num_features=num_features,
-            top_labels=top_labels
-        )
-
-        label_index = lime_exp.top_labels[0]
-        label_name = self.class_names[label_index]
-        attributions = dict(lime_exp.as_list(label=label_index))
-
-        return Explanation(
-            explainer_name="LIME",
-            target_class=label_name,
-            explanation_data={"feature_attributions": attributions}
-        )
+# src/explainiverse/explainers/attribution/lime_wrapper.py
+"""
+LIME Explainer - Local Interpretable Model-agnostic Explanations.
+
+LIME explains individual predictions by fitting a simple interpretable
+model (linear regression) to perturbed samples around the instance.
+
+Reference:
+    Ribeiro, M.T., Singh, S., & Guestrin, C. (2016). "Why Should I Trust You?":
+    Explaining the Predictions of Any Classifier. KDD 2016.
+"""
+
+import numpy as np
+from lime.lime_tabular import LimeTabularExplainer
+
+from explainiverse.core.explainer import BaseExplainer
+from explainiverse.core.explanation import Explanation
+
+
+class LimeExplainer(BaseExplainer):
+    """
+    LIME explainer for local, model-agnostic explanations.
+    
+    LIME (Local Interpretable Model-agnostic Explanations) explains individual
+    predictions by approximating the model locally with an interpretable model.
+    It generates perturbed samples around the instance and fits a weighted
+    linear model to understand feature contributions.
+    
+    This implementation wraps the official LIME library for tabular data.
+    
+    Attributes:
+        model: Model adapter with .predict() method
+        feature_names: List of feature names
+        class_names: List of class names
+        mode: 'classification' or 'regression'
+        explainer: The underlying LimeTabularExplainer
+    """
+
+    def __init__(self, model, training_data, feature_names, class_names, mode="classification"):
+        """
+        Initialize the LIME explainer.
+        
+        Args:
+            model: A model adapter (implements .predict()).
+            training_data: The data used to initialize LIME (2D np.ndarray).
+                          Used to compute statistics for perturbation generation.
+            feature_names: List of feature names.
+            class_names: List of class names.
+            mode: 'classification' or 'regression'.
+        """
+        super().__init__(model)
+        self.feature_names = list(feature_names)
+        self.class_names = list(class_names)
+        self.mode = mode
+
+        self.explainer = LimeTabularExplainer(
+            training_data=training_data,
+            feature_names=feature_names,
+            class_names=class_names,
+            mode=mode
+        )
+
+    def explain(self, instance, num_features=5, top_labels=1):
+        """
+        Generate a local explanation for the given instance.
+
+        Args:
+            instance: 1D numpy array (single row) to explain
+            num_features: Number of top features to include in explanation
+            top_labels: Number of top predicted labels to explain
+
+        Returns:
+            Explanation object with feature attributions
+        """
+        lime_exp = self.explainer.explain_instance(
+            data_row=instance,
+            predict_fn=self.model.predict,
+            num_features=num_features,
+            top_labels=top_labels
+        )
+
+        label_index = lime_exp.top_labels[0]
+        label_name = self.class_names[label_index]
+        attributions = dict(lime_exp.as_list(label=label_index))
+
+        return Explanation(
+            explainer_name="LIME",
+            target_class=label_name,
+            explanation_data={"feature_attributions": attributions}
+        )