Extract rules from an xgb.Booster model

Extract interpretable decision rules from a single tree in an xgboost boosted tree model. Each terminal node (leaf) becomes one rule representing the path from root to that leaf.

Usage

# S3 method for class 'xgb.Booster'
extract_rules(x, tree = 1L, ...)

Arguments

x

An xgb.Booster object from the xgboost package.

tree

Integer specifying which tree to extract rules from. Uses 1-based indexing (default is 1L). For multiclass models with num_class classes and nrounds boosting rounds, there are num_class * nrounds total trees.

...

Not currently used.

Value

A tibble with class c("rule_set_xgb.Booster", "rule_set") and columns:

• tree: integer, the tree number (matches input parameter).

• rules: list of R expressions, one per terminal node.

• id: integer, terminal node ID (1-based).

Details

xgboost uses 0-based indexing internally, but this function uses 1-based indexing for the tree parameter and output id column (R convention).

Split conditions in xgboost follow the pattern: Yes branch when feature < threshold, No branch when feature >= threshold. Rules are combinations of these conditions using AND logic.

Note: This function does not work with xgboost models containing categorical features or non-tree boosters (gblinear).

Examples

if (rlang::is_installed("xgboost")) {
  data(agaricus.train, package = "xgboost")

  # Binary classification
  set.seed(2847)
  bst <- xgboost::xgb.train(
    data = xgboost::xgb.DMatrix(agaricus.train$data, label = agaricus.train$label),
    nrounds = 3,
    max_depth = 3,
    objective = "binary:logistic"
  )

# Extract rules from first tree
rules <- extract_rules(bst, tree = 1L)

# View as text
rule_text(rules$rules[[1]])

  # Regression example
  data(mtcars)
  set.seed(8472)
  bst_reg <- xgboost::xgb.train(
    data = xgboost::xgb.DMatrix(as.matrix(mtcars[, -1]), label = mtcars$mpg),
    nrounds = 3,
    max_depth = 3,
    objective = "reg:squarederror"
  )
  rules_reg <- extract_rules(bst_reg, tree = 1L)
}
#> Warning: Passed invalid function arguments: max_depth. These should be passed as a list to argument 'params'. Conversion from argument to 'params' entry will be done automatically, but this behavior will become an error in a future version.
#> Warning: Argument 'objective' is only for custom objectives. For built-in objectives, pass the objective under 'params'. This warning will become an error in a future version.
#> Warning: Passed invalid function arguments: max_depth. These should be passed as a list to argument 'params'. Conversion from argument to 'params' entry will be done automatically, but this behavior will become an error in a future version.
#> Warning: Argument 'objective' is only for custom objectives. For built-in objectives, pass the objective under 'params'. This warning will become an error in a future version.