Spaces:
Sleeping
Sleeping
Download src/explainability/explainer.py from APEXPRIT/deception-analysis-api: direct link, hf CLI and curl.
- Browser
- Download file 23.8 kB
-
https://huggingface.co/spaces/APEXPRIT/deception-analysis-api/resolve/1fcb4a0c96fcffb7ed06fa7d5e69f73f5bb3c981/src/explainability/explainer.py
- Command line
-
hf download hf://spaces/APEXPRIT/deception-analysis-api@1fcb4a0c96fcffb7ed06fa7d5e69f73f5bb3c981/src/explainability/explainer.py
-
curl -L -o explainer.py https://huggingface.co/spaces/APEXPRIT/deception-analysis-api/resolve/1fcb4a0c96fcffb7ed06fa7d5e69f73f5bb3c981/src/explainability/explainer.py
23.8 kB
| """Explainability module for deception detection using SHAP and feature importance. | |
| This module provides interpretable explanations for deception predictions by | |
| combining SHAP values, feature importance, and domain knowledge to produce | |
| human-readable behavioral explanations. | |
| """ | |
| from __future__ import annotations | |
| import warnings | |
| from typing import Any, Dict, List, Optional, Tuple, Union | |
| import numpy as np | |
| import pandas as pd | |
| import shap | |
| from sklearn.inspection import permutation_importance | |
| from sklearn.utils import check_array | |
| from src.model.classifier import DeceptionClassifier | |
| class DeceptionExplainer: | |
| """Generates interpretable explanations for deception predictions. | |
| Combines SHAP values, feature importance, and domain knowledge | |
| to produce human-readable behavioral explanations. | |
| """ | |
| # Domain knowledge mapping: feature name -> behavioral interpretation | |
| FEATURE_INTERPRETATIONS = { | |
| 'eye_left_openness': 'Left eye openness (reduced blinking or gaze aversion may indicate deception)', | |
| 'eye_right_openness': 'Right eye openness (asymmetric eye behavior can signal cognitive load)', | |
| 'mouth_openness': 'Mouth openness (suppressed or exaggerated expressions may indicate deception)', | |
| 'mouth_width': 'Mouth width changes (forced smiles show different width patterns)', | |
| 'mouth_asymmetry': 'Mouth asymmetry (asymmetric expressions are harder to fake)', | |
| 'left_brow_height': 'Left eyebrow height (raised brows can indicate surprise or concern)', | |
| 'right_brow_height': 'Right eyebrow height (asymmetric brow activity linked to deception)', | |
| 'brow_asymmetry': 'Eyebrow asymmetry (involuntary micro-expressions often appear asymmetrically)', | |
| 'brow_tension': 'Eyebrow tension (furrowed brows indicate cognitive effort or stress)', | |
| 'nose_wrinkle': 'Nose wrinkle (disgust micro-expression, hard to fake voluntarily)', | |
| 'nostril_flare': 'Nostril flare (stress indicator, autonomic nervous system response)', | |
| 'nose_asymmetry': 'Nose asymmetry (subtle asymmetries reveal involuntary expressions)', | |
| 'head_pitch': 'Head pitch (nodding patterns differ between truthful and deceptive responses)', | |
| 'head_yaw': 'Head yaw (head turning can indicate avoidance behavior)', | |
| 'head_roll': 'Head tilt (unusual tilt patterns may indicate discomfort)', | |
| 'head_displacement': 'Head movement (excessive stillness or fidgeting both signal stress)', | |
| 'pitch_mean': 'Average pitch (elevated pitch is a stress indicator)', | |
| 'pitch_std': 'Pitch variability (reduced variability suggests rehearsed responses)', | |
| 'pitch_range': 'Pitch range (constricted range indicates tension)', | |
| 'pitch_variation_coefficient': 'Pitch variation coefficient (normalized pitch instability)', | |
| 'voiced_ratio': 'Voiced speech ratio (reduced voicing suggests hesitation)', | |
| 'pause_count': 'Number of pauses (increased pausing indicates cognitive load)', | |
| 'avg_pause_duration': 'Average pause length (longer pauses suggest response fabrication)', | |
| 'max_pause_duration': 'Longest pause (extended silence before answering is suspicious)', | |
| 'pause_rate': 'Pauses per minute (higher rate indicates cognitive effort)', | |
| 'speech_ratio': 'Speech ratio (less speech time relative to pauses suggests evasion)', | |
| 'energy_mean': 'Average speech energy (reduced energy may indicate withdrawal)', | |
| 'energy_std': 'Energy variability (high variability suggests emotional instability)', | |
| 'energy_range': 'Energy range (wide range indicates emotional dysregulation)', | |
| 'energy_variation': 'Energy variation coefficient (normalized energy instability)', | |
| 'spectral_centroid_mean': 'Spectral centroid (brightness of voice, shifts under stress)', | |
| 'spectral_bandwidth_mean': 'Spectral bandwidth (voice quality changes under deception)', | |
| 'audio_visual_sync': 'Audio-visual synchrony (desynchronization suggests incongruent behavior)', | |
| 'pause_gaze_coupling': 'Pause-gaze coupling (looking away while pausing is a deception cue)', | |
| 'stress_composite': 'Stress composite (combined physiological stress indicator)', | |
| } | |
| FEATURE_GROUPS = { | |
| 'Eye Behavior': ['eye_left_openness', 'eye_right_openness'], | |
| 'Mouth Dynamics': ['mouth_openness', 'mouth_width', 'mouth_asymmetry'], | |
| 'Eyebrow Activity': ['left_brow_height', 'right_brow_height', 'brow_asymmetry', 'brow_tension'], | |
| 'Nose Movement': ['nose_wrinkle', 'nostril_flare', 'nose_asymmetry'], | |
| 'Head Dynamics': ['head_pitch', 'head_yaw', 'head_roll', 'head_displacement'], | |
| 'Voice Pitch': ['pitch_mean', 'pitch_std', 'pitch_range', 'pitch_variation_coefficient'], | |
| 'Speech Timing': ['pause_count', 'avg_pause_duration', 'max_pause_duration', 'pause_rate', 'speech_ratio', 'voiced_ratio'], | |
| 'Voice Energy': ['energy_mean', 'energy_std', 'energy_range', 'energy_variation', 'spectral_centroid_mean', 'spectral_bandwidth_mean'], | |
| 'Cross-Modal': ['audio_visual_sync', 'pause_gaze_coupling', 'stress_composite'], | |
| } | |
| def __init__(self, classifier: DeceptionClassifier): | |
| """Initialize with a trained DeceptionClassifier. | |
| Args: | |
| classifier: A trained DeceptionClassifier instance. | |
| Raises: | |
| ValueError: If classifier is not trained. | |
| """ | |
| if not classifier.is_fitted_: | |
| warnings.warn("Classifier must be trained before creating explainer. Explainer will not work until trained.") | |
| self.classifier = classifier | |
| self._shap_explainer = None | |
| self._feature_names = classifier.feature_names_ | |
| def _init_shap_explainer(self) -> Optional[shap.TreeExplainer]: | |
| """Lazy-initialize SHAP TreeExplainer from the trained model. | |
| Returns: | |
| shap.TreeExplainer: Initialized SHAP explainer, or None on failure. | |
| Notes: | |
| Uses feature_perturbation='tree_path_dependent' for tree-based models. | |
| On failure, warns and returns None. | |
| """ | |
| if self._shap_explainer is None: | |
| try: | |
| # Use the underlying GradientBoostingClassifier (not calibrated model) | |
| # Research rationale: TreeExplainer works best with tree-based models | |
| # and provides exact SHAP values for gradient boosting. | |
| self._shap_explainer = shap.TreeExplainer( | |
| model=self.classifier.model, | |
| feature_perturbation='tree_path_dependent' | |
| ) | |
| except Exception as e: | |
| warnings.warn( | |
| f"Failed to initialize SHAP TreeExplainer: {e}. " | |
| "Falling back to permutation importance.", | |
| RuntimeWarning | |
| ) | |
| self._shap_explainer = None | |
| return self._shap_explainer | |
| def compute_shap_values(self, X: np.ndarray, feature_names: List[str]) -> np.ndarray: | |
| """Compute SHAP values using TreeExplainer. | |
| Args: | |
| X: Feature matrix of shape (n_samples, n_features). | |
| feature_names: Ordered list of feature names matching columns of X. | |
| Returns: | |
| np.ndarray: SHAP values array of shape (n_samples, n_features). | |
| Notes: | |
| - If SHAP fails, falls back to permutation importance. | |
| - Returns absolute SHAP values (magnitude of contribution). | |
| """ | |
| X = check_array(X, ensure_2d=True, dtype=np.float64) | |
| # Ensure feature names match | |
| if len(feature_names) != X.shape[1]: | |
| raise ValueError( | |
| f"Feature names length ({len(feature_names)}) " | |
| f"does not match X columns ({X.shape[1]})" | |
| ) | |
| # Scale features using classifier's scaler | |
| X_scaled = self.classifier.scaler.transform(X) | |
| try: | |
| explainer = self._init_shap_explainer() | |
| if explainer is None: | |
| raise RuntimeError("SHAP explainer could not be initialized.") | |
| shap_values = explainer.shap_values(X_scaled) | |
| # For binary classification, SHAP returns list of arrays for each class | |
| # We take the SHAP values for the positive class (deception) | |
| if isinstance(shap_values, list) and len(shap_values) == 2: | |
| shap_values = shap_values[1] # Positive class (deception) | |
| elif isinstance(shap_values, np.ndarray) and shap_values.ndim == 3: | |
| shap_values = shap_values[:, :, 1] # Positive class for multi-output | |
| except Exception as e: | |
| warnings.warn( | |
| f"SHAP computation failed: {e}. Falling back to permutation importance.", | |
| RuntimeWarning | |
| ) | |
| # Fallback: compute permutation importance as proxy for feature contribution | |
| shap_values = self._compute_fallback_importance(X_scaled, feature_names) | |
| return np.asarray(shap_values, dtype=np.float64) | |
| def _compute_fallback_importance( | |
| self, X_scaled: np.ndarray, feature_names: List[str] | |
| ) -> np.ndarray: | |
| """Compute permutation importance as fallback when SHAP fails. | |
| Args: | |
| X_scaled: Scaled feature matrix. | |
| feature_names: Feature names. | |
| Returns: | |
| np.ndarray: Importance values shaped (n_samples, n_features). | |
| """ | |
| # Use permutation importance to get global feature importance | |
| # Research rationale: permutation importance measures decrease in model | |
| # performance when a feature is randomly shuffled, providing a robust | |
| # alternative to SHAP for feature contribution estimation. | |
| try: | |
| result = permutation_importance( | |
| estimator=self.classifier.model, | |
| X=X_scaled, | |
| y=self.classifier.model.predict(X_scaled), # Use predicted labels | |
| n_repeats=10, | |
| random_state=42, | |
| n_jobs=-1 | |
| ) | |
| # Broadcast global importance to each sample | |
| importance = result.importances_mean | |
| importance = np.clip(importance, 0, None) # Ensure non-negative | |
| importance = importance / (np.sum(importance) + 1e-10) # Normalize | |
| # Create per-sample importance by adding small noise | |
| # This approximates sample-specific contributions | |
| n_samples = X_scaled.shape[0] | |
| noise = np.random.normal(0, 0.01 * importance.std(), (n_samples, len(importance))) | |
| shap_values = importance.reshape(1, -1) + noise | |
| return shap_values | |
| except Exception: | |
| # Ultimate fallback: uniform importance | |
| n_samples, n_features = X_scaled.shape | |
| return np.ones((n_samples, n_features)) / n_features | |
| def get_feature_importance( | |
| self, X: np.ndarray, feature_names: List[str], top_k: int = 10 | |
| ) -> pd.DataFrame: | |
| """Get ranked feature importance combining model importance and SHAP. | |
| Args: | |
| X: Feature matrix of shape (n_samples, n_features). | |
| feature_names: Ordered list of feature names. | |
| top_k: Number of top features to return (default: 10). | |
| Returns: | |
| pd.DataFrame: Columns: ['feature', 'importance', 'shap_importance', | |
| 'combined_score', 'rank', 'interpretation'] | |
| """ | |
| X = check_array(X, ensure_2d=True, dtype=np.float64) | |
| # 1. Get model's built-in feature importance | |
| try: | |
| model_importance = self.classifier.get_feature_importance() | |
| model_importance_dict = dict( | |
| zip(model_importance['feature'], model_importance['importance']) | |
| ) | |
| except Exception: | |
| model_importance_dict = {} | |
| # 2. Compute SHAP importance (mean absolute SHAP value per feature) | |
| shap_values = self.compute_shap_values(X, feature_names) | |
| shap_importance = np.mean(np.abs(shap_values), axis=0) | |
| # 3. Combine scores | |
| combined_scores = [] | |
| for i, feat in enumerate(feature_names): | |
| model_imp = model_importance_dict.get(feat, 0.0) | |
| shap_imp = shap_importance[i] if i < len(shap_importance) else 0.0 | |
| # Research rationale: weighted average gives more weight to SHAP | |
| # because it captures non-linear interactions better than Gini importance. | |
| combined = 0.3 * model_imp + 0.7 * shap_imp | |
| combined_scores.append({ | |
| 'feature': feat, | |
| 'importance': float(model_imp), | |
| 'shap_importance': float(shap_imp), | |
| 'combined_score': float(combined), | |
| 'interpretation': self.FEATURE_INTERPRETATIONS.get(feat, 'No interpretation available.') | |
| }) | |
| df = pd.DataFrame(combined_scores) | |
| df = df.sort_values('combined_score', ascending=False).reset_index(drop=True) | |
| df['rank'] = range(1, len(df) + 1) | |
| # Limit to top_k | |
| if top_k > 0: | |
| df = df.head(top_k) | |
| return df | |
| def get_ranked_indicators( | |
| self, X: np.ndarray, feature_names: List[str], top_k: int = 5 | |
| ) -> List[Dict]: | |
| """Get ranked deception indicators for a single sample. | |
| Args: | |
| X: Feature matrix of shape (1, n_features) for a single sample. | |
| feature_names: Ordered list of feature names. | |
| top_k: Number of top indicators to return (default: 5). | |
| Returns: | |
| List[Dict]: Each dict contains: | |
| - 'feature': feature name | |
| - 'value': original feature value | |
| - 'shap_value': SHAP contribution value | |
| - 'abs_contribution': absolute SHAP magnitude | |
| - 'direction': 'toward_deception' or 'toward_truth' | |
| - 'interpretation': behavioral interpretation | |
| """ | |
| if X.ndim != 2: | |
| raise ValueError("X must be 2D. Use shape (1, n_features) for single sample.") | |
| if X.shape[0] != 1: | |
| warnings.warn( | |
| "Multiple samples provided. Using first sample for indicator ranking.", | |
| UserWarning | |
| ) | |
| X = X[:1] | |
| # Compute SHAP values for the sample | |
| shap_values = self.compute_shap_values(X, feature_names) | |
| shap_sample = shap_values[0] | |
| # Get original feature values | |
| feature_values = X[0] | |
| # Create indicator dictionaries | |
| indicators = [] | |
| for i, feat in enumerate(feature_names): | |
| shap_val = shap_sample[i] | |
| feat_val = feature_values[i] | |
| # Determine direction based on SHAP sign | |
| # Positive SHAP pushes prediction toward deception (class 1) | |
| direction = 'toward_deception' if shap_val > 0 else 'toward_truth' | |
| indicators.append({ | |
| 'feature': feat, | |
| 'value': float(feat_val), | |
| 'shap_value': float(shap_val), | |
| 'abs_contribution': float(np.abs(shap_val)), | |
| 'direction': direction, | |
| 'interpretation': self.FEATURE_INTERPRETATIONS.get(feat, 'No interpretation available.') | |
| }) | |
| # Sort by absolute contribution (most influential first) | |
| indicators.sort(key=lambda x: x['abs_contribution'], reverse=True) | |
| # Return top_k indicators | |
| return indicators[:top_k] | |
| def explain_prediction( | |
| self, | |
| X: np.ndarray, | |
| feature_names: List[str], | |
| prediction: float, | |
| subject_id: Optional[str] = None | |
| ) -> Dict: | |
| """Generate complete explanation for a single prediction. | |
| Args: | |
| X: Feature matrix of shape (1, n_features) for a single sample. | |
| feature_names: Ordered list of feature names. | |
| prediction: Deception probability (0-1). | |
| subject_id: Optional subject identifier for contextualization. | |
| Returns: | |
| Dict: Explanation dictionary with keys: | |
| - 'verdict': 'truthful' or 'deceptive' based on threshold 0.5 | |
| - 'confidence': absolute distance from decision boundary | |
| - 'deception_probability': prediction probability | |
| - 'top_indicators': list of top indicators (from get_ranked_indicators) | |
| - 'group_contributions': dict of SHAP contributions per feature group | |
| - 'behavioral_summary': human-readable summary text | |
| - 'feature_values': dict of original feature values | |
| - 'subject_id': subject identifier if provided | |
| """ | |
| if X.ndim != 2 or X.shape[0] != 1: | |
| raise ValueError("X must be a single sample with shape (1, n_features).") | |
| # Compute SHAP values | |
| shap_values = self.compute_shap_values(X, feature_names) | |
| # Determine verdict | |
| verdict = 'deceptive' if prediction >= 0.5 else 'truthful' | |
| confidence = abs(prediction - 0.5) * 2 # Scale to 0-1 | |
| # Get top indicators | |
| top_indicators = self.get_ranked_indicators(X, feature_names, top_k=5) | |
| # Compute group contributions | |
| group_contributions = self.explain_group_contributions(shap_values, feature_names) | |
| # Generate behavioral summary | |
| behavioral_summary = self.generate_behavioral_summary( | |
| top_indicators, prediction, group_contributions | |
| ) | |
| # Prepare feature values dictionary | |
| feature_values = { | |
| feat: float(val) for feat, val in zip(feature_names, X[0]) | |
| } | |
| return { | |
| 'verdict': verdict, | |
| 'confidence': float(confidence), | |
| 'deception_probability': float(prediction), | |
| 'top_indicators': top_indicators, | |
| 'group_contributions': group_contributions, | |
| 'behavioral_summary': behavioral_summary, | |
| 'feature_values': feature_values, | |
| 'subject_id': subject_id | |
| } | |
| def generate_behavioral_summary( | |
| self, | |
| top_indicators: List[Dict], | |
| prediction: float, | |
| group_contributions: Dict[str, float] | |
| ) -> str: | |
| """Generate human-readable behavioral explanation paragraph. | |
| Args: | |
| top_indicators: Top indicators from get_ranked_indicators. | |
| prediction: Deception probability (0-1). | |
| group_contributions: Normalized SHAP contributions per feature group. | |
| Returns: | |
| str: Human-readable summary paragraph. | |
| Example: | |
| "The subject shows elevated deception probability (0.82). Key indicators include | |
| increased pause duration (SHAP: +0.12), which suggests cognitive load during | |
| response fabrication, and reduced audio-visual synchrony (SHAP: +0.09), | |
| indicating incongruent verbal and non-verbal behavior." | |
| """ | |
| # Determine deception level | |
| if prediction >= 0.7: | |
| level = "strongly elevated" | |
| elif prediction >= 0.6: | |
| level = "elevated" | |
| elif prediction >= 0.5: | |
| level = "slightly elevated" | |
| elif prediction >= 0.4: | |
| level = "slightly reduced" | |
| elif prediction >= 0.3: | |
| level = "reduced" | |
| else: | |
| level = "strongly reduced" | |
| # Build summary opening | |
| summary_parts = [ | |
| f"The subject shows {level} deception probability ({prediction:.2f})." | |
| ] | |
| # Add top indicators | |
| if top_indicators: | |
| indicator_desc = [] | |
| for idx, ind in enumerate(top_indicators[:3]): # top 3 | |
| feat = ind['feature'] | |
| shap_val = ind['shap_value'] | |
| direction = ind['direction'] | |
| interp = self.FEATURE_INTERPRETATIONS.get(feat, '') | |
| # Extract the main behavioral insight (first sentence) | |
| if interp: | |
| insight = interp.split('.')[0] + '.' | |
| else: | |
| insight = "This feature contributes to the prediction." | |
| # Format SHAP value with sign | |
| sign = '+' if shap_val >= 0 else '' | |
| indicator_desc.append( | |
| f"{feat.replace('_', ' ')} (SHAP: {sign}{shap_val:.2f}), " | |
| f"which {insight.lower()}" | |
| ) | |
| if indicator_desc: | |
| summary_parts.append("Key indicators include " + ", ".join(indicator_desc) + ".") | |
| # Add group contributions | |
| top_group = max(group_contributions.items(), key=lambda x: x[1]) if group_contributions else None | |
| if top_group: | |
| group_name, contrib = top_group | |
| summary_parts.append( | |
| f"The {group_name} feature group contributed the most ({contrib:.1%}) to the prediction, " | |
| f"suggesting that {group_name.lower()} played a dominant role." | |
| ) | |
| # Join into a single paragraph | |
| return " ".join(summary_parts) | |
| def explain_group_contributions( | |
| self, shap_values: np.ndarray, feature_names: List[str] | |
| ) -> Dict[str, float]: | |
| """Aggregate SHAP contribution per feature group, normalized to sum to 1.0. | |
| Args: | |
| shap_values: SHAP values array of shape (n_samples, n_features). | |
| feature_names: Ordered list of feature names. | |
| Returns: | |
| Dict[str, float]: Mapping from group name to normalized contribution. | |
| """ | |
| # Ensure single sample (take first if multiple) | |
| if shap_values.ndim == 2 and shap_values.shape[0] > 1: | |
| shap_values = shap_values[0:1] | |
| shap_abs = np.abs(shap_values).mean(axis=0) # average across samples (usually 1) | |
| # Map feature to group | |
| feature_to_group = {} | |
| for group, features in self.FEATURE_GROUPS.items(): | |
| for feat in features: | |
| feature_to_group[feat] = group | |
| # Aggregate contributions | |
| group_sums = {} | |
| for i, feat in enumerate(feature_names): | |
| if i >= len(shap_abs): | |
| continue | |
| group = feature_to_group.get(feat) | |
| if group is None: | |
| # Assign to 'Other' group | |
| group = 'Other' | |
| group_sums[group] = group_sums.get(group, 0.0) + shap_abs[i] | |
| # Normalize to sum to 1.0 | |
| total = sum(group_sums.values()) | |
| if total > 0: | |
| group_contributions = {k: v / total for k, v in group_sums.items()} | |
| else: | |
| group_contributions = {k: 0.0 for k in group_sums.keys()} | |
| return group_contributions | |