Class ExplainerBT (extends Explainer)
The Boosted Trees explainer.
This class adapts the generic :class:Explainer to a BoostedTrees model. It provides methods to:
- set an instance and derive its Boolean (literal-based) representation,
- compute different families of explanations (direct, contrastive, sufficient, tree_specific),
- optionally rectify (modify) the random forest 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.
Some methods are limited to binary classification (2 classes). When multi-class support
is not available, an exceptionNotImplementedErroris raised.
See also
- The documentation pages
- The paper Computing Abductive Explanations for Boosted Trees
def __init__(self, boosted_trees, instance=None): Highlight
Initialize an explainer for a Boosted Tree model.
Parameters
boosted_trees : BoostedTrees
The Boosted Trees model to explain.
instance : list[int] (optional, default: None)
The instance (observation) for which explanations will be computed.
If None, you must call set_instance before requesting explanations.
Methods for Calculating Explanations
def direct_reason(self): Highlight
Compute the direct reason for the current instance.
The direct reason is obtained by collecting the root-to-leaf path conditions that cover the instance across the forest, If the result contains excluded features, None is returned.
Returns
list[int] :
A list of literals representing the direct reason
None :
if excluded features appear.
def minimal_contrastive_reason(self, *, n=1, time_limit=None): Highlight
Compute n minimal contrastive reasons for the current instance.
Contrastive explanations explain why the instance has not been classified by the ML model as expected.
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.
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 minimal_tree_specific_reasons(self, *, n=10, time_limit=None): Highlight
Compute n minimal tree specific reasons for the current instance.
This method considers an Mixed Integer Programming problem (MIP) representing the boosted tree encoded. To solve it, several calls to a solver are performed and the result of each call is a minimal tree-specific explanation. The method prevents from finding the same explanation twice or more by adding constraints between each invocation.
Excluded features are not supported.
The reasons are in the form of binary variables, you must use the to_features method if you want to obtain a representation based on the features considered at start.
Parameters
n : int (default: 10)
Number of minimal tree-pecific explanations to compute.
time_limit : float (optional, default=None)
Time limit (seconds) for the whole enumeration. If reached, elapsed_time is set to Explaining.TIMEOUT.
Returns
None : tuple[int] | None
Returns n minimal tree-pecific explanations of the current instance in a Tuple (when n is set to 1, does not return a Tuple but just the reason).
This method is complete and therefore can be time-consuming.
def tree_specific_reason(self, *, n_iterations=50, time_limit=None, seed=0, history=True, theta=0): Highlight
Compute a tree specific reason for the current instance.
This method calls a greedy algorithm to compute a tree-specific explanation (that are, by definition, subset minimal for the inclusion). The algorithm is run n_iterations times and takes the smallest (according to the size of the reason) tree specific reason that has been computed is returned.
Excluded features are supported.
Parameters
n_iterations : int (optional, default: 50)
Number of randomized iterations used to extract the smallest one.
time_limit : float (optional, default=None)
Time limit (seconds) for the whole enumeration. If reached, elapsed_time is set to Explaining.TIMEOUT.
seed : int (optional, default: 0)
Random seed for the randomized iterations. Set to 0 to have a random seed.
Returns
None : tuple[int]
The tree specific reasonNone:
if computed reasons contain excluded features.
The method is heuristic and does not guarantee to return a minimal tree specific reason.
However, it is much faster than the exact method but it returns only one tree specific reason.
Explanation Verification Methods
def is_tree_specific_reason(self, reason, check_minimal_inclusion=False): Highlight
Heuristically check whether a given reason (subset of the binary representation) behaves like a tree specific reason.