Explaining Module

The Explaining module provides different methods for explaining decisions made by ML models. The classe Explainer is the main class that common functionality for computing explanations on various machine learning models. All explainers are subclasses of this last one.

The function of module Explaining.initialize returns the appropriate Explainer object according to a model.

from pyxai import Learning, Explaining, Tools
learner = Learning.Scikitlearn("../../dataset/iris.csv", problem_type=Learning.CLASSIFICATION)
model = learner.evaluate(splitting_method=Learning.HOLD_OUT, model_type=Learning.DT)

instance, prediction = learner.get_instances(model, n=1, is_correct=True)
explainer = Explaining.initialize(model, instance)

Methods

Main Methods

• Explainer.set_instance: Set the instance to explain and reset cached counters.
• Explainer.set_features_type: Define the types of features (numerical, categorical, binary) to handle dependencies (domain theory).
• Explainer.get_model: Return the machine learning model associated with the explainer.
• Explainer.predict: Return the prediction of an instance w.r.t. the model associated to the explainer.
• Explainer.activate_theory: Activate a theory in the resolution method.
• Explainer.deactivate_theory: Disable the theory-based reasoning in the explainer.
• Explainer.set_excluded_features: Set the features that the user do not want to see in explanations.
• Explainer.unset_excluded_features: Clear any feature exclusions previously set.

Human-Readable Explanation Methods

• Explainer.to_features: Converts a binary representation of a reason into the features space.
• Explainer.get_feature_names: Return the names of the features used in the model.
• Explainer.get_feature_names_from_literal: Retrieve the original feature name associated with a specific binary literal.
• Explainer.reason_contains_features: Returns True if the reason contains the feature_name.

Explanation verification methods

• Explainer.is_implicant: Check if a binary representation (partial or complete) implies the prediction.
• Explainer.is_reason: Return if the reason given in parameter is really a reason.
• Explainer.is_sufficient_reason: This method checks whether a reason is sufficient.
• Explainer.is_contrastive_reason: Check if a reason (subset of the binary representation) is contrastive.

• ExplainerRF.is_majoritary_reason: Heuristically check whether a given reason behaves like a majoritary reason.

• ExplainerBT.is_tree_specific_reason: Heuristically check whether a given reason (subset of the binary representation) behaves like a tree specific reason.

Methods for calculating explanations

• ExplainerDT.direct_reason: Compute the direct reason for the current instance.
• ExplainerDT.contrastive_reason: Compute up to n contrastive reasons for the current instance.
• ExplainerDT.necessary_literals: Return literals that are necessary for the current prediction.
• ExplainerDT.relevant_literals: Return literals that appear in non-unit clauses of the CNF core.
• ExplainerDT.sufficient_reason: Enumerate up to n sufficient reasons for the current prediction.
• ExplainerDT.preferred_sufficient_reason: Compute sufficient reasons optimized by a preference criterion.
• ExplainerDT.minimal_sufficient_reason: Compute up to n sufficient reasons of minimal size.
• ExplainerDT.n_sufficient_reasons: Return the total number of sufficient reasons per boolean attributes.

• ExplainerRF.direct_reason: Compute the direct reason for the current instance.
• ExplainerRF.minimal_contrastive_reason: Compute up to n contrastive reasons for the current instance.
• ExplainerRF.sufficient_reason: Compute a sufficient reason.
• ExplainerRF.minimal_sufficient_reason: Compute a minimal-size sufficient reason for the current instance.
• ExplainerRF.majoritary_reason: Compute a majoritary reason for the current instance.
• ExplainerRF.preferred_majoritary_reason: Compute sufficient reasons optimized by a preference criterion.
• ExplainerRF.minimal_majoritary_reason: Compute up to n minimal majoritary reasons of minimal size.

• ExplainerBT.direct_reason: Compute the direct reason for the current instance.
• ExplainerBT.tree_specific_reason: Compute a tree specific reason for the current instance.
• ExplainerBT.minimal_tree_specific_reasons: Compute n minimal tree specific reasons for the current instance.
• ExplainerBT.minimal_contrastive_reason: Compute n minimal contrastive reasons for the current instance.

• ExplainerRegressionBT.set_interval: For the regression case, one has to provide an interval, for which the prediction is acceptable for the user.
• ExplainerRegressionBT.extremum_range: The extremum range for predictions for the model.
• ExplainerRegressionBT.range_for_partial_instance: Extract the range for all possible extension of the partial instance.
• ExplainerRegressionBT.tree_specific_reason: Compute a tree specific reason for the current instance.

Rectification Methods

• ExplainerDT.rectify: Rectification enforces that the (parsed) conditions imply the given label in the model.
• ExplainerRF.rectify: Rectify the random forest to satisfy a labeled constraint.

Enumerations

Explaining.ALL

Explaining.ALL: Constant meaning that all explanations are requested

Explaining.TIMEOUT

Explaining.TIMEOUT: Time out has been reached when computing some explanations (see the documentation page)

PreferredReasonMethod

Represent the available methods for a preference criterion in some explanations.

• PreferredReasonMethod.Minimal | Explaining.MINIMAL | minimal:
  Equivalent to minimal_majoritary_reason().

• PreferredReasonMethod.FeatureImportance | Explaining.FEATURE_IMPORTANCE | feature-importance:
  The opposite of the f-importance of each feature in F as computed by Scikit-Learn.

• PreferredReasonMethod.Shapley | Explaining.SHAPLEY | shapley:
  Shapely values for the model trained on data. Only available with a model from scikitlearn or a save from scikitlearn. For each random forest F, the opposite of the SHAP score [Lundberg and Lee, 2017; Lundberg et al., 2020] of each feature of the instance x at hand given F computed using SHAP (shap.readthedocs.io/en/latest/api.html)

• PreferredReasonMethod.Weights | Explaining.WEIGHTS | weights:
  Weight given bu the user thought the weights parameters.

• PreferredReasonMethod.WORD_FREQUENCY | Explaining.WordFrequency | word-frequency:
  The opposite of the Zipf frequency of each feature viewed as a word in the wordfreq library.

• PreferredReasonMethod.WORD_FREQUENCY_LAYERS | Explaining.WordFrequencyLayers | word-frequency-layers:
  WORD_FREQUENCY with layers.

Dictionnaries

ImageDict

This Python Dictionnary contains some information about a learner, a dataset and a model.

• shape: (int, int) | (int, int, int)
  Tuple representing the number of horizontal and vertical pixels. If the number of values representing a pixel is not equal to 1, the last value of this tuple have to contain this number (example: (8,8,3) represents an image of 8 * 8 = 64 pixels where each pixel contains 3 color values (RGB)).

• dtype: numpy.dtype Domain of values for each pixel. For example, numpy.uint8 for 256 values from 0 to 255.

• get_pixel_value(instance, x, y, shape): Callable
  Python function with 4 parameters which returns the value of a pixel according to a pixel position (x,y). Get from the position of a pixel x and y a color value according to an instance.

• instance_index_to_pixel_position(i, shape): Callable
  Python function with 2 parameters which returns a pixel position (x,y) according to an index of the instance.

Example

TODO