explainiverse 0.6.0__py3-none-any.whl → 0.7.0__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.6.0"
+__version__ = "0.7.0"
 
 __all__ = [
     # Core

explainiverse/core/registry.py

@@ -374,6 +374,7 @@ def _create_default_registry() -> ExplainerRegistry:
     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.gradient.tcav import TCAVExplainer
     from explainiverse.explainers.example_based.protodash import ProtoDashExplainer
     
     registry = ExplainerRegistry()
@@ -569,6 +570,23 @@ def _create_default_registry() -> ExplainerRegistry:
         )
     )
     
+    # Register TCAV (Concept-based explanations for neural networks)
+    registry.register(
+        name="tcav",
+        explainer_class=TCAVExplainer,
+        meta=ExplainerMeta(
+            scope="local",
+            model_types=["neural"],
+            data_types=["tabular", "image"],
+            task_types=["classification"],
+            description="TCAV - Testing with Concept Activation Vectors for concept-based explanations (requires PyTorch)",
+            paper_reference="Kim et al., 2018 - 'Interpretability Beyond Feature Attribution: Quantitative Testing with Concept Activation Vectors' (ICML)",
+            complexity="O(n_concepts * n_test_inputs * forward_pass)",
+            requires_training_data=True,
+            supports_batching=True
+        )
+    )
+    
     # =========================================================================
     # Global Explainers (model-level)
     # =========================================================================

explainiverse/explainers/gradient/__init__.py

@@ -4,6 +4,15 @@ Gradient-based explainers for neural networks.
 
 These explainers require models that support gradient computation,
 typically via the PyTorchAdapter.
