Skip to contents

Build 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" or 1, "decreasing" or -1, or 0 for unconstrained. An unnamed vector as long as the model matrix is wide assigns the directions by position. A predictor named prior is 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:

  • setPredictor with forceUpdate = FALSE, the whole data frame or named columns: returns FALSE. 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.

  • setPredictor with forceUpdate = "partial" and updatePredictorPerObservationJointly: 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)