Monotone Constraints for BART
monotone.RdBuild a monotone-constraint specification making a BART fit monotone
increasing or decreasing in chosen predictors (monotone BART; Chipman,
George, McCulloch, and Shively 2022), and name the prior it is read under.
Pass the result as the monotone argument of dbarts,
bart or dbartsSpec; a plain direction vector
passed there is shorthand for monotone(directions) at the default
prior.
The constructor is not exported: it resolves by bare name inside the
arguments that take it, and elsewhere is written
dbartsForests$monotone(...); see dbartsForests.
Usage
monotone(directions, prior = c("joint", "leaf"))Arguments
- directions
The per-predictor directions. A named vector selects predictors by model-matrix column name, each element
"increasing"or1,"decreasing"or-1, or0for unconstrained. An unnamed vector as long as the model matrix is wide assigns the directions by position. A predictor namedprioris written like any other,monotone(c(prior = "increasing")).- prior
How the constraint enters the prior,
"joint"(the default) or"leaf"; see Details.
Details
Each tree is held monotone in the constrained predictors, so the sum of trees is too. The two priors differ in where the constraint acts.
"joint"The ordinary BART prior on the trees and their leaf values, conditioned on every tree being monotone. A tree whose leaf values would seldom be in order under the ordinary prior becomes less likely, so the constrained predictors get about half the share of splits they get in an unconstrained fit at 200 trees, and split counts understate their importance (less so under
"leaf")."leaf"The ordinary tree prior, unchanged; given a tree, its leaf values are drawn from the ordinary prior restricted to values in order. A tree move may then count the orderings of the tree's leaves that the constraint allows.
"joint" is the default because in a simulation study the two
priors fit alike, and "joint" never counts leaf orderings while
sampling, so its moves are never slow. (Drawing leaf values from the prior,
as samplePriorPredictive does, counts under either prior.) Under
either prior a constrained fit takes several times the time per sweep of
the same fit without the constraint: 4.5 to 8.5 times in that study.
With very few trees a constrained sampler moves slowly between tree shapes under either prior: a tree that has picked up extra splits tends to keep them, and the constraint then holds their leaves apart, which can overstate how steep the fitted function is. Use more trees.
Under "leaf" the count is negligible at 10 or more trees, but with
one to five trees a tree can grow large enough that a count takes seconds
to minutes per move, and its memory grows with it, to hundreds of
megabytes for the largest counts seen. There is no limit: the run
finishes on the stated model, and afterwards a warning of class
"dbartsSlowCountWarning" reports counts that took more than about
a second and names the remedies, more trees or prior = "joint". A
count can be interrupted, which raises R's interrupt condition and leaves
the pass over the trees partly applied, and a
count that runs out of memory is an ordinary error; either way the
sampler is left in a valid state.
The tree prior is the fit's, as without a constraint: power = 2
and base = 0.95, unless others are given. The mBART
paper used power = 0.8, base = 0.25, which gives smaller
trees; in a simulation study under "joint" at 200 trees it gave
sharper and more accurate fits, but narrower intervals that under-covered
with plentiful, low-noise data, and at 50 trees it was less accurate with
such data and under-covered more often. Pass
them as power and base to opt in (see Examples).
The fit is monotone in a constrained predictor along every line on which that predictor is observed, the other predictors at any values, missing ones and every factor level included; nothing is claimed where the constrained predictor itself is missing.
New predictor values given to a sampler (see
dbartsSampler) can leave a tree's leaf values out of
order. The calls that always complete - setPredictor with
forceUpdate = TRUE (its default when the whole matrix is replaced),
setData, setCutPoints, setState with
forceUpdate = TRUE, and a warm start, installTrees with
forceUpdate = TRUE or bart's warm.start - collapse
such a tree where its leaf values are out of order, each collapsed part
one leaf at the mean of the leaves it replaces weighted by their rows, and
keep the rest, without a message; that suits burn-in and is not a draw
from the posterior.
An unforced update is refused instead, as one that would empty a leaf is.
One unforced change can leave a tree out of order: the first missing value
in an unordered factor column that has none. Two leaves that share no
level of the factor can both be reached by a missing value, and the
constraint then orders them. Which leaves a missing value reaches is
settled by the side each rule on the column draws when the value arrives
(see ‘Missing values in predictors’ in
dbartsSampler), so the same update
can keep the order under one draw and break it under another. What each
call does where the sides drawn leave a tree out of order:
setPredictorwithforceUpdate = FALSE, the whole data frame or named columns: returnsFALSE. The sampler's trees, fits, predictors and random number generator are as they were before the call. As after any refused update, the draws that follow can differ in their last digits from those it would otherwise have made.setPredictorwithforceUpdate = "partial"andupdatePredictorPerObservationJointly: each row that brings the missing value is declined, and the other rows are installed.
A numeric column's first missing value breaks no order and is installed.
Such a refusal is not cured by proposing other values: a refused update
puts the generator back, so the same sides are drawn again until the
sampler has run, and where the data favor such trees a later draw can
break the order too. Code that proposes the value again until it is
accepted may never finish. The way to bring the value in is
forceUpdate = TRUE, which completes and collapses those trees as
above; the alternative is to leave the value as it was.
Only numeric and ordered columns are eligible: a direction on a categorical
(unordered factor) predictor is an error. Names, positions and every
direction are validated against the model matrix at fit time; prior
is matched when the specification is built. An all-zero specification fits
the unconstrained model.
A constraint forces birth/death-only tree proposals (a control
naming a non-default proposal.probs is then an error). The leaf
scale is fixed: k is 2 unless another number is given, or a fixed
sd may be named, and a hyperprior on either is an error. Linear and
Gaussian-process leaves, variance forests, multi-forest models and
family = "multinomial" are not supported under it. It may be
combined with interactions and blocks.
Value
A dbartsMonotone specification object, a list of directions
and prior, resolved when a sampler is built. A fit records the prior
as monotone.prior, which print and summary show.
References
Chipman, H. A., George, E. I., McCulloch, R. E., and Shively, T. S. (2022) mBART: multidimensional monotone BART. Bayesian Analysis 17(2), 515–544.
Examples
set.seed(0)
n <- 100L
x <- matrix(runif(n * 3), n, 3, dimnames = list(NULL, c("x1", "x2", "x3")))
y <- 2 * x[, 1] - x[, 2] + sin(2 * pi * x[, 3]) + rnorm(n, 0, 0.2)
df <- data.frame(y, x)
## increasing in x1, decreasing in x2, free in x3, under the default prior
fit <- bart(y ~ x1 + x2 + x3, df,
monotone = monotone(c(x1 = "increasing", x2 = "decreasing")),
n.trees = 25L, n.samples = 20L, n.burn = 20L,
n.chains = 1L, verbose = FALSE)
fit$monotone.prior
#> [1] "joint"
## the plain vector, positionally, is the same specification
fit.plain <- bart(y ~ x1 + x2 + x3, df,
monotone = c(1, -1, 0),
n.trees = 25L, n.samples = 20L, n.burn = 20L,
n.chains = 1L, verbose = FALSE)
## the "leaf" prior
fit.leaf <- bart(y ~ x1 + x2 + x3, df,
monotone = monotone(c(x1 = "increasing", x2 = "decreasing"),
prior = "leaf"),
n.trees = 25L, n.samples = 20L, n.burn = 20L,
n.chains = 1L, verbose = FALSE)
## the mBART paper's tree prior, as an opt-in
fit.mbart <- bart(y ~ x1 + x2 + x3, df,
monotone = c(x1 = "increasing", x2 = "decreasing"),
power = 0.8, base = 0.25,
n.trees = 25L, n.samples = 20L, n.burn = 20L,
n.chains = 1L, verbose = FALSE)