explainiverse 0.2.2__py3-none-any.whl → 0.2.4__py3-none-any.whl

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.2"
+__version__ = "0.2.4"
 
 __all__ = [
     # Core

explainiverse/core/registry.py

@@ -369,6 +369,8 @@ def _create_default_registry() -> ExplainerRegistry:
     from explainiverse.explainers.global_explainers.ale import ALEExplainer
     from explainiverse.explainers.global_explainers.sage import SAGEExplainer
     from explainiverse.explainers.counterfactual.dice_wrapper import CounterfactualExplainer
+    from explainiverse.explainers.gradient.integrated_gradients import IntegratedGradientsExplainer
+    from explainiverse.explainers.gradient.gradcam import GradCAMExplainer
     
     registry = ExplainerRegistry()
     
@@ -461,6 +463,40 @@ def _create_default_registry() -> ExplainerRegistry:
         )
     )
     
+    # Register Integrated Gradients (for neural networks)
+    registry.register(
+        name="integrated_gradients",
+        explainer_class=IntegratedGradientsExplainer,
+        meta=ExplainerMeta(
+            scope="local",
+            model_types=["neural"],
+            data_types=["tabular", "image"],
+            task_types=["classification", "regression"],
+            description="Integrated Gradients - axiomatic attributions for neural networks (requires PyTorch)",
+            paper_reference="Sundararajan et al., 2017 - 'Axiomatic Attribution for Deep Networks' (ICML)",
+            complexity="O(n_steps * forward_pass)",
+            requires_training_data=False,
+            supports_batching=True
+        )
+    )
+    
+    # Register GradCAM (for CNNs)
+    registry.register(
+        name="gradcam",
+        explainer_class=GradCAMExplainer,
+        meta=ExplainerMeta(
+            scope="local",
+            model_types=["neural"],
+            data_types=["image"],
+            task_types=["classification"],
+            description="GradCAM/GradCAM++ - visual explanations for CNNs via gradient-weighted activations (requires PyTorch)",
+            paper_reference="Selvaraju et al., 2017 - 'Grad-CAM: Visual Explanations from Deep Networks' (ICCV)",
+            complexity="O(forward_pass + backward_pass)",
+            requires_training_data=False,
+            supports_batching=True
+        )
+    )
+    
     # =========================================================================
     # Global Explainers (model-level)
     # =========================================================================

explainiverse/explainers/__init__.py

@@ -8,6 +8,7 @@ Local Explainers (instance-level):
 - TreeSHAP: Optimized exact SHAP for tree-based models
 - Anchors: High-precision rule-based explanations
 - Counterfactual: Diverse counterfactual explanations
+- Integrated Gradients: Gradient-based attributions for neural networks
 
 Global Explainers (model-level):
 - Permutation Importance: Feature importance via permutation
@@ -25,6 +26,8 @@ from explainiverse.explainers.global_explainers.permutation_importance import Pe
 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
