teacher.neighbors

The teacher.neighbors module provides classes to generate neighborhoods from an instance. These neighborhoods are used in agnostic explainers, so that a blackbox can be explained in the locality of an instance. They are decoupled from the explainers so that different neighborhoods can be used or created ad-hoc for the different explainers.

Classes

These are the different neighborhoods implemented in the tool. They match the Estimator guidelines of scikit-learn and can be inherited and expanded to create a more adequate neighborhood for the different explainers.

BaseNeighborhood

Abstract base class from which all the neighbors must extend. Provided as baseline for new neighborhood creations.

FuzzyNeighborhood

Abstract base class that extends from BaseNeighborhood and provides methods to fuzzify a the neighborhood. This is a baseline to create neighborhoods to be used with fuzzy models such as FDT and used in Explainers based on those models such as FDTExplainer.

SimpleNeighborhood

Baseline functional neighborhood that replicates an instance as many times as required without modifying it.

LoreNeighborhood

Fuzzy adaptation of the neighborhood defined for the LORE algorithm, which uses a genetic generation to obtain sufficient modifications of the original instance to train a white-box classifier

---

class teacher.neighbors.BaseNeighborhood(instance, size, class_name, bb)

Base abstract neighborhood that provides the basic operations for all the other neighborhoods.

__init__(instance, size, class_name, bb)

Parameters:

• instance (array-like, of shape (n_features)) – Instance to generate the neighborhood from

• size (int) – Size of the neighborhood

• class_name (str) – Name of the feature that is the class value

• bb (scikit-learn compatible predictor) – Black-box already fitted with the input data.

abstract fit()

Perform the necessary operations to get a neighborhood from a given instance

get_X()

Return the neighborhood

Returns:

Neighborhood

Return type:

array-like, of shape (size, n_features)

Raises:

NotFittedError – If the neighborhood is not fitted yet

get_y()

Return the black-box prediction of the neighborhood

Returns:

Array of the predictions

Return type:

array-like, of shape(size)

Raises:

NotFittedError – If the neighborhood is not fitted yet

class teacher.neighbors.FuzzyNeighborhood(instance, size, class_name, bb)

Base Fuzzy abstract neighborhood that provides the starting point for all fuzzy neighborhoods

__init__(instance, size, class_name, bb)

Parameters:

• instance (array-like, of shape (n_features)) – Instance to generate the neighborhood from

• size (int) – Size of the neighborhood

• class_name (str) – Name of the feature that is the class value

• bb (scikit-learn compatible predictor) – Black-box already fitted with the input data.

fuzzify(get_division, **kwargs)

Method to fuzzify a fitted neighborhood, obtaining the fuzzy partitions and obtaining the membership degrees of the different fuzzy sets for all the instances of the neighborhood.

Parameters:

get_division (str, {"equal_width", "equal_freq", "entropy"}) – Type of fuzzy discretization of the neighborhood

Keyword Arguments:

• df_numerical_columns (list) – List with all the numerical columns

• df_categorical_columns (list) – List with all the categorical columns

• sets (int) – Number of sets, needed for get_division=”equal_width” or get_division=”equal_freq”

• fuzzy_labels (list, of shape (n_sets)) – Optional list of names for the sets generated with the methods get_division=”equal_width” or get_division=”equal_freq”

• class_name (str) – Name of the class variable, needed for get_division=”entropy”

• verbose (bool) – Debug flag

Raises:

• NotFittedError – Neighborhood must be fitted before fuzzifying

• ValueError – Argument mismatch

get_X_membership()

Return the membership degrees of the neighborhood

Returns:

Dictionary of shape {feature: {set_1: [pert_1, pert_2, …]}} with the pertenence degrees of the neighborhood extracted by teacher.fuzzy.dataset_membership()

Return type:

dict

Raises:

NotFuzzifiedError – If the neighborhood is not fuzzified yet

get_instance_membership()

Return the membership degrees of the instance

Returns:

Dictionary of shape {feature: {set_1: [pert_1, pert_2, …]}} with the pertenence degrees of the instance extracted by teacher.fuzzy.dataset_membership()

Return type:

dict

Raises:

NotFuzzifiedError – If the neighborhood is not fuzzified yet

get_fuzzy_variables()

