case-explainer 0.1.1__py3-none-any.whl

case_explainer/__init__.py

@@ -0,0 +1,13 @@
+"""
+Case-Explainer: General-Purpose Case-Based Explainability Module
+
+Provides model-agnostic explanations through training set precedent and 
+nearest neighbor correspondence.
+"""
+
+from .explainer import CaseExplainer
+from .explanation import Explanation
+from .metrics import compute_correspondence, euclidean_distance
+
+__version__ = "0.1.0"
+__all__ = ["CaseExplainer", "Explanation", "compute_correspondence", "euclidean_distance"]

case_explainer/explainer.py

@@ -0,0 +1,318 @@
+"""
+Main CaseExplainer class for case-based explanations.
+
+Based on refined Method 2 (case-based) from hardware trojan detection pipeline.
+Uses sklearn's NearestNeighbors for efficient k-NN lookups with pre-built index.
+"""
+
+import logging
+import numpy as np
+import pandas as pd
+from typing import List, Optional, Dict, Any, Union
+from sklearn.preprocessing import StandardScaler
+from sklearn.neighbors import NearestNeighbors
+
+logger = logging.getLogger(__name__)
+
+from .explanation import Explanation, Neighbor
+from .metrics import compute_correspondence
+
+
+class CaseExplainer:
+    """
+    General-purpose case-based explainability module.
+    
+    Provides model-agnostic explanations through training set precedent
+    and nearest neighbor correspondence. Builds k-NN index during initialization
+    for fast lookups during explanation.
+    
+    Based on refined Method 2 from hardware trojan detection pipeline:
+    - Pre-builds NearestNeighbors index on training data
+    - Uses distance-weighted correspondence: weight = 1 / (distance + 1)^3
+    - Supports class weights for imbalanced datasets
+    - Compatible with any classifier (sklearn, XGBoost, etc.)
+    
+    Example:
+        >>> from case_explainer import CaseExplainer
+        >>> explainer = CaseExplainer(X_train, y_train, k=5)
+        >>> explanation = explainer.explain_instance(test_sample, model=clf)
+        >>> print(f"Correspondence: {explanation.correspondence:.2%}")
+        >>> explanation.plot()
+    """
+    
+    def __init__(
+        self,
+        X_train: Union[np.ndarray, pd.DataFrame],
+        y_train: Union[np.ndarray, pd.Series, List],
+        k: int = 5,
+        feature_names: Optional[List[str]] = None,
+        class_names: Optional[Dict[int, str]] = None,
+        metric: str = 'euclidean',
+        algorithm: str = 'auto',
+        scale_data: bool = True,
+        class_weights: Optional[Dict[int, float]] = None,
+        metadata: Optional[Dict[str, List]] = None,
+        n_jobs: int = -1
+    ):
+        """
+        Initialize CaseExplainer with training data and build k-NN index.
+        
+        Args:
+            X_train: Training features (n_samples, n_features)
+            y_train: Training labels (n_samples,)
+            k: Number of nearest neighbors for explanations (default: 5)
+            feature_names: Names of features (optional)
+            class_names: Mapping from class labels to names (optional)
+            metric: Distance metric (default: 'euclidean')
+            algorithm: k-NN algorithm - 'auto', 'ball_tree', 'kd_tree', 'brute' (default: 'auto')
+            scale_data: Whether to standardize features (recommended: True)
+            class_weights: Optional weights for each class in correspondence computation
+                          e.g., {0: 1.0, 1: 2.0} to weight class 1 twice as much
+            metadata: Optional dict with metadata for each training sample
+                     e.g., {'sample_id': [...], 'source': [...], ...}
+            n_jobs: Number of parallel jobs for k-NN search (-1 = all CPUs)
+        """
+        # Convert inputs to numpy arrays
+        if isinstance(X_train, pd.DataFrame):
+            if feature_names is None:
+                feature_names = X_train.columns.tolist()
+            X_train = X_train.values
+        else:
+            X_train = np.asarray(X_train)
+        
+        if isinstance(y_train, (pd.Series, list)):
+            y_train = np.asarray(y_train)
+        
+        # Store original data
+        self.X_train_original = X_train.copy()
+        self.y_train = y_train.copy()
+        
+        # Validate shapes
+        if len(X_train) != len(y_train):
+            raise ValueError(f"X_train and y_train must have same length "
+                           f"(got {len(X_train)} and {len(y_train)})")
+        
+        self.n_samples, self.n_features = X_train.shape
+        self.k = k
+        self.feature_names = feature_names or [f"feature_{i}" for i in range(self.n_features)]
+        self.class_names = class_names or {}
+        self.metric = metric
+        self.algorithm = algorithm
+        self.scale_data = scale_data
+        self.class_weights = class_weights or {}
+        self.metadata = metadata or {}
+        self.n_jobs = n_jobs
+        
+        # Validate metadata
+        if self.metadata:
+            for key, values in self.metadata.items():
+                if len(values) != self.n_samples:
+                    raise ValueError(f"Metadata '{key}' has {len(values)} items, "
+                                   f"expected {self.n_samples}")
+        
+        # Scale data if requested
+        if scale_data:
+            self.scaler = StandardScaler()
+            self.X_train_scaled = self.scaler.fit_transform(X_train)
+        else:
+            self.scaler = None
+            self.X_train_scaled = X_train.copy()
+        
+        # Build k-NN index using sklearn's NearestNeighbors
+        # This is done once during initialization for efficiency
+        logger.info("Building k-NN index (k=%d, metric=%s, algorithm=%s)...", k, metric, algorithm)
+        self.nn_index = NearestNeighbors(
+            n_neighbors=min(k, self.n_samples),  # Handle case where k > n_samples
+            metric=metric,
+            algorithm=algorithm,
+            n_jobs=n_jobs
+        )
+        self.nn_index.fit(self.X_train_scaled)
+        logger.info("Index built on %d training samples", self.n_samples)
+    
+    def explain_instance(
+        self,
+        test_sample: Union[np.ndarray, pd.Series, List],
+        test_index: Optional[int] = None,
+        true_class: Optional[int] = None,
+        predicted_class: Optional[int] = None,
+        model: Optional[Any] = None,
+        k: Optional[int] = None,
+        return_provenance: bool = True,
+        distance_weighted: bool = True
+    ) -> Explanation:
+        """
+        Explain a prediction using case-based reasoning with k-NN precedent.
+        
+        This method:
+        1. Finds k nearest neighbors in the pre-built index
+        2. Computes weighted correspondence based on neighbor labels
+        3. Returns explanation with neighbor details and correspondence score
+        
+        Args:
+            test_sample: Sample to explain (n_features,)
+            test_index: Index in test set (optional, for tracking)
+            true_class: True class label (optional, for validation)
+            predicted_class: Predicted class (optional, will use model if not provided)
+            model: Trained model with predict() method (optional)
+            k: Number of neighbors (optional, uses default from init if not provided)
+            return_provenance: Include metadata in explanation
+            distance_weighted: Use distance weighting for correspondence
+            
+        Returns:
+            Explanation object with neighbors and correspondence
+        """
+        # Convert test sample to numpy array
+        if isinstance(test_sample, (pd.Series, list)):
+            test_sample = np.asarray(test_sample)
+        
+        if len(test_sample) != self.n_features:
+            raise ValueError(f"test_sample has {len(test_sample)} features, "
+                           f"expected {self.n_features}")
+        
+        # Scale test sample if needed
+        if self.scale_data:
+            test_sample_scaled = self.scaler.transform([test_sample])[0]
+        else:
+            test_sample_scaled = test_sample.copy()
+        
+        # Get prediction if not provided
+        if predicted_class is None:
+            if model is None:
+                raise ValueError("Either predicted_class or model must be provided")
+            predicted_class = int(model.predict([test_sample])[0])
+        
+        # Query pre-built k-NN index
+        k_actual = k if k is not None else self.k
+        k_actual = min(k_actual, self.n_samples)  # Handle case where k > n_samples
+        
+        distances, indices = self.nn_index.kneighbors(
+            [test_sample_scaled],
+            n_neighbors=k_actual
+        )
+        distances = distances[0]
+        indices = indices[0]
+        
+        # Create Neighbor objects
+        neighbors = []
+        for idx, dist in zip(indices, distances):
+            neighbor_metadata = {}
+            if return_provenance and self.metadata:
+                for key, values in self.metadata.items():
+                    neighbor_metadata[key] = values[idx]
+            
+            neighbor = Neighbor(
+                index=int(idx),
+                distance=float(dist),
+                label=int(self.y_train[idx]),
+                features=self.X_train_original[idx].copy(),
+                metadata=neighbor_metadata if neighbor_metadata else None
+            )
+            neighbors.append(neighbor)
+        
+        # Compute correspondence with optional class weighting
+        neighbor_tuples = [(n.index, n.distance, n.label) for n in neighbors]
+        correspondence, interpretation = compute_correspondence(
+            neighbor_tuples,
+            predicted_class,
+            distance_weighted=distance_weighted,
+            class_weights=self.class_weights
+        )
+        
+        # Create explanation
+        explanation = Explanation(
+            test_sample=test_sample.copy(),
+            test_index=test_index,
+            neighbors=neighbors,
+            predicted_class=predicted_class,
+            true_class=true_class,
+            correspondence=correspondence,
+            correspondence_interpretation=interpretation,
+            feature_names=self.feature_names,
+            class_names=self.class_names
+        )
+        
+        return explanation
+    
+    def explain_batch(
+        self,
+        X_test: Union[np.ndarray, pd.DataFrame],
+        y_test: Optional[Union[np.ndarray, pd.Series, List]] = None,
+        predictions: Optional[Union[np.ndarray, List]] = None,
+        model: Optional[Any] = None,
+        k: Optional[int] = None,
+        return_provenance: bool = True,
+        distance_weighted: bool = True
+    ) -> List[Explanation]:
+        """
+        Explain multiple predictions efficiently.
+        
+        Args:
+            X_test: Test samples (n_samples, n_features)
+            y_test: True labels (optional)
+            predictions: Predicted labels (optional, will use model if not provided)
+            model: Trained model (optional)
+            k: Number of neighbors (optional, uses default from init)
+            return_provenance: Include metadata
+            distance_weighted: Use distance weighting
+            
+        Returns:
+            List of Explanation objects
+        """
+        # Convert inputs
+        if isinstance(X_test, pd.DataFrame):
+            X_test = X_test.values
+        else:
+            X_test = np.asarray(X_test)
+        
+        if y_test is not None:
+            if isinstance(y_test, (pd.Series, list)):
+                y_test = np.asarray(y_test)
+        
+        if predictions is not None:
+            if isinstance(predictions, list):
+                predictions = np.asarray(predictions)
+        
+        # Generate explanations
+        explanations = []
+        for i, sample in enumerate(X_test):
+            true_class = None if y_test is None else int(y_test[i])
+            pred_class = None if predictions is None else int(predictions[i])
+            
+            explanation = self.explain_instance(
+                test_sample=sample,
+                test_index=i,
+                true_class=true_class,
+                predicted_class=pred_class,
+                model=model,
+                k=k,
+                return_provenance=return_provenance,
+                distance_weighted=distance_weighted
+            )
+            explanations.append(explanation)
+        
+        return explanations
+    
+    def get_training_info(self) -> Dict[str, Any]:
+        """Get information about the training data."""
+        unique_classes, class_counts = np.unique(self.y_train, return_counts=True)
+        
+        return {
+            "n_samples": self.n_samples,
+            "n_features": self.n_features,
+            "n_classes": len(unique_classes),
+            "classes": unique_classes.tolist(),
+            "class_counts": dict(zip(unique_classes.tolist(), class_counts.tolist())),
+            "feature_names": self.feature_names,
+            "class_names": self.class_names,
+            "algorithm": self.algorithm,
+            "metric": self.metric,
+            "scaled": self.scale_data,
+            "has_metadata": bool(self.metadata),
+            "default_k": self.k
+        }
+    
+    def __repr__(self) -> str:
+        return (f"CaseExplainer(n_samples={self.n_samples}, "
+                f"n_features={self.n_features}, "
+                f"k={self.k}, algorithm='{self.algorithm}')")

