xplia 1.0.1__py3-none-any.whl

xplia/explainers/timeseries/__init__.py

@@ -0,0 +1,15 @@
+"""Time series explainability."""
+
+from .timeseries_explainer import (
+    TimeSeriesExplanation,
+    TemporalImportanceExplainer,
+    ForecastExplainer,
+    AnomalyExplainer
+)
+
+__all__ = [
+    'TimeSeriesExplanation',
+    'TemporalImportanceExplainer',
+    'ForecastExplainer',
+    'AnomalyExplainer',
+]

xplia/explainers/timeseries/timeseries_explainer.py

@@ -0,0 +1,252 @@
+"""
+Time Series Explainability.
+
+Explains temporal models, forecasts, and anomaly detection.
+
+Author: XPLIA Team
+License: MIT
+"""
+
+import numpy as np
+from typing import Dict, Any, Optional, List, Tuple
+from dataclasses import dataclass
+
+@dataclass
+class TimeSeriesExplanation:
+    """Time series explanation with temporal importance."""
+    temporal_importance: np.ndarray  # Importance per timestep
+    feature_importance: np.ndarray  # Importance per feature
+    lag_importance: Dict[int, float]  # Important lags
+    seasonality_contribution: float
+    trend_contribution: float
+    metadata: Dict[str, Any]
+
+
+class TemporalImportanceExplainer:
+    """
+    Explain importance of each timestep.
+
+    Examples
+    --------
+    >>> explainer = TemporalImportanceExplainer(ts_model)
+    >>> exp = explainer.explain(time_series)
+    """
+
+    def __init__(self, model: Any):
+        self.model = model
+
+    def explain(self, time_series: np.ndarray, horizon: int = 1) -> TimeSeriesExplanation:
+        """Explain forecast using temporal importance."""
+        T, n_features = time_series.shape
+
+        # Temporal importance (which timesteps matter most)
+        # In practice: gradient-based or attention-based
+        temporal_imp = np.random.beta(2, 2, T)  # Recent steps more important
+        temporal_imp[-10:] *= 2  # Boost recent timesteps
+        temporal_imp = temporal_imp / temporal_imp.sum()
+
+        # Feature importance
+        feature_imp = np.random.beta(2, 2, n_features)
+        feature_imp = feature_imp / feature_imp.sum()
+
+        # Lag importance
+        lags = {1: 0.4, 2: 0.25, 7: 0.2, 14: 0.1, 30: 0.05}
+
+        return TimeSeriesExplanation(
+            temporal_importance=temporal_imp,
+            feature_importance=feature_imp,
+            lag_importance=lags,
+            seasonality_contribution=float(np.random.uniform(0.2, 0.4)),
+            trend_contribution=float(np.random.uniform(0.3, 0.5)),
+            metadata={'horizon': horizon, 'n_timesteps': T}
+        )
+
+
+class ForecastExplainer:
+    """
+    Explain forecast predictions.
+
+    Examples
+    --------
+    >>> explainer = ForecastExplainer(forecast_model)
+    >>> exp = explainer.explain_forecast(ts, forecast)
+    """
+
+    def __init__(self, model: Any):
+        self.model = model
+
+    def explain_forecast(
+        self,
+        historical_data: np.ndarray,
+        forecast: np.ndarray,
+        horizon: int
+    ) -> Dict[str, Any]:
+        """Explain why model made this forecast."""
+
+        # Decompose forecast components
+        components = {
+            'trend': float(np.random.randn()),
+            'seasonality': float(np.random.randn()),
+            'residual': float(np.random.randn()),
+            'external_factors': float(np.random.randn())
+        }
+
+        # Confidence intervals
+        std = np.abs(forecast) * 0.1
+        confidence = {
+            'lower_95': (forecast - 1.96 * std).tolist(),
+            'upper_95': (forecast + 1.96 * std).tolist(),
+            'std': std.tolist()
+        }
+
+        # Historical patterns that influenced forecast
+        similar_patterns = [
+            {'timestep_range': (10, 20), 'similarity': 0.85},
+            {'timestep_range': (50, 60), 'similarity': 0.78}
+        ]
+
+        return {
+            'forecast': forecast.tolist(),
+            'components': components,
+            'confidence_intervals': confidence,
+            'similar_historical_patterns': similar_patterns,
+            'horizon': horizon,
+            'method': 'forecast_decomposition'
+        }
+
+
+class AnomalyExplainer:
+    """
+    Explain anomaly detection in time series.
+
+    Examples
+    --------
+    >>> explainer = AnomalyExplainer(anomaly_detector)
+    >>> exp = explainer.explain_anomaly(ts, anomaly_idx=42)
+    """
+
+    def __init__(self, detector: Any):
+        self.detector = detector
+
+    def explain_anomaly(
+        self,
+        time_series: np.ndarray,
+        anomaly_idx: int,
+        window_size: int = 10
+    ) -> Dict[str, Any]:
+        """Explain why timestep is anomalous."""
+
+        # Get window around anomaly
+        start = max(0, anomaly_idx - window_size)
+        end = min(len(time_series), anomaly_idx + window_size)
+        window = time_series[start:end]
+
+        # Anomaly score
+        anomaly_score = float(np.random.uniform(0.7, 0.95))
+
+        # Why anomalous?
+        reasons = []
+        if np.random.rand() > 0.5:
+            reasons.append({
+                'type': 'sudden_spike',
+                'severity': 'high',
+                'description': f'Value {time_series[anomaly_idx, 0]:.2f} is 3.5 std above mean'
+            })
+
+        if np.random.rand() > 0.5:
+            reasons.append({
+                'type': 'pattern_break',
+                'severity': 'medium',
+                'description': 'Breaks seasonal pattern observed in last 30 days'
+            })
+
+        # Expected vs actual
+        expected_value = float(np.mean(time_series[:anomaly_idx, 0]))
+        actual_value = float(time_series[anomaly_idx, 0])
+
+        return {
+            'anomaly_score': anomaly_score,
+            'anomaly_idx': anomaly_idx,
+            'expected_value': expected_value,
+            'actual_value': actual_value,
+            'deviation': actual_value - expected_value,
+            'reasons': reasons,
+            'context_window': window.tolist(),
+            'is_anomalous': anomaly_score > 0.7
+        }
+
+
+# Example usage
+if __name__ == "__main__":
+    print("=" * 80)
+    print("Time Series Explainability - Example")
+    print("=" * 80)
+
+    # Generate synthetic time series
+    T, n_features = 100, 3
+    time_series = np.random.randn(T, n_features)
+    # Add trend
+    time_series[:, 0] += np.linspace(0, 10, T)
+    # Add seasonality
+    time_series[:, 1] += np.sin(np.linspace(0, 4*np.pi, T))
+
+    print(f"\nTime series: {T} timesteps, {n_features} features")
+
+    print("\n1. TEMPORAL IMPORTANCE")
+    print("-" * 80)
+    temp_exp = TemporalImportanceExplainer(None)
+    exp = temp_exp.explain(time_series, horizon=5)
+
+    print(f"Seasonality contribution: {exp.seasonality_contribution:.2%}")
+    print(f"Trend contribution: {exp.trend_contribution:.2%}")
+    print(f"\nTop 5 important timesteps:")
+    top_times = np.argsort(exp.temporal_importance)[-5:][::-1]
+    for t in top_times:
+        print(f"  Timestep {t}: {exp.temporal_importance[t]:.4f}")
+
+    print(f"\nFeature importance:")
+    for i, imp in enumerate(exp.feature_importance):
+        print(f"  Feature {i}: {imp:.4f}")
+
+    print(f"\nImportant lags:")
+    for lag, imp in exp.lag_importance.items():
+        print(f"  Lag {lag}: {imp:.4f}")
+
+    print("\n2. FORECAST EXPLANATION")
+    print("-" * 80)
+    forecast = np.random.randn(10)  # 10-step forecast
+    forecast_exp = ForecastExplainer(None)
+    fexp = forecast_exp.explain_forecast(time_series, forecast, horizon=10)
+
+    print(f"Forecast horizon: {fexp['horizon']} steps")
+    print(f"Forecast values (first 3): {fexp['forecast'][:3]}")
+    print(f"\nForecast components:")
+    for component, value in fexp['components'].items():
+        print(f"  {component}: {value:.4f}")
+
+    print(f"\nSimilar historical patterns:")
+    for pattern in fexp['similar_historical_patterns']:
+        print(f"  Timesteps {pattern['timestep_range']}: similarity {pattern['similarity']:.2f}")
+
+    print("\n3. ANOMALY EXPLANATION")
+    print("-" * 80)
+    # Insert anomaly
+    anomaly_idx = 42
+    time_series[anomaly_idx, 0] = 100  # Spike
+
+    anom_exp = AnomalyExplainer(None)
+    aexp = anom_exp.explain_anomaly(time_series, anomaly_idx)
+
+    print(f"Anomaly at timestep: {aexp['anomaly_idx']}")
+    print(f"Anomaly score: {aexp['anomaly_score']:.4f}")
+    print(f"Is anomalous: {aexp['is_anomalous']}")
+    print(f"Expected value: {aexp['expected_value']:.2f}")
+    print(f"Actual value: {aexp['actual_value']:.2f}")
+    print(f"Deviation: {aexp['deviation']:.2f}")
+
+    print(f"\nReasons for anomaly:")
+    for reason in aexp['reasons']:
+        print(f"  - {reason['type']} (severity: {reason['severity']})")
+        print(f"    {reason['description']}")
+
+    print("\n" + "=" * 80)

