explainiverse 0.7.0__tar.gz → 0.7.1__tar.gz

{explainiverse-0.7.0 → explainiverse-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: explainiverse
-Version: 0.7.0
+Version: 0.7.1
 Summary: Unified, extensible explainability framework supporting LIME, SHAP, Anchors, Counterfactuals, PDP, ALE, SAGE, and more
 Home-page: https://github.com/jemsbhai/explainiverse
 License: MIT
@@ -671,7 +671,7 @@ If you use Explainiverse in your research, please cite:
   author = {Syed, Muntaser},
   year = {2025},
   url = {https://github.com/jemsbhai/explainiverse},
-  version = {0.7.0}
+  version = {0.7.1}
 }
 ```
 

{explainiverse-0.7.0 → explainiverse-0.7.1}/README.md

@@ -640,7 +640,7 @@ If you use Explainiverse in your research, please cite:
   author = {Syed, Muntaser},
   year = {2025},
   url = {https://github.com/jemsbhai/explainiverse},
-  version = {0.7.0}
+  version = {0.7.1}
 }
 ```
 

{explainiverse-0.7.0 → explainiverse-0.7.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "explainiverse"
-version = "0.7.0"
+version = "0.7.1"
 description = "Unified, extensible explainability framework supporting LIME, SHAP, Anchors, Counterfactuals, PDP, ALE, SAGE, and more"
 authors = ["Muntaser Syed <jemsbhai@gmail.com>"]
 license = "MIT"

{explainiverse-0.7.0 → explainiverse-0.7.1}/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.7.0"
+__version__ = "0.7.1"
 
 __all__ = [
     # Core

{explainiverse-0.7.0 → explainiverse-0.7.1}/src/explainiverse/adapters/pytorch_adapter.py

@@ -25,7 +25,7 @@ Example:
 """
 
 import numpy as np
-from typing import List, Optional, Union, Callable
+from typing import List, Optional, Union, Tuple
 
 from .base_adapter import BaseModelAdapter
 
@@ -57,6 +57,11 @@ class PyTorchAdapter(BaseModelAdapter):
     explainability methods. Handles device management, tensor/numpy
     conversions, and supports both classification and regression tasks.
     
+    Supports:
+        - Multi-class classification (output shape: [batch, n_classes])
+        - Binary classification (output shape: [batch, 1] or [batch])
+        - Regression (output shape: [batch, n_outputs] or [batch])
+    
     Attributes:
         model: The PyTorch model (nn.Module)
         task: "classification" or "regression"
@@ -150,11 +155,27 @@ class PyTorchAdapter(BaseModelAdapter):
     def _apply_activation(self, output: "torch.Tensor") -> "torch.Tensor":
         """Apply output activation function."""
         if self.output_activation == "softmax":
+            # Handle different output shapes
+            if output.dim() == 1 or (output.dim() == 2 and output.shape[1] == 1):
+                # Binary: apply sigmoid instead of softmax
+                return torch.sigmoid(output)
             return torch.softmax(output, dim=-1)
         elif self.output_activation == "sigmoid":
             return torch.sigmoid(output)
         return output
     
+    def _normalize_output_shape(self, output: "torch.Tensor") -> "torch.Tensor":
+        """
+        Normalize output to consistent 2D shape (batch, outputs).
+        
+        Handles:
+            - (batch,) -> (batch, 1)
+            - (batch, n) -> (batch, n)
+        """
+        if output.dim() == 1:
+            return output.unsqueeze(-1)
+        return output
+    
     def predict(self, data: np.ndarray) -> np.ndarray:
         """
         Generate predictions for input data.
@@ -183,16 +204,66 @@ class PyTorchAdapter(BaseModelAdapter):
                 tensor_batch = self._to_tensor(batch)
                 
                 output = self.model(tensor_batch)
+                output = self._normalize_output_shape(output)
                 output = self._apply_activation(output)
                 outputs.append(self._to_numpy(output))
         
         return np.vstack(outputs)
     
+    def _get_target_scores(
+        self,
+        output: "torch.Tensor",
+        target_class: Optional[Union[int, "torch.Tensor"]] = None
+    ) -> "torch.Tensor":
+        """
+        Extract target scores for gradient computation.
+        
+        Handles both multi-class and binary classification outputs.
+        
+        Args:
+            output: Raw model output (logits)
+            target_class: Target class index or tensor of indices
+            
+        Returns:
+            Target scores tensor for backpropagation
+        """
+        batch_size = output.shape[0]
+        
+        # Normalize to 2D
+        if output.dim() == 1:
+            output = output.unsqueeze(-1)
+        
+        n_outputs = output.shape[1]
+        
+        if self.task == "classification":
+            if n_outputs == 1:
+                # Binary classification with single logit
+                # Score is the logit itself (positive class score)
+                return output.squeeze(-1)
+            else:
+                # Multi-class classification
+                if target_class is None:
+                    target_class = output.argmax(dim=-1)
+                elif isinstance(target_class, int):
+                    target_class = torch.tensor(
+                        [target_class] * batch_size,
+                        device=self.device
+                    )
+                
+                # Gather scores for target class
+                return output.gather(1, target_class.view(-1, 1)).squeeze(-1)
+        else:
+            # Regression: use first output or sum of outputs
+            if n_outputs == 1:
+                return output.squeeze(-1)
+            else:
+                return output.sum(dim=-1)
+    
     def predict_with_gradients(
         self,
         data: np.ndarray,
         target_class: Optional[int] = None
-    ) -> tuple:
+    ) -> Tuple[np.ndarray, np.ndarray]:
         """
         Generate predictions and compute gradients w.r.t. inputs.
         
@@ -203,11 +274,17 @@ class PyTorchAdapter(BaseModelAdapter):
             data: Input data as numpy array.
             target_class: Class index for gradient computation.
                          If None, uses the predicted class.
+                         For binary classification with single output,
+                         this is ignored (gradient w.r.t. the single logit).
         
         Returns:
             Tuple of (predictions, gradients) as numpy arrays.
+            - predictions: (batch, n_classes) probabilities
+            - gradients: same shape as input data
         """
         data = np.array(data)
+        original_shape = data.shape
+        
         if data.ndim == 1:
             data = data.reshape(1, -1)
         
@@ -217,20 +294,13 @@ class PyTorchAdapter(BaseModelAdapter):
         
         # Forward pass
         output = self.model(tensor_data)
-        activated_output = self._apply_activation(output)
         
-        # Determine target for gradient
-        if self.task == "classification":
-            if target_class is None:
-                target_class = output.argmax(dim=-1)
-            elif isinstance(target_class, int):
-                target_class = torch.tensor([target_class] * data.shape[0], device=self.device)
-            
-            # Select target class scores for gradient
-            target_scores = output.gather(1, target_class.view(-1, 1)).squeeze()
-        else:
-            # Regression: gradient w.r.t. output
-            target_scores = output.squeeze()
+        # Get activated output for return
+        output_normalized = self._normalize_output_shape(output)
+        activated_output = self._apply_activation(output_normalized)
+        
+        # Get target scores for gradient computation
+        target_scores = self._get_target_scores(output, target_class)
         
         # Backward pass
         if target_scores.dim() == 0:
@@ -295,7 +365,7 @@ class PyTorchAdapter(BaseModelAdapter):
         data: np.ndarray,
         layer_name: str,
         target_class: Optional[int] = None
-    ) -> tuple:
+    ) -> Tuple[np.ndarray, np.ndarray]:
         """
         Get gradients of output w.r.t. a specific layer's activations.
         
@@ -339,15 +409,8 @@ class PyTorchAdapter(BaseModelAdapter):
             
             output = self.model(tensor_data)
             
-            if self.task == "classification":
-                if target_class is None:
-                    target_class = output.argmax(dim=-1)
-                elif isinstance(target_class, int):
-                    target_class = torch.tensor([target_class] * data.shape[0], device=self.device)
-                
-                target_scores = output.gather(1, target_class.view(-1, 1)).squeeze()
-            else:
-                target_scores = output.squeeze()
+            # Get target scores using the new method
+            target_scores = self._get_target_scores(output, target_class)
             
             if target_scores.dim() == 0:
                 target_scores.backward()

explainiverse-0.7.1/src/explainiverse/core/explanation.py

@@ -0,0 +1,179 @@
+# src/explainiverse/core/explanation.py
+"""
+Unified container for explanation results.
+
+The Explanation class provides a standardized format for all explainer outputs,
+enabling consistent handling across different explanation methods.
+"""
+
+from typing import Dict, List, Optional, Any
+
+
+class Explanation:
+    """
+    Unified container for explanation results.
+    
+    Attributes:
+        explainer_name: Name of the explainer that generated this explanation
+        target_class: The class/output being explained
+        explanation_data: Dictionary containing explanation details
+            (e.g., feature_attributions, heatmaps, rules)
+        feature_names: Optional list of feature names for index resolution
+        metadata: Optional additional metadata about the explanation
+    
+    Example:
+        >>> explanation = Explanation(
+        ...     explainer_name="LIME",
+        ...     target_class="cat",
+        ...     explanation_data={"feature_attributions": {"fur": 0.8, "whiskers": 0.6}},
+        ...     feature_names=["fur", "whiskers", "tail", "ears"]
+        ... )
+        >>> print(explanation.get_top_features(k=2))
+        [('fur', 0.8), ('whiskers', 0.6)]
+    """
+
+    def __init__(
+        self,
+        explainer_name: str,
+        target_class: str,
+        explanation_data: Dict[str, Any],
+        feature_names: Optional[List[str]] = None,
+        metadata: Optional[Dict[str, Any]] = None
+    ):
+        """
+        Initialize an Explanation object.
+        
+        Args:
+            explainer_name: Name of the explainer (e.g., "LIME", "SHAP")
+            target_class: The target class or output being explained
+            explanation_data: Dictionary containing the explanation details.
+                Common keys include:
+                - "feature_attributions": Dict[str, float] mapping feature names to importance
+                - "attributions_raw": List[float] of raw attribution values
+                - "heatmap": np.ndarray for image explanations
+                - "rules": List of rule strings for rule-based explanations
+            feature_names: Optional list of feature names. If provided, enables
+                index-based lookup in evaluation metrics.
+            metadata: Optional additional metadata (e.g., computation time, parameters)
+        """
+        self.explainer_name = explainer_name
+        self.target_class = target_class
+        self.explanation_data = explanation_data
+        self.feature_names = list(feature_names) if feature_names is not None else None
+        self.metadata = metadata or {}
+
+    def __repr__(self):
+        n_features = len(self.feature_names) if self.feature_names else "N/A"
+        return (
+            f"Explanation(explainer='{self.explainer_name}', "
+            f"target='{self.target_class}', "
+            f"keys={list(self.explanation_data.keys())}, "
+            f"n_features={n_features})"
+        )
+
+    def get_attributions(self) -> Optional[Dict[str, float]]:
+        """
+        Get feature attributions if available.
+        
+        Returns:
+            Dictionary mapping feature names to attribution values,
+            or None if not available.
+        """
+        return self.explanation_data.get("feature_attributions")
+    
+    def get_top_features(self, k: int = 5, absolute: bool = True) -> List[tuple]:
+        """
+        Get the top-k most important features.
+        
+        Args:
+            k: Number of top features to return
+            absolute: If True, rank by absolute value of attribution
+            
+        Returns:
+            List of (feature_name, attribution_value) tuples sorted by importance
+        """
+        attributions = self.get_attributions()
+        if not attributions:
+            return []
+        
+        if absolute:
+            sorted_items = sorted(
+                attributions.items(),
+                key=lambda x: abs(x[1]),
+                reverse=True
+            )
+        else:
+            sorted_items = sorted(
+                attributions.items(),
+                key=lambda x: x[1],
+                reverse=True
+            )
+        
+        return sorted_items[:k]
+    
+    def get_feature_index(self, feature_name: str) -> Optional[int]:
+        """
+        Get the index of a feature by name.
+        
+        Args:
+            feature_name: Name of the feature
+            
+        Returns:
+            Index of the feature, or None if not found or feature_names not set
+        """
+        if self.feature_names is None:
+            return None
+        try:
+            return self.feature_names.index(feature_name)
+        except ValueError:
+            return None
+
+    def plot(self, plot_type: str = 'bar', **kwargs):
+        """
+        Visualize the explanation.
+        
+        Args:
+            plot_type: Type of plot ('bar', 'waterfall', 'heatmap')
+            **kwargs: Additional arguments passed to the plotting function
+            
+        Note:
+            This is a placeholder for future visualization integration.
+        """
+        print(
+            f"[plot: {plot_type}] Plotting explanation for {self.target_class} "
+            f"from {self.explainer_name}."
+        )
+        
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert explanation to a dictionary for serialization.
+        
+        Returns:
+            Dictionary representation of the explanation
+        """
+        return {
+            "explainer_name": self.explainer_name,
+            "target_class": self.target_class,
+            "explanation_data": self.explanation_data,
+            "feature_names": self.feature_names,
+            "metadata": self.metadata
+        }
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Explanation":
+        """
+        Create an Explanation from a dictionary.
+        
+        Args:
+            data: Dictionary with explanation data
+            
+        Returns:
+            Explanation instance
+        """
+        return cls(
+            explainer_name=data["explainer_name"],
+            target_class=data["target_class"],
+            explanation_data=data["explanation_data"],
+            feature_names=data.get("feature_names"),
+            metadata=data.get("metadata", {})
+        )

