Ctrl+K

teacher.explanation#

The teacher.explanation module includes the methods to generate factual and counterfactual explanations, as well as the Explainer classes

Factual explanations#

Factual explanations are those that let us help to explain the classification of an instance into a determined category. In this case, a factual explanation is formed by a rule or set of rules that are extracted from the rule-based model that classifies the instance. The following methods generate factual explanations as explained in this article:

FID3_factual()

Baseline factual that takes the single rule with the maximum matching from all the fired rules.

m_factual()

Factual associated with the mean, which adds rules to the factual until the cummulative association degree is higher than the average association degree.

c_factual():

Factual associated with the quotient (and with minimum mass). This factual adds rules to the factual as long as they are sufficiently alike. If the minimum mass is established, the cummulative association degree must be higher than that.

mr_factual()

Minimum robust factual, which adds only the number of rules needed for the factual to be robust.

Counterfactual explanations#

Counterfactual explanations are those that let us see which are the minimum changes needed in an instance for it to change class. In this case a counterfactual is formed by a set of tuples (attribute, value) that would represent those changes. In a fuzzy case, guaranteeing the minimum changes needed is a complex problem, so the counterfactuals explained here are extracted from the set of rules generated by the model, and the closest one is chosen according to the metrics defined in this article. The following methods generate counterfactual explanations:

i_counterfactual()

Counterfactual with respect to the instance

f_counterfactual()

Counterfactual with respect to the factual explanation

Explainer#

The Explainer are classes that follow the guidelines of scikit-learn modules in that they can be fitted with data to generate an explanation. They use a white-box model to wrap around an instance and a black-box in order to generate an explanation. Currently, the white-box models supported are defined in teacher.tree. In order to fit the white-box models, the Explainer uses a neighborhood from those defined in teacher.neighbors

FID3Explainer

Baseline explainer that uses an ID3 tree.

FDTExplainer

This explainer uses an FDT tree.

teacher.explanation.FID3_factual(instance, rule_list, threshold=0.01)[source]#

Generate the factual extracted for the ID3, this is, the rule with the maximum matching with the instance.

Parameters:

  • instance (dict, of format {feature: {set_1: pert_1, set_2: pert_2, ...}, ...}) – Fuzzy representation of the instance with all the features and pertenence degrees to each fuzzy set

  • rule_list (list[Rule]) – List of candidate rules to form part of the factual

  • threshold (float, optional) – Activation threshold with which a rule is considered to be fired by the instance, by default 0.01

Returns:

List of factual rules

Return type:

list[Rule]

teacher.explanation.m_factual(instance, rule_list, class_val)[source]#

Generate the factual associated to the mean.

Parameters:

  • instance (dict, of format {feature: {set_1: pert_1, set_2: pert_2, ...}, ...}) – Fuzzy representation of the instance with all the features and pertenence degrees to each fuzzy set

  • rule_list (list[Rule]) – List of candidate rules to form part of the factual

  • class_val (str) – Predicted value that the factual will explain

Returns:

List of factual rules

Return type:

list[Rule]

teacher.explanation.mr_factual(instance, rule_list, class_val)[source]#

Generate the minimum robust factual.

Parameters:

  • instance (dict, of format {set_1: pert_1, set_2: pert_2, ...}, ...}) – Fuzzy representation of the instance with all the features and pertenence degrees to each fuzzy set

  • rule_list (list[Rule]) – List of candidate rules to form part of the factual

  • class_val (str) – Predicted value that the factual will explain

Returns:

List of factual rules

Return type:

list[Rule]

teacher.explanation.c_factual(instance, rule_list, class_val, lam, beta=None)[source]#

Generate the factual associated to the lambda quotient. If beta is passed, it generate the minimum mass factual.

Parameters:

  • instance (dict, of format {set_1: pert_1, set_2: pert_2, ...}, ...}) – Fuzzy representation of the instance with all the features and pertenence degrees to each fuzzy set

  • rule_list (list[Rule]) – List of candidate rules to form part of the factual

  • class_val (str) – Predicted value that the factual will explain

  • lam (float, greater or equals to 0) – Lambda quotient to determine which rules form part of the factual

  • beta (float, greater than 0, optional) – If passed, minimum mass to obtain the rules which form part of the factual, by default None

Returns:

List of factual rules

Return type:

list[Rule]

teacher.explanation.FID3_counterfactual(factual, counter_rules)[source]#

Returns a list that contains the counterfactual for each of the different class values not predicted, as the rule with the most equal literals to the rule.

Parameters:

  • factual (Rule) – List of rules that correspond to a factual explanation of the instance

  • counter_rules (list[Rule]) – List of candidate rules to form part of the counterfactual

Returns:

Tuple with the list of counterfactual rules and the distance

Return type:

(list[Rule], float)

teacher.explanation.i_counterfactual(instance, rule_list, class_val, df_numerical_columns, multiclass=False)[source]#

Return a list that contains the counterfactual with respect to the instance

Parameters:

  • instance (dict, {feature: {set_1: pert_1, set_2: pert_2, ...}, ...}) – Fuzzy representation of the instance with all the features and pertenence degrees to each fuzzy set

  • rule_list (list[Rule]) – List of candidate rules to form part of the counterfactual

  • class_val (str) – Predicted value that the factual will explain

  • df_numerical_columns (list) – List of the numerical columns of the instance, used to compute the distance