Return the fuzzy variables used in the neighborhood

Returns:

List with all the fuzzy variables already generated

Return type:

list[FuzzyVariable]

Raises:

NotFuzzifiedError – If the neighborhood is not fuzzified yet

abstract fit()

Perform the necessary operations to get a neighborhood from a given instance

get_X()

Return the neighborhood

Returns:

Neighborhood

Return type:

array-like, of shape (size, n_features)

Raises:

NotFittedError – If the neighborhood is not fitted yet

get_y()

Return the black-box prediction of the neighborhood

Returns:

Array of the predictions

Return type:

array-like, of shape(size)

Raises:

NotFittedError – If the neighborhood is not fitted yet

class teacher.neighbors.SimpleNeighborhood(instance, size, class_name, bb)

Simple neighborhood that is formed by copying the instance as many times as the size of the neighborhood without modifying it

__init__(instance, size, class_name, bb)

Parameters:

• instance (array-like, of shape (n_features)) – Instance to generate the neighborhood from

• size (int) – Size of the neighborhood

• class_name (str) – Name of the feature that is the class value

• bb (scikit-learn compatible predictor) – Black-box already fitted with the input data.

fit()

Perform the necessary operations to get a neighborhood from a given instance

get_X()

Return the neighborhood

Returns:

Neighborhood

Return type:

array-like, of shape (size, n_features)

Raises:

NotFittedError – If the neighborhood is not fitted yet

get_y()

Return the black-box prediction of the neighborhood

Returns:

Array of the predictions

Return type:

array-like, of shape(size)

Raises:

NotFittedError – If the neighborhood is not fitted yet

class teacher.neighbors.LoreNeighborhood(instance, size, class_name, bb, dataset, X2E, idx_record_to_explain)

Fuzzy adaptation of the neighborhood used by LORE, which generates the different elements by modifying the instance using a genetic algorithm in order to obtain elements for all the different possible class values.

__init__(instance, size, class_name, bb, dataset, X2E, idx_record_to_explain)

Parameters:

• instance (array-like, of shape (n_features)) – Instance to generate the neighborhood from

• size (int) – Size of the neighborhood

• class_name (str) – Name of the feature that is the class value

• bb (scikit-learn compatible predictor) – Black-box already fitted with the input data.

• X2E (LORE styled dataset - Legacy) – Necessary dataset for the LORE genetic algorithm to work

• idx_record_to_explain (int - Legacy) – Index of the instance to explain in X2E

fit()

Perform the necessary operations to get a neighborhood from a given instance

fuzzify(get_division, **kwargs)

Method to fuzzify a fitted neighborhood, obtaining the fuzzy partitions and obtaining the membership degrees of the different fuzzy sets for all the instances of the neighborhood.

Parameters:

get_division (str, {"equal_width", "equal_freq", "entropy"}) – Type of fuzzy discretization of the neighborhood

Keyword Arguments:

• df_numerical_columns (list) – List with all the numerical columns

• df_categorical_columns (list) – List with all the categorical columns

• sets (int) – Number of sets, needed for get_division=”equal_width” or get_division=”equal_freq”

• fuzzy_labels (list, of shape (n_sets)) – Optional list of names for the sets generated with the methods get_division=”equal_width” or get_division=”equal_freq”

• class_name (str) – Name of the class variable, needed for get_division=”entropy”

• verbose (bool) – Debug flag

Raises:

• NotFittedError – Neighborhood must be fitted before fuzzifying

• ValueError – Argument mismatch

get_X()

Return the neighborhood

Returns:

Neighborhood

Return type:

array-like, of shape (size, n_features)

Raises:

NotFittedError – If the neighborhood is not fitted yet

get_X_membership()

Return the membership degrees of the neighborhood

Returns:

Dictionary of shape {feature: {set_1: [pert_1, pert_2, …]}} with the pertenence degrees of the neighborhood extracted by teacher.fuzzy.dataset_membership()

Return type:

dict

Raises:

NotFuzzifiedError – If the neighborhood is not fuzzified yet

get_fuzzy_variables()

Return the fuzzy variables used in the neighborhood

Returns:

List with all the fuzzy variables already generated

Return type:

list[FuzzyVariable]

Raises:

NotFuzzifiedError – If the neighborhood is not fuzzified yet

