CrucibleXAI.Explanation (CrucibleXAI v0.4.0)
View SourceExplanation structure for XAI methods.
This module defines the common structure for explanations generated by various XAI methods (LIME, SHAP, feature attribution, etc.) and provides utility functions for analyzing and visualizing explanations.
Fields
:instance- The instance being explained:feature_weights- Map of feature_index => weight/importance:intercept- Intercept/baseline value (optional):score- Quality score of the explanation (e.g., R² for LIME):method- The XAI method used (:lime,:shap,:permutation, etc.):metadata- Additional method-specific metadata
Examples
iex> explanation = %CrucibleXAI.Explanation{
...> instance: [1.0, 2.0, 3.0],
...> feature_weights: %{0 => 0.5, 1 => -0.3, 2 => 0.8},
...> intercept: 1.0,
...> score: 0.95,
...> method: :lime,
...> metadata: %{num_samples: 5000}
...> }
iex> explanation.method
:limeSummary
Functions
Get feature importance as absolute values.
Get negative features (features that decrease prediction).
Get positive features (features that increase prediction).
Convert explanation to JSON-serializable map.
Visualize explanation as text.
Get top k features by absolute weight.
Types
Functions
Get feature importance as absolute values.
Returns all features sorted by absolute importance (absolute value of weight).
Parameters
explanation- The explanation struct
Returns
List of {feature_index, absolute_importance} tuples
Examples
iex> explanation = %CrucibleXAI.Explanation{
...> instance: [1, 2, 3],
...> feature_weights: %{0 => 0.5, 1 => -0.8, 2 => 0.3},
...> method: :lime
...> }
iex> CrucibleXAI.Explanation.feature_importance(explanation)
[{1, 0.8}, {0, 0.5}, {2, 0.3}]Get negative features (features that decrease prediction).
Returns features with negative weights, sorted by absolute weight in descending order.
Parameters
explanation- The explanation struct
Returns
List of {feature_index, weight} tuples for negative features
Examples
iex> explanation = %CrucibleXAI.Explanation{
...> instance: [1, 2, 3],
...> feature_weights: %{0 => 0.5, 1 => -0.8, 2 => -0.3},
...> method: :lime
...> }
iex> CrucibleXAI.Explanation.negative_features(explanation)
[{1, -0.8}, {2, -0.3}]Get positive features (features that increase prediction).
Returns features with positive weights, sorted by weight in descending order.
Parameters
explanation- The explanation struct
Returns
List of {feature_index, weight} tuples for positive features
Examples
iex> explanation = %CrucibleXAI.Explanation{
...> instance: [1, 2, 3],
...> feature_weights: %{0 => 0.5, 1 => -0.3, 2 => 0.8},
...> method: :lime
...> }
iex> CrucibleXAI.Explanation.positive_features(explanation)
[{2, 0.8}, {0, 0.5}]Convert explanation to JSON-serializable map.
Parameters
explanation- The explanation struct
Returns
Map with string keys suitable for JSON encoding
Examples
iex> explanation = %CrucibleXAI.Explanation{
...> instance: [1.0, 2.0],
...> feature_weights: %{0 => 0.5, 1 => 0.3},
...> method: :lime
...> }
iex> map = CrucibleXAI.Explanation.to_map(explanation)
iex> map.method
"lime"Visualize explanation as text.
Generates a human-readable text representation of the explanation.
Parameters
explanation- The explanation structopts- Options::num_features- Number of features to display (default: 10):feature_names- Map of feature_index => name
Returns
String containing formatted explanation
Examples
iex> explanation = %CrucibleXAI.Explanation{
...> instance: [1.0, 2.0],
...> feature_weights: %{0 => 0.5, 1 => -0.3},
...> intercept: 1.0,
...> score: 0.95,
...> method: :lime,
...> metadata: %{}
...> }
iex> text = CrucibleXAI.Explanation.to_text(explanation)
iex> String.contains?(text, "LIME")
true@spec top_features(t(), pos_integer()) :: [{integer(), float()}]
Get top k features by absolute weight.
Returns a list of {feature_index, weight} tuples sorted by absolute weight in descending order.
Parameters
explanation- The explanation structk- Number of top features to return
Returns
List of {feature_index, weight} tuples
Examples
iex> explanation = %CrucibleXAI.Explanation{
...> instance: [1, 2, 3],
...> feature_weights: %{0 => 0.5, 1 => -0.8, 2 => 0.3},
...> method: :lime
...> }
iex> CrucibleXAI.Explanation.top_features(explanation, 2)
[{1, -0.8}, {0, 0.5}]