explainiverse-0.7.1/src/explainiverse/engine/suite.py

@@ -0,0 +1,252 @@
+# src/explainiverse/engine/suite.py
+"""
+ExplanationSuite - Multi-explainer comparison and evaluation.
+
+Provides utilities for running multiple explainers on the same instances
+and comparing their outputs.
+"""
+
+from typing import Dict, List, Optional, Any, Tuple
+import numpy as np
+
+
+class ExplanationSuite:
+    """
+    Run and compare multiple explainers on the same instances.
+    
+    This class provides a unified interface for:
+    - Running multiple explainers on a single instance
+    - Comparing attribution scores side-by-side
+    - Suggesting the best explainer based on model/task characteristics
+    - Evaluating explainers using ROAR (Remove And Retrain)
+    
+    Example:
+        >>> from explainiverse import ExplanationSuite, SklearnAdapter
+        >>> suite = ExplanationSuite(
+        ...     model=adapter,
+        ...     explainer_configs=[
+        ...         ("lime", {"training_data": X_train, "feature_names": fnames, "class_names": cnames}),
+        ...         ("shap", {"background_data": X_train[:50], "feature_names": fnames, "class_names": cnames}),
+        ...     ]
+        ... )
+        >>> results = suite.run(X_test[0])
+        >>> suite.compare()
+    """
+
+    def __init__(
+        self,
+        model,
+        explainer_configs: List[Tuple[str, Dict[str, Any]]],
+        data_meta: Optional[Dict[str, Any]] = None
+    ):
+        """
+        Initialize the ExplanationSuite.
+        
+        Args:
+            model: A model adapter (e.g., SklearnAdapter, PyTorchAdapter)
+            explainer_configs: List of (explainer_name, kwargs) tuples.
+                The explainer_name should match a registered explainer in
+                the default_registry (e.g., "lime", "shap", "treeshap").
+            data_meta: Optional metadata about the task, scope, or preference.
+                Can include "task" ("classification" or "regression").
+        """
+        self.model = model
+        self.configs = explainer_configs
+        self.data_meta = data_meta or {}
+        self.explanations: Dict[str, Any] = {}
+        self._registry = None
+
+    def _get_registry(self):
+        """Lazy load the registry to avoid circular imports."""
+        if self._registry is None:
+            from explainiverse.core.registry import default_registry
+            self._registry = default_registry
+        return self._registry
+
+    def run(self, instance: np.ndarray) -> Dict[str, Any]:
+        """
+        Run all configured explainers on a single instance.
+        
+        Args:
+            instance: Input instance to explain (1D numpy array)
+            
+        Returns:
+            Dictionary mapping explainer names to Explanation objects
+        """
+        instance = np.asarray(instance)
+        registry = self._get_registry()
+        
+        for name, params in self.configs:
+            try:
+                explainer = registry.create(name, model=self.model, **params)
+                explanation = explainer.explain(instance)
+                self.explanations[name] = explanation
+            except Exception as e:
+                print(f"[ExplanationSuite] Warning: Failed to run {name}: {e}")
+                continue
+        
+        return self.explanations
+
+    def compare(self) -> None:
+        """
+        Print attribution scores side-by-side for comparison.
+        """
+        if not self.explanations:
+            print("No explanations to compare. Run suite.run(instance) first.")
+            return
+        
+        # Collect all feature names across explanations
+        all_keys = set()
+        for explanation in self.explanations.values():
+            attrs = explanation.explanation_data.get("feature_attributions", {})
+            all_keys.update(attrs.keys())
+
+        print("\nSide-by-Side Comparison:")
+        print("-" * 60)
+        
+        # Header
+        header = ["Feature"] + list(self.explanations.keys())
+        print(" | ".join(f"{h:>15}" for h in header))
+        print("-" * 60)
+        
+        # Rows
+        for key in sorted(all_keys):
+            row = [f"{key:>15}"]
+            for name in self.explanations:
+                value = self.explanations[name].explanation_data.get(
+                    "feature_attributions", {}
+                ).get(key, None)
+                if value is not None:
+                    row.append(f"{value:>15.4f}")
+                else:
+                    row.append(f"{'—':>15}")
+            print(" | ".join(row))
+
+    def suggest_best(self) -> str:
+        """
+        Suggest the best explainer based on model type and task characteristics.
+        
+        Returns:
+            Name of the suggested explainer
+        """
+        task = self.data_meta.get("task", "unknown")
+        model = self.model.model if hasattr(self.model, 'model') else self.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:
+                # Check output dimensions
+                if hasattr(model, 'n_features_in_'):
+                    test_input = np.zeros((1, model.n_features_in_))
+                    output = self.model.predict(test_input)
+                    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 TreeSHAP
+        model_type_str = str(type(model)).lower()
+        if any(tree_type in model_type_str for tree_type in ['tree', 'forest', 'xgb', 'lgbm', 'catboost']):
+            return "treeshap"
+
+        # 4. Neural networks → prefer gradient methods
+        if 'torch' in model_type_str or 'keras' in model_type_str or 'tensorflow' in model_type_str:
+            return "integrated_gradients"
+
+        # 5. Default fallback
+        return "lime"
+
+    def evaluate_roar(
+        self,
+        X_train: np.ndarray,
+        y_train: np.ndarray,
+        X_test: np.ndarray,
+        y_test: np.ndarray,
+        top_k: int = 2,
+        model_class=None,
+        model_kwargs: Optional[Dict] = None
+    ) -> Dict[str, float]:
+        """
+        Evaluate each explainer using ROAR (Remove And Retrain).
+        
+        ROAR measures explanation quality by retraining the model after
+        removing the top-k important features identified by each explainer.
+        A larger accuracy drop indicates more faithful explanations.
+        
+        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()
+                        If None, uses the same type as self.model.model
+            model_kwargs: Optional keyword args for new model instance
+
+        Returns:
+            Dict mapping explainer names to accuracy drops
+        """
+        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:
+            raw_model = self.model.model if hasattr(self.model, 'model') else self.model
+            model_class = type(raw_model)
+
+        roar_scores = {}
+
+        for name, explanation in self.explanations.items():
+            print(f"[ROAR] Evaluating explainer: {name}")
+            try:
+                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],
+                    top_k=top_k,
+                    model_kwargs=model_kwargs
+                )
+                roar_scores[name] = roar
+            except Exception as e:
+                print(f"[ROAR] Failed for {name}: {e}")
+                roar_scores[name] = 0.0
+
+        return roar_scores
+    
+    def get_explanation(self, name: str):
+        """
+        Get a specific explanation by explainer name.
+        
+        Args:
+            name: Name of the explainer
+            
+        Returns:
+            Explanation object or None if not found
+        """
+        return self.explanations.get(name)
+    
+    def list_explainers(self) -> List[str]:
+        """
+        List all configured explainer names.
+        
+        Returns:
+            List of explainer names
+        """
+        return [name for name, _ in self.configs]
+    
+    def list_completed(self) -> List[str]:
+        """
+        List explainers that have been run successfully.
+        
+        Returns:
+            List of explainer names with results
+        """
+        return list(self.explanations.keys())