shap_tree – Tree SHAP – exact polynomial-time Shapley values for tree ensembles.#

Back to op axis | Back to L7 | Browse all options

Operational op under axis op, sub-layer L7_A_importance_dag_body, layer l7. Standalone callable: mf.functions.shap_tree_importance.

Function signature#

mf.functions.shap_tree_importance(
    result: FitResultBase,
    X: np.ndarray | pd.DataFrame,
) -> SHAPImportanceResult

Parameters#

name

type

default

constraint

description

result

FitResultBase

—

—

Fitted result object exposing ._model (the raw sklearn estimator). Returned by any L4 standalone callable such as mf.functions.ridge_fit, mf.functions.random_forest_fit, etc.

X

`np.ndarray

pd.DataFrame`

—

—

Returns#

SHAPImportanceResult — frozen dataclass with fit results.

Attribute

Type

Description

.shap_values_

np.ndarray

SHAP values, shape (n_samples, n_features).

.expected_value_

float

SHAP base value (expected model output).

.feature_names_

list[str]

Feature names.

.explainer_type

str

Explainer used (TreeExplainer / KernelExplainer).

.summary(top_n=10)

str

Table of mean absolute SHAP values.

Behavior#

Lundberg-Erion-Lee (2020) algorithm computing exact Shapley values in O(T·L·D²) time (T trees, L leaves, D depth) instead of O(2^M) brute-force. Available for random_forest / extra_trees / gradient_boosting / xgboost / lightgbm / catboost.

Returns per-prediction SHAP values; the output_table_format L7.B axis controls whether the result is the global mean-|SHAP| ranking or the per-row decomposition.

When to use

Default importance op for tree ensembles; exact and fast.

When NOT to use

Non-tree models – use shap_kernel or shap_linear instead.

In recipe context#

Set params.op = "shap_tree" in the relevant layer to activate this op within a recipe:

# Layer L7 recipe fragment
params:
  op: shap_tree

References#

  • macroforecast design Part 3, L7: ‘every importance op produces (table, figure) pairs; the L7.B sub-layer governs export shape.’

  • Lundberg & Lee (2017) ‘A Unified Approach to Interpreting Model Predictions’, NeurIPS 30: 4765-4774.

  • Lundberg, Erion & Lee (2020) ‘From local explanations to global understanding with explainable AI for trees’, Nature Machine Intelligence 2: 56-67.