get_instance_membership()

Return the membership degrees of the instance

Returns:

Dictionary of shape {feature: {set_1: [pert_1, pert_2, …]}} with the pertenence degrees of the instance extracted by teacher.fuzzy.dataset_membership()

Return type:

dict

Raises:

NotFuzzifiedError – If the neighborhood is not fuzzified yet

get_y()

Return the black-box prediction of the neighborhood

Returns:

Array of the predictions

Return type:

array-like, of shape(size)

Raises:

NotFittedError – If the neighborhood is not fitted yet

class teacher.neighbors.SamplingNeighborhood(instance, size, class_name, bb, dataset, X2E, idx_record_to_explain, neighbor_generation='slow', neighbor_range='std')

Fuzzy sampling neighborhood, which checks the range of the different features in order to compute a random neighborhood that is representative of the different variables close to the instance.

__init__(instance, size, class_name, bb, dataset, X2E, idx_record_to_explain, neighbor_generation='slow', neighbor_range='std')

Parameters:

• instance (array-like, of shape (n_features)) – Instance to generate the neighborhood from

• size (int) – Size of the neighborhood

• class_name (str) – Name of the feature that is the class value

• bb (scikit-learn compatible predictor) – Black-box already fitted with the input data.

• X2E (LORE styled dataset - Legacy) – Necessary dataset for the LORE genetic algorithm to work

• idx_record_to_explain (int - Legacy) – Index of the instance to explain in X2E

• neighbor_generation (str, default='slow') – Method to generate the neighborhood. It can be ‘slow’ or ‘fast’. ‘slow’ uses the instance to be explained while ‘fast’ also looks for the closest instance from different classes to generate the neighborhood.

• neighbor_range (float or str, default='std') – Range of the neighborhood. If it is a float, it will be the percentage of the range of the feature. If it is ‘std’, it will be the standard deviation of the feature.

fit()

Perform the necessary operations to get a neighborhood from a given instance

fuzzify(get_division, **kwargs)

Method to fuzzify a fitted neighborhood, obtaining the fuzzy partitions and obtaining the membership degrees of the different fuzzy sets for all the instances of the neighborhood.

Parameters:

get_division (str, {"equal_width", "equal_freq", "entropy"}) – Type of fuzzy discretization of the neighborhood

Keyword Arguments:

• df_numerical_columns (list) – List with all the numerical columns

• df_categorical_columns (list) – List with all the categorical columns

• sets (int) – Number of sets, needed for get_division=”equal_width” or get_division=”equal_freq”

• fuzzy_labels (list, of shape (n_sets)) – Optional list of names for the sets generated with the methods get_division=”equal_width” or get_division=”equal_freq”

• class_name (str) – Name of the class variable, needed for get_division=”entropy”

• verbose (bool) – Debug flag

Raises:

• NotFittedError – Neighborhood must be fitted before fuzzifying

• ValueError – Argument mismatch

get_X()

Return the neighborhood

Returns:

Neighborhood

Return type:

array-like, of shape (size, n_features)

Raises:

NotFittedError – If the neighborhood is not fitted yet

get_X_membership()

Return the membership degrees of the neighborhood

Returns:

Dictionary of shape {feature: {set_1: [pert_1, pert_2, …]}} with the pertenence degrees of the neighborhood extracted by teacher.fuzzy.dataset_membership()

Return type:

dict

Raises:

NotFuzzifiedError – If the neighborhood is not fuzzified yet

get_fuzzy_variables()

Return the fuzzy variables used in the neighborhood

Returns:

List with all the fuzzy variables already generated

Return type:

list[FuzzyVariable]

Raises:

NotFuzzifiedError – If the neighborhood is not fuzzified yet

get_instance_membership()

Return the membership degrees of the instance

Returns:

Dictionary of shape {feature: {set_1: [pert_1, pert_2, …]}} with the pertenence degrees of the instance extracted by teacher.fuzzy.dataset_membership()

Return type:

dict

Raises:

NotFuzzifiedError – If the neighborhood is not fuzzified yet

get_y()

Return the black-box prediction of the neighborhood

Returns:

Array of the predictions

Return type:

array-like, of shape(size)

Raises:

NotFittedError – If the neighborhood is not fitted yet