explainiverse 0.5.0__tar.gz → 0.6.0__tar.gz

{explainiverse-0.5.0 → explainiverse-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: explainiverse
-Version: 0.5.0
+Version: 0.6.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
@@ -35,7 +35,7 @@ Description-Content-Type: text/markdown
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**Explainiverse** is a unified, extensible Python framework for Explainable AI (XAI). It provides a standardized interface for **15 state-of-the-art explanation methods** across local, global, gradient-based, and example-based paradigms, along with **comprehensive evaluation metrics** for assessing explanation quality.
+**Explainiverse** is a unified, extensible Python framework for Explainable AI (XAI). It provides a standardized interface for **16 state-of-the-art explanation methods** across local, global, gradient-based, and example-based paradigms, along with **comprehensive evaluation metrics** for assessing explanation quality.
 
 ---
 
@@ -43,7 +43,7 @@ Description-Content-Type: text/markdown
 
 | Feature | Description |
 |---------|-------------|
-| **15 Explainers** | LIME, KernelSHAP, TreeSHAP, Integrated Gradients, DeepLIFT, DeepSHAP, SmoothGrad, GradCAM/GradCAM++, Anchors, Counterfactual, Permutation Importance, PDP, ALE, SAGE, ProtoDash |
+| **16 Explainers** | LIME, KernelSHAP, TreeSHAP, Integrated Gradients, DeepLIFT, DeepSHAP, SmoothGrad, Saliency Maps, GradCAM/GradCAM++, Anchors, Counterfactual, Permutation Importance, PDP, ALE, SAGE, ProtoDash |
 | **8 Evaluation Metrics** | Faithfulness (PGI, PGU, Comprehensiveness, Sufficiency, Correlation) and Stability (RIS, ROS, Lipschitz) |
 | **Unified API** | Consistent `BaseExplainer` interface with standardized `Explanation` output |
 | **Plugin Registry** | Filter explainers by scope, model type, data type; automatic recommendations |
@@ -64,6 +64,7 @@ Description-Content-Type: text/markdown
 | **DeepLIFT** | Gradient | [Shrikumar et al., 2017](https://arxiv.org/abs/1704.02685) |
 | **DeepSHAP** | Gradient + Shapley | [Lundberg & Lee, 2017](https://arxiv.org/abs/1705.07874) |
 | **SmoothGrad** | Gradient | [Smilkov et al., 2017](https://arxiv.org/abs/1706.03825) |
+| **Saliency Maps** | Gradient | [Simonyan et al., 2014](https://arxiv.org/abs/1312.6034) |
 | **GradCAM / GradCAM++** | Gradient (CNN) | [Selvaraju et al., 2017](https://arxiv.org/abs/1610.02391) |
 | **Anchors** | Rule-Based | [Ribeiro et al., 2018](https://ojs.aaai.org/index.php/AAAI/article/view/11491) |
 | **Counterfactual** | Contrastive | [Mothilal et al., 2020](https://arxiv.org/abs/1905.07697) |
@@ -233,6 +234,41 @@ deepshap = DeepLIFTShapExplainer(
 explanation = deepshap.explain(X[0])
 ```
 
+### Saliency Maps
+
+```python
+from explainiverse.explainers.gradient import SaliencyExplainer
+
+# Saliency Maps - simplest and fastest gradient method
+explainer = SaliencyExplainer(
+    model=adapter,
+    feature_names=feature_names,
+    class_names=class_names,
+    absolute_value=True  # Default: absolute gradient magnitudes
+)
+
+# Standard saliency (absolute gradients)
+explanation = explainer.explain(X[0], method="saliency")
+
+# Input × Gradient (gradient scaled by input values)
+explanation = explainer.explain(X[0], method="input_times_gradient")
+
+# Signed saliency (keep gradient direction)
+explainer_signed = SaliencyExplainer(
+    model=adapter,
+    feature_names=feature_names,
+    class_names=class_names,
+    absolute_value=False
+)
+explanation = explainer_signed.explain(X[0])
+
+# Compare all variants
+variants = explainer.compute_all_variants(X[0])
+print(variants["saliency_absolute"])
+print(variants["saliency_signed"])
+print(variants["input_times_gradient"])
+```
+
 ### SmoothGrad
 
 ```python
@@ -552,7 +588,7 @@ poetry run pytest tests/test_smoothgrad.py::TestSmoothGradBasic -v
 ### Completed ✅
 - [x] Core framework (BaseExplainer, Explanation, Registry)
 - [x] Perturbation methods: LIME, KernelSHAP, TreeSHAP
-- [x] Gradient methods: Integrated Gradients, DeepLIFT, DeepSHAP, SmoothGrad, GradCAM/GradCAM++
+- [x] Gradient methods: Integrated Gradients, DeepLIFT, DeepSHAP, SmoothGrad, Saliency Maps, GradCAM/GradCAM++
 - [x] Rule-based: Anchors
 - [x] Counterfactual: DiCE-style
 - [x] Global: Permutation Importance, PDP, ALE, SAGE
@@ -562,7 +598,6 @@ poetry run pytest tests/test_smoothgrad.py::TestSmoothGradBasic -v
 - [x] PyTorch adapter with gradient support
 
 ### In Progress 🚧
-- [ ] Saliency Maps (vanilla gradients)
 - [ ] TCAV (Testing with Concept Activation Vectors)
 - [ ] Layer-wise Relevance Propagation (LRP)
 
@@ -585,7 +620,7 @@ If you use Explainiverse in your research, please cite:
   author = {Syed, Muntaser},
   year = {2025},
   url = {https://github.com/jemsbhai/explainiverse},
-  version = {0.5.0}
+  version = {0.6.0}
 }
 ```
 

{explainiverse-0.5.0 → explainiverse-0.6.0}/README.md

@@ -4,7 +4,7 @@
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**Explainiverse** is a unified, extensible Python framework for Explainable AI (XAI). It provides a standardized interface for **15 state-of-the-art explanation methods** across local, global, gradient-based, and example-based paradigms, along with **comprehensive evaluation metrics** for assessing explanation quality.
+**Explainiverse** is a unified, extensible Python framework for Explainable AI (XAI). It provides a standardized interface for **16 state-of-the-art explanation methods** across local, global, gradient-based, and example-based paradigms, along with **comprehensive evaluation metrics** for assessing explanation quality.
 
 ---
 
@@ -12,7 +12,7 @@
 
 | Feature | Description |
 |---------|-------------|
-| **15 Explainers** | LIME, KernelSHAP, TreeSHAP, Integrated Gradients, DeepLIFT, DeepSHAP, SmoothGrad, GradCAM/GradCAM++, Anchors, Counterfactual, Permutation Importance, PDP, ALE, SAGE, ProtoDash |
+| **16 Explainers** | LIME, KernelSHAP, TreeSHAP, Integrated Gradients, DeepLIFT, DeepSHAP, SmoothGrad, Saliency Maps, GradCAM/GradCAM++, Anchors, Counterfactual, Permutation Importance, PDP, ALE, SAGE, ProtoDash |
 | **8 Evaluation Metrics** | Faithfulness (PGI, PGU, Comprehensiveness, Sufficiency, Correlation) and Stability (RIS, ROS, Lipschitz) |
 | **Unified API** | Consistent `BaseExplainer` interface with standardized `Explanation` output |
 | **Plugin Registry** | Filter explainers by scope, model type, data type; automatic recommendations |
@@ -33,6 +33,7 @@
 | **DeepLIFT** | Gradient | [Shrikumar et al., 2017](https://arxiv.org/abs/1704.02685) |
 | **DeepSHAP** | Gradient + Shapley | [Lundberg & Lee, 2017](https://arxiv.org/abs/1705.07874) |
 | **SmoothGrad** | Gradient | [Smilkov et al., 2017](https://arxiv.org/abs/1706.03825) |
+| **Saliency Maps** | Gradient | [Simonyan et al., 2014](https://arxiv.org/abs/1312.6034) |
 | **GradCAM / GradCAM++** | Gradient (CNN) | [Selvaraju et al., 2017](https://arxiv.org/abs/1610.02391) |
 | **Anchors** | Rule-Based | [Ribeiro et al., 2018](https://ojs.aaai.org/index.php/AAAI/article/view/11491) |
 | **Counterfactual** | Contrastive | [Mothilal et al., 2020](https://arxiv.org/abs/1905.07697) |
@@ -202,6 +203,41 @@ deepshap = DeepLIFTShapExplainer(
 explanation = deepshap.explain(X[0])
 ```
 
+### Saliency Maps
+
+```python
+from explainiverse.explainers.gradient import SaliencyExplainer
+
+# Saliency Maps - simplest and fastest gradient method
+explainer = SaliencyExplainer(
+    model=adapter,
+    feature_names=feature_names,
+    class_names=class_names,
+    absolute_value=True  # Default: absolute gradient magnitudes
+)
+
+# Standard saliency (absolute gradients)
+explanation = explainer.explain(X[0], method="saliency")
+
+# Input × Gradient (gradient scaled by input values)
+explanation = explainer.explain(X[0], method="input_times_gradient")
+
+# Signed saliency (keep gradient direction)
+explainer_signed = SaliencyExplainer(
+    model=adapter,
+    feature_names=feature_names,
+    class_names=class_names,
+    absolute_value=False
+)
+explanation = explainer_signed.explain(X[0])
+
+# Compare all variants
+variants = explainer.compute_all_variants(X[0])
+print(variants["saliency_absolute"])
+print(variants["saliency_signed"])
+print(variants["input_times_gradient"])
+```
+
 ### SmoothGrad
 
 ```python
@@ -521,7 +557,7 @@ poetry run pytest tests/test_smoothgrad.py::TestSmoothGradBasic -v
 ### Completed ✅
 - [x] Core framework (BaseExplainer, Explanation, Registry)
 - [x] Perturbation methods: LIME, KernelSHAP, TreeSHAP
-- [x] Gradient methods: Integrated Gradients, DeepLIFT, DeepSHAP, SmoothGrad, GradCAM/GradCAM++
+- [x] Gradient methods: Integrated Gradients, DeepLIFT, DeepSHAP, SmoothGrad, Saliency Maps, GradCAM/GradCAM++
 - [x] Rule-based: Anchors
 - [x] Counterfactual: DiCE-style
 - [x] Global: Permutation Importance, PDP, ALE, SAGE
@@ -531,7 +567,6 @@ poetry run pytest tests/test_smoothgrad.py::TestSmoothGradBasic -v
 - [x] PyTorch adapter with gradient support
 
 ### In Progress 🚧
-- [ ] Saliency Maps (vanilla gradients)
 - [ ] TCAV (Testing with Concept Activation Vectors)
 - [ ] Layer-wise Relevance Propagation (LRP)
 
@@ -554,7 +589,7 @@ If you use Explainiverse in your research, please cite:
   author = {Syed, Muntaser},
   year = {2025},
   url = {https://github.com/jemsbhai/explainiverse},
-  version = {0.5.0}
+  version = {0.6.0}
 }
 ```
 

{explainiverse-0.5.0 → explainiverse-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "explainiverse"
-version = "0.5.0"
+version = "0.6.0"
 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.5.0 → explainiverse-0.6.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.5.0"
+__version__ = "0.6.0"
 
 __all__ = [
     # Core

{explainiverse-0.5.0 → explainiverse-0.6.0}/src/explainiverse/core/registry.py

@@ -373,6 +373,7 @@ def _create_default_registry() -> ExplainerRegistry:
     from explainiverse.explainers.gradient.gradcam import GradCAMExplainer
     from explainiverse.explainers.gradient.deeplift import DeepLIFTExplainer, DeepLIFTShapExplainer
     from explainiverse.explainers.gradient.smoothgrad import SmoothGradExplainer
+    from explainiverse.explainers.gradient.saliency import SaliencyExplainer
     from explainiverse.explainers.example_based.protodash import ProtoDashExplainer
     
     registry = ExplainerRegistry()
@@ -551,6 +552,23 @@ def _create_default_registry() -> ExplainerRegistry:
         )
     )
     
+    # Register Saliency Maps (for neural networks)
+    registry.register(
+        name="saliency",
+        explainer_class=SaliencyExplainer,
+        meta=ExplainerMeta(
+            scope="local",
+            model_types=["neural"],
+            data_types=["tabular", "image"],
+            task_types=["classification", "regression"],
+            description="Saliency Maps - gradient-based feature attribution (requires PyTorch)",
+            paper_reference="Simonyan et al., 2014 - 'Deep Inside Convolutional Networks' (ICLR Workshop)",
+            complexity="O(forward_pass + backward_pass)",
+            requires_training_data=False,
+            supports_batching=True
+        )
+    )
+    
     # =========================================================================
     # Global Explainers (model-level)
     # =========================================================================

{explainiverse-0.5.0 → explainiverse-0.6.0}/src/explainiverse/explainers/gradient/__init__.py

@@ -10,6 +10,7 @@ from explainiverse.explainers.gradient.integrated_gradients import IntegratedGra
 from explainiverse.explainers.gradient.gradcam import GradCAMExplainer
 from explainiverse.explainers.gradient.deeplift import DeepLIFTExplainer, DeepLIFTShapExplainer
 from explainiverse.explainers.gradient.smoothgrad import SmoothGradExplainer
+from explainiverse.explainers.gradient.saliency import SaliencyExplainer
 
 __all__ = [
     "IntegratedGradientsExplainer", 
@@ -17,4 +18,5 @@ __all__ = [
     "DeepLIFTExplainer",
     "DeepLIFTShapExplainer",
     "SmoothGradExplainer",
+    "SaliencyExplainer",
 ]

explainiverse-0.6.0/src/explainiverse/explainers/gradient/saliency.py

@@ -0,0 +1,293 @@
+# src/explainiverse/explainers/gradient/saliency.py
+"""
+Saliency Maps - Gradient-Based Feature Attribution.
+
+Saliency Maps compute feature attributions using the gradient of the output
+with respect to the input. This is one of the simplest and fastest gradient-based
+attribution methods, requiring only a single forward and backward pass.
+
+Key Properties:
+- Simple: Just compute the gradient of output w.r.t. input
+- Fast: Single forward + backward pass
+- Foundation: Base method that other gradient methods build upon
+- Variants: Absolute saliency, signed saliency, input × gradient
+
+Variants:
+- Saliency (absolute): |∂f(x)/∂x| - magnitude of sensitivity
+- Saliency (signed): ∂f(x)/∂x - direction and magnitude
+- Input × Gradient: x ⊙ ∂f(x)/∂x - scaled by input values
+
+Reference:
+    Simonyan, K., Vedaldi, A., & Zisserman, A. (2014).
+    Deep Inside Convolutional Networks: Visualising Image Classification
+    Models and Saliency Maps.
+    ICLR Workshop 2014.
+    https://arxiv.org/abs/1312.6034
+
+Example:
+    from explainiverse.explainers.gradient import SaliencyExplainer
+    from explainiverse.adapters import PyTorchAdapter
+    
+    adapter = PyTorchAdapter(model, task="classification")
+    
+    explainer = SaliencyExplainer(
+        model=adapter,
+        feature_names=feature_names
+    )
+    
+    explanation = explainer.explain(instance)
+"""
+
+import numpy as np
+from typing import List, Optional
+
+from explainiverse.core.explainer import BaseExplainer
+from explainiverse.core.explanation import Explanation
+
+
+class SaliencyExplainer(BaseExplainer):
+    """
+    Saliency Maps explainer for neural networks.
+    
+    Computes attributions using the gradient of the model output with respect
+    to the input features. This is the simplest gradient-based attribution
+    method and serves as the foundation for more sophisticated techniques.
+    
+    Algorithm:
+        Saliency(x) = ∂f(x)/∂x  (signed)
+        Saliency(x) = |∂f(x)/∂x|  (absolute, default)
+        InputTimesGradient(x) = x ⊙ ∂f(x)/∂x
+    
+    Attributes:
+        model: Model adapter with predict_with_gradients() method
+        feature_names: List of feature names
+        class_names: List of class names (for classification)
+        absolute_value: Whether to take absolute value of gradients
+    
+    Example:
+        >>> explainer = SaliencyExplainer(adapter, feature_names)
+        >>> explanation = explainer.explain(instance)
+        >>> print(explanation.explanation_data["feature_attributions"])
+    """
+    
+    def __init__(
+        self,
+        model,
+        feature_names: List[str],
+        class_names: Optional[List[str]] = None,
+        absolute_value: bool = True
+    ):
+        """
+        Initialize the Saliency explainer.
+        
+        Args:
+            model: A model adapter with predict_with_gradients() method.
+                   Use PyTorchAdapter for PyTorch models.
+            feature_names: List of input feature names.
+            class_names: List of class names (for classification tasks).
+            absolute_value: If True (default), return absolute value of
+                          gradients. Set to False for signed saliency.
+        
+        Raises:
+            TypeError: If model doesn't have predict_with_gradients method.
+        """
+        super().__init__(model)
+        
+        # Validate model has gradient capability
+        if not hasattr(model, 'predict_with_gradients'):
+            raise TypeError(
+                "Model adapter must have predict_with_gradients() method. "
+                "Use PyTorchAdapter for PyTorch models."
+            )
+        
+        self.feature_names = list(feature_names)
+        self.class_names = list(class_names) if class_names else None
+        self.absolute_value = absolute_value
+    
+    def _compute_saliency(
+        self,
+        instance: np.ndarray,
+        target_class: Optional[int] = None,
+        method: str = "saliency"
+    ) -> np.ndarray:
+        """
+        Compute saliency attributions for a single instance.
+        
+        Args:
+            instance: Input instance (1D array).
+            target_class: Target class for gradient computation.
+            method: Attribution method:
+                - "saliency": Raw gradient (default)
+                - "input_times_gradient": Gradient multiplied by input
+            
+        Returns:
+            Array of attribution scores for each input feature.
+        """
+        instance = instance.flatten().astype(np.float32)
+        
+        # Compute gradient
+        _, gradients = self.model.predict_with_gradients(
+            instance.reshape(1, -1),
+            target_class=target_class
+        )
+        gradients = gradients.flatten()
+        
+        # Apply method
+        if method == "saliency":
+            attributions = gradients
+        elif method == "input_times_gradient":
+            attributions = instance * gradients
+        else:
+            raise ValueError(
+                f"Unknown method: '{method}'. "
+                f"Use 'saliency' or 'input_times_gradient'."
+            )
+        
+        # Apply absolute value if configured
+        if self.absolute_value and method == "saliency":
+            attributions = np.abs(attributions)
+        
+        return attributions
+    
+    def explain(
+        self,
+        instance: np.ndarray,
+        target_class: Optional[int] = None,
+        method: str = "saliency"
+    ) -> Explanation:
+        """
+        Generate Saliency explanation for an instance.
+        
+        Args:
+            instance: 1D numpy array of input features.
+            target_class: For classification, which class to explain.
+                         If None, uses the predicted class.
+            method: Attribution method:
+                - "saliency": Gradient-based saliency (default)
+                - "input_times_gradient": Gradient × input
+        
+        Returns:
+            Explanation object with feature attributions.
+        
+        Example:
+            >>> explanation = explainer.explain(instance)
+            >>> print(explanation.explanation_data["feature_attributions"])
+        """
+        instance = np.array(instance).flatten().astype(np.float32)
+        
+        # Determine target class if not specified
+        if target_class is None and self.class_names:
+            predictions = self.model.predict(instance.reshape(1, -1))
+            target_class = int(np.argmax(predictions))
+        
+        # Compute saliency
+        attributions = self._compute_saliency(instance, target_class, method)
+        
+        # Build attributions dict
+        attributions_dict = {
+            fname: float(attributions[i])
+            for i, fname in enumerate(self.feature_names)
+        }
+        
+        # Determine explainer name based on method
+        if method == "saliency":
+            explainer_name = "Saliency"
+        elif method == "input_times_gradient":
+            explainer_name = "InputTimesGradient"
+        else:
+            explainer_name = f"Saliency_{method}"
+        
+        # Determine class name
+        if self.class_names and target_class is not None:
+            label_name = self.class_names[target_class]
+        else:
+            label_name = f"class_{target_class}" if target_class is not None else "output"
+        
+        explanation_data = {
+            "feature_attributions": attributions_dict,
+            "attributions_raw": attributions.tolist(),
+            "method": method,
+            "absolute_value": self.absolute_value if method == "saliency" else False
+        }
+        
+        return Explanation(
+            explainer_name=explainer_name,
+            target_class=label_name,
+            explanation_data=explanation_data
+        )
+    
+    def explain_batch(
+        self,
+        X: np.ndarray,
+        target_class: Optional[int] = None,
+        method: str = "saliency"
+    ) -> List[Explanation]:
+        """
+        Generate explanations for multiple instances.
+        
+        Args:
+            X: 2D numpy array of instances (n_samples, n_features),
+               or 1D array for single instance.
+            target_class: Target class for all instances. If None,
+                         uses predicted class for each instance.
+            method: Attribution method (see explain()).
+        
+        Returns:
+            List of Explanation objects.
+        
+        Example:
+            >>> explanations = explainer.explain_batch(X_test[:10])
+            >>> for exp in explanations:
+            ...     print(exp.target_class)
+        """
+        X = np.array(X)
+        if X.ndim == 1:
+            X = X.reshape(1, -1)
+        
+        return [
+            self.explain(X[i], target_class=target_class, method=method)
+            for i in range(X.shape[0])
+        ]
+    
+    def compute_all_variants(
+        self,
+        instance: np.ndarray,
+        target_class: Optional[int] = None
+    ) -> dict:
+        """
+        Compute all saliency variants for comparison.
+        
+        Useful for analyzing which variant provides the best explanation
+        for a given instance or model architecture.
+        
+        Args:
+            instance: Input instance.
+            target_class: Target class for gradient computation.
+        
+        Returns:
+            Dictionary containing:
+                - saliency_absolute: |∂f/∂x|
+                - saliency_signed: ∂f/∂x
+                - input_times_gradient: x ⊙ ∂f/∂x
+        """
+        instance = np.array(instance).flatten().astype(np.float32)
+        
+        # Determine target class
+        if target_class is None and self.class_names:
+            predictions = self.model.predict(instance.reshape(1, -1))
+            target_class = int(np.argmax(predictions))
+        
+        # Compute gradient (only once)
+        _, gradients = self.model.predict_with_gradients(
+            instance.reshape(1, -1),
+            target_class=target_class
+        )
+        gradients = gradients.flatten()
+        
+        return {
+            "saliency_absolute": np.abs(gradients).tolist(),
+            "saliency_signed": gradients.tolist(),
+            "input_times_gradient": (instance * gradients).tolist(),
+            "feature_names": self.feature_names,
+            "target_class": target_class
+        }