explainiverse 0.1.1a1__py3-none-any.whl → 0.2.0__py3-none-any.whl

explainiverse/explainers/global_explainers/partial_dependence.py

@@ -0,0 +1,192 @@
+# src/explainiverse/explainers/global_explainers/partial_dependence.py
+"""
+Partial Dependence Plot (PDP) Explainer.
+
+Shows the marginal effect of one or two features on the predicted outcome,
+averaging over the values of all other features.
+
+Reference:
+    Friedman, J.H. (2001). Greedy function approximation: A gradient boosting machine.
+    Annals of Statistics, 29(5), 1189-1232.
+"""
+
+import numpy as np
+from typing import List, Optional, Union, Tuple
+from explainiverse.core.explainer import BaseExplainer
+from explainiverse.core.explanation import Explanation
+
+
+class PartialDependenceExplainer(BaseExplainer):
+    """
+    Partial Dependence Plot (PDP) explainer.
+    
+    Computes the average prediction for each value of the feature(s) of interest,
+    marginalizing over all other features. This shows the relationship between
+    the feature and the predicted outcome.
+    
+    Attributes:
+        model: Model adapter with .predict() method
+        X: Training/reference data
+        feature_names: List of feature names
+        grid_resolution: Number of points in the PDP grid
+        percentile_range: Range of percentiles to use for grid (default: 5-95)
+    """
+    
+    def __init__(
+        self,
+        model,
+        X: np.ndarray,
+        feature_names: List[str],
+        grid_resolution: int = 50,
+        percentile_range: Tuple[float, float] = (5, 95)
+    ):
+        """
+        Initialize the PDP explainer.
+        
+        Args:
+            model: Model adapter with .predict() method
+            X: Reference dataset (n_samples, n_features)
+            feature_names: List of feature names
+            grid_resolution: Number of grid points for each feature
+            percentile_range: Tuple of (min_percentile, max_percentile) for grid
+        """
+        super().__init__(model)
+        self.X = np.array(X)
+        self.feature_names = list(feature_names)
+        self.grid_resolution = grid_resolution
+        self.percentile_range = percentile_range
+    
+    def _get_feature_idx(self, feature: Union[int, str]) -> int:
+        """Convert feature name to index if needed."""
+        if isinstance(feature, str):
+            return self.feature_names.index(feature)
+        return feature
+    
+    def _create_grid(self, feature_idx: int) -> np.ndarray:
+        """Create a grid of values for a feature."""
+        values = self.X[:, feature_idx]
+        grid = np.linspace(
+            np.percentile(values, self.percentile_range[0]),
+            np.percentile(values, self.percentile_range[1]),
+            self.grid_resolution
+        )
+        return grid
+    
+    def _compute_pdp_1d(self, feature_idx: int, target_class: int = 1) -> Tuple[np.ndarray, np.ndarray]:
+        """
+        Compute 1D partial dependence for a single feature.
+        
+        Args:
+            feature_idx: Index of the feature
+            target_class: Class index for which to compute PDP
+            
+        Returns:
+            Tuple of (grid_values, pdp_values)
+        """
+        grid = self._create_grid(feature_idx)
+        pdp_values = []
+        
+        for value in grid:
+            X_temp = self.X.copy()
+            X_temp[:, feature_idx] = value
+            
+            predictions = self.model.predict(X_temp)
+            
+            # Handle multi-class predictions
+            if predictions.ndim == 2:
+                avg_pred = np.mean(predictions[:, target_class])
+            else:
+                avg_pred = np.mean(predictions)
+            
+            pdp_values.append(avg_pred)
+        
+        return grid, np.array(pdp_values)
+    
+    def _compute_pdp_2d(
+        self,
+        feature_idx1: int,
+        feature_idx2: int,
+        target_class: int = 1
+    ) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+        """
+        Compute 2D partial dependence for feature interaction.
+        
+        Args:
+            feature_idx1: Index of first feature
+            feature_idx2: Index of second feature
+            target_class: Class index for which to compute PDP
+            
+        Returns:
+            Tuple of (grid1, grid2, pdp_values_2d)
+        """
+        grid1 = self._create_grid(feature_idx1)
+        grid2 = self._create_grid(feature_idx2)
+        
+        pdp_values = np.zeros((len(grid1), len(grid2)))
+        
+        for i, val1 in enumerate(grid1):
+            for j, val2 in enumerate(grid2):
+                X_temp = self.X.copy()
+                X_temp[:, feature_idx1] = val1
+                X_temp[:, feature_idx2] = val2
+                
+                predictions = self.model.predict(X_temp)
+                
+                if predictions.ndim == 2:
+                    avg_pred = np.mean(predictions[:, target_class])
+                else:
+                    avg_pred = np.mean(predictions)
+                
+                pdp_values[i, j] = avg_pred
+        
+        return grid1, grid2, pdp_values
+    
+    def explain(
+        self,
+        features: List[Union[int, str, Tuple[int, int]]],
+        target_class: int = 1,
+        **kwargs
+    ) -> Explanation:
+        """
+        Compute partial dependence for specified features.
+        
+        Args:
+            features: List of feature indices/names or tuples for interactions
+            target_class: Class index for which to compute PDP
+            
+        Returns:
+            Explanation object with PDP values and grids
+        """
+        pdp_results = {}
+        grid_results = {}
+        
+        for feature in features:
+            if isinstance(feature, tuple):
+                # 2D interaction
+                idx1 = self._get_feature_idx(feature[0])
+                idx2 = self._get_feature_idx(feature[1])
+                
+                grid1, grid2, pdp = self._compute_pdp_2d(idx1, idx2, target_class)
+                
+                key = f"{self.feature_names[idx1]}_x_{self.feature_names[idx2]}"
+                pdp_results[key] = pdp.tolist()
+                grid_results[key] = {"grid1": grid1.tolist(), "grid2": grid2.tolist()}
+            else:
+                # 1D PDP
+                idx = self._get_feature_idx(feature)
+                grid, pdp = self._compute_pdp_1d(idx, target_class)
+                
+                key = self.feature_names[idx]
+                pdp_results[key] = pdp.tolist()
+                grid_results[key] = grid.tolist()
+        
+        return Explanation(
+            explainer_name="PartialDependence",
+            target_class=f"class_{target_class}",
+            explanation_data={
+                "pdp_values": pdp_results,
+                "grid_values": grid_results,
+                "features_analyzed": [str(f) for f in features],
+                "interaction": any(isinstance(f, tuple) for f in features)
+            }
+        )

