Class Explainer
The base class for all explainers in PyXAI.
This class provides common functionality for computing explanations on various machine learning models (Decision Trees, Random Forests, Boosted Trees). It manages the input instance, its binary representation, feature types (numerical, categorical, binary), and the inclusion/exclusion of features in the generated explanations.
Attributes
target_prediction : int|float
The prediction of the model for the current instance.
instance : list[float]
The current instance to be explained (property).
binary_representation : list[int]
The internal Boolean representation of the instance (property).
elapsed_time : float
Execution time of the last explanation computation (property).
It is equal to Explainer.TIMEOUT if time limit was reached.
visualisation : Visualisation
Object used to display or save explanation results (property).
See the Visualisation class for more information.
Main Methods
def activate_theory(self): Highlight
Add a theory in the resolution method.
This allows to represent the fact that conditions depend on other conditions of a numerical attribute in explainer.
def deactivate_theory(self): Highlight
Disable the theory-based reasoning in the explainer.
def get_model(self): Highlight
Return the machine learning model associated with the explainer.
Returns
DecisionTree, RandomForest, etc. :
The model instance.
def predict(self, instance): Highlight
def set_excluded_features(self, excluded_features): Highlight
def set_features_type(self, features_types): Highlight
Define the types of features (numerical, categorical, binary) to handle dependencies (theory).
This method allows the explainer to understand relationships between features, especially those created by one-hot encoding.
Parameters
features_types : (str | dict)
Path to a .types file (JSON) or a dictionary describing the features.
Raises
ValueError
NotImplementedError
Examples
>>>
australian_types = {
"numerical": Learning.DEFAULT,
"categorical": {"A4*": (1, 2, 3),
"A5*": tuple(range(1, 15)),
"A6*": (1, 2, 3, 4, 5, 7, 8, 9),
"A12*": tuple(range(1, 4))},
"binary": ["A1", "A8", "A9", "A11"],
}
def set_instance(self, instance): Highlight
Set the instance to explain and reset cached counters.
Once the Explainer is built, you can explain several instances using it. Each time you want to explain a new instance, you need to call the function set_instance (it is not necessary to create a new Explainer object).
def unset_excluded_features(self): Highlight
Clear any feature exclusions previously set.
Human-readable Explanations Methods
def get_feature_names(self): Highlight
def get_feature_names_from_literal(self, literal): Highlight
def reason_contains_features(self, reason, features_name): Highlight
def to_features(self,
binary_representation,
eliminate_redundant_features=True,
details=False,
contrastive=False,
without_intervals=False): Highlight
Converts a binary representation of a reason into the features space.
When the parameter details is set to False, returns a Tuple of String where each String represents a condition “<id_feature> <operator> <threshold>” associated with the binary representation given as first parameter. By default, a string represents such a condition but if you need more information, you can set the parameter details to True. In this case, the method returns a Tuple of Dict where each dictionary provides more information on the condition. This method also allows one to eliminate redundant conditions. For example, if we have “feature_a > 3” and “feature_a > 2”, we keep only the binary variable linked to the Boolean corresponding to the “feature_a > 3”. Therefore, if you want to get all conditions, you have to set the parameter eliminate_redundant to False. The function to_features is independent of the instance given by the explainer through the initialize and set_instance methods, but depends only on the binary representation given by the parameter.
Parameters
binary_representation : list[int]
the binary representation to convert
eliminate_redundant_features : bool (optional, default: True)
eliminate possible redundant features.
details : bool (optional, default: False)
returns a detailed representation instead of a string
contrastive : bool (optional, default: False):
invert logic in order to explain a contrastive reason
The details provided with the details parameter set to
Truein the to_features function are represented by the keys of the returned dictionary:
-["id"]: The id of the feature.
-["name"]: The name of the feature (if labels are known, otherwise they are named f1, f2 and so on).
-["operator"]: The operator associated with the condition.
-["threshold"]: The threshold of the condition.
-["sign"]: The sign of the Boolean variable in the binary representation:Trueif the condition is satisfied elseFalse.
-["weight"]: The weight of the condition, used only with user preferences.
Explanation Verification Methods
def is_contrastive_reason(self, reason): Highlight
def is_implicant(self, binary_representation): Highlight
def is_reason(self, reason, *, n_samples=1000): Highlight
def is_sufficient_reason(self, reason, *, n_samples=50): Highlight
Checks if a reason is a sufficient one.
This method checks whether a reason is sufficient. To this purpose, we first call firstly the method is_reason to check whether n_samples complete binary representations from this reason (randomly generated) lead to the correct prediction or not. Then, we verify the minimality of the reason in the sense of set inclusion. To do that, we delete a literal of the reason, test with is_reason that this new binary representation is not a reason and put back this literal. The method repeats this operation on every literal of the reason. Because this method is based on random generation and a limited number of samples, it is not deterministic (i.e., it is not 100% sure to provide the right answer). Therefore, this method can return True, False or None.