shapiq.tree.InterventionalTreeExplainer

class shapiq.tree.InterventionalTreeExplainer(model, data, class_index=None, *, debug=False, max_order=2, index='SII', index_func=None, bool_tree=False, weight_fn=None)[source]

Bases: object

Any-order interventional Shapley-interaction explainer for tree models.

Extends interventional TreeSHAP to compute exact Shapley interactions of arbitrary order over a single decision tree or a tree ensemble (as validated by shapiq.tree.validation.validate_tree_model()). Each coalition’s contribution is decomposed against a reference background dataset using the E/R partition (features fixed by the explained point vs. by the reference), and the recursion is offloaded to one of two C++ kernels:

  • Dense flatten path — compute_interactions_flatten() for max_order <= 3 when the dense buffer fits within _DENSE_FLATTEN_MAX_RESULT_SIZE.

  • Sparse path — compute_interactions_batched_sparse() for higher orders or wide-feature trees.

Indices supported via the C path are listed in INDICES_C_IMPLEMENTATION_CAPABLE. Custom weight functions are accepted via weight_fn and routed through a precomputed lookup table.

The baseline value is computed from the validated trees by summing per-tree predictions over the reference data. validate_tree_model already scales sklearn ensemble trees by 1/n_estimators and extracts class-specific raw scores for XGBoost / LightGBM classifiers, so this single path lands on the same scale as the kernel for every supported model.

Variables:

  • tree – Validated tree (or list of trees) from validate_tree_model().

  • reference_data – Background dataset (shape (n_ref, n_features)) used to define interventional baselines, cast to float32.

  • baseline_value – Mean tree-prediction over reference_data (scalar); written as the order-0 entry of the returned interactions.

  • max_order – Maximum interaction order computed.

  • index – Interaction index (e.g. "SII"); replaced with "CUSTOM" when weight_fn is supplied.

  • n_players – Number of features.

Parameters:

  • model (object)

  • data (np.ndarray)

  • class_index (int | None)

  • debug (bool)

  • max_order (int)

  • index (str)

  • index_func (Callable | None)

  • bool_tree (bool)

  • weight_fn (Callable[[int, int, int], float] | None)

Initialize the InterventionalTreeExplainer.

Parameters:

  • model (object) – A fitted tree or tree ensemble compatible with shapiq.tree.validation.validate_tree_model() (sklearn, XGBoost, LightGBM, or a precomputed leaf-matrix list).

  • data (ndarray) – Background dataset of shape (n_ref, n_features) defining the interventional baseline.

  • class_index (int | None) – Class index for classifiers. For binary predict_proba models, defaults to 1 if left as None. Ignored for regressors.

  • debug (bool) – If True, the C++ kernel prints debug information. Defaults to False.

  • max_order (int) – Maximum interaction order to compute. Defaults to 2.

  • index (str) – Interaction index; one of INDICES_C_IMPLEMENTATION_CAPABLE. Replaced with "CUSTOM" when weight_fn is supplied. Defaults to "SII".

  • index_func (Callable | None) – Reserved for a Python-side custom index function. Defaults to None.

  • bool_tree (bool) – If True, the tree is treated as boolean (coalitions in \(\\{0, 1\\}^n\)) and preprocessed once with the BitSet DFS C++ helper instead of per-explanation. Used by ProxySHAP. Defaults to False.

  • weight_fn (Callable[[int, int, int], float] | None) – Optional custom weight callable with signature weight_fn(coalition_size, interaction_size, n_players) -> float. When supplied, overrides index and triggers building a precomputed lookup table. Defaults to None.

explain_function(x, **_)[source]

Compute interaction values for a single instance.

Routes to the dense flatten C kernel for low-order, narrow-feature cases and to the sparse batched C kernel otherwise (see the class docstring). The empty interaction () is always populated with self.baseline_value before constructing the result.

Parameters:

  • x (ndarray) – The instance to explain, as a 1-D array of length self.n_players.

  • _ (dict)

Return type:

InteractionValues

Returns:

InteractionValues carrying the requested interaction index, max_order=self.max_order, and min_order=1 as the declared lower bound on computed orders. Note that the underlying interactions dict still contains the empty-set entry () set to self.baseline_value, even though min_order reports 1.