Block-Additive Constraints for BART
blocks.RdBuild a block-additive constraint confining each whole tree in a BART fit to
one declared group of predictors, so the ensemble is exactly a sum of
per-group functions \(f = \sum_G f_G\) (a functional-ANOVA / grouped-GAMI
decomposition). Pass the result as the blocks argument of
dbarts or bart. The constraint is applied per
forest, so in a multi-forest model each forest can carry its own partition.
A multinomial fit applies it to each of its category forests, so
trees.per.group sums to the trees in one category forest.
The constructor is not exported: it resolves by bare name inside the
arguments that take it, and elsewhere is written
dbartsForests$blocks(...); see dbartsForests.
Arguments
- groups
A list partitioning the forest's predictors into disjoint blocks. Each entry 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. The partition must be total and disjoint: every predictor is named in exactly one group. A single vector (rather than a list) is taken as one group.
- trees.per.group
Optional integer vector, one entry per group, giving how many of the
n.treestrees each group receives; the entries must be positive and sum ton.trees.NULL(the default) distributes the trees as evenly as possible, with the firstn.trees %% length(groups)groups receiving one extra tree. A group's count sets how finely it divides its part of the forest's prior, not the size of that part; see Details.
Details
Each tree is assigned to exactly one group and split-restricted to that
group's predictors, so no path in the tree - and hence no term in the
ensemble - mixes predictors from different groups. The assignment is
deterministic and contiguous (the first trees.per.group[1] trees to
group 1, the next trees.per.group[2] to group 2, and so on) and
consumes no random numbers, so a fit is exactly reproducible.
Each of the \(G\) groups takes an equal part, \(1/G\), of the forest's
prior variance, whatever its tree count: a group of \(m_g\) trees gives
each of its leaves the variance \(s^2 / (G m_g)\), \(s\) the forest's
prior standard deviation, so the forest as a whole keeps the prior a forest
without groups has. trees.per.group says how complex each group's
function may be, not how much of the response it explains. With equal
counts every tree has the leaf prior of the same forest without groups.
Several forests with no basis written as their own terms,
y ~ forest(x1) + forest(x2), are the same model as the one forest
y ~ forest(x1 + x2, blocks = blocks(list("x1", "x2"))) at the same
tree counts (see forest's Details).
Unlike interactions(groups = ), which is a per-path
allow-list that leaves un-named predictors unconstrained, blocks
lowers to a static per-tree column mask: a predictor named in no block would
be masked out of every tree and never enter the fit. The partition is
therefore required to be total, and every value is validated against the
model matrix at fit time - an unpartitioned predictor, a predictor named in
more than one group, an unrecognized name, or a trees.per.group of the
wrong length, with a non-positive entry, or not summing to n.trees is
an error. For a forest that is already restricted to a subset of the columns,
the partition is over that forest's available columns.
blocks and interactions act on independent seams (which
columns a tree may use versus which may co-occur on a path) and may be
combined on one forest. Block-additivity is also orthogonal to monotone
constraints (see dbarts's monotone).
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)
## block-additive fit: f(x) = f1(x1) + f2(x2, x3), no tree mixing the blocks
fit <- bart(y ~ x1 + x2 + x3, df,
blocks = blocks(groups = list("x1", c("x2", "x3"))),
n.trees = 20L, n.samples = 20L, n.burn = 20L,
n.chains = 1L, verbose = FALSE)
## split the 20 trees explicitly: 5 to the first block, 15 to the second
fit.split <- bart(y ~ x1 + x2 + x3, df,
blocks = blocks(groups = list("x1", c("x2", "x3")),
trees.per.group = c(5L, 15L)),
n.trees = 20L, n.samples = 20L, n.burn = 20L,
n.chains = 1L, verbose = FALSE)