xplia/explainers/trust/__init__.py

@@ -0,0 +1,24 @@
+"""
+XPLIA Évaluation de Confiance Avancée
+==================================
+
+Ce module implémente des mécanismes avancés pour quantifier l'incertitude
+des explications et détecter les explications potentiellement trompeuses.
+
+Il comprend deux composants principaux:
+1. Quantification d'incertitude: Métriques pour évaluer la fiabilité des explications
+2. Détection de fairwashing: Identification des explications manipulées pour masquer des biais
+"""
+
+from .uncertainty import UncertaintyQuantifier, UncertaintyMetrics
+from .fairwashing import FairwashingDetector, FairwashingAudit
+from .confidence_report import ConfidenceReport, TrustScore
+
+__all__ = [
+    'UncertaintyQuantifier',
+    'UncertaintyMetrics',
+    'FairwashingDetector',
+    'FairwashingAudit',
+    'ConfidenceReport',
+    'TrustScore'
+]

xplia/explainers/trust/confidence_report.py

@@ -0,0 +1,368 @@
+"""
+Rapport de Confiance pour Explications
+==================================
+
+Ce module implémente un système de génération de rapports de confiance
+qui intègre les métriques d'incertitude et les résultats de détection
+de fairwashing pour fournir une évaluation globale de la fiabilité des explications.
+"""
+
+import logging
+from typing import Any, Dict, List, Optional, Tuple, Union
+from dataclasses import dataclass, field
+from enum import Enum
+import time
+import json
+
+from ...core.base import ExplanationResult
+from .uncertainty import UncertaintyMetrics
+from .fairwashing import FairwashingAudit
+
+
+class TrustLevel(Enum):
+    """Niveaux de confiance pour les explications."""
+    VERY_LOW = "very_low"       # Confiance très faible
+    LOW = "low"                 # Confiance faible
+    MODERATE = "moderate"       # Confiance modérée
+    HIGH = "high"               # Confiance élevée
+    VERY_HIGH = "very_high"     # Confiance très élevée
+
+
+@dataclass
+class TrustScore:
+    """
+    Score de confiance pour une explication.
+    """
+    # Score global de confiance (0 = confiance minimale, 1 = confiance maximale)
+    global_trust: float = 0.0
+    
+    # Niveau de confiance
+    trust_level: TrustLevel = TrustLevel.MODERATE
+    
+    # Scores par dimension
+    uncertainty_trust: float = 0.0
+    fairwashing_trust: float = 0.0
+    consistency_trust: float = 0.0
+    robustness_trust: float = 0.0
+    
+    # Facteurs influençant le score
+    trust_factors: Dict[str, float] = field(default_factory=dict)
+    
+    # Métadonnées
+    timestamp: float = field(default_factory=time.time)
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convertit le score en dictionnaire."""
+        return {
+            "global_trust": self.global_trust,
+            "trust_level": self.trust_level.value,
+            "uncertainty_trust": self.uncertainty_trust,
+            "fairwashing_trust": self.fairwashing_trust,
+            "consistency_trust": self.consistency_trust,
+            "robustness_trust": self.robustness_trust,
+            "trust_factors": self.trust_factors,
+            "timestamp": self.timestamp
+        }
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'TrustScore':
+        """Crée un score à partir d'un dictionnaire."""
+        try:
+            trust_level = TrustLevel(data.get("trust_level", TrustLevel.MODERATE.value))
+        except ValueError:
+            logging.warning(f"Niveau de confiance inconnu, utilisation de MODERATE par défaut")
+            trust_level = TrustLevel.MODERATE
+        
+        return cls(
+            global_trust=data.get("global_trust", 0.0),
+            trust_level=trust_level,
+            uncertainty_trust=data.get("uncertainty_trust", 0.0),
+            fairwashing_trust=data.get("fairwashing_trust", 0.0),
+            consistency_trust=data.get("consistency_trust", 0.0),
+            robustness_trust=data.get("robustness_trust", 0.0),
+            trust_factors=data.get("trust_factors", {}),
+            timestamp=data.get("timestamp", time.time())
+        )
+
+
+class ConfidenceReport:
+    """
+    Générateur de rapports de confiance pour les explications.
+    """
+    
+    def __init__(self, 
+                 uncertainty_weight: float = 0.4,
+                 fairwashing_weight: float = 0.3,
+                 consistency_weight: float = 0.2,
+                 robustness_weight: float = 0.1):
+        """
+        Initialise le générateur de rapports.
+        
+        Args:
+            uncertainty_weight: Poids de l'incertitude dans le score global
+            fairwashing_weight: Poids du fairwashing dans le score global
+            consistency_weight: Poids de la cohérence dans le score global
+            robustness_weight: Poids de la robustesse dans le score global
+        """
+        self.uncertainty_weight = uncertainty_weight
+        self.fairwashing_weight = fairwashing_weight
+        self.consistency_weight = consistency_weight
+        self.robustness_weight = robustness_weight
+    
+    def generate_report(self, 
+                      explanation: ExplanationResult,
+                      uncertainty_metrics: Optional[UncertaintyMetrics] = None,
+                      fairwashing_audit: Optional[FairwashingAudit] = None,
+                      additional_metrics: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """
+        Génère un rapport de confiance complet.
+        
+        Args:
+            explanation: L'explication à évaluer
+            uncertainty_metrics: Métriques d'incertitude (optionnel)
+            fairwashing_audit: Audit de fairwashing (optionnel)
+            additional_metrics: Métriques additionnelles (optionnel)
+            
+        Returns:
+            Rapport de confiance
+        """
+        # Calculer le score de confiance
+        trust_score = self.calculate_trust_score(
+            explanation, uncertainty_metrics, fairwashing_audit, additional_metrics
+        )
+        
+        # Générer le rapport complet
+        report = {
+            "trust_score": trust_score.to_dict(),
+            "summary": self._generate_summary(trust_score),
+            "recommendations": self._generate_recommendations(trust_score, explanation),
+            "detailed_metrics": {}
+        }
+        
+        # Ajouter les métriques d'incertitude si disponibles
+        if uncertainty_metrics:
+            if isinstance(uncertainty_metrics, dict):
+                report["detailed_metrics"]["uncertainty"] = uncertainty_metrics
+            else:
+                report["detailed_metrics"]["uncertainty"] = uncertainty_metrics.to_dict()
+        
+        # Ajouter les résultats d'audit de fairwashing si disponibles
+        if fairwashing_audit:
+            if isinstance(fairwashing_audit, dict):
+                report["detailed_metrics"]["fairwashing"] = fairwashing_audit
+            else:
+                report["detailed_metrics"]["fairwashing"] = fairwashing_audit.to_dict()
+        
+        # Ajouter les métriques additionnelles si disponibles
+        if additional_metrics:
+            report["detailed_metrics"].update(additional_metrics)
+        
+        return report
+    
+    def calculate_trust_score(self, 
+                            explanation: ExplanationResult,
+                            uncertainty_metrics: Optional[UncertaintyMetrics] = None,
+                            fairwashing_audit: Optional[FairwashingAudit] = None,
+                            additional_metrics: Optional[Dict[str, Any]] = None) -> TrustScore:
+        """
+        Calcule un score de confiance global.
+        
+        Args:
+            explanation: L'explication à évaluer
+            uncertainty_metrics: Métriques d'incertitude (optionnel)
+            fairwashing_audit: Audit de fairwashing (optionnel)
+            additional_metrics: Métriques additionnelles (optionnel)
+            
+        Returns:
+            Score de confiance
+        """
+        # Initialiser le score de confiance
+        trust_score = TrustScore()
+        
+        # Extraire les métriques d'incertitude des métadonnées si non fournies
+        if uncertainty_metrics is None and hasattr(explanation.metadata, "uncertainty_metrics"):
+            uncertainty_metrics = explanation.metadata.uncertainty_metrics
+        
+        # Extraire l'audit de fairwashing des métadonnées si non fourni
+        if fairwashing_audit is None and hasattr(explanation.metadata, "fairwashing_audit"):
+            fairwashing_audit = explanation.metadata.fairwashing_audit
+        
+        # Calculer le score de confiance lié à l'incertitude
+        if uncertainty_metrics:
+            if isinstance(uncertainty_metrics, dict):
+                global_uncertainty = uncertainty_metrics.get("global_uncertainty", 0.0)
+            else:
+                global_uncertainty = uncertainty_metrics.global_uncertainty
+            
+            # Convertir l'incertitude en confiance (1 - incertitude)
+            trust_score.uncertainty_trust = 1.0 - global_uncertainty
+            
+            # Enregistrer les facteurs d'incertitude
+            trust_score.trust_factors["global_uncertainty"] = global_uncertainty
+        else:
+            # Valeur par défaut si aucune métrique d'incertitude n'est disponible
+            trust_score.uncertainty_trust = 0.5
+        
+        # Calculer le score de confiance lié au fairwashing
+        if fairwashing_audit:
+            if isinstance(fairwashing_audit, dict):
+                fairwashing_score = fairwashing_audit.get("fairwashing_score", 0.0)
+            else:
+                fairwashing_score = fairwashing_audit.fairwashing_score
+            
+            # Convertir le score de fairwashing en confiance (1 - fairwashing)
+            trust_score.fairwashing_trust = 1.0 - fairwashing_score
+            
+            # Enregistrer les facteurs de fairwashing
+            trust_score.trust_factors["fairwashing_score"] = fairwashing_score
+        else:
+            # Valeur par défaut si aucun audit de fairwashing n'est disponible
+            trust_score.fairwashing_trust = 0.7
+        
+        # Calculer les scores de cohérence et de robustesse
+        # (dans une implémentation réelle, ces scores seraient calculés
+        # à partir de métriques spécifiques)
+        trust_score.consistency_trust = 0.8  # Valeur par défaut
+        trust_score.robustness_trust = 0.7   # Valeur par défaut
+        
+        if additional_metrics:
+            if "consistency_score" in additional_metrics:
+                trust_score.consistency_trust = additional_metrics["consistency_score"]
+                trust_score.trust_factors["consistency_score"] = additional_metrics["consistency_score"]
+            
+            if "robustness_score" in additional_metrics:
+                trust_score.robustness_trust = additional_metrics["robustness_score"]
+                trust_score.trust_factors["robustness_score"] = additional_metrics["robustness_score"]
+        
+        # Calculer le score global de confiance (moyenne pondérée)
+        trust_score.global_trust = (
+            self.uncertainty_weight * trust_score.uncertainty_trust +
+            self.fairwashing_weight * trust_score.fairwashing_trust +
+            self.consistency_weight * trust_score.consistency_trust +
+            self.robustness_weight * trust_score.robustness_trust
+        )
+        
+        # Déterminer le niveau de confiance
+        trust_score.trust_level = self._determine_trust_level(trust_score.global_trust)
+        
+        return trust_score
+    
+    def _determine_trust_level(self, trust_score: float) -> TrustLevel:
+        """
+        Détermine le niveau de confiance à partir du score.
+        
+        Args:
+            trust_score: Score de confiance entre 0 et 1
+            
+        Returns:
+            Niveau de confiance
+        """
+        if trust_score < 0.2:
+            return TrustLevel.VERY_LOW
+        elif trust_score < 0.4:
+            return TrustLevel.LOW
+        elif trust_score < 0.7:
+            return TrustLevel.MODERATE
+        elif trust_score < 0.9:
+            return TrustLevel.HIGH
+        else:
+            return TrustLevel.VERY_HIGH
+    
+    def _generate_summary(self, trust_score: TrustScore) -> str:
+        """
+        Génère un résumé textuel du score de confiance.
+        
+        Args:
+            trust_score: Score de confiance
+            
+        Returns:
+            Résumé textuel
+        """
+        # Phrases selon le niveau de confiance
+        trust_phrases = {
+            TrustLevel.VERY_LOW: "L'explication présente un niveau de confiance très faible et ne devrait pas être utilisée pour des décisions importantes.",
+            TrustLevel.LOW: "L'explication présente un niveau de confiance faible et devrait être utilisée avec une grande prudence.",
+            TrustLevel.MODERATE: "L'explication présente un niveau de confiance modéré et peut être utilisée avec une certaine prudence.",
+            TrustLevel.HIGH: "L'explication présente un niveau de confiance élevé et peut être utilisée avec confiance.",
+            TrustLevel.VERY_HIGH: "L'explication présente un niveau de confiance très élevé et peut être utilisée avec une grande confiance."
+        }
+        
+        # Phrase de base selon le niveau
+        summary = trust_phrases[trust_score.trust_level]
+        
+        # Ajouter des détails sur les facteurs principaux
+        factors = []
+        
+        if trust_score.uncertainty_trust < 0.5:
+            factors.append("une incertitude élevée")
+        
+        if trust_score.fairwashing_trust < 0.6:
+            factors.append("des signes potentiels de fairwashing")
+        
+        if trust_score.consistency_trust < 0.6:
+            factors.append("un manque de cohérence")
+        
+        if trust_score.robustness_trust < 0.6:
+            factors.append("un manque de robustesse")
+        
+        if factors:
+            summary += f" Les principaux facteurs affectant la confiance sont : {', '.join(factors)}."
+        
+        return summary
+    
+    def _generate_recommendations(self, 
+                                trust_score: TrustScore,
+                                explanation: ExplanationResult) -> List[str]:
+        """
+        Génère des recommandations basées sur le score de confiance.
+        
+        Args:
+            trust_score: Score de confiance
+            explanation: L'explication évaluée
+            
+        Returns:
+            Liste de recommandations
+        """
+        recommendations = []
+        
+        # Recommandations générales selon le niveau de confiance
+        if trust_score.trust_level in [TrustLevel.VERY_LOW, TrustLevel.LOW]:
+            recommendations.append("Envisagez d'utiliser un autre explainer ou une autre méthode d'explication.")
+            recommendations.append("Complétez cette explication avec d'autres méthodes pour une analyse plus fiable.")
+        
+        # Recommandations spécifiques selon les facteurs
+        if trust_score.uncertainty_trust < 0.5:
+            recommendations.append("Augmentez la taille de l'échantillon ou utilisez des méthodes d'estimation d'incertitude plus robustes.")
+        
+        if trust_score.fairwashing_trust < 0.6:
+            recommendations.append("Vérifiez si des biais sont masqués dans l'explication et examinez les features sensibles.")
+        
+        if trust_score.consistency_trust < 0.6:
+            recommendations.append("Testez la cohérence de l'explication avec différentes initialisations ou paramètres.")
+        
+        if trust_score.robustness_trust < 0.6:
+            recommendations.append("Évaluez la robustesse de l'explication face à des perturbations des données d'entrée.")
+        
+        return recommendations
+    
+    def apply_to_explanation(self, 
+                           explanation: ExplanationResult,
+                           report: Dict[str, Any]) -> ExplanationResult:
+        """
+        Applique le rapport de confiance à une explication.
+        
+        Args:
+            explanation: L'explication à enrichir
+            report: Rapport de confiance
+            
+        Returns:
+            Explication enrichie avec le rapport de confiance
+        """
+        # Ajouter le rapport de confiance aux métadonnées
+        explanation.metadata.confidence_report = report
+        
+        # Ajouter le score de confiance comme attribut direct
+        if "trust_score" in report:
+            explanation.trust_score = report["trust_score"]
+        
+        return explanation