+from explainiverse.explainers.gradient.integrated_gradients import IntegratedGradientsExplainer
+from explainiverse.explainers.gradient.gradcam import GradCAMExplainer
 
 __all__ = [
     # Local explainers
@@ -33,6 +36,8 @@ __all__ = [
     "TreeShapExplainer",
     "AnchorsExplainer",
     "CounterfactualExplainer",
+    "IntegratedGradientsExplainer",
+    "GradCAMExplainer",
     # Global explainers
     "PermutationImportanceExplainer",
     "PartialDependenceExplainer",

explainiverse/explainers/gradient/__init__.py

@@ -0,0 +1,12 @@
+# src/explainiverse/explainers/gradient/__init__.py
+"""
+Gradient-based explainers for neural networks.
+
+These explainers require models that support gradient computation,
+typically via the PyTorchAdapter.
+"""
+
+from explainiverse.explainers.gradient.integrated_gradients import IntegratedGradientsExplainer
+from explainiverse.explainers.gradient.gradcam import GradCAMExplainer
+
+__all__ = ["IntegratedGradientsExplainer", "GradCAMExplainer"]

explainiverse/explainers/gradient/gradcam.py

@@ -0,0 +1,390 @@
+# src/explainiverse/explainers/gradient/gradcam.py
+"""
+GradCAM and GradCAM++ - Visual Explanations for CNNs.
+
+GradCAM produces visual explanations by highlighting important regions
+in an image that contribute to the model's prediction. It uses gradients
+flowing into the final convolutional layer to produce a coarse localization map.
+
+GradCAM++ improves upon GradCAM by using a weighted combination of positive
+partial derivatives, providing better localization for multiple instances
+of the same class.
+
+References:
+    GradCAM: Selvaraju et al., 2017 - "Grad-CAM: Visual Explanations from
+    Deep Networks via Gradient-based Localization"
+    https://arxiv.org/abs/1610.02391
+    
+    GradCAM++: Chattopadhay et al., 2018 - "Grad-CAM++: Generalized Gradient-based
+    Visual Explanations for Deep Convolutional Networks"
+    https://arxiv.org/abs/1710.11063
+
+Example:
+    from explainiverse.explainers.gradient import GradCAMExplainer
+    from explainiverse.adapters import PyTorchAdapter
+    
+    # For a CNN model
+    adapter = PyTorchAdapter(cnn_model, task="classification")
+    
+    explainer = GradCAMExplainer(
+        model=adapter,
+        target_layer="layer4",  # Last conv layer
+        class_names=class_names
+    )
+    
+    explanation = explainer.explain(image)
+    heatmap = explanation.explanation_data["heatmap"]
+"""
+
+import numpy as np
+from typing import List, Optional, Tuple, Union
+
+from explainiverse.core.explainer import BaseExplainer
+from explainiverse.core.explanation import Explanation
+
+
+class GradCAMExplainer(BaseExplainer):
+    """
+    GradCAM and GradCAM++ explainer for CNNs.
+    
+    Produces visual heatmaps showing which regions of an input image
+    are most important for the model's prediction.
+    
+    Attributes:
+        model: PyTorchAdapter wrapping a CNN model
+        target_layer: Name of the convolutional layer to use
+        class_names: List of class names
+        method: "gradcam" or "gradcam++"
+    """
+    
+    def __init__(
+        self,
+        model,
+        target_layer: str,
+        class_names: Optional[List[str]] = None,
+        method: str = "gradcam"
+    ):
+        """
+        Initialize the GradCAM explainer.
+        
+        Args:
+            model: A PyTorchAdapter wrapping a CNN model.
+            target_layer: Name of the target convolutional layer.
+                         Usually the last conv layer before the classifier.
+                         Use adapter.list_layers() to see available layers.
+            class_names: List of class names for classification.
+            method: "gradcam" for standard GradCAM, "gradcam++" for improved version.
+        """
+        super().__init__(model)
+        
+        # Validate model has layer access
+        if not hasattr(model, 'get_layer_gradients'):
+            raise TypeError(
+                "Model adapter must have get_layer_gradients() method. "
+                "Use PyTorchAdapter for PyTorch models."
+            )
+        
+        self.target_layer = target_layer
+        self.class_names = list(class_names) if class_names else None
+        self.method = method.lower()
+        
+        if self.method not in ["gradcam", "gradcam++"]:
+            raise ValueError(f"Method must be 'gradcam' or 'gradcam++', got '{method}'")
+    
+    def _compute_gradcam(
+        self,
+        activations: np.ndarray,
+        gradients: np.ndarray
+    ) -> np.ndarray:
+        """
+        Compute standard GradCAM heatmap.
+        
+        GradCAM = ReLU(sum_k(alpha_k * A^k))
+        where alpha_k = global_avg_pool(gradients for channel k)
+        """
+        # Global average pooling of gradients to get weights
+        # activations shape: (batch, channels, height, width)
+        # gradients shape: (batch, channels, height, width)
+        
+        # For each channel, compute the average gradient (importance weight)
+        weights = np.mean(gradients, axis=(2, 3), keepdims=True)  # (batch, channels, 1, 1)
+        
+        # Weighted combination of activation maps
+        cam = np.sum(weights * activations, axis=1)  # (batch, height, width)
+        
+        # Apply ReLU (we only care about positive influence)
+        cam = np.maximum(cam, 0)
+        
+        return cam
+    
+    def _compute_gradcam_plusplus(
+        self,
+        activations: np.ndarray,
+        gradients: np.ndarray
+    ) -> np.ndarray:
+        """
+        Compute GradCAM++ heatmap.
+        
+        GradCAM++ uses higher-order derivatives to weight the gradients,
+        providing better localization especially for multiple instances.
+        """
+        # First derivative
+        grad_2 = gradients ** 2
+        grad_3 = gradients ** 3
+        
+        # Sum over spatial dimensions for denominator
+        sum_activations = np.sum(activations, axis=(2, 3), keepdims=True)
+        
+        # Avoid division by zero
+        eps = 1e-8
+        
+        # Alpha coefficients (pixel-wise weights)
+        alpha_num = grad_2
+        alpha_denom = 2 * grad_2 + sum_activations * grad_3 + eps
+        alpha = alpha_num / alpha_denom
+        
+        # Set alpha to 0 where gradients are 0
+        alpha = np.where(gradients != 0, alpha, 0)
+        
+        # Weights are sum of (alpha * ReLU(gradients))
+        weights = np.sum(alpha * np.maximum(gradients, 0), axis=(2, 3), keepdims=True)
+        
+        # Weighted combination
+        cam = np.sum(weights * activations, axis=1)
+        
+        # Apply ReLU
+        cam = np.maximum(cam, 0)
+        
+        return cam
+    
+    def _normalize_heatmap(self, heatmap: np.ndarray) -> np.ndarray:
+        """Normalize heatmap to [0, 1] range."""
+        heatmap = heatmap.squeeze()
+        
+        min_val = heatmap.min()
+        max_val = heatmap.max()
+        
+        if max_val - min_val > 1e-8:
+            heatmap = (heatmap - min_val) / (max_val - min_val)
+        else:
+            heatmap = np.zeros_like(heatmap)
+        
+        return heatmap
+    
+    def _resize_heatmap(
+        self,
+        heatmap: np.ndarray,
+        target_size: Tuple[int, int]
+    ) -> np.ndarray:
+        """
+        Resize heatmap to match input image size.
+        
+        Uses simple bilinear-like interpolation without requiring scipy/cv2.
+        """
+        h, w = heatmap.shape
+        target_h, target_w = target_size
+        
+        # Create coordinate grids
+        y_ratio = h / target_h
+        x_ratio = w / target_w
+        
+        y_coords = np.arange(target_h) * y_ratio
+        x_coords = np.arange(target_w) * x_ratio
+        
+        # Get integer indices and fractions
+        y_floor = np.floor(y_coords).astype(int)
+        x_floor = np.floor(x_coords).astype(int)
+        
+        y_ceil = np.minimum(y_floor + 1, h - 1)
+        x_ceil = np.minimum(x_floor + 1, w - 1)
+        
+        y_frac = y_coords - y_floor
+        x_frac = x_coords - x_floor
+        
+        # Bilinear interpolation
+        resized = np.zeros((target_h, target_w))
+        for i in range(target_h):
+            for j in range(target_w):
+                top_left = heatmap[y_floor[i], x_floor[j]]
+                top_right = heatmap[y_floor[i], x_ceil[j]]
+                bottom_left = heatmap[y_ceil[i], x_floor[j]]
+                bottom_right = heatmap[y_ceil[i], x_ceil[j]]
+                
+                top = top_left * (1 - x_frac[j]) + top_right * x_frac[j]
+                bottom = bottom_left * (1 - x_frac[j]) + bottom_right * x_frac[j]
+                
+                resized[i, j] = top * (1 - y_frac[i]) + bottom * y_frac[i]
+        
+        return resized
+    
+    def explain(
+        self,
+        image: np.ndarray,
+        target_class: Optional[int] = None,
+        resize_to_input: bool = True
+    ) -> Explanation:
+        """
+        Generate GradCAM explanation for an image.
+        
+        Args:
+            image: Input image as numpy array. Expected shapes:
+                   - (C, H, W) for single image
+                   - (1, C, H, W) for batched single image
+                   - (H, W, C) will be transposed automatically
+            target_class: Class to explain. If None, uses predicted class.
+            resize_to_input: If True, resize heatmap to match input size.
+        
+        Returns:
+            Explanation object with heatmap and metadata.
+        """
+        image = np.array(image, dtype=np.float32)
+        
+        # Handle different input shapes
+        if image.ndim == 3:
+            # Could be (C, H, W) or (H, W, C)
+            if image.shape[0] in [1, 3, 4]:  # Likely (C, H, W)
+                image = image[np.newaxis, ...]  # Add batch dim
+            else:  # Likely (H, W, C)
+                image = np.transpose(image, (2, 0, 1))[np.newaxis, ...]
+        elif image.ndim == 4:
+            pass  # Already (N, C, H, W)
+        else:
+            raise ValueError(f"Expected 3D or 4D input, got shape {image.shape}")
+        
+        input_size = (image.shape[2], image.shape[3])  # (H, W)
+        
+        # Get activations and gradients for target layer
+        activations, gradients = self.model.get_layer_gradients(
+            image,
+            layer_name=self.target_layer,
+            target_class=target_class
+        )
+        
+        # Ensure 4D: (batch, channels, height, width)
+        if activations.ndim == 2:
+            # Fully connected layer output, reshape
+            side = int(np.sqrt(activations.shape[1]))
+            activations = activations.reshape(1, 1, side, side)
+            gradients = gradients.reshape(1, 1, side, side)
+        elif activations.ndim == 3:
+            activations = activations[np.newaxis, ...]
+            gradients = gradients[np.newaxis, ...]
+        
+        # Compute CAM based on method
+        if self.method == "gradcam":
+            cam = self._compute_gradcam(activations, gradients)
+        else:  # gradcam++
+            cam = self._compute_gradcam_plusplus(activations, gradients)
+        
+        # Normalize to [0, 1]
+        heatmap = self._normalize_heatmap(cam)
+        
+        # Optionally resize to input size
+        if resize_to_input and heatmap.shape != input_size:
+            heatmap = self._resize_heatmap(heatmap, input_size)
+        
+        # Determine target class info
+        if target_class is None:
+            predictions = self.model.predict(image)
+            target_class = int(np.argmax(predictions))
+        
+        if self.class_names and target_class < len(self.class_names):
+            label_name = self.class_names[target_class]
+        else:
+            label_name = f"class_{target_class}"
+        
+        return Explanation(
+            explainer_name=f"GradCAM" if self.method == "gradcam" else "GradCAM++",
+            target_class=label_name,
+            explanation_data={
+                "heatmap": heatmap.tolist(),
+                "heatmap_shape": list(heatmap.shape),
+                "target_layer": self.target_layer,
+                "method": self.method,
+                "input_shape": list(image.shape)
+            }
+        )
+    
+    def explain_batch(
+        self,
+        images: np.ndarray,
+        target_class: Optional[int] = None
+    ) -> List[Explanation]:
+        """
+        Generate explanations for multiple images.
+        
+        Args:
+            images: Batch of images (N, C, H, W).
+            target_class: Target class for all images.
+        
+        Returns:
+            List of Explanation objects.
+        """
+        images = np.array(images)
+        
+        return [
+            self.explain(images[i], target_class=target_class)
+            for i in range(images.shape[0])
+        ]
+    
+    def get_overlay(
+        self,
+        image: np.ndarray,
+        heatmap: np.ndarray,
+        alpha: float = 0.5,
+        colormap: str = "jet"
+    ) -> np.ndarray:
+        """
+        Create an overlay of the heatmap on the original image.
+        
+        This is a simple implementation without matplotlib/cv2 dependencies.
+        For better visualizations, use the heatmap with your preferred
+        visualization library.
+        
+        Args:
+            image: Original image (H, W, 3) in [0, 255] or [0, 1] range.
+            heatmap: GradCAM heatmap (H, W) in [0, 1] range.
+            alpha: Transparency of the heatmap overlay.
+            colormap: Color scheme (currently only "jet" supported).
+        
+        Returns:
+            Overlaid image as numpy array (H, W, 3) in [0, 1] range.
+        """
+        image = np.array(image)
+        heatmap = np.array(heatmap)
+        
+        # Normalize image to [0, 1]
+        if image.max() > 1:
+            image = image / 255.0
+        
+        # Handle channel-first format
+        if image.ndim == 3 and image.shape[0] in [1, 3]:
+            image = np.transpose(image, (1, 2, 0))
+        
+        # Simple jet colormap approximation
+        def jet_colormap(x):
+            """Simple jet colormap: blue -> cyan -> green -> yellow -> red"""
+            r = np.clip(1.5 - np.abs(4 * x - 3), 0, 1)
+            g = np.clip(1.5 - np.abs(4 * x - 2), 0, 1)
+            b = np.clip(1.5 - np.abs(4 * x - 1), 0, 1)
+            return np.stack([r, g, b], axis=-1)
+        
+        # Apply colormap to heatmap
+        colored_heatmap = jet_colormap(heatmap)
+        
+        # Ensure same size
+        if colored_heatmap.shape[:2] != image.shape[:2]:
+            colored_heatmap = self._resize_heatmap(
+                colored_heatmap.mean(axis=-1),
+                image.shape[:2]
+            )
+            colored_heatmap = jet_colormap(colored_heatmap)
+        
+        # Blend
+        if image.ndim == 2:
+            image = np.stack([image] * 3, axis=-1)
+        
+        overlay = (1 - alpha) * image + alpha * colored_heatmap
+        overlay = np.clip(overlay, 0, 1)
+        
+        return overlay

explainiverse/explainers/gradient/integrated_gradients.py

@@ -0,0 +1,348 @@
+# src/explainiverse/explainers/gradient/integrated_gradients.py
+"""
+Integrated Gradients - Axiomatic Attribution for Deep Networks.
+
+Integrated Gradients computes feature attributions by accumulating gradients
+along a straight-line path from a baseline to the input. It satisfies two
+key axioms:
+- Sensitivity: If a feature differs between input and baseline and changes
+  the prediction, it receives non-zero attribution.
+- Implementation Invariance: Attributions are identical for functionally
+  equivalent networks.
+
+Reference:
+    Sundararajan, M., Taly, A., & Yan, Q. (2017). Axiomatic Attribution for
+    Deep Networks. ICML 2017. https://arxiv.org/abs/1703.01365
+
+Example:
+    from explainiverse.explainers.gradient import IntegratedGradientsExplainer
+    from explainiverse.adapters import PyTorchAdapter
+    
+    adapter = PyTorchAdapter(model, task="classification")
+    
+    explainer = IntegratedGradientsExplainer(
+        model=adapter,
+        feature_names=feature_names,
+        n_steps=50
+    )
+    
+    explanation = explainer.explain(instance)
+"""
+
+import numpy as np
+from typing import List, Optional, Union, Callable
+
+from explainiverse.core.explainer import BaseExplainer
+from explainiverse.core.explanation import Explanation
+
+
+class IntegratedGradientsExplainer(BaseExplainer):
+    """
+    Integrated Gradients explainer for neural networks.
+    
+    Computes attributions by integrating gradients along the path from
+    a baseline (default: zero vector) to the input. The integral is
+    approximated using the Riemann sum.
+    
+    Attributes:
+        model: Model adapter with predict_with_gradients() method
+        feature_names: List of feature names
+        class_names: List of class names (for classification)
+        n_steps: Number of steps for integral approximation
+        baseline: Baseline input (default: zeros)
+        method: Integration method ("riemann_middle", "riemann_left", "riemann_right", "riemann_trapezoid")
+    """
+    
+    def __init__(
+        self,
+        model,
+        feature_names: List[str],
+        class_names: Optional[List[str]] = None,
+        n_steps: int = 50,
+        baseline: Optional[np.ndarray] = None,
+        method: str = "riemann_middle"
+    ):
+        """
+        Initialize the Integrated Gradients 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).
+            n_steps: Number of steps for approximating the integral.
+                    More steps = more accurate but slower. Default: 50.
+            baseline: Baseline input for comparison. If None, uses zeros.
+                     Can also be "random" for random baseline or a callable.
+            method: Integration method:
+                   - "riemann_middle": Middle Riemann sum (default, most accurate)
+                   - "riemann_left": Left Riemann sum
+                   - "riemann_right": Right Riemann sum
+                   - "riemann_trapezoid": Trapezoidal rule
+        """
+        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.n_steps = n_steps
+        self.baseline = baseline
+        self.method = method
+    
+    def _get_baseline(self, instance: np.ndarray) -> np.ndarray:
+        """Get the baseline for a given input shape."""
+        if self.baseline is None:
+            # Default: zero baseline
+            return np.zeros_like(instance)
+        elif isinstance(self.baseline, str) and self.baseline == "random":
+            # Random baseline (useful for images)
+            return np.random.uniform(
+                low=instance.min(),
+                high=instance.max(),
+                size=instance.shape
+            ).astype(instance.dtype)
+        elif callable(self.baseline):
+            return self.baseline(instance)
+        else:
+            return np.array(self.baseline).reshape(instance.shape)
+    
+    def _get_interpolation_alphas(self) -> np.ndarray:
+        """Get interpolation points based on method."""
+        if self.method == "riemann_left":
+            return np.linspace(0, 1 - 1/self.n_steps, self.n_steps)
+        elif self.method == "riemann_right":
+            return np.linspace(1/self.n_steps, 1, self.n_steps)
+        elif self.method == "riemann_middle":
+            return np.linspace(0.5/self.n_steps, 1 - 0.5/self.n_steps, self.n_steps)
+        elif self.method == "riemann_trapezoid":
+            return np.linspace(0, 1, self.n_steps + 1)
+        else:
+            raise ValueError(f"Unknown method: {self.method}")
+    
+    def _compute_integrated_gradients(
+        self,
+        instance: np.ndarray,
+        baseline: np.ndarray,
+        target_class: Optional[int] = None
+    ) -> np.ndarray:
+        """
+        Compute integrated gradients for a single instance.
+        
+        The integral is approximated as:
+        IG_i = (x_i - x'_i) * sum_{k=1}^{m} grad_i(x' + k/m * (x - x')) / m
+        
+        where x is the input, x' is the baseline, and m is n_steps.
+        """
+        # Get interpolation points
+        alphas = self._get_interpolation_alphas()
+        
+        # Compute path from baseline to input
+        # Shape: (n_steps, n_features)
+        delta = instance - baseline
+        interpolated_inputs = baseline + alphas[:, np.newaxis] * delta
+        
+        # Compute gradients at each interpolation point
+        all_gradients = []
+        for interp_input in interpolated_inputs:
+            _, gradients = self.model.predict_with_gradients(
+                interp_input.reshape(1, -1),
+                target_class=target_class
+            )
+            all_gradients.append(gradients.flatten())
+        
+        all_gradients = np.array(all_gradients)  # Shape: (n_steps, n_features)
+        
+        # Approximate the integral
+        if self.method == "riemann_trapezoid":
+            # Trapezoidal rule: (f(0) + 2*f(1) + ... + 2*f(n-1) + f(n)) / (2n)
+            weights = np.ones(self.n_steps + 1)
+            weights[0] = 0.5
+            weights[-1] = 0.5
+            avg_gradients = np.average(all_gradients, axis=0, weights=weights)
+        else:
+            # Standard Riemann sum: average of gradients
+            avg_gradients = np.mean(all_gradients, axis=0)
+        
+        # Scale by input - baseline difference
+        integrated_gradients = delta * avg_gradients
+        
+        return integrated_gradients
+    
+    def explain(
+        self,
+        instance: np.ndarray,
+        target_class: Optional[int] = None,
+        baseline: Optional[np.ndarray] = None,
+        return_convergence_delta: bool = False
+    ) -> Explanation:
+        """
+        Generate Integrated Gradients 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.
+            baseline: Override the default baseline for this explanation.
+            return_convergence_delta: If True, include the convergence delta
+                                     (difference between sum of attributions
+                                     and prediction difference).
+        
+        Returns:
+            Explanation object with feature attributions.
+        """
+        instance = np.array(instance).flatten().astype(np.float32)
+        
+        # Get baseline
+        if baseline is not None:
+            bl = np.array(baseline).flatten().astype(np.float32)
+        else:
+            bl = self._get_baseline(instance)
+        
+        # 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 integrated gradients
+        ig_attributions = self._compute_integrated_gradients(
+            instance, bl, target_class
+        )
+        
+        # Build attributions dict
+        attributions = {
+            fname: float(ig_attributions[i])
+            for i, fname in enumerate(self.feature_names)
+        }
+        
+        # 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,
+            "attributions_raw": ig_attributions.tolist(),
+            "baseline": bl.tolist(),
+            "n_steps": self.n_steps,
+            "method": self.method
+        }
+        
+        # Optionally compute convergence delta
+        if return_convergence_delta:
+            # The sum of attributions should equal F(x) - F(baseline)
+            pred_input = self.model.predict(instance.reshape(1, -1))
+            pred_baseline = self.model.predict(bl.reshape(1, -1))
+            
+            if target_class is not None:
+                pred_diff = pred_input[0, target_class] - pred_baseline[0, target_class]
+            else:
+                pred_diff = pred_input[0, 0] - pred_baseline[0, 0]
+            
+            attribution_sum = np.sum(ig_attributions)
+            convergence_delta = abs(pred_diff - attribution_sum)
+            
+            explanation_data["convergence_delta"] = float(convergence_delta)
+            explanation_data["prediction_difference"] = float(pred_diff)
+            explanation_data["attribution_sum"] = float(attribution_sum)
+        
+        return Explanation(
+            explainer_name="IntegratedGradients",
+            target_class=label_name,
+            explanation_data=explanation_data
+        )
+    
+    def explain_batch(
+        self,
+        X: np.ndarray,
+        target_class: Optional[int] = None
+    ) -> List[Explanation]:
+        """
+        Generate explanations for multiple instances.
+        
+        Note: This is not optimized for batching - it processes
+        instances sequentially. For large batches, consider using
+        the batched gradient computation in a custom implementation.
+        
+        Args:
+            X: 2D numpy array of instances (n_samples, n_features).
+            target_class: Target class for all instances.
+        
+        Returns:
+            List of Explanation objects.
+        """
+        X = np.array(X)
+        if X.ndim == 1:
+            X = X.reshape(1, -1)
+        
+        return [
+            self.explain(X[i], target_class=target_class)
+            for i in range(X.shape[0])
+        ]
+    
+    def compute_attributions_with_noise(
+        self,
+        instance: np.ndarray,
+        target_class: Optional[int] = None,
+        n_samples: int = 5,
+        noise_scale: float = 0.1
+    ) -> Explanation:
+        """
+        Compute attributions averaged over noisy baselines (SmoothGrad-style).
+        
+        This can help reduce noise in the attributions by averaging over
+        multiple baselines sampled around the zero baseline.
+        
+        Args:
+            instance: Input instance.
+            target_class: Target class for attribution.
+            n_samples: Number of noisy baselines to average.
+            noise_scale: Standard deviation of Gaussian noise.
+        
+        Returns:
+            Explanation with averaged attributions.
+        """
+        instance = np.array(instance).flatten().astype(np.float32)
+        
+        all_attributions = []
+        for _ in range(n_samples):
+            # Create noisy baseline
+            noise = np.random.normal(0, noise_scale, instance.shape).astype(np.float32)
+            noisy_baseline = noise  # Noise around zero
+            
+            ig = self._compute_integrated_gradients(
+                instance, noisy_baseline, target_class
+            )
+            all_attributions.append(ig)
+        
+        # Average attributions
+        avg_attributions = np.mean(all_attributions, axis=0)
+        std_attributions = np.std(all_attributions, axis=0)
+        
+        attributions = {
+            fname: float(avg_attributions[i])
+            for i, fname in enumerate(self.feature_names)
+        }
+        
+        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"
+        
+        return Explanation(
+            explainer_name="IntegratedGradients_Smooth",
+            target_class=label_name,
+            explanation_data={
+                "feature_attributions": attributions,
+                "attributions_raw": avg_attributions.tolist(),
+                "attributions_std": std_attributions.tolist(),
+                "n_samples": n_samples,
+                "noise_scale": noise_scale
+            }
+        )

{explainiverse-0.2.2.dist-info → explainiverse-0.2.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: explainiverse
-Version: 0.2.2
+Version: 0.2.4
 Summary: Unified, extensible explainability framework supporting LIME, SHAP, Anchors, Counterfactuals, PDP, ALE, SAGE, and more
 Home-page: https://github.com/jemsbhai/explainiverse
 License: MIT
@@ -31,7 +31,7 @@ Description-Content-Type: text/markdown
 # Explainiverse
 
 **Explainiverse** is a unified, extensible Python framework for Explainable AI (XAI).  
-It provides a standardized interface for model-agnostic explainability with 9 state-of-the-art XAI methods, evaluation metrics, and a plugin registry for easy extensibility.
+It provides a standardized interface for model-agnostic explainability with 11 state-of-the-art XAI methods, evaluation metrics, and a plugin registry for easy extensibility.
 
 ---
 
@@ -43,6 +43,8 @@ It provides a standardized interface for model-agnostic explainability with 9 st
 - **LIME** - Local Interpretable Model-agnostic Explanations ([Ribeiro et al., 2016](https://arxiv.org/abs/1602.04938))
 - **SHAP** - SHapley Additive exPlanations via KernelSHAP ([Lundberg & Lee, 2017](https://arxiv.org/abs/1705.07874))
 - **TreeSHAP** - Exact SHAP values for tree models, 10x+ faster ([Lundberg et al., 2018](https://arxiv.org/abs/1802.03888))
+- **Integrated Gradients** - Axiomatic attributions for neural networks ([Sundararajan et al., 2017](https://arxiv.org/abs/1703.01365))
+- **GradCAM/GradCAM++** - Visual explanations for CNNs ([Selvaraju et al., 2017](https://arxiv.org/abs/1610.02391))
 - **Anchors** - High-precision rule-based explanations ([Ribeiro et al., 2018](https://ojs.aaai.org/index.php/AAAI/article/view/11491))
 - **Counterfactual** - DiCE-style diverse counterfactual explanations ([Mothilal et al., 2020](https://arxiv.org/abs/1905.07697))
 
@@ -109,7 +111,7 @@ adapter = SklearnAdapter(model, class_names=iris.target_names.tolist())
 
 # List available explainers
 print(default_registry.list_explainers())
-# ['lime', 'shap', 'treeshap', 'anchors', 'counterfactual', 'permutation_importance', 'partial_dependence', 'ale', 'sage']
+# ['lime', 'shap', 'treeshap', 'integrated_gradients', 'gradcam', 'anchors', 'counterfactual', 'permutation_importance', 'partial_dependence', 'ale', 'sage']
 
 # Create and use an explainer
 explainer = default_registry.create(
@@ -128,11 +130,11 @@ print(explanation.explanation_data["feature_attributions"])
 ```python
 # Find local explainers for tabular data
 local_tabular = default_registry.filter(scope="local", data_type="tabular")
-print(local_tabular)  # ['lime', 'shap', 'treeshap', 'anchors', 'counterfactual']
+print(local_tabular)  # ['lime', 'shap', 'treeshap', 'integrated_gradients', 'anchors', 'counterfactual']
 
-# Find explainers optimized for tree models
-tree_explainers = default_registry.filter(model_type="tree")
-print(tree_explainers)  # ['treeshap']
+# Find explainers for images/CNNs
+image_explainers = default_registry.filter(data_type="image")
+print(image_explainers)  # ['lime', 'integrated_gradients', 'gradcam']
 
 # Get recommendations
 recommendations = default_registry.recommend(
@@ -200,6 +202,61 @@ predictions, gradients = adapter.predict_with_gradients(X)
 activations = adapter.get_layer_output(X, layer_name="0")
 ```
 
+### Integrated Gradients for Neural Networks
+
+```python
+from explainiverse.explainers import IntegratedGradientsExplainer
+from explainiverse import PyTorchAdapter
+
+# Wrap your PyTorch model
+adapter = PyTorchAdapter(model, task="classification", class_names=class_names)
+
+# Create IG explainer
+explainer = IntegratedGradientsExplainer(
+    model=adapter,
+    feature_names=feature_names,
+    class_names=class_names,
+    n_steps=50  # More steps = more accurate
+)
+
+# Explain a prediction
+explanation = explainer.explain(X_test[0])
+print(explanation.explanation_data["feature_attributions"])
+
+# Check convergence (sum of attributions ≈ F(x) - F(baseline))
+explanation = explainer.explain(X_test[0], return_convergence_delta=True)
+print(f"Convergence delta: {explanation.explanation_data['convergence_delta']}")
+```
+
+### GradCAM for CNN Visual Explanations
+
+```python
+from explainiverse.explainers import GradCAMExplainer
+from explainiverse import PyTorchAdapter
+
+# Wrap your CNN model
+adapter = PyTorchAdapter(cnn_model, task="classification", class_names=class_names)
+
+# Find the last convolutional layer
+layers = adapter.list_layers()
+target_layer = "layer4"  # Adjust based on your model architecture
+
+# Create GradCAM explainer
+explainer = GradCAMExplainer(
+    model=adapter,
+    target_layer=target_layer,
+    class_names=class_names,
+    method="gradcam"  # or "gradcam++" for improved version
+)
+
+# Explain an image prediction
+explanation = explainer.explain(image)  # image shape: (C, H, W) or (N, C, H, W)
+heatmap = explanation.explanation_data["heatmap"]
+
+# Create overlay visualization
+overlay = explainer.get_overlay(original_image, heatmap, alpha=0.5)
+```
+
 ### Using Specific Explainers
 
 ```python
@@ -300,13 +357,13 @@ poetry run pytest tests/test_new_explainers.py -v
 ## Roadmap
 
 - [x] LIME, SHAP (KernelSHAP)
-- [x] TreeSHAP (optimized for tree models) ✅ NEW
+- [x] TreeSHAP (optimized for tree models) ✅
 - [x] Anchors, Counterfactuals
 - [x] Permutation Importance, PDP, ALE, SAGE
 - [x] Explainer Registry with filtering
-- [x] PyTorch Adapter ✅ NEW
-- [ ] Integrated Gradients (gradient-based for neural nets)
-- [ ] GradCAM for CNNs
+- [x] PyTorch Adapter ✅
+- [x] Integrated Gradients ✅
+- [x] GradCAM/GradCAM++ for CNNs ✅ NEW
 - [ ] TensorFlow adapter
 - [ ] Interactive visualization dashboard
 

{explainiverse-0.2.2.dist-info → explainiverse-0.2.4.dist-info}/RECORD

@@ -1,4 +1,4 @@
-explainiverse/__init__.py,sha256=-4H6WbfGwpeoNpO9w0CEahKQBPsvIYe_lK5e10cZWD0,1612
+explainiverse/__init__.py,sha256=EEo8Stx-Lau5WZLQ5wqA4ESGY9HA_j-dqnpyp9MgV90,1612
 explainiverse/adapters/__init__.py,sha256=HcQGISyp-YQ4jEj2IYveX_c9X5otLcTNWRnVRRhzRik,781
 explainiverse/adapters/base_adapter.py,sha256=Nqt0GeDn_-PjTyJcZsE8dRTulavqFQsv8sMYWS_ps-M,603
 explainiverse/adapters/pytorch_adapter.py,sha256=GTilJAR1VF_OgWG88qZoqlqefHaSXB3i9iOwCJkyHTg,13318
@@ -6,12 +6,12 @@ explainiverse/adapters/sklearn_adapter.py,sha256=pzIBtMuqrG-6ZbUqUCMt7rSk3Ow0Fgr
 explainiverse/core/__init__.py,sha256=P3jHMnH5coFqTTO1w-gT-rurkCM1-9r3pF-055pbXMg,474
 explainiverse/core/explainer.py,sha256=Z9on-9VblYDlQx9oBm1BHpmAf_NsQajZ3qr-u48Aejo,784
 explainiverse/core/explanation.py,sha256=6zxFh_TH8tFHc-r_H5-WHQ05Sp1Kp2TxLz3gyFek5jo,881
-explainiverse/core/registry.py,sha256=_BXWi1fJY3cGjYA1Xn1DwvY91jbpJrpX6_8EVzrRT20,19876
+explainiverse/core/registry.py,sha256=BjyPhcxWC8zaiRflDF3JCaUMPsBmHHDNfwM13bTWxjE,21476
 explainiverse/engine/__init__.py,sha256=1sZO8nH1mmwK2e-KUavBQm7zYDWUe27nyWoFy9tgsiA,197
 explainiverse/engine/suite.py,sha256=sq8SK_6Pf0qRckTmVJ7Mdosu9bhkjAGPGN8ymLGFP9E,4914
 explainiverse/evaluation/__init__.py,sha256=Y50L_b4HKthg4epwcayPHXh0l4i4MUuzvaNlqPmUNZY,212
 explainiverse/evaluation/metrics.py,sha256=tSBXtyA_-0zOGCGjlPZU6LdGKRH_QpWfgKa78sdlovs,7453
-explainiverse/explainers/__init__.py,sha256=Op-Z_BTJ7BdqA_9gTnruomN2-rKtrkPCt1Zq1iCzxr0,1758
+explainiverse/explainers/__init__.py,sha256=epXDNoYIAxW0KNtGBCkjS28FmDSBYry59HdTY9vJXCs,2057
 explainiverse/explainers/attribution/__init__.py,sha256=YeVs9bS_IWDtqGbp6T37V6Zp5ZDWzLdAXHxxyFGpiQM,431
 explainiverse/explainers/attribution/lime_wrapper.py,sha256=OnXIV7t6yd-vt38sIi7XmHFbgzlZfCEbRlFyGGd5XiE,3245
 explainiverse/explainers/attribution/shap_wrapper.py,sha256=tKie5AvN7mb55PWOYdMvW0lUAYjfHPzYosEloEY2ZzI,3210
@@ -23,9 +23,12 @@ explainiverse/explainers/global_explainers/ale.py,sha256=tgG3XTppCf8LiD7uKzBt4DI
 explainiverse/explainers/global_explainers/partial_dependence.py,sha256=dH6yMjpwZads3pACR3rSykTbssLGHH7e6HfMlpl-S3I,6745
 explainiverse/explainers/global_explainers/permutation_importance.py,sha256=bcgKz1S_D3lrBMgpqEF_Z6qw8Knxl_cfR50hrSO2tBc,4410
 explainiverse/explainers/global_explainers/sage.py,sha256=57Xw1SK529x5JXWt0TVrcFYUUP3C65LfUwgoM-Z3gaw,5839
+explainiverse/explainers/gradient/__init__.py,sha256=lVPiSGV_swSwV8k7Z4c6XETwDdTRO09D6bv8TSMsNd8,441
+explainiverse/explainers/gradient/gradcam.py,sha256=ywW_8PhALwegkpSUDQMFvvVFkA5NnMMW6BB5tb3i8bw,13721
+explainiverse/explainers/gradient/integrated_gradients.py,sha256=feBgY3Vw2rDti7fxRZtLkxse75m2dbP_R05ARqo2BRM,13367
 explainiverse/explainers/rule_based/__init__.py,sha256=gKzlFCAzwurAMLJcuYgal4XhDj1thteBGcaHWmN7iWk,243
 explainiverse/explainers/rule_based/anchors_wrapper.py,sha256=ML7W6aam-eMGZHy5ilol8qupZvNBJpYAFatEEPnuMyo,13254
-explainiverse-0.2.2.dist-info/LICENSE,sha256=28rbHe8rJgmUlRdxJACfq1Sj-MtCEhyHxkJedQd1ZYA,1070
-explainiverse-0.2.2.dist-info/METADATA,sha256=kis3ejJCLRhBJWf5p13FzY2ZeSbnWfJxk6LS1hd7A1w,9497
-explainiverse-0.2.2.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
-explainiverse-0.2.2.dist-info/RECORD,,
+explainiverse-0.2.4.dist-info/LICENSE,sha256=28rbHe8rJgmUlRdxJACfq1Sj-MtCEhyHxkJedQd1ZYA,1070
+explainiverse-0.2.4.dist-info/METADATA,sha256=5LUzE3WCwdp0QRyonWTkRyHnFmPjGcSlnzbs011f8ZA,11483
+explainiverse-0.2.4.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+explainiverse-0.2.4.dist-info/RECORD,,