case_explainer/explanation.py

@@ -0,0 +1,233 @@
+"""
+Explanation object for case-based explanations.
+"""
+
+import numpy as np
+import matplotlib.pyplot as plt
+from typing import List, Tuple, Optional, Dict, Any
+
+
+class Neighbor:
+    """Represents a single nearest neighbor."""
+    
+    def __init__(
+        self,
+        index: int,
+        distance: float,
+        label: int,
+        features: np.ndarray,
+        metadata: Optional[Dict[str, Any]] = None
+    ):
+        self.index = index
+        self.distance = distance
+        self.label = label
+        self.features = features
+        self.metadata = metadata or {}
+    
+    def __repr__(self) -> str:
+        meta_str = f", {self.metadata}" if self.metadata else ""
+        return f"Neighbor(index={self.index}, distance={self.distance:.4f}, label={self.label}{meta_str})"
+
+
+class Explanation:
+    """
+    Explanation object containing case-based explanation details.
+    """
+    
+    def __init__(
+        self,
+        test_sample: np.ndarray,
+        test_index: Optional[int],
+        neighbors: List[Neighbor],
+        predicted_class: int,
+        true_class: Optional[int],
+        correspondence: float,
+        correspondence_interpretation: str,
+        feature_names: Optional[List[str]] = None,
+        class_names: Optional[Dict[int, str]] = None
+    ):
+        """
+        Initialize explanation.
+        
+        Args:
+            test_sample: The test sample being explained
+            test_index: Index in test set (if applicable)
+            neighbors: List of Neighbor objects
+            predicted_class: Predicted class label
+            true_class: True class label (if available)
+            correspondence: Correspondence score [0, 1]
+            correspondence_interpretation: "high", "medium", or "low"
+            feature_names: Names of features (optional)
+            class_names: Mapping from class labels to names (optional)
+        """
+        self.test_sample = test_sample
+        self.test_index = test_index
+        self.neighbors = neighbors
+        self.predicted_class = predicted_class
+        self.true_class = true_class
+        self.correspondence = correspondence
+        self.correspondence_interpretation = correspondence_interpretation
+        self.feature_names = feature_names or [f"feature_{i}" for i in range(len(test_sample))]
+        # Convert class_names list to dict if needed
+        if isinstance(class_names, list):
+            self.class_names = {i: name for i, name in enumerate(class_names)}
+        else:
+            self.class_names = class_names or {}
+    
+    def get_predicted_class_name(self) -> str:
+        """Get the predicted class name."""
+        return self.class_names.get(self.predicted_class, str(self.predicted_class))
+    
+    def get_true_class_name(self) -> Optional[str]:
+        """Get the true class name."""
+        if self.true_class is None:
+            return None
+        return self.class_names.get(self.true_class, str(self.true_class))
+    
+    def is_correct(self) -> Optional[bool]:
+        """Check if prediction matches true label (if available)."""
+        if self.true_class is None:
+            return None
+        return self.predicted_class == self.true_class
+    
+    def summary(self) -> str:
+        """Generate a text summary of the explanation."""
+        lines = []
+        lines.append("=" * 60)
+        lines.append("CASE-BASED EXPLANATION")
+        lines.append("=" * 60)
+        
+        if self.test_index is not None:
+            lines.append(f"Test sample index: {self.test_index}")
+        
+        lines.append(f"Predicted class: {self.get_predicted_class_name()}")
+        
+        if self.true_class is not None:
+            correct_str = "[OK]" if self.is_correct() else "[X]"
+            lines.append(f"True class: {self.get_true_class_name()} {correct_str}")
+        
+        lines.append(f"Correspondence: {self.correspondence:.2%} ({self.correspondence_interpretation})")
+        lines.append("")
+        lines.append(f"Nearest {len(self.neighbors)} neighbors:")
+        lines.append("-" * 60)
+        
+        for i, neighbor in enumerate(self.neighbors, 1):
+            neighbor_class = self.class_names.get(neighbor.label, str(neighbor.label))
+            match_str = "*" if neighbor.label == self.predicted_class else " "
+            lines.append(f"{i}. [{match_str}] Index {neighbor.index}: class {neighbor_class}, "
+                        f"distance {neighbor.distance:.4f}")
+            
+            # Add metadata if available
+            if neighbor.metadata:
+                for key, value in neighbor.metadata.items():
+                    lines.append(f"      {key}: {value}")
+        
+        lines.append("=" * 60)
+        return "\n".join(lines)
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Export explanation as dictionary (for JSON serialization)."""
+        return {
+            "test_index": self.test_index,
+            "test_sample": self.test_sample.tolist(),
+            "predicted_class": self.predicted_class,
+            "predicted_class_name": self.get_predicted_class_name(),
+            "true_class": self.true_class,
+            "true_class_name": self.get_true_class_name(),
+            "is_correct": self.is_correct(),
+            "correspondence": float(self.correspondence),
+            "correspondence_interpretation": self.correspondence_interpretation,
+            "neighbors": [
+                {
+                    "index": n.index,
+                    "distance": float(n.distance),
+                    "label": n.label,
+                    "label_name": self.class_names.get(n.label, str(n.label)),
+                    "features": n.features.tolist(),
+                    "metadata": n.metadata
+                }
+                for n in self.neighbors
+            ],
+            "feature_names": self.feature_names
+        }
+    
+    def plot(
+        self,
+        plot_type: str = 'radar',
+        highlight_differences: bool = True,
+        show_distances: bool = True,
+        save_path: Optional[str] = None,
+        figsize: Tuple[int, int] = (12, 8)
+    ) -> None:
+        """
+        Visualize the explanation.
+        
+        Args:
+            plot_type: 'radar', 'bar', or 'parallel'
+            highlight_differences: Whether to highlight feature differences
+            show_distances: Whether to show distance values
+            save_path: Path to save figure (if provided)
+            figsize: Figure size
+        """
+        if plot_type == 'bar':
+            self._plot_bar(figsize, save_path)
+        elif plot_type == 'radar':
+            self._plot_radar(figsize, save_path)
+        elif plot_type == 'parallel':
+            self._plot_parallel(figsize, save_path)
+        else:
+            raise ValueError(f"Unknown plot type: {plot_type}")
+    
+    def _plot_bar(self, figsize: Tuple[int, int], save_path: Optional[str]) -> None:
+        """Create bar plot comparing features."""
+        n_features = len(self.test_sample)
+        n_neighbors = len(self.neighbors)
+        
+        fig, ax = plt.subplots(figsize=figsize)
+        
+        x = np.arange(n_features)
+        width = 0.8 / (n_neighbors + 1)
+        
+        # Plot test sample
+        ax.bar(x, self.test_sample, width, label='Test Sample', 
+               color='red', alpha=0.8, edgecolor='black', linewidth=2)
+        
+        # Plot neighbors
+        colors = plt.cm.Blues(np.linspace(0.3, 0.8, n_neighbors))
+        for i, neighbor in enumerate(self.neighbors):
+            offset = width * (i + 1)
+            match_str = "*" if neighbor.label == self.predicted_class else ""
+            ax.bar(x + offset, neighbor.features, width,
+                   label=f'Neighbor {i+1} {match_str}', 
+                   color=colors[i], alpha=0.6)
+        
+        ax.set_xlabel('Features')
+        ax.set_ylabel('Feature Values')
+        ax.set_title(f'Case-Based Explanation (Correspondence: {self.correspondence:.2%})')
+        ax.set_xticks(x + width * n_neighbors / 2)
+        ax.set_xticklabels(self.feature_names, rotation=45, ha='right')
+        ax.legend()
+        ax.grid(axis='y', alpha=0.3)
+        
+        plt.tight_layout()
+        
+        if save_path:
+            plt.savefig(save_path, dpi=150, bbox_inches='tight')
+        else:
+            plt.show()
+    
+    def _plot_radar(self, figsize: Tuple[int, int], save_path: Optional[str]) -> None:
+        """Create radar plot (not implemented yet - use bar for now)."""
+        print("Radar plot not yet implemented, using bar plot instead.")
+        self._plot_bar(figsize, save_path)
+    
+    def _plot_parallel(self, figsize: Tuple[int, int], save_path: Optional[str]) -> None:
+        """Create parallel coordinates plot (not implemented yet - use bar for now)."""
+        print("Parallel coordinates plot not yet implemented, using bar plot instead.")
+        self._plot_bar(figsize, save_path)
+    
+    def __repr__(self) -> str:
+        return (f"Explanation(test_index={self.test_index}, "
+                f"predicted={self.get_predicted_class_name()}, "
+                f"correspondence={self.correspondence:.2%}, "
+                f"neighbors={len(self.neighbors)})")

case_explainer/indexing.py

@@ -0,0 +1,108 @@
+"""
+Indexing strategies for efficient nearest neighbor search.
+"""
+
+import numpy as np
+from typing import List, Tuple, Optional
+from sklearn.neighbors import KDTree, BallTree
+from abc import ABC, abstractmethod
+
+
+class IndexStrategy(ABC):
+    """Abstract base class for indexing strategies."""
+    
+    @abstractmethod
+    def build(self, X: np.ndarray) -> None:
+        """Build the index from data."""
+        pass
+    
+    @abstractmethod
+    def query(self, point: np.ndarray, k: int) -> Tuple[np.ndarray, np.ndarray]:
+        """
+        Query for k nearest neighbors.
+        
+        Returns:
+            distances: Array of distances (k,)
+            indices: Array of indices (k,)
+        """
+        pass
+
+
+class BruteForceIndex(IndexStrategy):
+    """Brute force search - computes all distances."""
+    
+    def __init__(self):
+        self.X = None
+    
+    def build(self, X: np.ndarray) -> None:
+        """Store the training data."""
+        self.X = X
+    
+    def query(self, point: np.ndarray, k: int) -> Tuple[np.ndarray, np.ndarray]:
+        """Find k nearest neighbors by computing all distances."""
+        from .metrics import compute_all_distances
+        
+        distances = compute_all_distances(point, self.X)
+        # Get indices of k smallest distances
+        indices = np.argpartition(distances, min(k, len(distances) - 1))[:k]
+        # Sort by distance
+        sorted_idx = np.argsort(distances[indices])
+        indices = indices[sorted_idx]
+        distances = distances[indices]
+        
+        return distances, indices
+
+
+class KDTreeIndex(IndexStrategy):
+    """K-D Tree for fast nearest neighbor search (best for low dimensions)."""
+    
+    def __init__(self, leaf_size: int = 30):
+        self.leaf_size = leaf_size
+        self.tree = None
+    
+    def build(self, X: np.ndarray) -> None:
+        """Build K-D tree."""
+        self.tree = KDTree(X, leaf_size=self.leaf_size, metric='euclidean')
+    
+    def query(self, point: np.ndarray, k: int) -> Tuple[np.ndarray, np.ndarray]:
+        """Query K-D tree for k nearest neighbors."""
+        distances, indices = self.tree.query([point], k=k)
+        return distances[0], indices[0]
+
+
+class BallTreeIndex(IndexStrategy):
+    """Ball Tree for nearest neighbor search (better for high dimensions)."""
+    
+    def __init__(self, leaf_size: int = 30):
+        self.leaf_size = leaf_size
+        self.tree = None
+    
+    def build(self, X: np.ndarray) -> None:
+        """Build Ball tree."""
+        self.tree = BallTree(X, leaf_size=self.leaf_size, metric='euclidean')
+    
+    def query(self, point: np.ndarray, k: int) -> Tuple[np.ndarray, np.ndarray]:
+        """Query Ball tree for k nearest neighbors."""
+        distances, indices = self.tree.query([point], k=k)
+        return distances[0], indices[0]
+
+
+def create_index(method: str = 'kd_tree', **kwargs) -> IndexStrategy:
+    """
+    Factory function to create an index.
+    
+    Args:
+        method: One of 'brute', 'kd_tree', 'ball_tree'
+        **kwargs: Additional arguments for the index
+        
+    Returns:
+        IndexStrategy instance
+    """
+    if method == 'brute':
+        return BruteForceIndex()
+    elif method == 'kd_tree':
+        return KDTreeIndex(**kwargs)
+    elif method == 'ball_tree':
+        return BallTreeIndex(**kwargs)
+    else:
+        raise ValueError(f"Unknown index method: {method}")

case_explainer/metrics.py

@@ -0,0 +1,111 @@
+"""
+Distance metrics and correspondence calculation.
+"""
+
+import numpy as np
+from scipy.spatial import distance as scipy_distance
+from typing import List, Tuple, Optional, Dict
+
+
+def euclidean_distance(point1: np.ndarray, point2: np.ndarray) -> float:
+    """
+    Calculate Euclidean distance between two points.
+    
+    Args:
+        point1: First point as numpy array
+        point2: Second point as numpy array
+        
+    Returns:
+        Euclidean distance as float
+    """
+    return scipy_distance.euclidean(point1, point2)
+
+
+def compute_correspondence(
+    neighbors: List[Tuple[int, float, int]],
+    predicted_class: int,
+    distance_weighted: bool = True,
+    class_weights: Optional[Dict[int, float]] = None
+) -> Tuple[float, str]:
+    """
+    Quantify agreement between prediction and retrieved neighbors.
+    
+    Based on refined Method 2 formula from hardware trojan detection pipeline:
+    weight(class_c) = sum_{i in neighbors with class c} class_weight_c / (distance_i + 1)^3
+    
+    Correspondence = weight(predicted_class) / sum(weight(all_classes))
+    
+    Args:
+        neighbors: List of tuples (index, distance, label) for k nearest neighbors
+        predicted_class: The predicted class label
+        distance_weighted: Whether to weight by inverse cubed distance (default: True)
+        class_weights: Optional weights for each class, e.g., {0: 1.0, 1: 2.0}
+                      for imbalanced datasets (default: all weights = 1.0)
+        
+    Returns:
+        correspondence: float in [0, 1]
+        interpretation: "high" (>0.85), "medium" (0.70-0.85), "low" (<0.70)
+    """
+    if not neighbors:
+        return 0.0, "undefined"
+    
+    # Default class weights to 1.0 if not provided
+    if class_weights is None:
+        class_weights = {}
+    
+    if distance_weighted:
+        # Weight by inverse cubed distance (refined formula from pipeline)
+        # weight = class_weight / (distance + 1)^3
+        class_weight_sums = {}
+        for _, dist, label in neighbors:
+            weight_multiplier = class_weights.get(label, 1.0)
+            weight = weight_multiplier / ((dist + 1.0) ** 3)
+            
+            if label not in class_weight_sums:
+                class_weight_sums[label] = 0.0
+            class_weight_sums[label] += weight
+        
+        total_weight = sum(class_weight_sums.values())
+        if total_weight == 0:
+            return 0.0, "undefined"
+            
+        correspondence = class_weight_sums.get(predicted_class, 0.0) / total_weight
+    else:
+        # Simple voting with class weights
+        class_counts = {}
+        for _, _, label in neighbors:
+            weight = class_weights.get(label, 1.0)
+            if label not in class_counts:
+                class_counts[label] = 0.0
+            class_counts[label] += weight
+        
+        total_count = sum(class_counts.values())
+        if total_count == 0:
+            return 0.0, "undefined"
+            
+        correspondence = class_counts.get(predicted_class, 0.0) / total_count
+    
+    # Interpret correspondence
+    if correspondence >= 0.85:
+        interpretation = "high"
+    elif correspondence >= 0.70:
+        interpretation = "medium"
+    else:
+        interpretation = "low"
+    
+    return correspondence, interpretation
+
+
+def compute_all_distances(point: np.ndarray, data: np.ndarray) -> np.ndarray:
+    """
+    Compute Euclidean distances from a point to all points in a dataset.
+    
+    Args:
+        point: Query point as 1D numpy array
+        data: Dataset as 2D numpy array (n_samples, n_features)
+        
+    Returns:
+        Array of distances (n_samples,)
+    """
+    # scipy_distance.cdist is faster than a loop
+    return scipy_distance.cdist([point], data, metric='euclidean')[0]

case_explainer-0.1.1.dist-info/METADATA

@@ -0,0 +1,424 @@
+Metadata-Version: 2.4
+Name: case-explainer
+Version: 0.1.1
+Summary: General-purpose case-based explainability for machine learning
+Home-page: https://github.com/paulwhitten/case-explainer
+Author: Paul Whitten
+Author-email: Paul Whitten <pcw@case.edu>
+License: MIT
+Project-URL: Homepage, https://github.com/paulwhitten/case-explainer
+Project-URL: Documentation, https://paulwhitten.github.io/case-explainer/
+Project-URL: Repository, https://github.com/paulwhitten/case-explainer
+Project-URL: Bug Tracker, https://github.com/paulwhitten/case-explainer/issues
+Keywords: explainability,interpretability,machine-learning,case-based-reasoning,nearest-neighbors
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: scipy>=1.7.0
+Requires-Dist: scikit-learn>=1.0.0
+Requires-Dist: matplotlib>=3.3.0
+Requires-Dist: pandas>=1.3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
+Requires-Dist: black>=22.0.0; extra == "dev"
+Requires-Dist: flake8>=4.0.0; extra == "dev"
+Requires-Dist: mypy>=0.950; extra == "dev"
+Requires-Dist: build>=0.10.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# Case-Explainer: General-Purpose Case-Based Explainability
+
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![PyPI version](https://img.shields.io/pypi/v/case-explainer.svg)](https://pypi.org/project/case-explainer/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Documentation](https://img.shields.io/badge/docs-online-blue.svg)](https://paulwhitten.github.io/case-explainer/)
+[![CI](https://github.com/paulwhitten/case-explainer/actions/workflows/ci.yml/badge.svg)](https://github.com/paulwhitten/case-explainer/actions/workflows/ci.yml)
+
+Provides model-agnostic explanations through training set precedent and nearest neighbor correspondence.
+
+**[Read the full documentation](https://paulwhitten.github.io/case-explainer/)**
+
+## What is Case-Based Explainability?
+
+While some explainability methods provide feature importance scores, case-based explainability answers: **"Why was this prediction made?"** by showing similar training examples.
+
+Instead of: *"Feature X has importance 0.45"*  
+You get: *"This sample is classified as X because it resembles these 5 training examples"*
+
+## Features
+
+- **Model-agnostic**: Works with any classifier (sklearn, XGBoost, neural networks, etc.)
+- **Correspondence metric**: Quantifies agreement between prediction and neighbors
+- **Multiple indexing strategies**: K-D Tree, Ball Tree, or brute force
+- **Automatic scaling**: Optional feature standardization
+- **Metadata tracking**: Attach provenance data to training samples
+- **Sklearn-compatible API**: Familiar interface for ML practitioners
+- **Batch explanations**: Explain multiple predictions efficiently
+
+## Installation
+
+```bash
+pip install case-explainer
+```
+
+Or, to install the latest development version from source:
+
+```bash
+git clone https://github.com/paulwhitten/case-explainer.git
+cd case-explainer
+pip install -e .
+
+# With development/test dependencies (pytest, pytest-cov, etc.)
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+from case_explainer import CaseExplainer
+from sklearn.datasets import load_iris
+from sklearn.model_selection import train_test_split
+from sklearn.ensemble import RandomForestClassifier
+
+# Load data
+X, y = load_iris(return_X_y=True)
+X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.3)
+
+# Train classifier
+clf = RandomForestClassifier()
+clf.fit(X_train, y_train)
+
+# Create explainer
+explainer = CaseExplainer(
+    X_train=X_train,
+    y_train=y_train,
+    feature_names=['sepal_len', 'sepal_width', 'petal_len', 'petal_width'],
+    algorithm='kd_tree'
+)
+
+# Explain a prediction
+explanation = explainer.explain_instance(X_test[0], k=5, model=clf)
+print(f"Correspondence: {explanation.correspondence:.2%}")
+print(explanation.summary())
+```
+
+## Core Concepts
+
+### Correspondence Metric
+
+Quantifies agreement between prediction and retrieved neighbors using inverse-cubed distance weighting:
+
+```
+w(c) = sum[ 1 / (distance + 1)^3 ] for neighbors with class c
+Correspondence = w(predicted_class) / sum( w(all_classes) )
+```
+
+The `+1` offset in the denominator prevents division by zero when a test sample is identical to a training sample (distance = 0). In that case the weight is simply `1 / 1 = 1`.
+
+**Example Interpretation Thresholds** (domain-dependent, not universal standards):
+- **High (≥85%)**: Strong agreement with training precedent
+- **Medium (70-85%)**: Moderate agreement
+- **Low (<70%)**: Weak agreement, prediction may be uncertain
+
+*Note: These thresholds are illustrative examples. Appropriate thresholds should be determined empirically for each specific domain and use case based on validation studies.*
+
+### Indexing Strategies
+
+- **`kd_tree`**: Fast for low-dimensional data (<20 features)
+- **`ball_tree`**: Better for high-dimensional data
+- **`brute`**: Exact search for small datasets (<10k samples)
+
+## Examples
+
+See `quickstart.py` for a complete working example:
+
+```bash
+python quickstart.py
+```
+
+### Tutorial Notebooks
+
+Interactive Jupyter notebooks for each validated domain:
+
+- [Iris Classification](notebooks/01_iris_tutorial.ipynb) - Introductory multi-class example
+- [Breast Cancer Diagnosis](notebooks/02_breast_cancer_tutorial.ipynb) - Medical diagnosis domain
+- [Fraud Detection](notebooks/03_fraud_detection_tutorial.ipynb) - Financial security with extreme class imbalance
+- [Hardware Trojan Detection](notebooks/04_hardware_trojan_tutorial.ipynb) - Large-scale security domain
+
+### Benchmarking
+
+Comprehensive performance benchmarks across multiple datasets:
+
+```bash
+python benchmark.py              # Full benchmark including MNIST
+python benchmark.py --no-mnist   # Skip MNIST (faster)
+python benchmark.py --help       # See all options
+```
+
+Results (single run on reference hardware):
+- **Speed**: 14-37 ms per explanation depending on dataset size
+- **Memory**: <1 MB to 131 MB (scales with data size and dimensionality)
+- **Correspondence**: 87-100% neighbor agreement across validated domains
+- **Scalability**: Tested up to 200k training samples
+
+**Note on Correspondence**: This metric measures agreement between predictions and retrieved neighbors, not prediction accuracy or quality. High correspondence indicates consistency with training data patterns, not necessarily correct predictions.
+
+### Documentation
+
+**[View full API documentation online](https://paulwhitten.github.io/case-explainer/)**
+
+Build and view documentation locally:
+
+```bash
+# Build documentation
+cd docs
+make html
+
+# View documentation locally
+python3 -m http.server 8000 --directory docs/_build/html
+# Then open http://localhost:8000 in your browser
+```
+
+The documentation includes:
+- Complete API reference for all classes and functions
+- Usage examples and code snippets
+- Theory and mathematical foundations
+- Configuration guides and best practices
+
+## Security & Privacy Considerations
+
+**IMPORTANT:** Case-based explanations expose actual training samples as evidence. This can leak sensitive information:
+
+- **Medical domains:** Patient records, diagnoses, treatments
+- **Financial domains:** Account details, transaction patterns
+- **Security domains:** Attack signatures, system vulnerabilities
+- **Personal data:** User behavior, preferences, demographics
+
+**Before using in production with sensitive data:**
+1. Implement feature masking for sensitive columns
+2. Consider differential privacy mechanisms
+3. Apply anonymization to metadata
+4. Set up access control and audit logging
+5. Review legal/regulatory requirements (GDPR, HIPAA, etc.)
+
+**Privacy protection features are planned for Phase 2.** For now, use only with non-sensitive data or in controlled research environments.
+
+Unlike LIME/SHAP which only show feature importance, case-explainer exposes training sample features. Evaluate whether this trade-off is acceptable for your use case.
+
+---
+
+## API Overview
+
+### CaseExplainer
+
+```python
+explainer = CaseExplainer(
+    X_train,                # Training features
+    y_train,                # Training labels
+    feature_names=None,     # Optional feature names
+    class_names=None,       # Optional class names {0: 'cat', 1: 'dog'}
+    algorithm='kd_tree',    # Indexing strategy
+    scale_data=True,        # Standardize features
+    metadata=None           # Optional provenance data
+)
+```
+
+### Explain Single Instance
+
+```python
+explanation = explainer.explain_instance(
+    test_sample,            # Sample to explain
+    k=5,                    # Number of neighbors
+    model=clf,              # Trained classifier
+    true_class=None,        # Optional true label
+    distance_weighted=True  # Use distance weighting
+)
+```
+
+### Explain Batch
+
+```python
+explanations = explainer.explain_batch(
+    X_test,                 # Test samples
+    k=5,                    # Number of neighbors
+    y_test=None,            # Optional true labels
+    model=clf               # Trained classifier
+)
+```
+
+### Explanation Object
+
+```python
+explanation.correspondence          # Correspondence score [0, 1]
+explanation.correspondence_interpretation  # 'high', 'medium', 'low'
+explanation.neighbors               # List of Neighbor objects
+explanation.predicted_class         # Predicted class
+explanation.is_correct()            # True if prediction matches label
+explanation.summary()               # Text summary
+explanation.to_dict()               # Export as dictionary
+explanation.plot()                  # Visualize (bar plot)
+```
+
+## Validated Domains
+
+**Hardware Trojan Detection** (56,959 samples, 5 features)
+- 99.3% average correspondence across indexing methods
+- High neighbor agreement on imbalanced security data
+- 25.7 ms/sample explanation time (single run, reference hardware)
+
+**Credit Card Fraud Detection** (284,807 samples, 30 features)
+- 100% average correspondence (complete agreement with retrieved neighbors)
+- Highly imbalanced dataset (268:1 normal:fraud ratio)
+- 36.4 ms/sample explanation time (single run, reference hardware)
+
+**Medical Diagnosis - Breast Cancer** (569 samples, 30 features)
+- 93.3% average correspondence
+- Correct predictions: 96.2% correspondence vs 47.3% for incorrect predictions
+- 25.9 ms/sample explanation time (single run, reference hardware)
+
+**Also Validated On:**
+- Iris (92.7%), Wine (91.8%), Digits (94.9%), MNIST (87.5%)
+- See `benchmark.py` for full results across 7 datasets
+
+*Note: Correspondence measures neighbor agreement, not prediction quality. High correspondence with incorrect predictions indicates the model has learned incorrect patterns in the training data.*
+
+## When to Use Case-Based Explainability
+
+**Case-Explainer is well-suited for scenarios where:**
+- Domain experts need to verify predictions against known training cases
+- Precedent-based reasoning is valued (medical diagnosis, legal decisions, security analysis)
+- Concrete examples are more intuitive than feature importance scores
+- Training data has provenance or metadata worth surfacing to users
+- Fast explanation generation is needed for real-time or interactive systems
+
+**Alternative approaches (LIME, SHAP) may be preferable when:**
+- Feature contributions are more relevant than training precedents
+- Training data cannot be exposed due to privacy/security constraints
+- Model debugging requires understanding feature-level behavior
+
+### Comparison with LIME and SHAP
+
+| Aspect | Case-Explainer | LIME | SHAP |
+|--------|---------------|------|------|
+| Explanation type | Training precedents (similar cases) | Local surrogate model (feature importance) | Shapley values (feature importance) |
+| Output | k nearest neighbors + correspondence score | Per-feature importance for one prediction | Per-feature importance (local and global) |
+| Privacy risk | High -- exposes actual training samples | Low -- uses synthetic perturbations | Low -- no sample exposure |
+| Speed (pipeline, HW trojan) | ~13 ms/sample | ~25 ms/sample | ~1 ms/sample (TreeSHAP) |
+| Model-agnostic | Yes | Yes | Yes (KernelSHAP); tree-specific variants are faster |
+| Best for | Precedent-based reasoning, domain expert verification | Local feature contributions, model debugging | Global + local feature analysis, theoretical guarantees |
+
+*Timing from the hardware trojan detection pipeline (XGBoost classifier, 5 features, ~57k samples). SHAP uses TreeSHAP which exploits tree structure for speed; KernelSHAP (model-agnostic) is substantially slower. LIME and Case-Explainer speeds are model-agnostic. Results will vary with dataset size, dimensionality, and hardware.*
+
+## Limitations
+
+**Privacy and Security**
+- Exposes actual training samples, which may contain sensitive information
+- Not suitable for sensitive data without additional privacy protection mechanisms
+- Privacy-preserving features are planned for future releases
+
+**Correspondence Metric**
+- Measures neighbor agreement, not prediction correctness or quality
+- High correspondence can occur with incorrect predictions if training data contains systematic errors
+- Thresholds for "high/medium/low" must be validated per domain
+
+**Performance Benchmarks**
+- Timing and memory results are from single runs on reference hardware
+- No statistical error bars or confidence intervals provided
+- Results may vary significantly on different hardware and with different parameters
+
+**Scalability**
+- Memory usage scales linearly with training set size
+- Very large datasets (>1M samples) may require approximate nearest neighbor methods (not yet implemented)
+
+**Interpretability**
+- Assumes users can meaningfully interpret feature values of retrieved neighbors
+- Multi-feature patterns may be difficult to assess without domain expertise
+- High-dimensional data may require dimensionality reduction for effective interpretation
+
+## Development Status
+
+### Core Functionality MVP
+- [x] CaseExplainer class with sklearn-compatible API
+- [x] Correspondence metric with distance weighting
+- [x] Multiple indexing strategies (K-D tree, Ball tree, brute force)
+- [x] Explanation object with summary and visualization
+- [x] Metadata/provenance tracking
+- [x] Batch explanation support
+
+### Phase 1: Multi-Domain Validation
+- [x] Hardware trojan detection (validated in JETTA paper)
+- [x] Medical diagnosis (UCI Breast Cancer)
+- [x] Fraud detection (Credit Card Fraud)
+- [x] Benchmarking (time, memory, correspondence)
+
+### Phase 2: Documentation - IN PROGRESS
+- [x] API reference
+- [x] Tutorial notebooks (4 domains)
+- [x] Comparison guide (vs LIME/SHAP)
+- [x] Code coverage >90%
+
+### Phase 3: Testing & Quality
+- [x] Unit test suite (pytest, >90% coverage)
+- [x] Multi-Python version compatibility (3.8–3.12)
+- [x] Integration tests across validated domains
+- [ ] Privacy-preserving features (feature masking, differential privacy)
+- [ ] Approximate nearest neighbors (Annoy, FAISS) for large-scale data
+
+### Phase 4: Release & Distribution
+- [x] PyPI package (`pip install case-explainer`)
+- [x] GitHub Pages documentation (https://paulwhitten.github.io/case-explainer/)
+- [x] CI/CD pipeline (GitHub Actions: test matrix, publish to PyPI)
+- [ ] Zenodo DOI
+
+## Citation
+
+If you use this module in academic work, please cite:
+
+```bibtex
+@software{case_explainer2025,
+  author = {Whitten, Paul and Wolff, Francis and Papachristou, Chris},
+  title = {Case-Explainer: General-Purpose Case-Based Explainability},
+  year = {2025},
+  url = {https://github.com/paulwhitten/case-explainer}
+}
+```
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Contributing
+
+Contributions welcome! Core functionality and release infrastructure are complete.
+
+**Priority areas:**
+- Additional distance metrics (Manhattan, Cosine)
+- Approximate nearest neighbors (Annoy, FAISS) for large-scale data
+- Radar and parallel coordinate visualizations
+- More comprehensive unit tests
+
+## Contact
+
+Questions? Issues? Open a GitHub issue or contact pcw@case.edu.
+
+## Acknowledgments
+
+- Inspired by Caruana et al. (1999) "Case-based explanation of non-case-based learning"
+- Validated on hardware trojan detection research
+- Built with scikit-learn, scipy, and matplotlib

case_explainer-0.1.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+case_explainer/__init__.py,sha256=Um44dCy3i570jUhtpj5pk8TF8-diFJ1R2lpKCu0CE3U,433
+case_explainer/explainer.py,sha256=E1wdNo8c46dlaQ8hQMcGMRzjt5qYwCYOmpKkgpLjoKc,12680
+case_explainer/explanation.py,sha256=cM_x9wfKa1cda7mBVz2h2DmU8Wuk7XUC3bQzsxWWT8Q,9115
+case_explainer/indexing.py,sha256=xK3onjsEH8mo8Vzz0EhhzUdqzOUyrp-bhw08gfsv-T8,3375
+case_explainer/metrics.py,sha256=BVK1ymb0dhpLex2J-Nn77gG-ybZY2VOBB6v4zei_nDA,3747
+case_explainer-0.1.1.dist-info/licenses/LICENSE,sha256=NgFFFRrWHUd7Z_rl5QnCQqZNRc3B5WhRa1sy87ubrrE,1104
+case_explainer-0.1.1.dist-info/METADATA,sha256=JEooQ_XZOVEdx3ySDdfwadHKxnxrorovGCLAAkUhTy8,16887
+case_explainer-0.1.1.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+case_explainer-0.1.1.dist-info/top_level.txt,sha256=682HZHMTXvyhYJa1vPUoTDcJRcrm7KDsL3nzURW91MA,15
+case_explainer-0.1.1.dist-info/RECORD,,

case_explainer-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

case_explainer-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Paul Whitten, Francis Wolff, Chris Papachristou
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

case_explainer-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+case_explainer