explainiverse/explainers/global_explainers/permutation_importance.py

@@ -0,0 +1,123 @@
+# src/explainiverse/explainers/global_explainers/permutation_importance.py
+"""
+Permutation Feature Importance Explainer.
+
+Measures feature importance by measuring the decrease in model performance
+when a feature's values are randomly shuffled.
+
+Reference:
+    Breiman, L. (2001). Random Forests. Machine Learning, 45(1), 5-32.
+"""
+
+import numpy as np
+from typing import List, Optional, Callable
+from sklearn.metrics import accuracy_score
+
+from explainiverse.core.explainer import BaseExplainer
+from explainiverse.core.explanation import Explanation
+
+
+class PermutationImportanceExplainer(BaseExplainer):
+    """
+    Global explainer based on permutation feature importance.
+    
+    Measures how much the model's performance decreases when each feature
+    is randomly shuffled, breaking the relationship between the feature
+    and the target.
+    
+    Attributes:
+        model: Model adapter with .predict() method
+        X: Feature matrix for evaluation
+        y: True labels
+        feature_names: List of feature names
+        n_repeats: Number of times to permute each feature
+        scoring_fn: Function to compute score (higher is better)
+        random_state: Random seed for reproducibility
+    """
+    
+    def __init__(
+        self,
+        model,
+        X: np.ndarray,
+        y: np.ndarray,
+        feature_names: List[str],
+        n_repeats: int = 10,
+        scoring_fn: Optional[Callable] = None,
+        random_state: int = 42
+    ):
+        """
+        Initialize the Permutation Importance explainer.
+        
+        Args:
+            model: Model adapter with .predict() method
+            X: Feature matrix (n_samples, n_features)
+            y: True labels (n_samples,)
+            feature_names: List of feature names
+            n_repeats: Number of permutation repeats per feature
+            scoring_fn: Custom scoring function (default: accuracy)
+            random_state: Random seed
+        """
+        super().__init__(model)
+        self.X = np.array(X)
+        self.y = np.array(y)
+        self.feature_names = feature_names
+        self.n_repeats = n_repeats
+        self.scoring_fn = scoring_fn or self._default_scorer
+        self.random_state = random_state
+        self.rng = np.random.RandomState(random_state)
+    
+    def _default_scorer(self, y_true: np.ndarray, y_pred: np.ndarray) -> float:
+        """Default scoring function: accuracy for classification."""
+        if y_pred.ndim == 2:
+            y_pred = np.argmax(y_pred, axis=1)
+        return accuracy_score(y_true, y_pred)
+    
+    def _compute_baseline_score(self) -> float:
+        """Compute model performance on unperturbed data."""
+        predictions = self.model.predict(self.X)
+        return self.scoring_fn(self.y, predictions)
+    
+    def _permute_feature(self, X: np.ndarray, feature_idx: int) -> np.ndarray:
+        """Create a copy of X with one feature permuted."""
+        X_permuted = X.copy()
+        self.rng.shuffle(X_permuted[:, feature_idx])
+        return X_permuted
+    
+    def explain(self, **kwargs) -> Explanation:
+        """
+        Compute permutation feature importance.
+        
+        Returns:
+            Explanation object with:
+                - feature_attributions: dict of {feature_name: importance}
+                - std: dict of {feature_name: std across repeats}
+                - baseline_score: original model score
+        """
+        baseline_score = self._compute_baseline_score()
+        
+        importances = {}
+        stds = {}
+        
+        for idx, fname in enumerate(self.feature_names):
+            scores = []
+            
+            for _ in range(self.n_repeats):
+                X_permuted = self._permute_feature(self.X, idx)
+                predictions = self.model.predict(X_permuted)
+                score = self.scoring_fn(self.y, predictions)
+                scores.append(score)
+            
+            # Importance = drop in score when feature is permuted
+            importance = baseline_score - np.mean(scores)
+            importances[fname] = float(importance)
+            stds[fname] = float(np.std(scores))
+        
+        return Explanation(
+            explainer_name="PermutationImportance",
+            target_class="global",
+            explanation_data={
+                "feature_attributions": importances,
+                "std": stds,
+                "baseline_score": baseline_score
+            }
+        )

