Skip to contents

Build an interaction-constraint specification restricting which predictors may jointly shape a BART fit. Pass the result as the interactions argument of dbarts or bart. The constraint is applied per forest, so in a multi-forest model one forest can be held additive-or-low-order while another stays free. A multinomial fit applies it to each of its category forests.

The constructor is not exported: it resolves by bare name inside the arguments that take it, and elsewhere is written dbartsForests$interactions(...); see dbartsForests.

Usage

interactions(max.order = NULL, groups = NULL, forbid = NULL)

Arguments

max.order

Optional cap on the number of distinct predictors that may appear together on any single root-to-leaf path. max.order = 1 makes the forest additive (each tree splits on one predictor); max.order = 2 allows bounded pairwise interactions; and so on. A single integer of at least 1, or NULL for no cap.

groups

Optional co-occurrence allow-list: a list of predictor sets. Two named predictors may share a root-to-leaf path only if some group contains both; every other pair of named predictors is forbidden. Predictors named in no group are unconstrained. Each set is a character vector of model-matrix column names (a bare factor term name expands to its indicator columns) or a numeric vector of column indices. A single vector (rather than a list) is taken as one group.

forbid

Optional co-occurrence deny-list: a list whose entries each name two or more predictors barred from ever sharing a root-to-leaf path (an entry of more than two forbids every pair within it). Columns are named or indexed as for groups. A single vector (rather than a list) is taken as one forbidden set.

Details

All three restrictions lower to a single per-node admissibility rule over the set of predictors already used by a node's ancestors: max.order bars a new predictor once the path's distinct count reaches the cap, while groups and forbid bar a predictor whose forbidden partner sits above it. The constraint is hard (an availability ban), applied inside the tree proposals, and a warm start cuts back a tree that breaks it, so a constrained fit never visits a path that violates it; an unconstrained fit is unaffected.

Names and indices resolve against the model matrix at fit time, where every value is validated: an unrecognized name, an empty group, a max.order below 1, and a reference to a column dropped from the design are each an error there. Supplying none of the three arguments is instead an error immediately, at construction: interactions() with no arguments never produces an object to pass to dbarts/bart.

Monotone constraints (see dbarts's monotone) and interaction constraints are orthogonal and may be combined.

A groups partition that is both disjoint and total (every predictor named in exactly one group) already makes the fit block-additive: the root split fixes each tree's group, and the co-occurrence rule confines every descendant to that same group, so the ensemble is exactly a sum of per-group functions \(f = \sum_G f_G\) - a functional-ANOVA / grouped-GAMI decomposition that holds at every MCMC state. Under this idiom each tree's group is chosen adaptively (by its root draw each sweep), so the number of trees devoted to a group floats with the data. blocks gives the same decomposition with a fixed per-group tree count and a static per-tree mask instead of an adaptive per-path allow-list; use it when a group needs guaranteed representation or a deterministic layout.

Value

A dbartsInteractions specification object, resolved when a sampler is built.

Examples

set.seed(0)
n <- 100L
x <- matrix(runif(n * 3), n, 3, dimnames = list(NULL, c("x1", "x2", "x3")))
y <- 2 * x[, 1] + ifelse(x[, 2] > 0.5, 1, -1) + rnorm(n, 0, 0.2)
df <- data.frame(y, x)

## additive fit: no tree splits on more than one predictor on any path
fit.additive <- bart(y ~ x1 + x2 + x3, df,
                      interactions = interactions(max.order = 1),
                      n.trees = 25L, n.samples = 20L, n.burn = 20L,
                      n.chains = 1L, verbose = FALSE)

## forbid x1 and x2 from ever interacting, but allow order-2 interactions
## among the rest
fit.forbid <- bart(y ~ x1 + x2 + x3, df,
                    interactions = interactions(max.order = 2,
                                                forbid = list(c("x1", "x2"))),
                    n.trees = 25L, n.samples = 20L, n.burn = 20L,
                    n.chains = 1L, verbose = FALSE)