Returns:

Set of pairs feature-value with the changes that need to be applied to the instance to change class value.

Return type:

set((feature, value))

teacher.explanation.f_counterfactual(factual, instance, rule_list, class_val, df_numerical_columns, tau=0.5)[source]#

Return a list that contains the counterfactual with respect to the factual

Parameters:

  • factual (list[Rule]) – List of rules that correspond to a factual explanation of the instance for the class value class_val

  • instance (dict, {feature: {set_1: pert_1, set_2: pert_2, ...}, ...}) – Fuzzy representation of the instance with all the features and pertenence degrees to each fuzzy set

  • rule_list (list[Rule]) – List of candidate rules to form part of the counterfactual

  • class_val (str) – Predicted value that the factual will explain

  • df_numerical_columns (list) – List of the numerical columns of the instance, used to compute the distance

  • tau (float, optional) – Importance degree of new elements added or substracted from a rule in contrast to existing elements that have been modified, used to compute the distance , by default 0.5

Returns:

Set of pairs feature-value with the changes that need to be applied to the instance to change class value.

Return type:

set((feature, value))

teacher.explanation.d_counterfactual(decoded_instance, instance_membership, rule_list, class_val, continuous, discrete, mad, distance='moth', tau=0.5)[source]#

Return a list that contains the counterfactual with the closest distance

Parameters:

  • decoded_instance (list) – List of values of the decoded instance

  • instance_membership (dict, {feature: {set_1: pert_1, set_2: pert_2, ...}, ...}) – Fuzzy representation of the instance with all the features and pertenence degrees to each fuzzy set

  • rule_list (list[Rule]) – List of candidate rules to form part of the counterfactual

  • class_val (str) – Predicted value that the factual will explain

  • continuous (list) – List of the numerical columns of the instance, used to compute the distance

  • discrete (list) – List of the categorical columns of the instance, used to compute the distance

  • mad (float) – Mean absolute deviation of the dataset

  • tau (float, optional) – Importance degree of new elements added or substracted from a rule in contrast to existing elements that have been modified, used to compute the distance , by default 0.5

Returns:

Set of pairs feature-value with the changes that need to be applied to the instance to change class value.

Return type:

set((feature, value))

class teacher.explanation.FID3Explainer[source]#

This Explainer uses the ID3 tree implemented in teacher as a white box model to explain a local instance of a scikit-learn compatible black box classifier. Only intended for use as a baseline. It uses its own set of factual and counterfactual explanation generation methods.

fit(instance, target, neighborhood)[source]#

Build a FID3Explainer from the instance, the target and the neighborhood around the instance.

Parameters:

  • instance (array-like of shape (,n_features)) – The input instance

  • target (array-like of shape (1,)) – The expected target

  • neighborhood (LoreNeighborhood) – Neighborhood fitted around the instance to train the whitebox model

class teacher.explanation.FDTExplainer[source]#

This Explainer uses the FDT implemented in teacher as a white box model to explain a local instance of a scikit-learn compatible black box classifier.

fit(instance, target, neighborhood, df_num_cols, factual, counterfactual, **kwargs)[source]#

Build a FDTExplainer from the instance, the target and the neighborhood around the instance

Parameters:

  • instance (array-like of shape (,n_features)) – The input instance

  • target (array-like of shape (1,)) – The expected target

  • neighborhood (class extending from BaseNeighborhood) – Neighborhood fitted around the instance to train the whitebox model

  • df_num_cols (array-like of shape (n_numerical) where) – n_numerical are the number of numerical columns

  • factual ({"m_factual", "mr_factual", "c_factual"}) – The function to compute the factual explanation. Supported methods are explained in this article.

  • counterfactual ({"f_counterfactual", "i_counterfactual"}) – The function to compute the factual explanation. Supported methods are explained in this article.

Raises:

  • ValueError – Factual method invalid

  • ValueError – Counterfactual method invalid

  • ValueError – ‘c_factual’ chosen but no ‘lam’ parameter given

class teacher.explanation.FBDTExplainer[source]#

This Explainer uses the FBDT implemented in teacher as a white box model to explain a local instance of a scikit-learn compatible black box classifier.

fit(instance, target, neighborhood, factual, counterfactual, **kwargs)[source]#

Build a FDTExplainer from the instance, the target and the neighborhood around the instance

Parameters:

  • instance (array-like of shape (,n_features)) – The input instance

  • target (array-like of shape (1,)) – The expected target

  • neighborhood (class extending from BaseNeighborhood) – Neighborhood fitted around the instance to train the whitebox model

  • factual ({"m_factual", "mr_factual", "c_factual"}) – The function to compute the factual explanation. Supported methods are explained in this article.

  • counterfactual ({"f_counterfactual", "i_counterfactual"}) – The function to compute the factual explanation. Supported methods are explained in this article.

Raises:

  • ValueError – Factual method invalid

  • ValueError – Counterfactual method invalid

  • ValueError – ‘c_factual’ chosen but no ‘lam’ parameter given

On this page
Show Source