explainy.explanations package#
Submodules#
explainy.explanations.counterfactual_explanation module#
Counterfactual Explanation#
Counterfactual explanations tell us how the values of an instance have to change to significantly change its prediction. A counterfactual explanation of a prediction describes the smallest change to the feature values that changes the prediction to a predefined output. By creating counterfactual instances, we learn about how the model makes its predictions and can explain individual predictions [1].
Characteristics#
local
contrastive
Source#
[1] Molnar, Christoph. “Interpretable machine learning. A Guide for Making Black Box Models Explainable”, 2019. https://christophm.github.io/interpretable-ml-book/
- class explainy.explanations.counterfactual_explanation.CounterfactualExplanation(X: DataFrame, y: ndarray, model: ClassifierMixin | RegressorMixin, y_desired: float, number_of_features: int = 4, config: Dict[str, str] | None = None, delta: float | None = None)[source]#
Bases:
ExplanationBase
Contrastive, local Explanation
- explain(sample_index: int, sample_name: str | None = None, separator: str = '\n') Explanation [source]#
- Main function to create the explanation of the given sample. The
method_text, natural_language_text and the plots are create per sample.
- Args:
sample_index (int): number of the sample to create the explanation for sample_name (str, optional): name of the sample. Defaults to None. separator (str, optional): separator for the natural language text. Defaults to “
“.
- Returns:
Explanation: Explanation object containg the explainations
- explanation_name: str = 'counterfactual'#
- explanation_style: str = 'contrastive'#
- explanation_type: str = 'local'#
- get_feature_importance(x_ref: ndarray, x_counter_factual: ndarray) list [source]#
Calculate the importance of each feature. Take the reference features and replace every feature with the new counter_factual value. Calculat the absulte difference that this feature adds to the prediction. A larger absolute value, means a larger contribution and therefore a more important feature.
- Parameters:
x_ref (np.ndarray) – reference features.
x_counter_factual (np.ndarray) – counter factual features.
- Returns:
list of the feature sorted by importance
- Return type:
list
- get_feature_values(x_ref: ndarray, x_counter_factual: ndarray, decimal: int = 2, debug: bool = False)[source]#
Arrange the reference and the counter factual features in a dataframe
- Parameters:
x_ref (np.array) – features of the sample
x_counter_factual (np.array) – features of the counter factual sample to achive y_desired
decimal (int) – decimal number to round the values to in the plot
debug (bool) – if True, plot the dataframe
- Returns:
None.
- get_method_text() str [source]#
Define the method introduction text of the explanation type.
- Returns:
method text explanation
- Return type:
str
- get_natural_language_text() str [source]#
Define the natural language output using the feature names and its values for this explanation type
- Returns:
natural language explanation
- Return type:
str
- get_prediction_from_new_feature_value(feature_index: int, x_ref: ndarray, x_counter_factual: ndarray) float [source]#
Replace the value of the feauture at the postition of thw feature_index and predict a new value for this new set of features
- Parameters:
feature_index (int) – The index of the feature to replace with the counterfactual value.
x_ref (np.ndarray) – reference features.
x_counter_factual (np.ndarray) – counter factual features.
- Returns:
predicted value with the updated features values.
- Return type:
prediction (float)
explainy.explanations.permutation_explanation module#
Permutation feature importance#
Permutation feature importance measures the increase in the prediction error of the model after we permuted the feature’s values, which breaks the relationship between the feature and the true outcome [1].
Permutation importance does not reflect to the intrinsic predictive value of a feature by itself but how important this feature is for a particular model [2].
Characteristics#
global
non-contrastive
Source#
[1] Molnar, Christoph. “Interpretable machine learning. A Guide for Making Black Box Models Explainable”, 2019. https://christophm.github.io/interpretable-ml-book/
[2] https://scikit-learn.org/stable/modules/permutation_importance.html
- class explainy.explanations.permutation_explanation.PermutationExplanation(X: DataFrame, y: array, model: ClassifierMixin | RegressorMixin, number_of_features: int = 4, config: Dict[str, str] | None = None, n_repeats: int | None = 30, random_state: int | None = 0, **kwargs)[source]#
Bases:
ExplanationBase
Non-contrastive, global Explanation
- explain(sample_index: int, sample_name: str | None = None, separator: str = '\n') Explanation [source]#
Main function to create the explanation of the given sample. The method_text, natural_language_text and the plots are create per sample.
- Parameters:
sample_index (int) – number of the sample to create the explanation for
- Returns:
Explanation object containg the explainations
- Return type:
- explanation_name: str = 'permutation'#
- explanation_style: str = 'non-contrastive'#
- explanation_type: str = 'global'#
explainy.explanations.shap_explanation module#
SHAP Explanation#
A prediction can be explained by assuming that each feature value of the instance is a “player” in a game where the prediction is the payout. Shapley values (a method from coalitional game theory) tells us how to fairly distribute the “payout” among the features. The Shapley value is the average marginal contribution of a feature value across all possible coalitions [1].
Characteristics#
local
non-contrastive
Source#
[1] Molnar, Christoph. “Interpretable machine learning. A Guide for Making Black Box Models Explainable”, 2019. https://christophm.github.io/interpretable-ml-book/
- class explainy.explanations.shap_explanation.ShapExplanation(X: DataFrame, y: ndarray, model: ClassifierMixin | RegressorMixin, number_of_features: int = 4, config: Dict[str, str] | None = None, **kwargs)[source]#
Bases:
ExplanationBase
Non-contrastive, local Explanation
- explain(sample_index: int, sample_name: str | None = None, separator: str = '\n') Explanation [source]#
Main function to create the explanation of the given sample. The method_text, natural_language_text and the plots are create per sample.
- Parameters:
sample_index (int) – number of the sample to create the explanation for
- Returns:
Explanation object containg the explainations
- Return type:
- explanation_name: str = 'shap'#
- explanation_style: str = 'non-contrastive'#
- explanation_type: str = 'local'#
- get_feature_values(sample_index: int = 0) List[Tuple[str, float]] [source]#
Extract the feature name and its importance per sample - get absolute values to get the strongst postive and negative contribution - sort by importance -> highst to lowest
- Parameters:
sample_index (int, optional) – sample for which the explanation should
0. (be returned. Defaults to) –
- Returns:
list of tuples for each feature and its importance of a sample.
- Return type:
feature_values (list(tuple(str, float)))
explainy.explanations.surrogate_model_explanation module#
Global Surrogate Model#
A global surrogate model is an interpretable model that is trained to approximate the predictions of a black box model. We can draw conclusions about the black box model by interpreting the surrogate model [1].
Characteristics#
global
contrastive
Source#
[1] Molnar, Christoph. “Interpretable machine learning. A Guide for Making Black Box Models Explainable”, 2019. https://christophm.github.io/interpretable-ml-book/
- class explainy.explanations.surrogate_model_explanation.SurrogateModelExplanation(X: DataFrame, y: DataFrame | ndarray, model: ClassifierMixin | RegressorMixin, number_of_features: int = 4, config: Dict[str, str] | None = None, kind: str = 'tree', **kwargs: dict)[source]#
Bases:
ExplanationBase
Contrastive, global Explanation
- explain(sample_index: int, sample_name: str | None = None, separator: str = '\n') Explanation [source]#
Main function to create the explanation of the given sample.
The method_text, natural_language_text and the plots are create per sample.
- Args:
sample_index (int): number of the sample to create the explanation for sample_name (str, optional): name of the sample. Defaults to None. separator (str, optional): seprator for the string concatenation. Defaults to ‘
‘.
- Returns:
Explanation: Explanation object containg the explainations
- explanation_name: str = 'surrogate'#
- explanation_style: str = 'contrastive'#
- explanation_type: str = 'global'#
- get_method_text() str [source]#
Define the method introduction text of the explanation type.
- Returns:
method_text explanation
- Return type:
str
- get_natural_language_text() str [source]#
Define the natural language output using the feature names and its values for this explanation type
- Returns:
natural_language_text explanation
- Return type:
str
- get_surrogate_model(estimator: ClassifierMixin | RegressorMixin) ClassifierMixin | RegressorMixin [source]#
Get the surrogate model per kind with the defined hyperparamters
- Parameters:
estimator (ModelType) – surrogate estimator
- Returns:
surrogate estimator with hyperparamters
- Return type:
ModelType
- importance() str [source]#
Return the importance of the surrogate model
- Returns:
importance of the surrogate model
- Return type:
str