explainiverse 0.2.5__tar.gz → 0.4.0__tar.gz

{explainiverse-0.2.5 → explainiverse-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: explainiverse
-Version: 0.2.5
+Version: 0.4.0
 Summary: Unified, extensible explainability framework supporting LIME, SHAP, Anchors, Counterfactuals, PDP, ALE, SAGE, and more
 Home-page: https://github.com/jemsbhai/explainiverse
 License: MIT
@@ -20,6 +20,7 @@ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Provides-Extra: torch
 Requires-Dist: lime (>=0.2.0.1,<0.3.0.0)
 Requires-Dist: numpy (>=1.24,<2.0)
+Requires-Dist: pandas (>=1.5,<3.0)
 Requires-Dist: scikit-learn (>=1.1,<1.6)
 Requires-Dist: scipy (>=1.10,<2.0)
 Requires-Dist: shap (>=0.48.0,<0.49.0)

{explainiverse-0.2.5 → explainiverse-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "explainiverse"
-version = "0.2.5"
+version = "0.4.0"
 description = "Unified, extensible explainability framework supporting LIME, SHAP, Anchors, Counterfactuals, PDP, ALE, SAGE, and more"
 authors = ["Muntaser Syed <jemsbhai@gmail.com>"]
 license = "MIT"
@@ -27,6 +27,7 @@ numpy = ">=1.24,<2.0"
 lime = "^0.2.0.1"
 scikit-learn = ">=1.1,<1.6"
 shap = "^0.48.0"
+pandas = ">=1.5,<3.0"
 scipy = ">=1.10,<2.0"
 xgboost = ">=1.7,<3.0"
 torch = { version = ">=2.0", optional = true }

{explainiverse-0.2.5 → explainiverse-0.4.0}/src/explainiverse/__init__.py

@@ -33,7 +33,7 @@ from explainiverse.adapters.sklearn_adapter import SklearnAdapter
 from explainiverse.adapters import TORCH_AVAILABLE
 from explainiverse.engine.suite import ExplanationSuite
 
-__version__ = "0.2.5"
+__version__ = "0.4.0"
 
 __all__ = [
     # Core

{explainiverse-0.2.5 → explainiverse-0.4.0}/src/explainiverse/core/registry.py

@@ -372,6 +372,7 @@ def _create_default_registry() -> ExplainerRegistry:
     from explainiverse.explainers.gradient.integrated_gradients import IntegratedGradientsExplainer
     from explainiverse.explainers.gradient.gradcam import GradCAMExplainer
     from explainiverse.explainers.gradient.deeplift import DeepLIFTExplainer, DeepLIFTShapExplainer
+    from explainiverse.explainers.example_based.protodash import ProtoDashExplainer
     
     registry = ExplainerRegistry()
     
@@ -604,6 +605,27 @@ def _create_default_registry() -> ExplainerRegistry:
         )
     )
     
+    # =========================================================================
+    # Example-Based Explainers
+    # =========================================================================
+    
+    # Register ProtoDash
+    registry.register(
+        name="protodash",
+        explainer_class=ProtoDashExplainer,
+        meta=ExplainerMeta(
+            scope="local",
+            model_types=["any"],
+            data_types=["tabular"],
+            task_types=["classification", "regression"],
+            description="ProtoDash - prototype selection with importance weights for example-based explanations",
+            paper_reference="Gurumoorthy et al., 2019 - 'Efficient Data Representation by Selecting Prototypes' (ICDM)",
+            complexity="O(n_prototypes * n_samples^2)",
+            requires_training_data=True,
+            supports_batching=True
+        )
+    )
+    
     return registry
 
 

explainiverse-0.4.0/src/explainiverse/evaluation/__init__.py

@@ -0,0 +1,60 @@
+# src/explainiverse/evaluation/__init__.py
+"""
+Evaluation metrics for explanation quality.
+
+Includes:
+- Faithfulness metrics (PGI, PGU, Comprehensiveness, Sufficiency)
+- Stability metrics (RIS, ROS, Lipschitz)
+- Perturbation metrics (AOPC, ROAR)
+"""
+
+from explainiverse.evaluation.metrics import (
+    compute_aopc,
+    compute_batch_aopc,
+    compute_roar,
+    compute_roar_curve,
+)
+
+from explainiverse.evaluation.faithfulness import (
+    compute_pgi,
+    compute_pgu,
+    compute_faithfulness_score,
+    compute_comprehensiveness,
+    compute_sufficiency,
+    compute_faithfulness_correlation,
+    compare_explainer_faithfulness,
+    compute_batch_faithfulness,
+)
+
+from explainiverse.evaluation.stability import (
+    compute_ris,
+    compute_ros,
+    compute_lipschitz_estimate,
+    compute_stability_metrics,
+    compute_batch_stability,
+    compare_explainer_stability,
+)
+
+__all__ = [
+    # Perturbation metrics (existing)
+    "compute_aopc",
+    "compute_batch_aopc",
+    "compute_roar",
+    "compute_roar_curve",
+    # Faithfulness metrics (new)
+    "compute_pgi",
+    "compute_pgu",
+    "compute_faithfulness_score",
+    "compute_comprehensiveness",
+    "compute_sufficiency",
+    "compute_faithfulness_correlation",
+    "compare_explainer_faithfulness",
+    "compute_batch_faithfulness",
+    # Stability metrics (new)
+    "compute_ris",
+    "compute_ros",
+    "compute_lipschitz_estimate",
+    "compute_stability_metrics",
+    "compute_batch_stability",
+    "compare_explainer_stability",
+]

explainiverse-0.4.0/src/explainiverse/evaluation/_utils.py

@@ -0,0 +1,325 @@
+# src/explainiverse/evaluation/_utils.py
+"""
+Shared utility functions for evaluation metrics.
+"""
+import numpy as np
+import re
+from typing import Union, Callable, List, Tuple
+from explainiverse.core.explanation import Explanation
+
+
+def _extract_base_feature_name(feature_str: str) -> str:
+    """
+    Extract the base feature name from LIME-style feature strings.
+    
+    LIME returns strings like "petal width (cm) <= 0.80" or "feature_2 > 3.5".
+    This extracts just the feature name part.
+    
+    Args:
+        feature_str: Feature string possibly with conditions
+        
+    Returns:
+        Base feature name
+    """
+    # Remove comparison operators and values
+    # Pattern matches: name <= value, name < value, name >= value, name > value, name = value
+    patterns = [
+        r'^(.+?)\s*<=\s*[\d\.\-]+$',
+        r'^(.+?)\s*>=\s*[\d\.\-]+$',
+        r'^(.+?)\s*<\s*[\d\.\-]+$',
+        r'^(.+?)\s*>\s*[\d\.\-]+$',
+        r'^(.+?)\s*=\s*[\d\.\-]+$',
+    ]
+    
+    for pattern in patterns:
+        match = re.match(pattern, feature_str.strip())
+        if match:
+            return match.group(1).strip()
+    
+    # No match found, return as-is
+    return feature_str.strip()
+
+
+def _match_feature_to_index(
+    feature_key: str,
+    feature_names: List[str]
+) -> int:
+    """
+    Match a feature key (possibly with LIME conditions) to its index.
+    
+    Args:
+        feature_key: Feature name from explanation (may include conditions)
+        feature_names: List of original feature names
+        
+    Returns:
+        Index of the matching feature, or -1 if not found
+    """
+    # Try exact match first
+    if feature_key in feature_names:
+        return feature_names.index(feature_key)
+    
+    # Try extracting base name
+    base_name = _extract_base_feature_name(feature_key)
+    if base_name in feature_names:
+        return feature_names.index(base_name)
+    
+    # Try partial matching (feature name is contained in key)
+    for i, fname in enumerate(feature_names):
+        if fname in feature_key:
+            return i
+    
+    # Try index extraction from patterns like "feature_2" or "f2" or "feat_2"
+    patterns = [
+        r'feature[_\s]*(\d+)',
+        r'feat[_\s]*(\d+)',
+        r'^f(\d+)$',
+        r'^x(\d+)$',
+    ]
+    for pattern in patterns:
+        match = re.search(pattern, feature_key, re.IGNORECASE)
+        if match:
+            idx = int(match.group(1))
+            if 0 <= idx < len(feature_names):
+                return idx
+    
+    return -1
+
+
+def get_sorted_feature_indices(
+    explanation: Explanation,
+    descending: bool = True
+) -> List[int]:
+    """
+    Extract feature indices sorted by absolute attribution value.
+    
+    Handles various feature naming conventions:
+    - Clean names: "sepal length", "feature_0"
+    - LIME-style: "sepal length <= 5.0", "feature_0 > 2.3"
+    - Indexed: "f0", "x1", "feat_2"
+    
+    Args:
+        explanation: Explanation object with feature_attributions
+        descending: If True, sort from most to least important
+        
+    Returns:
+        List of feature indices sorted by importance
+    """
+    attributions = explanation.explanation_data.get("feature_attributions", {})
+    
+    if not attributions:
+        raise ValueError("No feature attributions found in explanation.")
+    
+    # Sort features by absolute importance
+    sorted_features = sorted(
+        attributions.items(),
+        key=lambda x: abs(x[1]),
+        reverse=descending
+    )
+    
+    # Map feature names to indices
+    feature_indices = []
+    feature_names = getattr(explanation, 'feature_names', None)
+    
+    for i, (fname, _) in enumerate(sorted_features):
+        if feature_names is not None:
+            idx = _match_feature_to_index(fname, feature_names)
+            if idx >= 0:
+                feature_indices.append(idx)
+            else:
+                # Fallback: use position in sorted list
+                feature_indices.append(i % len(feature_names))
+        else:
+            # No feature_names available - try to extract index from name
+            patterns = [
+                r'feature[_\s]*(\d+)',
+                r'feat[_\s]*(\d+)',
+                r'^f(\d+)',
+                r'^x(\d+)',
+            ]
+            found = False
+            for pattern in patterns:
+                match = re.search(pattern, fname, re.IGNORECASE)
+                if match:
+                    feature_indices.append(int(match.group(1)))
+                    found = True
+                    break
+            if not found:
+                feature_indices.append(i)
+    
+    return feature_indices
+
+
+def compute_baseline_values(
+    baseline: Union[str, float, np.ndarray, Callable],
+    background_data: np.ndarray = None,
+    n_features: int = None
+) -> np.ndarray:
+    """
+    Compute per-feature baseline values for perturbation.
+    
+    Args:
+        baseline: Baseline specification - one of:
+            - "mean": Use mean of background_data
+            - "median": Use median of background_data
+            - float/int: Use this value for all features
+            - np.ndarray: Use these values directly (must match n_features)
+            - Callable: Function that takes background_data and returns baseline array
+        background_data: Reference data for computing statistics (required for "mean"/"median")
+        n_features: Number of features (required if baseline is scalar)
+        
+    Returns:
+        1D numpy array of baseline values, one per feature
+    """
+    if isinstance(baseline, str):
+        if background_data is None:
+            raise ValueError(f"background_data required for baseline='{baseline}'")
+        if baseline == "mean":
+            return np.mean(background_data, axis=0)
+        elif baseline == "median":
+            return np.median(background_data, axis=0)
+        else:
+            raise ValueError(f"Unsupported string baseline: {baseline}")
+    
+    elif callable(baseline):
+        if background_data is None:
+            raise ValueError("background_data required for callable baseline")
+        result = baseline(background_data)
+        return np.asarray(result)
+    
+    elif isinstance(baseline, np.ndarray):
+        return baseline
+    
+    elif isinstance(baseline, (float, int, np.number)):
+        if n_features is None:
+            raise ValueError("n_features required for scalar baseline")
+        return np.full(n_features, baseline)
+    
+    else:
+        raise ValueError(f"Invalid baseline type: {type(baseline)}")
+
+
+def apply_feature_mask(
+    instance: np.ndarray,
+    feature_indices: List[int],
+    baseline_values: np.ndarray
+) -> np.ndarray:
+    """
+    Replace specified features with baseline values.
+    
+    Args:
+        instance: Original instance (1D array)
+        feature_indices: Indices of features to replace
+        baseline_values: Per-feature baseline values
+        
+    Returns:
+        Modified instance with specified features replaced
+    """
+    modified = instance.copy()
+    for idx in feature_indices:
+        if idx < len(modified) and idx < len(baseline_values):
+            modified[idx] = baseline_values[idx]
+    return modified
+
+
+def resolve_k(k: Union[int, float], n_features: int) -> int:
+    """
+    Resolve k to an integer number of features.
+    
+    Args:
+        k: Either an integer count or a float fraction (0-1)
+        n_features: Total number of features
+        
+    Returns:
+        Integer number of features
+    """
+    if isinstance(k, float) and 0 < k <= 1:
+        return max(1, int(k * n_features))
+    elif isinstance(k, int) and k > 0:
+        return min(k, n_features)
+    else:
+        raise ValueError(f"k must be positive int or float in (0, 1], got {k}")
+
+
+def get_prediction_value(
+    model,
+    instance: np.ndarray,
+    output_type: str = "probability"
+) -> float:
+    """
+    Get a scalar prediction value from a model.
+    
+    Works with both raw sklearn models and explainiverse adapters.
+    For adapters, .predict() typically returns probabilities.
+    
+    Args:
+        model: Model adapter with predict/predict_proba methods
+        instance: Single instance (1D array)
+        output_type: "probability" (max prob) or "class" (predicted class)
+        
+    Returns:
+        Scalar prediction value
+    """
+    instance_2d = instance.reshape(1, -1)
+    
+    if output_type == "probability":
+        # Try predict_proba first (raw sklearn model)
+        if hasattr(model, 'predict_proba'):
+            proba = model.predict_proba(instance_2d)
+            if isinstance(proba, np.ndarray):
+                if proba.ndim == 2:
+                    return float(np.max(proba[0]))
+                return float(np.max(proba))
+            return float(np.max(proba[0]))
+        
+        # Fall back to predict (adapter returns probs from predict)
+        pred = model.predict(instance_2d)
+        if isinstance(pred, np.ndarray):
+            if pred.ndim == 2:
+                return float(np.max(pred[0]))
+            elif pred.ndim == 1:
+                return float(np.max(pred))
+        return float(pred[0]) if hasattr(pred, '__getitem__') else float(pred)
+    
+    elif output_type == "class":
+        # For class prediction, use argmax of probabilities
+        if hasattr(model, 'predict_proba'):
+            proba = model.predict_proba(instance_2d)
+            return float(np.argmax(proba[0]))
+        pred = model.predict(instance_2d)
+        if isinstance(pred, np.ndarray) and pred.ndim == 2:
+            return float(np.argmax(pred[0]))
+        return float(pred[0]) if hasattr(pred, '__getitem__') else float(pred)
+    
+    else:
+        raise ValueError(f"Unknown output_type: {output_type}")
+
+
+def compute_prediction_change(
+    model,
+    original: np.ndarray,
+    perturbed: np.ndarray,
+    metric: str = "absolute"
+) -> float:
+    """
+    Compute the change in prediction between original and perturbed instances.
+    
+    Args:
+        model: Model adapter
+        original: Original instance
+        perturbed: Perturbed instance
+        metric: "absolute" for |p1 - p2|, "relative" for |p1 - p2| / p1
+        
+    Returns:
+        Prediction change value
+    """
+    orig_pred = get_prediction_value(model, original)
+    pert_pred = get_prediction_value(model, perturbed)
+    
+    if metric == "absolute":
+        return abs(orig_pred - pert_pred)
+    elif metric == "relative":
+        if abs(orig_pred) < 1e-10:
+            return abs(pert_pred)
+        return abs(orig_pred - pert_pred) / abs(orig_pred)
+    else:
+        raise ValueError(f"Unknown metric: {metric}")