+
+Explainers:
+    - IntegratedGradientsExplainer: Axiomatic attributions via path integration
+    - GradCAMExplainer: Visual explanations for CNNs
+    - DeepLIFTExplainer: Reference-based attribution
+    - DeepLIFTShapExplainer: DeepLIFT + SHAP combination
+    - SmoothGradExplainer: Noise-averaged gradients
+    - SaliencyExplainer: Basic gradient attribution
+    - TCAVExplainer: Concept-based explanations (TCAV)
 """
 
 from explainiverse.explainers.gradient.integrated_gradients import IntegratedGradientsExplainer
@@ -11,6 +20,7 @@ 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.gradient.tcav import TCAVExplainer, ConceptActivationVector
 
 __all__ = [
     "IntegratedGradientsExplainer", 
@@ -19,4 +29,6 @@ __all__ = [
     "DeepLIFTShapExplainer",
     "SmoothGradExplainer",
     "SaliencyExplainer",
+    "TCAVExplainer",
+    "ConceptActivationVector",
 ]

explainiverse/explainers/gradient/tcav.py

@@ -0,0 +1,865 @@
+# src/explainiverse/explainers/gradient/tcav.py
+"""
+TCAV - Testing with Concept Activation Vectors.
+
+TCAV provides human-interpretable explanations by quantifying how much
+a model's predictions are influenced by high-level concepts. Instead of
+attributing importance to individual features, TCAV explains which
+human-understandable concepts (e.g., "striped", "furry") are important
+for a model's predictions.
+
+Key Components:
+    - Concept Activation Vectors (CAVs): Learned direction in activation space
+      that separates concept examples from random examples
+    - Directional Derivatives: Gradient of model output in CAV direction
+    - TCAV Score: Fraction of inputs where concept positively influences prediction
+    - Statistical Testing: Significance against random concepts
+
+Reference:
+    Kim, B., Wattenberg, M., Gilmer, J., Cai, C., Wexler, J., Viegas, F., &
+    Sayres, R. (2018). Interpretability Beyond Feature Attribution:
+    Quantitative Testing with Concept Activation Vectors (TCAV).
+    ICML 2018. https://arxiv.org/abs/1711.11279
+
+Example:
+    from explainiverse.explainers.gradient import TCAVExplainer
+    from explainiverse.adapters import PyTorchAdapter
+
+    adapter = PyTorchAdapter(model, task="classification")
+
+    explainer = TCAVExplainer(
+        model=adapter,
+        layer_name="layer3",
+        class_names=["zebra", "horse", "dog"]
+    )
+
+    # Learn a concept (e.g., "striped")
+    explainer.learn_concept(
+        concept_name="striped",
+        concept_examples=striped_images,
+        negative_examples=random_images
+    )
+
+    # Compute TCAV score for target class
+    result = explainer.compute_tcav_score(
+        test_inputs=test_images,
+        target_class=0,  # zebra
+        concept_name="striped"
+    )
+"""
+
+import numpy as np
+from typing import List, Optional, Dict, Any, Union, Tuple
+from collections import defaultdict
+
+from explainiverse.core.explainer import BaseExplainer
+from explainiverse.core.explanation import Explanation
+
+# Check if sklearn is available for linear classifier
+try:
+    from sklearn.linear_model import SGDClassifier, LogisticRegression
+    from sklearn.model_selection import train_test_split
+    from sklearn.metrics import accuracy_score
+    SKLEARN_AVAILABLE = True
+except ImportError:
+    SKLEARN_AVAILABLE = False
+
+# Check if scipy is available for statistical tests
+try:
+    from scipy import stats
+    SCIPY_AVAILABLE = True
+except ImportError:
+    SCIPY_AVAILABLE = False
+
+
+def _check_dependencies():
+    """Check required dependencies for TCAV."""
+    if not SKLEARN_AVAILABLE:
+        raise ImportError(
+            "scikit-learn is required for TCAV. "
+            "Install it with: pip install scikit-learn"
+        )
+    if not SCIPY_AVAILABLE:
+        raise ImportError(
+            "scipy is required for TCAV statistical testing. "
+            "Install it with: pip install scipy"
+        )
+
+
+class ConceptActivationVector:
+    """
+    Represents a learned Concept Activation Vector (CAV).
+    
+    A CAV is the normal vector to the hyperplane that separates
+    concept examples from random (negative) examples in the
+    activation space of a neural network layer.
+    
+    Attributes:
+        concept_name: Human-readable name of the concept
+        layer_name: Name of the layer this CAV was trained on
+        vector: The CAV direction (normal to separating hyperplane)
+        classifier: The trained linear classifier
+        accuracy: Classification accuracy on held-out data (Python float)
+        metadata: Additional training information
+    """
+    
+    def __init__(
+        self,
+        concept_name: str,
+        layer_name: str,
+        vector: np.ndarray,
+        classifier: Any,
+        accuracy: float,
+        metadata: Optional[Dict[str, Any]] = None
+    ):
+        self.concept_name = concept_name
+        self.layer_name = layer_name
+        self.vector = vector / np.linalg.norm(vector)  # Normalize
+        self.classifier = classifier
+        # Ensure accuracy is Python float, not numpy.float64
+        # sklearn.metrics.accuracy_score returns numpy.float64
+        self.accuracy = float(accuracy)
+        self.metadata = metadata or {}
+    
+    def __repr__(self):
+        return (f"CAV(concept='{self.concept_name}', "
+                f"layer='{self.layer_name}', "
+                f"accuracy={self.accuracy:.3f})")
+
+
+class TCAVExplainer(BaseExplainer):
+    """
+    TCAV (Testing with Concept Activation Vectors) explainer.
+    
+    TCAV explains model predictions using high-level human concepts
+    rather than low-level features. It quantifies how sensitive a
+    model's predictions are to specific concepts.
+    
+    The TCAV score for a concept C and class k is the fraction of
+    inputs of class k for which the model's prediction increases
+    when moving in the direction of concept C.
+    
+    Attributes:
+        model: Model adapter with layer access (PyTorchAdapter)
+        layer_name: Target layer for activation extraction
+        class_names: List of class names
+        concepts: Dictionary of learned CAVs
+        random_concepts: Dictionary of random CAVs for statistical testing
+    """
+    
+    def __init__(
+        self,
+        model,
+        layer_name: str,
+        class_names: Optional[List[str]] = None,
+        cav_classifier: str = "logistic",
+        random_seed: int = 42
+    ):
+        """
+        Initialize the TCAV explainer.
+        
+        Args:
+            model: A model adapter with get_layer_output() and
+                   get_layer_gradients() methods. Use PyTorchAdapter.
+            layer_name: Name of the layer to extract activations from.
+                       Use model.list_layers() to see available layers.
+            class_names: List of class names for the model's outputs.
+            cav_classifier: Type of linear classifier for CAV training:
+                           - "logistic": Logistic Regression (default)
+                           - "sgd": SGD Classifier (faster for large data)
+            random_seed: Random seed for reproducibility.
+        """
+        _check_dependencies()
+        super().__init__(model)
+        
+        # Validate model capabilities
+        if not hasattr(model, 'get_layer_output'):
+            raise TypeError(
+                "Model adapter must have get_layer_output() method. "
+                "Use PyTorchAdapter for PyTorch models."
+            )
+        if not hasattr(model, 'get_layer_gradients'):
+            raise TypeError(
+                "Model adapter must have get_layer_gradients() method. "
+                "Use PyTorchAdapter for PyTorch models."
+            )
+        
+        self.layer_name = layer_name
+        self.class_names = list(class_names) if class_names else None
+        self.cav_classifier = cav_classifier
+        self.random_seed = random_seed
+        
+        # Storage for learned concepts
+        self.concepts: Dict[str, ConceptActivationVector] = {}
+        self.random_concepts: Dict[str, List[ConceptActivationVector]] = defaultdict(list)
+        
+        # Validate layer exists
+        if hasattr(model, 'list_layers'):
+            available_layers = model.list_layers()
+            if layer_name not in available_layers:
+                raise ValueError(
+                    f"Layer '{layer_name}' not found. "
+                    f"Available layers: {available_layers}"
+                )
+    
+    def _get_activations(self, inputs: np.ndarray) -> np.ndarray:
+        """
+        Extract activations from the target layer.
+        
+        Args:
+            inputs: Input data (n_samples, ...)
+            
+        Returns:
+            Flattened activations (n_samples, n_features)
+        """
+        activations = self.model.get_layer_output(inputs, self.layer_name)
+        
+        # Flatten activations if multi-dimensional (e.g., CNN feature maps)
+        if activations.ndim > 2:
+            # Global average pooling for spatial dimensions
+            # Shape: (batch, channels, height, width) -> (batch, channels)
+            activations = activations.mean(axis=tuple(range(2, activations.ndim)))
+        
+        return activations
+    
+    def _get_gradients_wrt_layer(
+        self,
+        inputs: np.ndarray,
+        target_class: int
+    ) -> np.ndarray:
+        """
+        Get gradients of output w.r.t. layer activations.
+        
+        Args:
+            inputs: Input data
+            target_class: Target class index
+            
+        Returns:
+            Gradients w.r.t. layer activations (n_samples, n_features)
+        """
+        activations, gradients = self.model.get_layer_gradients(
+            inputs, self.layer_name, target_class=target_class
+        )
+        
+        # Flatten gradients if multi-dimensional
+        if gradients.ndim > 2:
+            gradients = gradients.mean(axis=tuple(range(2, gradients.ndim)))
+        
+        return gradients
+    
+    def _train_cav(
+        self,
+        concept_activations: np.ndarray,
+        negative_activations: np.ndarray,
+        test_size: float = 0.2
+    ) -> Tuple[np.ndarray, Any, float]:
+        """
+        Train a CAV (linear classifier) to separate concept from negative examples.
+        
+        Args:
+            concept_activations: Activations for concept examples
+            negative_activations: Activations for negative examples
+            test_size: Fraction of data to use for accuracy estimation
+            
+        Returns:
+            Tuple of (cav_vector, classifier, accuracy)
+            Note: accuracy is returned as Python float, not numpy.float64
+        """
+        np.random.seed(self.random_seed)
+        
+        # Prepare training data
+        X = np.vstack([concept_activations, negative_activations])
+        y = np.array([1] * len(concept_activations) + [0] * len(negative_activations))
+        
+        # Split for accuracy estimation
+        if test_size > 0 and len(X) >= 10:
+            X_train, X_test, y_train, y_test = train_test_split(
+                X, y, test_size=test_size, random_state=self.random_seed, stratify=y
+            )
+        else:
+            X_train, y_train = X, y
+            X_test, y_test = X, y
+        
+        # Train classifier
+        if self.cav_classifier == "sgd":
+            classifier = SGDClassifier(
+                loss='hinge',
+                max_iter=1000,
+                random_state=self.random_seed,
+                n_jobs=-1
+            )
+        else:  # logistic
+            classifier = LogisticRegression(
+                max_iter=1000,
+                random_state=self.random_seed,
+                n_jobs=-1,
+                solver='lbfgs'
+            )
+        
+        classifier.fit(X_train, y_train)
+        
+        # Compute accuracy and convert to Python float
+        # accuracy_score returns numpy.float64
+        accuracy = float(accuracy_score(y_test, classifier.predict(X_test)))
+        
+        # Extract CAV (normal vector to separating hyperplane)
+        # For linear classifiers, this is the coefficient vector
+        cav_vector = classifier.coef_.flatten()
+        
+        return cav_vector, classifier, accuracy
+    
+    def learn_concept(
+        self,
+        concept_name: str,
+        concept_examples: np.ndarray,
+        negative_examples: Optional[np.ndarray] = None,
+        test_size: float = 0.2,
+        min_accuracy: float = 0.6
+    ) -> ConceptActivationVector:
+        """
+        Learn a Concept Activation Vector from examples.
+        
+        The CAV is the direction in activation space that separates
+        concept examples from negative (non-concept) examples.
+        
+        Args:
+            concept_name: Human-readable name for the concept.
+            concept_examples: Examples that exhibit the concept.
+                            Shape: (n_concept, ...) matching model input.
+            negative_examples: Examples that don't exhibit the concept.
+                             If None, random noise is used (not recommended).
+                             Shape: (n_negative, ...) matching model input.
+            test_size: Fraction of data to hold out for accuracy estimation.
+            min_accuracy: Minimum accuracy for CAV to be considered valid.
+                         Low accuracy suggests concept isn't linearly separable.
+        
+        Returns:
+            The learned ConceptActivationVector.
+            
+        Raises:
+            ValueError: If CAV accuracy is below min_accuracy threshold.
+        """
+        concept_examples = np.array(concept_examples)
+        
+        if negative_examples is None:
+            # Generate random negative examples (not recommended)
+            import warnings
+            warnings.warn(
+                "No negative examples provided. Using random noise. "
+                "For meaningful CAVs, provide actual non-concept examples.",
+                UserWarning
+            )
+            negative_examples = np.random.randn(*concept_examples.shape).astype(np.float32)
+        else:
+            negative_examples = np.array(negative_examples)
+        
+        # Extract activations
+        concept_acts = self._get_activations(concept_examples)
+        negative_acts = self._get_activations(negative_examples)
+        
+        # Train CAV (accuracy is already Python float from _train_cav)
+        cav_vector, classifier, accuracy = self._train_cav(
+            concept_acts, negative_acts, test_size
+        )
+        
+        if accuracy < min_accuracy:
+            raise ValueError(
+                f"CAV accuracy ({accuracy:.3f}) is below threshold ({min_accuracy}). "
+                f"The concept '{concept_name}' may not be linearly separable in "
+                f"layer '{self.layer_name}'. Consider using a different layer "
+                f"or providing more/better examples."
+            )
+        
+        # Create CAV object (accuracy is already Python float)
+        cav = ConceptActivationVector(
+            concept_name=concept_name,
+            layer_name=self.layer_name,
+            vector=cav_vector,
+            classifier=classifier,
+            accuracy=accuracy,
+            metadata={
+                "n_concept_examples": int(len(concept_examples)),
+                "n_negative_examples": int(len(negative_examples)),
+                "test_size": float(test_size)
+            }
+        )
+        
+        # Store the CAV
+        self.concepts[concept_name] = cav
+        
+        return cav
+    
+    def learn_random_concepts(
+        self,
+        negative_examples: np.ndarray,
+        n_random: int = 10,
+        concept_name_prefix: str = "_random"
+    ) -> List[ConceptActivationVector]:
+        """
+        Learn random CAVs for statistical significance testing.
+        
+        Random CAVs are trained by splitting random examples into
+        two arbitrary groups. They serve as a baseline to test
+        whether a concept's TCAV score is significantly different
+        from random.
+        
+        Args:
+            negative_examples: Pool of examples to sample from.
+            n_random: Number of random CAVs to train.
+            concept_name_prefix: Prefix for random concept names.
+            
+        Returns:
+            List of random CAVs.
+        """
+        negative_examples = np.array(negative_examples)
+        random_cavs = []
+        
+        # Get all activations
+        all_acts = self._get_activations(negative_examples)
+        n_samples = len(all_acts)
+        
+        for i in range(n_random):
+            np.random.seed(self.random_seed + i)
+            
+            # Randomly split into two groups
+            indices = np.random.permutation(n_samples)
+            split_point = n_samples // 2
+            
+            group1_acts = all_acts[indices[:split_point]]
+            group2_acts = all_acts[indices[split_point:]]
+            
+            # Train CAV on arbitrary split
+            try:
+                cav_vector, classifier, accuracy = self._train_cav(
+                    group1_acts, group2_acts, test_size=0.0
+                )
+                
+                cav = ConceptActivationVector(
+                    concept_name=f"{concept_name_prefix}_{i}",
+                    layer_name=self.layer_name,
+                    vector=cav_vector,
+                    classifier=classifier,
+                    accuracy=accuracy,  # Already Python float from _train_cav
+                    metadata={"random_seed": int(self.random_seed + i)}
+                )
+                
+                random_cavs.append(cav)
+            except Exception:
+                # Skip failed random CAVs
+                continue
+        
+        # Store random CAVs
+        self.random_concepts[concept_name_prefix] = random_cavs
+        
+        return random_cavs
+    
+    def compute_directional_derivative(
+        self,
+        inputs: np.ndarray,
+        cav: ConceptActivationVector,
+        target_class: int
+    ) -> np.ndarray:
+        """
+        Compute directional derivative of predictions in CAV direction.
+        
+        The directional derivative measures how the model's output for
+        the target class changes when moving in the CAV direction.
+        
+        S_C,k(x) = ∇h_l,k(x) · v_C
+        
+        where h_l,k is the model's logit for class k at layer l,
+        and v_C is the CAV direction.
+        
+        Args:
+            inputs: Input data (n_samples, ...)
+            cav: The Concept Activation Vector
+            target_class: Target class index
+            
+        Returns:
+            Directional derivatives as numpy array (n_samples,)
+            Note: Returns numpy array for efficient computation;
+                  individual values should be converted to float if needed.
+        """
+        # Get gradients w.r.t. layer activations
+        gradients = self._get_gradients_wrt_layer(inputs, target_class)
+        
+        # Compute dot product with CAV
+        # S_C,k(x) = ∇h_l,k(x) · v_C
+        directional_derivatives = np.dot(gradients, cav.vector)
+        
+        return directional_derivatives
+    
+    def compute_tcav_score(
+        self,
+        test_inputs: np.ndarray,
+        target_class: int,
+        concept_name: str,
+        return_derivatives: bool = False
+    ) -> Union[float, Tuple[float, np.ndarray]]:
+        """
+        Compute TCAV score for a concept and target class.
+        
+        The TCAV score is the fraction of test inputs for which
+        the model's prediction for the target class increases
+        when moving in the concept direction.
+        
+        TCAV_C,k = |{x : S_C,k(x) > 0}| / |X|
+        
+        A score > 0.5 indicates the concept positively influences
+        the prediction, while < 0.5 indicates negative influence.
+        
+        Args:
+            test_inputs: Test examples to compute TCAV score over.
+            target_class: Target class index.
+            concept_name: Name of the concept (must be learned first).
+            return_derivatives: If True, also return the directional derivatives.
+            
+        Returns:
+            TCAV score as Python float in [0, 1].
+            If return_derivatives=True, returns (score, derivatives) where
+            score is Python float and derivatives is numpy array.
+        """
+        if concept_name not in self.concepts:
+            raise ValueError(
+                f"Concept '{concept_name}' not found. "
+                f"Available concepts: {list(self.concepts.keys())}. "
+                f"Use learn_concept() first."
+            )
+        
+        test_inputs = np.array(test_inputs)
+        cav = self.concepts[concept_name]
+        
+        # Compute directional derivatives
+        derivatives = self.compute_directional_derivative(
+            test_inputs, cav, target_class
+        )
+        
+        # TCAV score = fraction with positive derivative
+        # np.mean returns numpy.float64, convert to Python float
+        tcav_score = float(np.mean(derivatives > 0))
+        
+        if return_derivatives:
+            return tcav_score, derivatives
+        return tcav_score
+    
+    def statistical_significance_test(
+        self,
+        test_inputs: np.ndarray,
+        target_class: int,
+        concept_name: str,
+        n_random: int = 10,
+        negative_examples: Optional[np.ndarray] = None,
+        alpha: float = 0.05
+    ) -> Dict[str, Any]:
+        """
+        Test statistical significance of TCAV score against random concepts.
+        
+        Performs a two-sided t-test comparing the concept's TCAV score
+        against the distribution of random TCAV scores.
+        
+        Args:
+            test_inputs: Test examples to compute TCAV scores over.
+            target_class: Target class index.
+            concept_name: Name of the concept to test.
+            n_random: Number of random concepts for comparison.
+            negative_examples: Examples for training random concepts.
+                             If None, uses test_inputs (not ideal).
+            alpha: Significance level for the test.
+            
+        Returns:
+            Dictionary containing (all values are Python native types):
+            - tcav_score: The concept's TCAV score (float)
+            - random_scores: List of random TCAV scores (list of float)
+            - random_mean: Mean of random scores (float)
+            - random_std: Std of random scores (float)
+            - t_statistic: t-statistic from t-test (float)
+            - p_value: p-value from t-test (float)
+            - significant: Whether the result is significant at level alpha (bool)
+            - effect_size: Cohen's d effect size (float)
+            - alpha: The significance level used (float)
+        """
+        test_inputs = np.array(test_inputs)
+        
+        # Compute concept TCAV score (already Python float from compute_tcav_score)
+        concept_score = self.compute_tcav_score(
+            test_inputs, target_class, concept_name
+        )
+        
+        # Train random CAVs if not already done
+        if negative_examples is None:
+            negative_examples = test_inputs
+        
+        random_prefix = f"_random_{concept_name}_{target_class}"
+        
+        if random_prefix not in self.random_concepts or \
+           len(self.random_concepts[random_prefix]) < n_random:
+            self.learn_random_concepts(
+                negative_examples,
+                n_random=n_random,
+                concept_name_prefix=random_prefix
+            )
+        
+        random_cavs = self.random_concepts[random_prefix][:n_random]
+        
+        # Compute random TCAV scores
+        random_scores = []
+        for random_cav in random_cavs:
+            derivatives = self.compute_directional_derivative(
+                test_inputs, random_cav, target_class
+            )
+            # Convert to Python float immediately
+            random_score = float(np.mean(derivatives > 0))
+            random_scores.append(random_score)
+        
+        # Convert to numpy array for statistical computations
+        random_scores_array = np.array(random_scores)
+        
+        # Perform one-sample t-test against concept score
+        # scipy.stats.ttest_1samp returns numpy scalars
+        t_stat_np, p_value_np = stats.ttest_1samp(random_scores_array, concept_score)
+        
+        # Convert scipy/numpy results to Python native types
+        t_stat = float(t_stat_np)
+        p_value = float(p_value_np)
+        
+        # Compute effect size (Cohen's d)
+        random_std = float(random_scores_array.std())
+        random_mean = float(random_scores_array.mean())
+        
+        if random_std > 0:
+            effect_size = float((concept_score - random_mean) / random_std)
+        else:
+            # Handle zero std case
+            if concept_score != random_mean:
+                effect_size = float('inf') if concept_score > random_mean else float('-inf')
+            else:
+                effect_size = 0.0
+        
+        # Compute significance as Python bool (not numpy.bool_)
+        significant = bool(p_value < alpha)
+        
+        return {
+            "tcav_score": concept_score,  # Already Python float
+            "random_scores": random_scores,  # Already list of Python floats
+            "random_mean": random_mean,
+            "random_std": random_std,
+            "t_statistic": t_stat,
+            "p_value": p_value,
+            "significant": significant,
+            "effect_size": effect_size,
+            "alpha": float(alpha)
+        }
+    
+    def explain(
+        self,
+        test_inputs: np.ndarray,
+        target_class: Optional[int] = None,
+        concept_names: Optional[List[str]] = None,
+        run_significance_test: bool = False,
+        negative_examples: Optional[np.ndarray] = None,
+        n_random: int = 10
+    ) -> Explanation:
+        """
+        Generate TCAV explanation for test inputs.
+        
+        Computes TCAV scores for all (or specified) concepts
+        and optionally runs statistical significance tests.
+        
+        Args:
+            test_inputs: Input examples to explain.
+            target_class: Target class to explain. If None, uses
+                         the most common predicted class.
+            concept_names: List of concepts to include. If None,
+                          uses all learned concepts.
+            run_significance_test: Whether to run statistical tests.
+            negative_examples: Examples for random CAVs (for significance test).
+            n_random: Number of random concepts for significance test.
+            
+        Returns:
+            Explanation object with TCAV scores for each concept.
+        """
+        test_inputs = np.array(test_inputs)
+        
+        if len(self.concepts) == 0:
+            raise ValueError(
+                "No concepts learned. Use learn_concept() first."
+            )
+        
+        # Determine target class
+        if target_class is None:
+            predictions = self.model.predict(test_inputs)
+            if predictions.ndim > 1:
+                target_class = int(np.argmax(np.bincount(
+                    np.argmax(predictions, axis=1)
+                )))
+            else:
+                target_class = 0
+        
+        # Determine concepts to analyze
+        if concept_names is None:
+            concept_names = list(self.concepts.keys())
+        
+        # Compute TCAV scores for each concept
+        tcav_scores = {}
+        significance_results = {}
+        
+        for concept_name in concept_names:
+            if concept_name not in self.concepts:
+                continue
+            
+            # compute_tcav_score returns Python float
+            score, derivatives = self.compute_tcav_score(
+                test_inputs, target_class, concept_name,
+                return_derivatives=True
+            )
+            
+            tcav_scores[concept_name] = {
+                "score": score,  # Already Python float
+                "cav_accuracy": self.concepts[concept_name].accuracy,  # Already Python float
+                "positive_count": int(np.sum(derivatives > 0)),
+                "total_count": int(len(derivatives))
+            }
+            
+            # Optionally run significance test
+            if run_significance_test:
+                neg_examples = negative_examples if negative_examples is not None else test_inputs
+                # statistical_significance_test returns dict with Python native types
+                sig_result = self.statistical_significance_test(
+                    test_inputs, target_class, concept_name,
+                    n_random=n_random,
+                    negative_examples=neg_examples
+                )
+                significance_results[concept_name] = sig_result
+        
+        # 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}"
+        
+        explanation_data = {
+            "tcav_scores": tcav_scores,
+            "target_class": int(target_class),
+            "n_test_inputs": int(len(test_inputs)),
+            "layer_name": self.layer_name,
+            "concepts_analyzed": list(concept_names)  # Ensure it's a list
+        }
+        
+        if run_significance_test:
+            explanation_data["significance_tests"] = significance_results
+        
+        return Explanation(
+            explainer_name="TCAV",
+            target_class=label_name,
+            explanation_data=explanation_data
+        )
+    
+    def explain_batch(
+        self,
+        X: np.ndarray,
+        target_class: Optional[int] = None,
+        **kwargs
+    ) -> List[Explanation]:
+        """
+        TCAV typically explains batches together, not individually.
+        
+        For TCAV, it makes more sense to analyze a batch of inputs
+        together to compute meaningful TCAV scores. This method
+        returns a single explanation for the batch.
+        
+        Args:
+            X: Batch of inputs.
+            target_class: Target class to explain.
+            **kwargs: Additional arguments passed to explain().
+            
+        Returns:
+            List containing a single Explanation for the batch.
+        """
+        return [self.explain(X, target_class=target_class, **kwargs)]
+    
+    def get_most_influential_concepts(
+        self,
+        test_inputs: np.ndarray,
+        target_class: int,
+        top_k: int = 5
+    ) -> List[Tuple[str, float]]:
+        """
+        Get the most influential concepts for the target class.
+        
+        Ranks concepts by how much they positively influence
+        the model's prediction for the target class.
+        
+        Args:
+            test_inputs: Test examples.
+            target_class: Target class index.
+            top_k: Number of top concepts to return.
+            
+        Returns:
+            List of (concept_name, tcav_score) tuples, sorted by score descending.
+            All scores are Python floats.
+        """
+        scores = []
+        
+        for concept_name in self.concepts:
+            # compute_tcav_score returns Python float
+            score = self.compute_tcav_score(
+                test_inputs, target_class, concept_name
+            )
+            scores.append((concept_name, score))
+        
+        # Sort by score (higher = more positive influence)
+        scores.sort(key=lambda x: x[1], reverse=True)
+        
+        return scores[:top_k]
+    
+    def compare_concepts(
+        self,
+        test_inputs: np.ndarray,
+        target_classes: List[int],
+        concept_names: Optional[List[str]] = None
+    ) -> Dict[str, Dict[int, float]]:
+        """
+        Compare TCAV scores across multiple target classes.
+        
+        Useful for understanding which concepts are important
+        for different classes.
+        
+        Args:
+            test_inputs: Test examples.
+            target_classes: List of class indices to compare.
+            concept_names: Concepts to analyze (default: all).
+            
+        Returns:
+            Dictionary mapping concept names to {class_idx: tcav_score}.
+            All scores are Python floats.
+        """
+        if concept_names is None:
+            concept_names = list(self.concepts.keys())
+        
+        results: Dict[str, Dict[int, float]] = {}
+        
+        for concept_name in concept_names:
+            results[concept_name] = {}
+            for class_idx in target_classes:
+                # compute_tcav_score returns Python float
+                score = self.compute_tcav_score(
+                    test_inputs, class_idx, concept_name
+                )
+                results[concept_name][class_idx] = score
+        
+        return results
+    
+    def list_concepts(self) -> List[str]:
+        """List all learned concept names."""
+        return list(self.concepts.keys())
+    
+    def get_concept(self, concept_name: str) -> ConceptActivationVector:
+        """Get a specific CAV by name."""
+        if concept_name not in self.concepts:
+            raise ValueError(f"Concept '{concept_name}' not found.")
+        return self.concepts[concept_name]
+    
+    def remove_concept(self, concept_name: str) -> None:
+        """Remove a learned concept."""
+        if concept_name in self.concepts:
+            del self.concepts[concept_name]

{explainiverse-0.6.0.dist-info → explainiverse-0.7.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: explainiverse
-Version: 0.6.0
+Version: 0.7.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 **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.
+**Explainiverse** is a unified, extensible Python framework for Explainable AI (XAI). It provides a standardized interface for **17 state-of-the-art explanation methods** across local, global, gradient-based, concept-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 |
 |---------|-------------|
-| **16 Explainers** | LIME, KernelSHAP, TreeSHAP, Integrated Gradients, DeepLIFT, DeepSHAP, SmoothGrad, Saliency Maps, GradCAM/GradCAM++, Anchors, Counterfactual, Permutation Importance, PDP, ALE, SAGE, ProtoDash |
+| **17 Explainers** | LIME, KernelSHAP, TreeSHAP, Integrated Gradients, DeepLIFT, DeepSHAP, SmoothGrad, Saliency Maps, GradCAM/GradCAM++, TCAV, 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 |
@@ -66,6 +66,7 @@ Description-Content-Type: text/markdown
 | **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) |
+| **TCAV** | Concept-Based | [Kim et al., 2018](https://arxiv.org/abs/1711.11279) |
 | **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) |
 | **ProtoDash** | Example-Based | [Gurumoorthy et al., 2019](https://arxiv.org/abs/1707.01212) |
@@ -142,8 +143,8 @@ adapter = SklearnAdapter(model, class_names=iris.target_names.tolist())
 # List all available explainers
 print(default_registry.list_explainers())
 # ['lime', 'shap', 'treeshap', 'integrated_gradients', 'deeplift', 'deepshap', 
-#  'smoothgrad', 'gradcam', 'anchors', 'counterfactual', 'protodash',
-#  'permutation_importance', 'partial_dependence', 'ale', 'sage']
+#  'smoothgrad', 'saliency', 'gradcam', 'tcav', 'anchors', 'counterfactual', 
+#  'protodash', 'permutation_importance', 'partial_dependence', 'ale', 'sage']
 
 # Create an explainer via registry
 explainer = default_registry.create(
@@ -317,6 +318,56 @@ heatmap = explanation.explanation_data["heatmap"]
 overlay = explainer.get_overlay(original_image, heatmap, alpha=0.5)
 ```
 
+### TCAV (Concept-Based Explanations)
+
+```python
+from explainiverse.explainers.gradient import TCAVExplainer
+
+# For neural network models with concept examples
+adapter = PyTorchAdapter(model, task="classification", class_names=class_names)
+
+# Create TCAV explainer targeting a specific layer
+explainer = TCAVExplainer(
+    model=adapter,
+    layer_name="layer3",  # Target layer for concept analysis
+    class_names=class_names
+)
+
+# Learn a concept from examples (e.g., "striped" pattern)
+explainer.learn_concept(
+    concept_name="striped",
+    concept_examples=striped_images,      # Images with stripes
+    negative_examples=random_images,      # Random images without stripes
+    min_accuracy=0.6                      # Minimum CAV classifier accuracy
+)
+
+# Compute TCAV score: fraction of inputs where concept positively influences prediction
+tcav_score = explainer.compute_tcav_score(
+    test_inputs=test_images,
+    target_class=0,           # e.g., "zebra"
+    concept_name="striped"
+)
+print(f"TCAV score: {tcav_score:.3f}")  # >0.5 means concept positively influences class
+
+# Statistical significance testing against random concepts
+result = explainer.statistical_significance_test(
+    test_inputs=test_images,
+    target_class=0,
+    concept_name="striped",
+    n_random=10,
+    negative_examples=random_images
+)
+print(f"p-value: {result['p_value']:.4f}, significant: {result['significant']}")
+
+# Full explanation with multiple concepts
+explanation = explainer.explain(
+    test_inputs=test_images,
+    target_class=0,
+    run_significance_test=True
+)
+print(explanation.explanation_data["tcav_scores"])
+```
+
 ---
 
 ## Example-Based Explanations
@@ -551,7 +602,7 @@ explainiverse/
 │   └── pytorch_adapter.py  # With gradient support
 ├── explainers/
 │   ├── attribution/      # LIME, SHAP, TreeSHAP
-│   ├── gradient/         # IG, DeepLIFT, DeepSHAP, SmoothGrad, GradCAM
+│   ├── gradient/         # IG, DeepLIFT, DeepSHAP, SmoothGrad, Saliency, GradCAM, TCAV
 │   ├── rule_based/       # Anchors
 │   ├── counterfactual/   # DiCE-style
 │   ├── global_explainers/  # Permutation, PDP, ALE, SAGE
@@ -589,6 +640,7 @@ poetry run pytest tests/test_smoothgrad.py::TestSmoothGradBasic -v
 - [x] Core framework (BaseExplainer, Explanation, Registry)
 - [x] Perturbation methods: LIME, KernelSHAP, TreeSHAP
 - [x] Gradient methods: Integrated Gradients, DeepLIFT, DeepSHAP, SmoothGrad, Saliency Maps, GradCAM/GradCAM++
+- [x] Concept-based: TCAV (Testing with Concept Activation Vectors)
 - [x] Rule-based: Anchors
 - [x] Counterfactual: DiCE-style
 - [x] Global: Permutation Importance, PDP, ALE, SAGE
@@ -598,7 +650,6 @@ poetry run pytest tests/test_smoothgrad.py::TestSmoothGradBasic -v
 - [x] PyTorch adapter with gradient support
 
 ### In Progress 🚧
-- [ ] TCAV (Testing with Concept Activation Vectors)
 - [ ] Layer-wise Relevance Propagation (LRP)
 
 ### Planned 📋
@@ -620,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.6.0}
+  version = {0.7.0}
 }
 ```
 
@@ -648,5 +699,5 @@ MIT License - see [LICENSE](LICENSE) for details.
 
 ## Acknowledgments
 
-Explainiverse builds upon the foundational work of many researchers in the XAI community. We thank the authors of LIME, SHAP, Integrated Gradients, DeepLIFT, GradCAM, Anchors, DiCE, ALE, SAGE, and ProtoDash for their contributions to interpretable machine learning.
+Explainiverse builds upon the foundational work of many researchers in the XAI community. We thank the authors of LIME, SHAP, Integrated Gradients, DeepLIFT, GradCAM, TCAV, Anchors, DiCE, ALE, SAGE, and ProtoDash for their contributions to interpretable machine learning.
 

{explainiverse-0.6.0.dist-info → explainiverse-0.7.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-explainiverse/__init__.py,sha256=oVivthTc0ts34DyEPWhilq7YOGYDjLLRvWxoKYHsIlo,1612
+explainiverse/__init__.py,sha256=u67gp9ZbzMDs2ECjXvs4aZUbjELRPfx32jGszJhhZ7U,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,7 +6,7 @@ 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=ZIq9Jzrr_oXi5tvGmY0k9gVNA34EtGIeTpWO5hQ3iVg,25527
+explainiverse/core/registry.py,sha256=BAqk2FKqbrZcoLqlODXRCOolb57DBgS-Kxs_CCtngvw,26376
 explainiverse/engine/__init__.py,sha256=1sZO8nH1mmwK2e-KUavBQm7zYDWUe27nyWoFy9tgsiA,197
 explainiverse/engine/suite.py,sha256=sq8SK_6Pf0qRckTmVJ7Mdosu9bhkjAGPGN8ymLGFP9E,4914
 explainiverse/evaluation/__init__.py,sha256=ePE97KwSjg_IChZ03DeQax8GruTjx-BVrMSi_nzoyoA,1501
@@ -28,15 +28,16 @@ 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=-A6hk5k9kbSOf8iTkzWvpnQ6SRVc72KvpVUH_1fuFNI,805
+explainiverse/explainers/gradient/__init__.py,sha256=Tkf9jiXVfjVVDAhBocDc2tzFJK8RZv8H1pN8J0Ha53o,1362
 explainiverse/explainers/gradient/deeplift.py,sha256=MWOlslizUeoZs31moy2iBgp02N08nBsVU-RoEpODg3M,27775
 explainiverse/explainers/gradient/gradcam.py,sha256=ywW_8PhALwegkpSUDQMFvvVFkA5NnMMW6BB5tb3i8bw,13721
 explainiverse/explainers/gradient/integrated_gradients.py,sha256=feBgY3Vw2rDti7fxRZtLkxse75m2dbP_R05ARqo2BRM,13367
 explainiverse/explainers/gradient/saliency.py,sha256=pcimyuSqKzsIR1yCMNWfH2M7T_vcDKkwcVv0zQlPL3w,10305
 explainiverse/explainers/gradient/smoothgrad.py,sha256=COIKZSFcApmMkA62M0AForHiYlQ6hSFx5hZIabRXGlM,15727
+explainiverse/explainers/gradient/tcav.py,sha256=zc-8wMsc2ZOhUeSZNBJ6H6BPXlVMJ9DRcAMiL25wU9I,32242
 explainiverse/explainers/rule_based/__init__.py,sha256=gKzlFCAzwurAMLJcuYgal4XhDj1thteBGcaHWmN7iWk,243
 explainiverse/explainers/rule_based/anchors_wrapper.py,sha256=ML7W6aam-eMGZHy5ilol8qupZvNBJpYAFatEEPnuMyo,13254
-explainiverse-0.6.0.dist-info/LICENSE,sha256=28rbHe8rJgmUlRdxJACfq1Sj-MtCEhyHxkJedQd1ZYA,1070
-explainiverse-0.6.0.dist-info/METADATA,sha256=KLQeJ57yUbYptTo5uS7IaVA3i6I60n3qXS7vfbW8vaU,19569
-explainiverse-0.6.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
-explainiverse-0.6.0.dist-info/RECORD,,
+explainiverse-0.7.0.dist-info/LICENSE,sha256=28rbHe8rJgmUlRdxJACfq1Sj-MtCEhyHxkJedQd1ZYA,1070
+explainiverse-0.7.0.dist-info/METADATA,sha256=DoZnwq5ew4n_xKcuoWu7Xi6uPb386yUTeDMPHWsWg1s,21352
+explainiverse-0.7.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+explainiverse-0.7.0.dist-info/RECORD,,