trustformers_debug/interpretability/
counterfactual.rs

1//! Counterfactual generation and analysis
2//!
3//! This module provides counterfactual explanation capabilities, helping to understand
4//! what changes would be needed to achieve different model predictions.
5
6use chrono::{DateTime, Utc};
7use serde::{Deserialize, Serialize};
8use std::collections::HashMap;
9
10/// Counterfactual generation result
11#[derive(Debug, Clone, Serialize, Deserialize)]
12pub struct CounterfactualResult {
13    /// Analysis timestamp
14    pub timestamp: DateTime<Utc>,
15    /// Generated counterfactuals
16    pub counterfactuals: Vec<Counterfactual>,
17    /// Counterfactual quality metrics
18    pub quality_metrics: CounterfactualQualityMetrics,
19    /// Feature sensitivity analysis
20    pub feature_sensitivity: FeatureSensitivityAnalysis,
21    /// Decision boundary analysis
22    pub decision_boundary: DecisionBoundaryAnalysis,
23    /// Actionable insights
24    pub actionable_insights: Vec<ActionableInsight>,
25}
26
27/// Individual counterfactual example
28#[derive(Debug, Clone, Serialize, Deserialize)]
29pub struct Counterfactual {
30    /// Counterfactual ID
31    pub id: String,
32    /// Original instance
33    pub original_instance: HashMap<String, f64>,
34    /// Counterfactual instance
35    pub counterfactual_instance: HashMap<String, f64>,
36    /// Changed features
37    pub changed_features: Vec<FeatureChange>,
38    /// Original prediction
39    pub original_prediction: f64,
40    /// Counterfactual prediction
41    pub counterfactual_prediction: f64,
42    /// Distance from original
43    pub distance: f64,
44    /// Plausibility score
45    pub plausibility: f64,
46    /// Actionability score
47    pub actionability: f64,
48}
49
50/// Change made to a feature in counterfactual
51#[derive(Debug, Clone, Serialize, Deserialize)]
52pub struct FeatureChange {
53    /// Feature name
54    pub feature_name: String,
55    /// Original value
56    pub original_value: f64,
57    /// New value
58    pub new_value: f64,
59    /// Change magnitude
60    pub change_magnitude: f64,
61    /// Change direction
62    pub change_direction: ChangeDirection,
63    /// Change difficulty/cost
64    pub change_cost: f64,
65}
66
67/// Direction of feature change
68#[derive(Debug, Clone, Serialize, Deserialize)]
69pub enum ChangeDirection {
70    Increase,
71    Decrease,
72    Categorical,
73}
74
75/// Quality metrics for counterfactuals
76#[derive(Debug, Clone, Serialize, Deserialize)]
77pub struct CounterfactualQualityMetrics {
78    /// Average distance to original instances
79    pub avg_distance: f64,
80    /// Average plausibility score
81    pub avg_plausibility: f64,
82    /// Average actionability score
83    pub avg_actionability: f64,
84    /// Diversity among counterfactuals
85    pub diversity: f64,
86    /// Coverage of feature space
87    pub coverage: f64,
88    /// Sparsity (average number of changed features)
89    pub sparsity: f64,
90}
91
92/// Feature sensitivity analysis from counterfactuals
93#[derive(Debug, Clone, Serialize, Deserialize)]
94pub struct FeatureSensitivityAnalysis {
95    /// Sensitivity scores for each feature
96    pub feature_sensitivities: HashMap<String, f64>,
97    /// Most sensitive features
98    pub most_sensitive: Vec<String>,
99    /// Least sensitive features
100    pub least_sensitive: Vec<String>,
101    /// Feature interaction effects
102    pub interaction_effects: Vec<InteractionEffect>,
103    /// Threshold analysis
104    pub threshold_analysis: ThresholdAnalysis,
105}
106
107/// Effect of feature interactions on sensitivity
108#[derive(Debug, Clone, Serialize, Deserialize)]
109pub struct InteractionEffect {
110    /// Features involved in interaction
111    pub features: Vec<String>,
112    /// Interaction effect magnitude
113    pub effect_magnitude: f64,
114    /// Effect type
115    pub effect_type: InteractionEffectType,
116}
117
118/// Type of interaction effect
119#[derive(Debug, Clone, Serialize, Deserialize)]
120pub enum InteractionEffectType {
121    /// Synergistic (combined effect > sum of individual effects)
122    Synergistic,
123    /// Antagonistic (combined effect < sum of individual effects)
124    Antagonistic,
125    /// Independent (combined effect = sum of individual effects)
126    Independent,
127}
128
129/// Analysis of decision thresholds
130#[derive(Debug, Clone, Serialize, Deserialize)]
131pub struct ThresholdAnalysis {
132    /// Feature thresholds for decision changes
133    pub feature_thresholds: HashMap<String, f64>,
134    /// Threshold confidence intervals
135    pub threshold_confidence: HashMap<String, (f64, f64)>,
136    /// Critical features (small changes cause big effects)
137    pub critical_features: Vec<String>,
138    /// Robust features (large changes needed for effects)
139    pub robust_features: Vec<String>,
140}
141
142/// Decision boundary analysis
143#[derive(Debug, Clone, Serialize, Deserialize)]
144pub struct DecisionBoundaryAnalysis {
145    /// Local boundary curvature
146    pub boundary_curvature: f64,
147    /// Boundary complexity
148    pub boundary_complexity: f64,
149    /// Distance to boundary
150    pub distance_to_boundary: f64,
151    /// Boundary crossing points
152    pub crossing_points: Vec<BoundaryCrossingPoint>,
153    /// Local linearity assessment
154    pub local_linearity: f64,
155}
156
157/// Point where instance crosses decision boundary
158#[derive(Debug, Clone, Serialize, Deserialize)]
159pub struct BoundaryCrossingPoint {
160    /// Point coordinates in feature space
161    pub coordinates: HashMap<String, f64>,
162    /// Distance from original instance
163    pub distance: f64,
164    /// Prediction at crossing point
165    pub boundary_prediction: f64,
166    /// Crossing direction
167    pub crossing_direction: Vec<f64>,
168}
169
170/// Actionable insight from counterfactual analysis
171#[derive(Debug, Clone, Serialize, Deserialize)]
172pub struct ActionableInsight {
173    /// Insight description
174    pub description: String,
175    /// Required feature changes
176    pub required_changes: Vec<FeatureChange>,
177    /// Expected outcome
178    pub expected_outcome: f64,
179    /// Confidence in insight
180    pub confidence: f64,
181    /// Implementation difficulty
182    pub difficulty: ImplementationDifficulty,
183    /// Time horizon for implementation
184    pub time_horizon: TimeHorizon,
185}
186
187/// Difficulty of implementing suggested changes
188#[derive(Debug, Clone, Serialize, Deserialize)]
189pub enum ImplementationDifficulty {
190    Easy,
191    Moderate,
192    Hard,
193    VeryHard,
194    Impossible,
195}
196
197/// Time horizon for implementing changes
198#[derive(Debug, Clone, Serialize, Deserialize)]
199pub enum TimeHorizon {
200    Immediate,
201    ShortTerm,
202    MediumTerm,
203    LongTerm,
204}
trustformers_debug/interpretability/counterfactual.rs

trustformers_debug/interpretability/
counterfactual.rs
