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)

Bases: ExplanationBase

Contrastive, local Explanation

explain(sample_index: int, sample_name: str | None = None, separator: str = '\n') → Explanation

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

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)

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

Define the method introduction text of the explanation type.

Returns:

method text explanation

Return type:

str

get_natural_language_text() → str

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

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)

importance() → DataFrame

Return the feature importance

Returns:

dataframe with the feature importance

Return type:

pd.DataFrame

plot(sample_index: int, kind: str = 'table') → None

Create the plot of the counterfactual table

Parameters:

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: 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)

Bases: ExplanationBase

Non-contrastive, global Explanation

explain(sample_index: int, sample_name: str | None = None, separator: str = '\n') → Explanation

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

explanation_name: str = 'permutation'

explanation_style: str = 'non-contrastive'

explanation_type: str = 'global'

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

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

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: DataFrame, y: ndarray, model: ClassifierMixin | RegressorMixin, number_of_features: int = 4, config: Dict[str, str] | None = None, **kwargs)

Bases: ExplanationBase

Non-contrastive, local Explanation

explain(sample_index: int, sample_name: str | None = None, separator: str = '\n') → Explanation

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

explanation_name: str = 'shap'

explanation_style: str = 'non-contrastive'

explanation_type: str = 'local'

get_feature_values(sample_index: int = 0) → List[Tuple[str, float]]

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)))

plot(sample_index: int, kind: str = 'bar') → None

Plot the shap values

Parameters:

• sample_index (int, optional) – DESCRIPTION. Defaults to 0.

• kind (TYPE, optional) – DESCRIPTION. Defaults to “bar”.

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: DataFrame, y: DataFrame | ndarray, model: ClassifierMixin | RegressorMixin, number_of_features: int = 4, config: Dict[str, str] | None = None, kind: str = 'tree', **kwargs: dict)

Bases: ExplanationBase

Contrastive, global Explanation

explain(sample_index: int, sample_name: str | None = None, separator: str = '\n') → Explanation

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_feature_values()

Get the feature values

get_method_text() → str

Define the method introduction text of the explanation type.

Returns:

method_text explanation

Return type:

str

get_natural_language_text() → str

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

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

Return the importance of the surrogate model

Returns:

importance of the surrogate model

Return type:

str

plot(sample_index: int = None) → None

Plot the surrogate model

Parameters:

sample_index (int) – index of the sample in scope.

Raises:

Exception – if the type of kind is not supported

save(sample_index: int, sample_name: str | None = None) → None

Save the explanations to a csv file, save the plots

Parameters:

• sample_index (int) – index of sample in scope

• sample_name (str) – name of the sample in scope

Returns:

None.

Module contents