shapiq.tree.TreeModel¶

class shapiq.tree.TreeModel(children_left, children_right, children_missing, features, thresholds, values, node_sample_weight, empty_prediction=None, leaf_mask=None, n_features_in_tree=None, max_feature_id=None, feature_ids=None, root_node_id=None, n_nodes=None, nodes=None, decision_type=None, feature_map_original_internal=None, feature_map_internal_original=None, original_output_type='raw', intercepts=None, coeffs=None)[source]¶

Bases: object

Internal representation of a single tree used by the shapiq tree explainers.

Each library-specific converter (scikit-learn, XGBoost, LightGBM, CatBoost) targets this common format so that the downstream algorithms (TreeSHAP-IQ, LinearTreeSHAP, InterventionalTreeSHAP) only need to understand one node-array layout.

Constructor arguments that fall back to a computed default when None is passed are documented on __init__(). The attributes below describe what is available on a fully initialized instance.

Variables:

children_left – The left children of each node in a tree. Leaf nodes are -1.
children_right – The right children of each node in a tree. Leaf nodes are -1.
children_missing – The child each node routes missing-value samples to. Used together with children_left to derive children_left_default during __init__.
children_left_default – Boolean mask. True at index i if missing-value samples at node i are routed to children_left[i]. Derived from children_missing.
features – The feature indices of the decision nodes in a tree. Leaf nodes are -2.
thresholds – The thresholds of the decision nodes in a tree. Leaf nodes are np.nan.
values – The leaf-node values, flattened to a 1-D array. Non-leaf nodes are set to 0.
node_sample_weight – The sample weights of the nodes in a tree.
empty_prediction – The empty prediction of the tree model (weighted mean of leaf values).
leaf_mask – The boolean mask of the leaf nodes in a tree.
n_features_in_tree – The number of distinct features actually used by decision nodes.
max_feature_id – The maximum feature index used by any decision node (or 0 if none).
feature_ids – The set of feature indices used by decision nodes.
root_node_id – The root node id of the tree model. Defaults to 0.
n_nodes – The number of nodes in the tree model.
decision_type – The split comparison used by decision_function(). Either "<=" (default) or "<".
nodes – The node ids of the tree model as np.arange(n_nodes).
feature_map_original_internal – Mapping of feature indices from the original feature indices (as in the model) to the internal feature indices (as in the tree model).
feature_map_internal_original – Mapping of feature indices from the internal feature indices (as in the tree model) to the original feature indices (as in the model).
original_output_type – The original output type of the tree model. Defaults to "raw". Currently not used by downstream algorithms.
intercepts – Per-leaf intercept terms for linear-leaf tree models. Currently unused.
coeffs – Per-leaf coefficient vectors for linear-leaf tree models. Currently unused.

Parameters:

children_left (ndarray[tuple[Any, ...], dtype[int64]])
children_right (ndarray[tuple[Any, ...], dtype[int64]])
children_missing (ndarray[tuple[Any, ...], dtype[int64]])
features (ndarray[tuple[Any, ...], dtype[int64]])
thresholds (ndarray[tuple[Any, ...], dtype[floating]])
values (ndarray[tuple[Any, ...], dtype[floating]])
node_sample_weight (ndarray[tuple[Any, ...], dtype[floating]])
empty_prediction (float)
leaf_mask (ndarray[tuple[Any, ...], dtype[bool]])
n_features_in_tree (int)
max_feature_id (int)
feature_ids (set[int])
root_node_id (int)
n_nodes (int)
nodes (ndarray[tuple[Any, ...], dtype[int64]])
decision_type (str)
feature_map_original_internal (dict[int, int])
feature_map_internal_original (dict[int, int])
original_output_type (str)
intercepts (ndarray[tuple[Any, ...], dtype[floating]])
coeffs (ndarray[tuple[Any, ...], dtype[floating]])

Initialize the TreeModel.

All numpy-array arguments must share a common node ordering. Arguments listed as None-able fall back to a value computed from the mandatory arrays.

Parameters:

children_left (ndarray[tuple[Any, ...], dtype[int_]]) – Left-child node ids; -1 denotes a leaf.
children_right (ndarray[tuple[Any, ...], dtype[int_]]) – Right-child node ids; -1 denotes a leaf.
children_missing (ndarray[tuple[Any, ...], dtype[int_]]) – Node id to which missing-value samples are routed.
features (ndarray[tuple[Any, ...], dtype[int_]]) – Decision-node feature indices. Leaf positions are sanitized to -2.
thresholds (ndarray[tuple[Any, ...], dtype[floating]]) – Decision-node thresholds. Leaf positions are sanitized to np.nan.
values (ndarray[tuple[Any, ...], dtype[floating]]) – Leaf-node values. Higher-dim arrays are flattened to 1-D; non-leaf positions are forced to 0.
node_sample_weight (ndarray[tuple[Any, ...], dtype[floating]]) – Per-node sample weights. NaN at leaves is replaced with 1.
empty_prediction (float | None) – Pre-computed empty prediction. None triggers compute_empty_prediction().
leaf_mask (ndarray[tuple[Any, ...], dtype[bool]] | None) – Boolean mask of leaf nodes. None derives it from children_left == -1.
n_features_in_tree (int | None) – Number of distinct features used by decision nodes. None derives it from the unique values in features (excluding -2).
max_feature_id (int | None) – Largest feature index used. None derives it from features.
feature_ids (set[int] | None) – Set of feature indices used by decision nodes. None derives it from features.
root_node_id (int | None) – Root node id. None defaults to 0.
n_nodes (int | None) – Number of nodes. None derives it from len(children_left).
nodes (ndarray[tuple[Any, ...], dtype[int_]] | None) – Node-id array. None defaults to np.arange(n_nodes).
decision_type (str | None) – Split comparison used by decision_function() ("<=" or "<"). None defaults to "<=".
feature_map_original_internal (dict[int, int] | None) – Mapping from original to internal feature indices. None defaults to the identity mapping on feature_ids.
feature_map_internal_original (dict[int, int] | None) – Mapping from internal to original feature indices. None defaults to the identity mapping on feature_ids.
original_output_type (str) – Currently unused; accepted for forward compatibility.
intercepts (ndarray[tuple[Any, ...], dtype[floating]] | None) – Currently unused; accepted for forward compatibility with linear-leaf trees.
coeffs (ndarray[tuple[Any, ...], dtype[floating]] | None) – Currently unused; accepted for forward compatibility with linear-leaf trees.

compute_empty_prediction()[source]¶

Compute the empty prediction of the tree model.

The method computes the empty prediction of the tree model by taking the weighted average of the leaf node values. The method modifies the tree model in place.

Return type:: None

decision_function(value, threshold, *, left_default)[source]¶

Decision function for split nodes.

The function compares the input value to the threshold using the specified decision type. If the value is NaN, the function returns the left_default.

Parameters:

value (float) – The feature value to compare.
threshold (float) – The threshold to compare the feature value against.
left_default (bool) – The default direction to take if the value is NaN. True for left, False for right.

Return type:

bool

Returns:

A boolean indicating whether to go left (True) or right (False) at the split node.

predict_one(x)[source]¶

Predicts the output of a single instance.

Parameters:: x (ndarray[tuple[Any, ...], dtype[floating]]) – The instance to predict as a 1-dimensional array.
Return type:: float
Returns:: The prediction of the instance with the tree model.

reduce_feature_complexity()[source]¶

Reduces the feature complexity of the tree model.

The method reduces the feature complexity of the tree model by removing unused features and reindexing the feature indices of the decision nodes in the tree. The method modifies the tree model in place. To see the original feature mappings after the reduction, use the feature_map_original_internal and feature_map_internal_original attributes.

For example, consider a tree model with the following feature indices:

[0, 1, 8]

The method will remove the unused feature indices and reindex the feature indices of the decision nodes in the tree to the following:

[0, 1, 2]

Feature '8' is ‘renamed’ to '2' such that in the internal representation a one-hot vector (and matrices) of length 3 suffices to represent the feature indices.