Class ExplainerDT (extends Explainer)
The Decision-tree explainer.
This class adapts the Explainer class to a DecisionTree model. It provides methods to:
- set an instance and derive its Boolean (literal-based) representation,
- compute different families of explanations (direct, contrastive, sufficient, preferred),
- query literals that are necessary or relevant for the current prediction,
- optionally rectify (modify) the decision tree to enforce a desired label under given conditions.
Some functions come from the parent class Explainer, their documentation is available in the dedicated page:
- Main Methods:
set_instance,set_features_type,get_model,predict,activate_theory,deactivate_theory,set_excluded_features,unset_excluded_features; - Human-Readable Explanation Methods:
to_features,get_feature_names,get_feature_names_from_literal,reason_contains_features; - Explanation verification methods:
is_implicant,is_reason,is_sufficient_reason,is_contrastive_reason.
See also
- The documentation pages
- The paper On the Explanatory Power of Decision Trees
def __init__(self, tree, instance=None): Highlight
Initialize an explainer for a decision tree.
Parameters
tree : DecisionTree
The model in the form of a DecisionTree.
instance : list[float] (optional, default: None)
The instance (observation) for which explanations will be computed.
If None, you must call set_instance before requesting explanations.
def rectify(self, *, conditions, label, tests=False): Highlight
Rectify the decision tree to satisfy a labeled constraint.
Rectification enforces that the (parsed) conditions imply the given label in the model, then simplifies the resulting tree (optionally leveraging the explainer’s theory constraints).
Parameters
conditions : list of int
Conditions (premises part of the classification rule) in the form of a binary representation (list of literals).
label : int
Label representing the conclusion part of the classification rule.
tests : bool (optional, default: False)
If True, runs additional post-steps checks (can be expensive) to ensure rectification
preserved the intended implicant property.
Returns
None : DecisionTree
The rectified (and simplified) decision tree.
Methods for Calculating Explanations
def contrastive_reason(self, *, n=1): Highlight
Compute up to n contrastive reasons for the current instance.
Contrastive explanations explain why the instance has not been classified by the ML model as expected. Returns n contrastive reasons sorted by increasing of the size for the current instance in a Tuple (when n is set to 1, does not return a Tuple but just the reason). Supports excluded features.
Parameters
n : int | Explaining.ALL (optional, default=1)
Maximum number of contrastive reasons to return. If a Explaining.ALL is provided,
all computed candidates are formatted/returned.
Returns
tuple[int] :
if n == 1, returns a single reason as a tuple of literals.
tuple[tuple[int]] :
If n > 1, returns a tuple of reasons (each one is a tuple of literals).
None :
If all reasons contain excluded features.
As the contrastive_reason returns the contrastive reasons in a ascending order according to their sizes,
the minimal contrastive reasons are the first ones in the returned tuple.
def minimal_sufficient_reason(self, *, n=1, time_limit=None): Highlight
Compute up to n sufficient reasons of minimal size.
Parameters
n : int | Explaining.ALL, (optional, default=1)
Maximum number of sufficient reasons to enumerate. If Explaining.ALL, treated as unbounded.
time_limit : float (optional, default=None)
Time limit (seconds) for the whole enumeration. If reached, elapsed_time is set to Explaining.TIMEOUT.
Returns
tuple[int] :
if n == 1, returns a single reason as a tuple of literals.
tuple[tuple[int]] :
If n > 1, returns a tuple of reasons (each one is a tuple of literals).
None :
If all reasons contain excluded features.
def n_sufficient_reasons(self, time_limit=None): Highlight
Return the total number of sufficient reasons.
Parameters
time_limit : float (optional, default=None)
Time limit (seconds) for the whole enumeration. If reached, elapsed_time is set to Explaining.TIMEOUT.
def n_sufficient_reasons_per_attribute(self, *, time_limit=None): Highlight
Return the total number of sufficient reasons per boolean attributes.
Parameters
time_limit : float (optional, default=None)
Time limit (seconds) for the whole enumeration. If reached, elapsed_time is set to Explaining.TIMEOUT.
Returns
dict :
A dictionary where the keys are the literals and the values the numbers of sufficient reasons.
def necessary_literals(self): Highlight
def preferred_sufficient_reason(self, *, method, n=1, time_limit=None, weights=None, features_partition=None): Highlight
Compute sufficient reasons optimized by a preference criterion.
This method searches for sufficient reasons that maximize a score derived from feature weights. Optimization is performed using a MaxSAT solver (hard clauses enforce correctness; soft clauses penalize selecting literals).
Parameters
method : PreferredReasonMethod | str
The preference method used to discriminate reasons.
Possible values are defined in the PreferredReasonMethod enum.
n : int | Explaining.ALL, (optional, default=1)
Maximum number of preferred reasons to return (ties with the identical best score are returned
up to n).
time_limit : float (optional, default=None)
Time limit (seconds) for the whole enumeration. If reached, elapsed_time is set to Explaining.TIMEOUT.
weights : list[float] | None (optional)
per-feature weights
If None, weights are computed from using the parameter method.
features_partition : object | None (optional, default: None)
partitioning information passed to the weight computation helper.
Returns
tuple[int] :
if n == 1, returns a single reason as a tuple of literals.
tuple[tuple[int]] :
If n > 1, returns a tuple of reasons (each one is a tuple of literals).
None :
If all reasons contain excluded features.
def relevant_literals(self): Highlight
def sufficient_reason(self, *, n=1, time_limit=None): Highlight
Enumerate up to n sufficient reasons for the current prediction.
A sufficient reason is a (typically) minimal subset of the binary representation that still entails the current prediction.
Returns n sufficient reasons of the current instance in a Tuple (when n is set to 1, does not return a tuple but just the reason). Supports the excluded features. The reasons are in the form of binary variables, you must use the to_features method if you want to get a representation based on the features represented at start.
Parameters
n : int | Explaining.ALL, (optional, default=1)
Maximum number of sufficient reasons to enumerate. If Explaining.ALL, treated as unbounded.
time_limit : float (optional, default=None)
Time limit (seconds) for the whole enumeration. If reached, elapsed_time is set to Explaining.TIMEOUT.
Returns
tuple[int] :
if n == 1, returns a single reason as a tuple of literals.
tuple[tuple[int]] :
If n > 1, returns a tuple of reasons (each one is a tuple of literals).
None :
If all reasons contain excluded features.