explainiverse/explainers/global_explainers/sage.py

@@ -0,0 +1,164 @@
+# src/explainiverse/explainers/global_explainers/sage.py
+"""
+SAGE (Shapley Additive Global importancE) Explainer.
+
+SAGE extends SHAP to provide global feature importance by computing
+the expected Shapley value across all samples. This gives a theoretically
+grounded global importance measure.
+
+Reference:
+    Covert, I., Lundberg, S., & Lee, S.I. (2020). Understanding Global Feature
+    Contributions with Additive Importance Measures. NeurIPS 2020.
+"""
+
+import numpy as np
+from typing import List, Optional, Callable
+from sklearn.metrics import accuracy_score, mean_squared_error
+from explainiverse.core.explainer import BaseExplainer
+from explainiverse.core.explanation import Explanation
+
+
+class SAGEExplainer(BaseExplainer):
+    """
+    SAGE: Shapley Additive Global importancE.
+    
+    Computes global feature importance using Shapley values, averaging
+    contributions across all samples. Unlike permutation importance,
+    SAGE accounts for feature interactions.
+    
+    Attributes:
+        model: Model adapter with .predict() method
+        X: Feature matrix
+        y: Target values
+        feature_names: List of feature names
+        n_permutations: Number of permutation samples for approximation
+        loss_fn: Loss function (default: accuracy for classification)
+    """
+    
+    def __init__(
+        self,
+        model,
+        X: np.ndarray,
+        y: np.ndarray,
+        feature_names: List[str],
+        n_permutations: int = 100,
+        loss_fn: Optional[Callable] = None,
+        task: str = "classification",
+        random_state: int = 42
+    ):
+        """
+        Initialize the SAGE explainer.
+        
+        Args:
+            model: Model adapter with .predict() method
+            X: Feature matrix (n_samples, n_features)
+            y: Target values (n_samples,)
+            feature_names: List of feature names
+            n_permutations: Number of permutations for approximation
+            loss_fn: Custom loss function (lower is better)
+            task: "classification" or "regression"
+            random_state: Random seed
+        """
+        super().__init__(model)
+        self.X = np.array(X)
+        self.y = np.array(y)
+        self.feature_names = list(feature_names)
+        self.n_permutations = n_permutations
+        self.task = task
+        self.random_state = random_state
+        self.rng = np.random.RandomState(random_state)
+        
+        if loss_fn is None:
+            if task == "classification":
+                self.loss_fn = lambda y_true, y_pred: 1.0 - accuracy_score(
+                    y_true, np.argmax(y_pred, axis=1) if y_pred.ndim == 2 else y_pred
+                )
+            else:
+                self.loss_fn = lambda y_true, y_pred: mean_squared_error(y_true, y_pred)
+        else:
+            self.loss_fn = loss_fn
+    
+    def _compute_loss(self, X_masked: np.ndarray) -> float:
+        """Compute loss on masked data."""
+        predictions = self.model.predict(X_masked)
+        return self.loss_fn(self.y, predictions)
+    
+    def _marginal_contribution(
+        self,
+        feature_idx: int,
+        feature_order: List[int],
+        position: int
+    ) -> float:
+        """
+        Compute marginal contribution of a feature given a feature ordering.
+        
+        The marginal contribution is the change in loss when adding the feature
+        to the set of features that come before it in the ordering.
+        """
+        n_samples, n_features = self.X.shape
+        
+        # Features before this one in the ordering
+        features_before = set(feature_order[:position])
+        features_with = features_before | {feature_idx}
+        
+        # Create masked versions
+        X_without = self.X.copy()
+        X_with = self.X.copy()
+        
+        # Mask features NOT in the respective sets by replacing with random samples
+        for j in range(n_features):
+            if j not in features_before:
+                # Shuffle this feature (marginalizing out)
+                shuffle_idx = self.rng.permutation(n_samples)
+                X_without[:, j] = self.X[shuffle_idx, j]
+            
+            if j not in features_with:
+                shuffle_idx = self.rng.permutation(n_samples)
+                X_with[:, j] = self.X[shuffle_idx, j]
+        
+        loss_without = self._compute_loss(X_without)
+        loss_with = self._compute_loss(X_with)
+        
+        # Marginal contribution = reduction in loss
+        return loss_without - loss_with
+    
+    def explain(self, **kwargs) -> Explanation:
+        """
+        Compute SAGE values for all features.
+        
+        Uses permutation sampling to approximate the Shapley values.
+        
+        Returns:
+            Explanation object with global feature importance (SAGE values)
+        """
+        n_features = len(self.feature_names)
+        sage_values = np.zeros(n_features)
+        
+        for _ in range(self.n_permutations):
+            # Random feature ordering
+            order = self.rng.permutation(n_features).tolist()
+            
+            for position, feature_idx in enumerate(order):
+                contribution = self._marginal_contribution(
+                    feature_idx, order, position
+                )
+                sage_values[feature_idx] += contribution
+        
+        # Average over permutations
+        sage_values /= self.n_permutations
+        
+        # Create attribution dict
+        attributions = {
+            fname: float(sage_values[i])
+            for i, fname in enumerate(self.feature_names)
+        }
+        
+        return Explanation(
+            explainer_name="SAGE",
+            target_class="global",
+            explanation_data={
+                "feature_attributions": attributions,
+                "n_permutations": self.n_permutations,
+                "task": self.task
+            }
+        )

explainiverse/explainers/rule_based/__init__.py

@@ -0,0 +1,8 @@
+# src/explainiverse/explainers/rule_based/__init__.py
+"""
+Rule-based explainers - explanations in the form of if-then rules.
+"""
+
+from explainiverse.explainers.rule_based.anchors_wrapper import AnchorsExplainer
+
+__all__ = ["AnchorsExplainer"]