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: pandas.core.frame.DataFrame, y: numpy.array, model: sklearn.base.BaseEstimator, number_of_features: int = 4, config: Dict = None, y_desired: float = None, delta: float = None, random_state: int = 0, **kwargs)[source]¶

Bases: explainy.core.explanation_base.ExplanationBase

Contrastive, local Explanation

explain(sample_index, sample_name=None, separator='\n')[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 (int) – number of the sample to create the explanation for
Returns: None.

format_features_for_plot() → None[source]¶

map categorical variables
replace one-hot-encoded value with True, False strings

Returns: None.

get_feature_importance(x_ref, x_counter_factual)[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 (TYPE) – DESCRIPTION.
x_counter_factual (TYPE) – DESCRIPTION.

Returns

None.

get_feature_values(x_ref, x_counter_factual, decimal=2, debug=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

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_value(ii, x_ref, x_counter_factual)[source]¶

replace the value of the feauture at postion ii and predict a new value for this new set of features

Parameters

ii (TYPE) – DESCRIPTION.
x_ref (TYPE) – DESCRIPTION.
x_counter_factual (TYPE) – DESCRIPTION.

Returns

DESCRIPTION.

Return type

difference (TYPE)

importance() → pandas.core.frame.DataFrame[source]¶

plot(sample_index: int, kind: str = 'table', **kwargs: dict) → None[source]¶

Create the plot of the counterfactual table

Parameters

sample_index (int) – index of the sample in scope
kind (str, optional) – kind of plot. Defaults to ‘table’.

Raises

Exception – raise Exception if the “kind” of plot is not supported

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: pandas.core.frame.DataFrame, y: numpy.array, model: Union[sklearn.base.ClassifierMixin, sklearn.base.RegressorMixin], number_of_features: int = 4, config: Dict = None, n_repeats: Optional[int] = 30, random_state: Optional[int] = 0, **kwargs)[source]¶

Bases: explainy.core.explanation_base.ExplanationBase

Non-contrastive, global Explanation

explain(sample_index: int, sample_name: str = None, separator='\n')[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: None.

get_feature_values() → List[Tuple[str, float]][source]¶

extract the feature name and its importance per sample, sort by importance -> highest to lowest

Returns: list of tuples for each feature and its importance of a sample.
Return type: feature_values (list(tuple(str, float)))

plot(sample_index: int = None, kind: str = 'bar') → None[source]¶

Plot method that calls different kinds of plot types

Parameters: kind (TYPE, optional) – DESCRIPTION. Defaults to ‘bar’.
Returns: None.

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: pandas.core.frame.DataFrame, y: numpy.array, model: sklearn.base.BaseEstimator, number_of_features: int = 4, config: Dict = None, **kwargs)[source]¶

Bases: explainy.core.explanation_base.ExplanationBase

Non-contrastive, local Explanation

explain(sample_index, sample_name=None, separator='\n') → None[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: None.

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
returned. Defaults to 0. (be) –

Returns

list of tuples for each feature and its importance of a sample.

Return type

feature_values (list(tuple(str, float)))

plot(sample_index: int, kind='bar') → None[source]¶

Plot the shap values

Parameters

sample_index (int, optional) – DESCRIPTION. Defaults to 0.
kind (TYPE, optional) – DESCRIPTION. Defaults to “bar”.

Returns

DESCRIPTION.

Return type

None

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: Union[pandas.core.frame.DataFrame, numpy.array], y: Union[pandas.core.frame.DataFrame, numpy.array], model: Union[sklearn.base.ClassifierMixin, sklearn.base.RegressorMixin], number_of_features: int = 4, config: Dict = None, kind: str = 'tree', **kwargs: dict)[source]¶

Bases: explainy.core.explanation_base.ExplanationBase

Contrastive, global Explanation

explain(sample_index: int, sample_name: str = None, separator: str = '\n') → explainy.core.explanation.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: explantion object containg the explainations

get_feature_values()[source]¶

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: Union[sklearn.base.ClassifierMixin, sklearn.base.RegressorMixin]) → Union[sklearn.base.ClassifierMixin, sklearn.base.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

plot(index_sample: int = None) → None[source]¶

Plot the surrogate model

Parameters: index_sample (int, optional) – index of the sample in scope. Defaults to None.
Raises: Exception – if the type of kind is not supported

save(sample_index: int, sample_name: str = None) → None[source]¶

Save the explanations to a csv file, save the plots

Parameters

sample_index ([type]) – [description]
sample_name ([type], optional) – [description]. Defaults to None.

Returns

None.

set_defaults()[source]¶

Module contents¶

explainy.core package

explainy.utils package