Package 'dbarts'

Title: Discrete Bayesian Additive Regression Trees Sampler
Description: Fits Bayesian additive regression trees (BART; Chipman, George, and McCulloch (2010) <doi:10.1214/09-AOAS285>) while allowing the updating of predictors or response so that BART can be incorporated as a conditional model in a Gibbs/Metropolis-Hastings sampler. Supports continuous, probit, logistic, multinomial, ordinal, negative-binomial, semicontinuous two-part, and survival (accelerated failure time and discrete-time hazard) responses, robust Student-t errors, heteroscedastic variance forests, monotonicity and interaction constraints, variable selection through 'DART' priors, missing-value incorporation, categorical and sparse predictors, and linear or Gaussian-process leaf models. Also provides a BayesTree-compatible interface.
Authors: Vincent Dorie [aut, cre] (ORCID: <https://orcid.org/0000-0002-9576-3064>), Hugh Chipman [aut], Robert McCulloch [aut], R Core Team [ctb] (basis of RNG), Guido U Draheim [ctb] (ax_check_compile_flag.m4), Maarten Bosmans [ctb] (ax_check_compile_flag.m4), Christophe Tournayre [ctb] (ax_compiler_ext.m4), Michael Petch [ctb] (ax_compiler_ext.m4), Rafael de Lucena Valle [ctb] (ax_compiler_ext.m4), Steven G. Johnson [ctb] (ax_compiler_vendor.m4, ax_pthread.m4, ORCID: <https://orcid.org/0000-0001-7327-4967>), Matteo Frigo [ctb] (ax_compiler_vendor.m4), John Zaitseff [ctb] (ax_compiler_vendor.m4), Daniel Richard G. [ctb] (ax_pthread.m4)
Maintainer: Vincent Dorie <[email protected]>
License: GPL (>= 2)
Version: 1.0-0
Built: 2026-11-12 01:39:48 UTC
Source: https://github.com/vdorie/dbarts

Help Index


Discrete Bayesian Additive Regression Trees Sampler

Description

Fits Bayesian additive regression trees (BART; Chipman, George, and McCulloch 2010), a Bayesian “sum-of-trees” model in which each tree is held to be a weak learner by its prior. The package offers two ways in, described below, and provides a BayesTree-compatible interface.

What distinguishes dbarts from other BART implementations is that its sampler is mutable: predictors, response, offset, and weights can be swapped between MCMC draws, so that BART can be a conditional model inside a larger Gibbs or Metropolis-Hastings sampler rather than only a standalone fit.

Fitting a model

For an ordinary fit, use one of the fitting functions. Each runs the sampler to completion and returns posterior draws.

  • bart - the current interface, taking a formula or matrices and reaching the full feature set, including every response family. This is the one to reach for first.

  • bartBT - the BayesTree-compatible interface, kept at its historical defaults (200 trees, one chain, BayesTree's tree-move mixture, factors expanded to indicator columns, binary responses probit, rows with missing values dropped).

  • xbart - crossvalidates over k, power, base, and the tree count.

  • pdbart - partial dependence plots for one or two variables.

Fits support predict, fitted, residuals, extract, plot, and summary; see bartBT's ‘Generics’ section for what each returns and on which scale. survivalProbabilities turns a survival fit into survival-curve draws.

Driving the sampler directly

dbarts builds a dbartsSampler without running it. The sampler is a reference class whose methods - run, setResponse, setPredictor, setOffset, setWeights, and the rest - map onto the underlying C++ engine, so an outer sampler can alternate its own draws with BART's. dbartsData and dbartsControl build its data and control objects, dbartsPriors its priors, and samplePriorPredictive draws from the prior for calibration before any fitting. dbartsSpec resolves the same specification without constructing a sampler, for packages that embed dbarts and supply their own design matrix.

Model features

Reached through bart and dbarts unless noted.

  • Response families (family): "gaussian", "probit", "logistic", accelerated failure time ("aft"), discrete-time survival hazard ("hazard", "hazard.logistic"), multinomial ("multinomial"), ordered categorical ("ordinal"), negative-binomial counts ("nbinom"), and semicontinuous two-part ("hurdle.lognormal", bart only). "auto", the default, resolves the family from the response.

  • Outlier-robust Student-t errors (family = student(...)) and a heteroscedastic variance forest (variance).

  • Structural constraints: monotonicity (monotone), interaction limits (interactions), and block-additivity (blocks).

  • Leaf models: constant, linear, or Gaussian-process (leaf.prior; see dbartsPriors).

  • Variable selection by the DART prior (split.probs = dart()).

  • Predictors: missing values incorporated in place unconditionally, unordered factors split on level subsets (factors), and sparse or mixed dense/sparse input (Matrix::dgCMatrix, sparseFactor).

  • Warm starts from a previous fit (warm.start) or by XBART-style grow-from-root (n.grow.sweeps).

Reproducibility

Every chain runs its own random number generator, so results never depend on the thread count and sampling does not advance R's stream. Calling set.seed beforehand suffices; passing seed instead makes a fit reproducible without touching R's stream at all. See bart's ‘Reproducibility’ section.

Memory

Two arrays of 4 bytes per observation per tree per chain dominate what the sampler itself holds, so its footprint is linear in the number of observations, the number of trees, and the number of chains, and everything else is a rounding error beside them. The predictor store costs 2 bytes per cell once, whatever the chain count, because every chain reads the same store. A test set costs its own store, 2 bytes per test cell, plus 16 bytes per test row per chain.

Worked examples, for the sampler alone (the engine and its predictor store, not the returned draws):

observations predictors trees chains sampler
10,000 10 75 1 7 MB
100,000 20 200 1 170 MB
100,000 20 200 4 660 MB
1,000,000 50 200 1 1.8 GB

A large-nn fit is usually limited not by the sampler but by the training predictions it returns. yhat.train is 8 bytes per observation per draw per chain, and two copies of it are live while the fit is packaged - the one the sampler wrote and the one the fit returns - so the 100,000-observation four-chain fit above at the default 500 draws peaks near 3.2 GB of returned array against 660 MB of sampler. The lever is keepTrainingFits = FALSE - an argument of bart and of dbartsControl, and keeptrainfits on bartBT - which drops the array and the fitted means taken from it; predict on a keepTrees fit recovers them for whichever rows are wanted. A per-draw callback (see bart) goes further alongside keepFits = FALSE by never allocating the array at all, taking the 100,000-observation four-chain fit above from about 3891 MB to about 698 MB, and a 1,000,000-observation one-chain fit at 50 predictors from about 10560 MB to about 2576 MB.

Two options cost more than their names suggest. keepTrees keeps every draw's trees, about 24 bytes per node per tree per draw per chain, which is 23 MB per chain at 200 trees and 500 draws and grows with the tree count and the draw count but not with nn. A designated-covariate leaf (leaf.prior = linear(...) or gp(...)) caches sufficient statistics keyed on leaf membership; measured, that cache runs about 13 to 14 bytes per observation per tree per chain, and at 100,000 observations, 200 trees and one chain it was 276 MB - larger than everything else the fit holds put together. It also replaces one of the two 4-byte arrays above with an 8-byte one.

Using dbarts from another package

Calling the R interface needs no special linkage. A package that drives the sampler from C should declare LinkingTo: dbarts and use the flat C API declared in the installed header ‘dbarts/dbarts.h’, whose entry points are reached through R_GetCCallable and versioned by the two-component handshake DBARTS_C_API_MAJOR/DBARTS_C_API_MINOR, with dbarts_apiHash() as an opt-in exact-ABI check, which moves on additive releases as well. That header creates no sampler and names no R type: the sampler is built in R - dbarts or dbartsSpec - and the handle the entry points take is the address in that object's external pointer, read with R_ExternalPtrAddr. See dbarts-embedding. The C++ interface of releases before 1.0-0, ‘dbarts/R_C_interface.hpp’, has been removed.

Author(s)

Vincent Dorie [email protected], with Hugh Chipman and Robert McCulloch. See citation("dbarts") for how to cite the package.

References

Chipman, H., George, E., and McCulloch, R. (2010) BART: Bayesian additive regression trees. The Annals of Applied Statistics, 4(1), 266–298. doi:10.1214/09-AOAS285.

See Also

bart to fit a model, dbarts to build a sampler, and the package vignettes: vignette("gibbs_sampler_mixture_model", package = "dbarts"), vignette("working_with_saved_trees", package = "dbarts") and vignette("dbarts-as-a-component", package = "dbarts").


Bayesian Additive Regression Trees with Extended Response Families

Description

BART is a Bayesian “sum-of-trees” model in which each tree is constrained by a prior to be a weak learner; see bartBT for the base gaussian/probit model definition. bart is dbarts' own formula-first fitting interface: besides the default gaussian/probit response it reaches further families through family - logistic, accelerated failure time (family = "aft"), discrete-time survival hazard (family = "hazard", "hazard.logistic"), K-category multinomial (family = "multinomial"), ordered categorical (family = "ordinal", a cumulative probit), negative-binomial counts (family = "nbinom"), and semicontinuous two-part responses (family = "hurdle.lognormal") - and, on its formula interface, an additional per-observation-modulated forest declared inline with a forest() term (see ‘Formula Terms’ below). None of these families is reachable from bartBT, which takes no family argument and always fits the gaussian or probit model.

Usage

bart(
    formula, data, test, subset, weights, offset, offset.test = offset,
    sigest = NULL, k = NULL,
    power = 2, base = 0.95, split.probs = NULL,
    n.trees = 75L,
    n.samples = 500L, n.burn = 500L,
    n.chains = 4L, n.threads = min(dbarts::guessNumCores(), n.chains),
    combineChains = TRUE,
    n.cuts = 100L, useQuantiles = FALSE,
    n.thin = 1L, keepTrainingFits = TRUE,
    printEvery = 100L, printCutoffs = 0L,
    verbose = TRUE, keepTrees = NULL,
    keepCall = TRUE, samplerOnly = FALSE,
    seed = NULL,
    monotone = NULL,
    interactions = NULL,
    blocks = NULL,
    variance = NULL,
    keepSampler = keepTrees,
    warm.start = NULL,
    n.grow.sweeps = 0L,
    factors = c("categorical", "indicators"),
    family = c("auto", "gaussian", "student", "probit", "logistic", "aft",
               "multinomial", "ordinal", "nbinom", "hazard", "hazard.probit",
               "hazard.logistic", "hurdle.lognormal"),
    weights.type = NULL,
    na.action = dbarts::na.keepPredictors,
    leaf.prior = NULL,
    storage = c("double", "single"), updateState = TRUE,
    keepFits = is.null(callback), callback = NULL,
    control = dbarts::dbartsControl(), ...)

## S3 method for class 'bartMultinomial'
extract(
    object,
    type = c("ev", "ppd", "bart", "forest", "loglik", "sigma", "k",
             "leaf.prior.sd", "varcount", "trees"),
    sample = c("train", "test"),
    combineChains = TRUE, ...)

## S3 method for class 'bartMultinomial'
fitted(
    object, type = c("ev", "class", "bart", "forest"),
    sample = c("train", "test"),
    ci.level = NULL, ...)

## S3 method for class 'bartMultinomial'
predict(
    object, newdata,
    type = c("ev", "ppd", "bart", "forest", "class"),
    offset = NULL, weights = NULL,
    combineChains = TRUE, ci.level = NULL,
    na.action = dbarts::na.keepPredictors, n.threads, ...)

## S3 method for class 'bartMultinomial'
print(x, ...)

## S3 method for class 'bartMultinomial'
residuals(object, ...)
## S3 method for class 'bartMultinomial'
family(object, ...)

## S3 method for class 'bartOrdinal'
extract(
    object, type = c("ev", "ppd", "bart", "loglik", "thresholds", "sigma", "k",
                     "leaf.prior.sd", "varcount"),
    sample = c("train", "test"),
    combineChains = TRUE, ...)

## S3 method for class 'bartOrdinal'
fitted(
    object, type = c("ev", "class", "bart"),
    sample = c("train", "test"),
    ci.level = NULL, ...)

## S3 method for class 'bartOrdinal'
predict(
    object, newdata,
    type = c("ev", "ppd", "bart", "class"),
    offset = NULL, weights = NULL,
    combineChains = TRUE, ci.level = NULL,
    na.action = dbarts::na.keepPredictors, n.threads, ...)

## S3 method for class 'bartOrdinal'
print(x, ...)

## S3 method for class 'bartOrdinal'
residuals(object, ...)
## S3 method for class 'bartOrdinal'
family(object, ...)

## S3 method for class 'bartNegbin'
extract(
    object, type = c("ev", "ppd", "bart", "loglik", "shape", "sigma", "k",
                     "leaf.prior.sd", "varcount"),
    sample = c("train", "test"),
    combineChains = TRUE, ...)

## S3 method for class 'bartNegbin'
fitted(
    object, type = c("ev", "ppd", "bart"),
    sample = c("train", "test"),
    ci.level = NULL, ...)

## S3 method for class 'bartNegbin'
predict(
    object, newdata,
    type = c("ev", "ppd", "bart"),
    offset = NULL, weights = NULL,
    combineChains = TRUE, ci.level = NULL,
    na.action = dbarts::na.keepPredictors, n.threads, ...)

## S3 method for class 'bartNegbin'
print(x, ...)

## S3 method for class 'bartNegbin'
residuals(object, ...)
## S3 method for class 'bartNegbin'
family(object, ...)

## S3 method for class 'bartHurdle'
extract(
    object,
    type = c("ev", "ppd", "prob", "bart", "loglik", "sigma", "k",
             "leaf.prior.sd", "varcount"),
    sample = c("train", "test"),
    combineChains = TRUE, ...)

## S3 method for class 'bartHurdle'
fitted(
    object, type = c("ev", "ppd", "prob", "bart"),
    sample = c("train", "test"), ci.level = NULL, ...)

## S3 method for class 'bartHurdle'
predict(
    object, newdata,
    type = c("ev", "ppd", "prob", "bart"),
    offset = NULL, weights = NULL,
    combineChains = TRUE, ci.level = NULL,
    na.action = dbarts::na.keepPredictors, n.threads, ...)

## S3 method for class 'bartHurdle'
print(x, ...)

## S3 method for class 'bartHurdle'
residuals(object, type = "ev", ...)
## S3 method for class 'bartHurdle'
family(object, ...)

## S3 method for class 'bartMultinomial'
plot(x, plquants = c(0.05, 0.95), cols = NULL, ...)

## S3 method for class 'bartOrdinal'
plot(x, plquants = c(0.05, 0.95), cols = NULL, ...)

## S3 method for class 'bartNegbin'
plot(x, plquants = c(0.05, 0.95), cols = c("blue", "black"), ...)

## S3 method for class 'bartHurdle'
plot(x, plquants = c(0.05, 0.95), cols = c("blue", "black"), ...)

## S3 method for class 'bartMultinomial'
summary(object, ...)

## S3 method for class 'bartOrdinal'
summary(object, vars = c("thresholds", "sigma", "k",
                                "leaf.prior.sd"), ...)

## S3 method for class 'bartNegbin'
summary(object, vars = c("shape", "sigma", "k",
                               "leaf.prior.sd"), ...)

## S3 method for class 'bartHurdle'
summary(object, vars = c("sigma", "k", "leaf.prior.sd",
                               "resid.df"), ...)

## S3 method for class 'summary.bartHurdle'
print(x, ...)

## S3 method for class 'bart'
sigma(object, ...)
## S3 method for class 'bartMultinomial'
sigma(object, ...)
## S3 method for class 'bartOrdinal'
sigma(object, ...)
## S3 method for class 'bartNegbin'
sigma(object, ...)
## S3 method for class 'bartHurdle'
sigma(object, ...)

## S3 method for class 'bart'
nobs(object, ...)
## S3 method for class 'bartMultinomial'
nobs(object, ...)
## S3 method for class 'bartOrdinal'
nobs(object, ...)
## S3 method for class 'bartNegbin'
nobs(object, ...)
## S3 method for class 'bartHurdle'
nobs(object, ...)

Arguments

Data and formula.

formula

An object of class formula following an analogous model description syntax as lm, including its offset() terms and data-dependent terms such as poly() (see dbarts's formula item), optionally written as a sum of forest() terms, each one forest of a model of several (see ‘Formula Terms’ below). For backward compatibility, can also be the bartBT matrix x.train (data then plays the role of y.train); see dbarts's formula item for the full data-frame-to-predictor mapping, including sparse Matrix::dgCMatrix and sparseFactor columns.

data

An optional data frame, list, or environment containing predictors, used together with a formula formula. For backward compatibility, can also be the bartBT vector y.train.

test

An optional matrix or data frame with the same number of predictors as data, or formula in backward-compatibility mode; if column names are present, a matching algorithm is used, and a data frame is read as a formula fit reads one, every predictor's name among its columns taken by name and any other column ignored (a matrix keeps its exact width), and an unnamed matrix against named predictors is read in the fit's column order, with no message. Refused, by name, when formula writes a model of several forests (‘Formula Terms’): an amplitude-coupled fit has no per-observation test replay. A formula whose one forest() has no basis is a single-forest fit and takes test.

subset

An optional vector of logicals or indices used to subset the data. Can be missing. A forest() term's predictors are columns of the same subsetted model frame as every other predictor, and its basis, which has a value for every row of data, is cut to the same rows (‘Formula Terms’), as is a basis given through dbarts's forests = (see forest's basis item).

weights

An optional vector of weights to be used in the fitting process. For a gaussian response, BART fits a model with observations y∣x∼N(f(x),σ2/w)y \mid x \sim N(f(x), \sigma^2 / w), where f(x)f(x) is the unknown function. A weight of 0 takes an observation out of the likelihood and out of the residual degrees of freedom but not out of the design: it still occupies a leaf and receives a fitted value, so a fit with zero weights is close to the fit on the remaining rows alone without being that fit: the trees may split off regions of zero-weight rows, whose fitted values then come from the prior. A row of weight 0 takes no part in the response's scale, which the leaf prior is stated against, in the center of a count fit's leaf prior, or in the default sd of a forest in a model of several forests: they are taken over the rows of positive weight when the sampler is created. The step is at 0 and not at a small weight, and weights or a mask set after creation leave the numbers creation set, so the three ways to leave a row out - weights or a mask at creation, weights or a mask set later, and subset - differ by when the row left. Where rows are out and the rows in hold fewer than two distinct values of the response, every row is used instead, under a warning of class dbartsScaleFallbackWarning. In one measured case (300 rows, 50 trees, the cut points held equal) the fitted mean at the remaining rows moved by no more than 0.02 of a posterior standard deviation with a random half of the rows at weight zero, and 0.05 with a whole region at weight zero; dbartsSampler's weights item has the figures. subset drops rows, and with them their part in the cut points and the response scale. How a weight is read is weights.type's (see that item): by default a gaussian or Student-t weight is the precision above, and on every other family a weight counts identical observations or, at 0 and 1, marks a row in or out of the likelihood. A probit fit (the default binary family here, and bartBT's) takes weights of 0 and 1 only, which name the rows in the data set, a 0 row leaving the likelihood but keeping its leaf occupancy, its latent and its fitted value, and weights identically 1 are treated as absent; the same holds for family = "ordinal". A family = "logistic", "nbinom" or "multinomial" fit reads its weights as observation counts, a row of weight ww standing for ww copies of itself, and requires non-negative whole numbers, a count of 0 leaving the row out of the likelihood; as a sweep's time grows with the total count, a weight times the row's trials (logistic), times y+ry + r (nbinom) or times the row total (multinomial) is refused above 10610^6. An nbinom fit's 0/1 weights are membership as a probit fit's are, and its leaf prior's center, the log of the total count over the total exposure, counts each row its weight's number of times; an exposure belongs in the offset, not in a weight. A training row's "ppd" draw is one observation like the row, whatever its weight: under precision at sd σ/w\sigma / \sqrt{w}, under frequency at sd σ\sigma, one 0/1 draw on a binary fit, one count on an nbinom fit, one category on an ordinal fit or a multinomial fit to categories, and a count vector at the row's trials on a multinomial fit to count rows; predict's weights draw more (below). A row at weight 0 has NA "ppd" draws on every family and in every route: a training row (extract, fitted(type = "ppd")), a row of the test sample whose test weight is 0, and, on a gaussian, Student-t or aft fit, a row given weights of 0 to predict; an aft fit takes no case weights at fit time, so only predict(weights = ) reaches a weight of 0 on it, with the same result. A credible band (ci.level) over such a row is NA in all three columns. A weight of 0 holds a row out of the fit, and under precision gives it no noise scale, σ/w\sigma / \sqrt{w}, as simulate gives NaN at a weight-0 row of an lm fit; no warning is raised, the row's fitted value is still reported, and every other row's draw is as it would be without the row. To draw such a row as a new observation, state its weight: predict(fit, type = "ppd", weights = 1).

A test sample's weights, the weights expression evaluated on test on the formula interface, mean what the fit's own do, and are checked by the same rule: each test row is drawn as a training row of that weight is, one observation, NA at a 0, so a logistic test row of weight 3 gives one 0/1 draw, except a binomial fit's test row, which draws at the trials its response columns give (see the family item). A test row with no weight on a count family (logistic, probit and the hazard families, nbinom, ordinal, multinomial) draws one trial, a binomial fit's test row carrying both count columns drawing at their k+fk + f; there extract(sample = "test") agrees with predict(newdata = test) given no weights, where the formula fit's weights name a column of test that holds a 0 (both give NA there), and on a gaussian, Student-t or aft fit with predict given the test weights.

For predict, the weights of the rows drawn by type = "ppd", one value or one per row. On a gaussian, Student-t or aft fit they are precisions, a 0 giving NA; under weights.type = "frequency" predict takes 1, a new observation, and 0, a row held out, and refuses other values, since a training row of weight ww stands for ww observations and its draw is one of them. On a count family a weight is the number of new trials the draw is made over: Binomial(w,p)\mathrm{Binomial}(w, p) successes on a binary fit, pp the fitted probability, a binomial fit given none drawing at the trials newdata's response columns give where it carries them, and at one trial where it was fit through the matrix interface (see the family item); on an nbinom fit the sum of ww new counts, one NB(size=wr,mu=wμ)\mathrm{NB}(\mathrm{size} = w r, \mathrm{mu} = w \mu) draw; on an ordinal or multinomial fit the count per category over ww new trials, an array of draws by rows by categories, so weights = 1 on a fit to categories gives each draw's category as a unit vector. A weight of 0 is zero new trials and draws zero counts, by every route; a row not to be drawn is left out of newdata. With no newdata, the weights given replace the fit's own at the training rows for the predictive draws, worked from the stored draws, and a training row whose fit weight is 0 keeps its NA draws when predict is given no weights. The types that draw nothing read no weight, and a missing weight follows na.action. A family = "hurdle.lognormal" fit takes weights of 0 and 1 on both its parts, with the same rows and the same result (see the family item). Where the fit took its weights from a column of its data on the formula interface (weights = w or an expression of columns, not a vector) and predict is given newdata that hold those columns and no weights, the column is read from newdata alone, never from the calling environment, and means what the fit's weights do, as a test sample's do: a precision on a gaussian or Student-t fit, so predict(fit, d, type = "ppd") on the training frame d equals the same call with weights = d$w; one new observation on the other families, a binomial fit still drawing at the trials its response columns give; and a weight of 0, or a missing one under na.pass, gives NA draws with no warning, every other draw unchanged. A missing weight in the column is answered by na.action as a missing weights is. newdata without the column, and a fit whose weights were a vector, draw as with no weights: at weight 1, a binomial fit at the trials its response columns give where newdata carry them. The column is checked by the fit's rule, as a test sample's weights are, and must be numeric. A test frame's weights column holding a missing value is refused at fit time, naming the rows and saying to fill them, drop them from test, or give predict the rows with na.action = na.pass.

offset

An additive offset entering the family's mean or link, applied to training data; see dbarts's offset item for the exact per-family formula. The same concept as bartBT's binaryOffset (which only ever applies to that function's probit/logistic default family). Can be missing. A formula's offset() terms are added to it, as in lm, and a family that refuses an offset refuses them alike.

For predict on a bart fit, the offset at the predicted rows: a single value, or one per row of newdata. The fit's offset() terms and offset argument are evaluated on newdata, as predict.lm evaluates them, and added to it, so newdata must then be a data frame carrying their data columns; every other name in them was fixed at its value when fitting. An offset argument given as a plain vector for the training rows applies only to a newdata of as many rows, as in lm; on any other newdata predict refuses unless given an offset, which takes its place. The same holds for predict on a bartOrdinal fit, whose latent is shifted by the offset before the thresholds are applied, and for survivalProbabilities.

For predict on a bartMultinomial fit, the same name carries a different shape: the per-category shift at the PREDICTED rows, an nrow(newdata) x K numeric matrix entering the K raw fits before the softmax, in the same layout as bart's own train-side offset above. It is never taken from the fit - these rows are not the fit's rows - so a fit trained with an offset REQUIRES one here, refusing by name rather than reporting the offset-free surface, which an explicit all-zero matrix asks for. NULL (the default) is the only value a fit trained without one takes by default, and passing the training offset back at the training rows reproduces yhat.train. A missing value in one of its rows is governed by na.action (see ‘At Prediction’ in na.keepPredictors); a scalar NA is always refused. A large negative entry is a shift like any other: the probabilities it drives are the exact softmax, so one far enough below its row's others underflows to zero (and its log to -Inf) as it would anywhere else.

For predict on a bartNegbin fit, the same name is the log-exposure shift at the PREDICTED rows, entering the replayed log mean η\eta additively before eηe^{\eta}. NULL (the default) takes the rule the bart paragraph above states: the fit's offset() terms and offset argument evaluated on newdata, and a plain vector for the training rows applying only to a newdata of as many rows. A single value is recycled over the predicted rows and a missing one is always refused; otherwise it has one value per row of newdata, and a missing value there is governed by na.action (see ‘At Prediction’ in na.keepPredictors).

On a family = "hurdle.lognormal" fit a plain offset, the argument or an offset() term, enters the POSITIVE part, where a log exposure makes a positive amount proportional to exposure, and the zero part's probit takes none; offset = list(zero = , positive = ) states each part's, either left out, each element a vector or an expression over the data (recorded as written, so predict can evaluate it on newdata). offset.test takes the same forms and defaults to offset, each element evaluated on the test frame, or reused where the rows match, or refused asking for offset.test. This differs from pscl's hurdle, where y ~ x + offset(log(t)) reaches both parts: here it reaches the positive part only, and a zero-part offset is written offset = list(zero = ). type = "prob" carries the zero part's offset, "bart" (the link) the positive part's, and "ev" and "ppd" both. A missing offset follows na.action as a missing weight does. For predict on a bartHurdle fit, each part's recorded offset is evaluated on newdata and an offset given (one value or one per row, entering the positive part, or a list naming the parts) is added to its part's; with no newdata an offset given replaces its part's at the training rows, read off the stored draws, a part the list leaves out keeping its own.

offset.test

The equivalent of offset for test observations (for family = "multinomial", an m x K matrix, see family). Defaults to the offset argument evaluated on test, as predict evaluates it on newdata, plus the formula's offset() terms evaluated there: a scalar is reused, offset = log(exposure) reads test's exposure, and a vector given for the training rows applies only to a test set of as many rows, any other length refused by name rather than silently recycled. Given explicitly, it is likewise a scalar or one value per test row, a bare name is looked up in test before data, and offset named in it is the argument's own value, the formula's offset() terms being evaluated on test and added to it. See dbarts's ‘Test offset synchronization’ details for how a live sampler keeps the two linked after fitting.

na.action

A function that filters incomplete rows, as lm takes one. The default na.keepPredictors drops rows with a missing RESPONSE and keeps rows with missing predictors, which the trees route; the base functions keep their usual meaning. A survival response is missing where its time or its status is, as survreg and coxph take it. NULL applies no action, as in lm, on the formula and matrix interfaces alike. A row whose weights or offset is missing is dropped by na.omit and na.exclude on the matrix interface as on the formula one, na.exclude padding it back; every other action leaves it to the refusal of that argument. See na.keepPredictors.

For predict, what to do with the rows of newdata that have missing values, and, with no newdata, the training rows whose per-row offset or weights has one; see ‘At Prediction’ in na.keepPredictors.

factors

How factor columns in a data frame enter the model, exactly as in dbarts. The default "categorical" keeps each unordered factor as a single predictor whose splits send a subset of its levels down each branch - a different model-matrix representation than bartBT's, which always expands every factor into indicator columns; "indicators" instead expands each factor into binary indicator columns, matching bartBT, and matches a test factor to the training levels by label, refusing by name a level with no training rows. A factor-predictor fit therefore changes if moved between the two interfaces. Subset splits let a single split separate any grouping of a factor's levels, where indicator columns need a chain of splits to do the same, and they give a factor the prior split probability of one predictor rather than one per level.

Family and priors.

family

The response family. "auto" (the default) fits gaussian models to continuous responses and probit models to those coded 0/1, exactly as dbarts; a two-level factor, logical, or two-level character response is also detected and fit as probit, an unordered factor (or character) response with three or more levels is detected and fit as multinomial, and an ordered factor with three or more levels is detected and fit as ordinal, and an n x K matrix (K >= 3) of non-negative whole numbers, on the matrix interface, as a cbind(c1, ..., cK) left-hand side, or held as one data-frame column, is read as per-category counts and fit as multinomial (an NA cell marks a missing row, as it does for family = "multinomial"). Every resolution of "auto" - gaussian, probit, multinomial, ordinal, aft for a Surv response - is reported once per call in a one-line message naming the family fit (suppressed by verbose = FALSE; an explicitly named family prints nothing). An n x 2 matrix under "auto" is an error naming its readings, successes and failures (add family = binomial), per-category counts (add family = "multinomial") and a (time, status) pair (use a Surv response or family = "aft"/"hazard"), and so is an n x K matrix with negative or fractional entries. A multinomial response is read alike here and in dbarts: a data frame of numeric columns is its matrix of counts, and a one-column character matrix its vector of labels; a wider character matrix, or a data frame with a column that is not numeric, is refused. "gaussian", "probit", and "logistic" force those fits directly; "aft", "hazard", "hazard.probit" (an accepted alias for "hazard"), "hazard.logistic", "multinomial", "ordinal", "nbinom", and "hurdle.lognormal" reach the extended families described below. A "probit" or "logistic" response that holds one class is fitted, with one warning saying so; the prior alone then drives the fitted probabilities toward 0 or 1. bartBT takes no family argument at all: every fit it makes is the default gaussian/probit pair. Base R family objects map as glm takes them (binomial is the logit link, so family = binomial is "logistic", not probit) and the rest are refused; see dbartsFamilies.

Every setting only one family reads rides the family object rather than this signature, in glm's idiom: a token string is the family at its defaults and a call is the family with settings. dbartsFamilies lists them. Among those settings is the residual scale's own prior, on the four families that draw a residual scale: gaussian(sigma = ), student(df, sigma = ), aft(sigma = ), and hurdle.lognormal(sigma = ) (the positive part's), where sigma is a dbartsPriors residual prior, chisq(df, quant) or fixed(value), resolved in the prior vocabulary inside the family call. family = gaussian(sigma = chisq(3, 0.9)) is the shipped default written out; family = gaussian(sigma = fixed(1)) pins the residual variance and suppresses the sampler's own draw. The families with no free residual scale (probit, logistic, ordinal, nbinom, multinomial, the hazard families) take no sigma argument at all. A family call forwarded through a wrapper's own ... resolves as if written here, with ordinary variables in it read where the call was written; a wrapper that takes the family as a named formal of its own forwards an ordinary variable, which has to hold a token or a prebuilt object (dbartsFamilies$gaussian(sigma = dbartsPriors$chisq(3, 0.9))).

family = binomial, stats::binomial() or "logistic" also fits a binomial response, written as glm writes it: cbind(successes, failures) on the left of a formula, or an n x 2 matrix of successes and failures as the response on the matrix interface, a data frame there being refused (a data object takes the pair as dbartsData(counts = )). A row of kk successes in nn trials is one logistic row of nn trials, drawn as its nn 0/1 rows would be. Successes and failures must be non-negative whole numbers, a factor or character column among those the left-hand side reads being refused, at the fit as at new rows, a row with a missing value going to na.action; nn times the row's weight is capped at 10610^6. The fit reports on two scales, as glm does: fitted(type = "ev") is the probability pp and its residual k/n−pk / n - p; the predictive draws are counts, Binomial(n,p)\mathrm{Binomial}(n, p) at a training row, so fitted(type = "ppd") estimates npn p and its residual is k−npk - n p. fit$y keeps the two columns as written. At new rows predict(type = "ppd") draws Binomial(w,p)\mathrm{Binomial}(w, p) with ww from its weights, as on a 0/1 fit; where no weights are given and newdata carries the response's columns, every one the formula's left-hand side names, a row draws Binomial(k+f,p)\mathrm{Binomial}(k + f, p) at the trials they give, and otherwise one trial. A fit made through the matrix interface carries no response columns to read, so its new rows draw one trial each unless predict is given weights, their trials; the formula route reads the trials from new data that carry both columns. A row missing either count is treated as a row missing its weight: refused by default, its draws NA under na.action = na.pass, dropped under na.omit; columns missing a count in every row read as absent, one trial a row. A row of the test sample draws at the trials its columns give, as predict does, a test weight of 0 holding it out and other weights not changing the trials; a test row missing a count is refused before the run, and a test sample without the columns draws one trial a row. The probabilities do not read the columns. A weight ww counts copies of the row: the row stands for wnw n trials in the likelihood, its log-likelihood is wlog⁡dbinom(k;n,p)w \log \mathrm{dbinom}(k; n, p), the binomial coefficient included as in glm's logLik, and its predictive draw is still one row's, Binomial(n,p)\mathrm{Binomial}(n, p). A row of no trials is out of the likelihood, with a warning, as a multinomial row of no trials is: its fitted probability is still reported, its draws are 0, its log-likelihood is 0 in every draw and its residual −p-p, its observed proportion read as 0. glm's other spelling, a proportion with the trials as weights, is refused with a message showing the cbind form, since a logistic weight counts copies of a row and its draw is one row; binomial("probit") with successes and failures is refused, the probit binomial not being fitted. xbart takes the binomial response as bart does.

family = "multinomial" fits a K-category softmax classifier: K forests, one per category, coupled through an interleaved Polya-Gamma one-vs-rest augmentation. When formula is a formula, data is required (not optional as for every other family): bart(y ~ x1 + x2, family = "multinomial", ...) with no data errors by name rather than resolving y/x1/x2 from the calling environment. y.train must be a factor (or character, coerced with factor) with at least two levels and no NA levels; a missing label, or - for the count-matrix form below - a row with any NA cell, is a missing response, routed through na.action exactly as for every other family (see na.keepPredictors); K = nlevels(y.train) is inferred, never given explicitly, and levels(y.train) is captured at fit time and carried on every K-shaped output (yhat.train's trailing dimension, fitted's columns, the fitted(type = "class") factor). Alternatively, y.train may be an n x K numeric matrix of nonnegative integer trial counts, one row per observation and one column per category, with row sum (trials) ni≥0n_i \ge 0: category k's count is then a binomial(nin_i, p_k) draw under the same one-vs-rest augmentation, K = ncol(y.train) is inferred, and the levels carried on every K-shaped output are colnames(y.train) when present, otherwise as.character(seq_len(K)). A one-hot count matrix (every ni=1n_i = 1) is the same model as the factor response above, reproduced bit for bit. A row with ni=0n_i = 0 contributes nothing to the likelihood and still receives fitted probabilities, as glm fits a row of zero prior weight, and the first such row in a session warns; its residuals are the negated fitted probabilities (observed 0, glm's response residual there), and its extract(type = "loglik") column is 0 in every draw, so drop those columns before passing the matrix to loo, which reports an infinite Pareto k for a constant column. The formula interface is supported alongside the matrix one: bart(formula, data, family = "multinomial") with a factor (or character) left-hand side routes to the factor response above, and a cbind(c1, ..., cK) ~ x left-hand side (the same idiom glm's binomial family uses) routes to the count-matrix response above, K and the levels taken from the cbind column names; the right-hand side is coded exactly as it is for every other family's formula fit, including predict on a data frame newdata. Under the default family = "auto", a factor (or character) response with three or more levels, or a count matrix with three or more columns of non-negative whole numbers (a cbind(c1, ..., cK) ~ x left-hand side, a matrix column of the data frame, or a bare matrix), is detected and fit as multinomial, reporting the choice in a one-line message; a two-level factor (or logical) response resolves to probit, and a numeric vector response is unchanged. A two-column matrix is never read as counts under "auto", since it is equally a (time, status) pair: it needs family = "multinomial" (or a Surv response) to be fit. weights are observation counts, non-negative whole numbers (see the weights item), a row of weight ww the row written out ww times; on a count fit that is its counts times ww. subset, samplerOnly, warm.start, n.grow.sweeps, a non-uniform split.probs (a vector or dart()), monotone, and variance are all refused with an error naming the limitation (the K-forest engine copies only power/base/proposal-probability fields from the temporary sampler it builds, so DART, fixed split probabilities, monotone direction constraints, and a variance forest never reach it). offset is accepted only as an n x K numeric matrix, entering the K forests' raw fits before the softmax, one column per category, in the same layout as a count-matrix y.train; a flat (length-n) offset is refused by name, since a common per-observation shift is the softmax's own null direction and is identically inert. offset.test takes an m x K numeric matrix for the m test rows, in the same column layout as offset; omitted, it defaults to offset when the row counts match, and an offset beside a test set of another length is refused by name asking for offset.test. An explicit offset.test = NULL means no test offset. A reused default is a copy taken at fit time: on a kept sampler, neither $setOffset nor $setCategoryOffset moves it (see dbarts's ‘Test offset synchronization’, which describes a directly built sampler). A data frame is accepted for offset and offset.test alike, and column names, when present, are matched to the category levels (a permutation is reordered by name, other names are refused; an unnamed count-matrix fit matches offset columns by position; a permutation of its column indices is still reordered, and other names are ignored), for predict's offset as well. A flat offset.test is refused like a flat offset, and a missing or non-finite value is refused as in offset. yhat.test then carries the test offset and equals predict's replay at test given offset = offset.test. test is supported: an x.test of the same column structure as x.train reports the K-category softmax probabilities on the held-out rows as yhat.test, shaped and levels-named exactly like yhat.train (see ‘Value’). keepTrees is supported too: it retains every one of the K forests' trees so predict can replay them at new predictors afterward, reproducing yhat.test bitwise when newdata matches the fit-time test; without keepTrees, predict errors. A fit trained with an offset replays as well, given predict's offset at the new rows, and refuses by name without it: no resident offset describes rows the fit never saw. The per-forest leaf scale follows its own K-dependent calibration (the K = 2 scale is the logistic scale π3\pi\sqrt{3} divided by 2\sqrt{2}, for the identified pairwise log-odds); k is read from the usual leaf prior exactly as for any other family, but the leaf prior's scale itself is NOT consulted - the multinomial engine calibrates its own. The fit's class is "bartMultinomial", not "bart": see ‘Value’ below and the extract/fitted/predict methods for bartMultinomial objects.

family = "ordinal" fits an ordered categorical response by a cumulative probit (a single forest, unlike multinomial's K): a latent z=f(x)+ϵz = f(x) + \epsilon with ϵ∼N(0,1)\epsilon \sim N(0, 1) is cut at ordered thresholds −∞=γ0<γ1=0<γ2<…<γK−1<γK=∞-\infty = \gamma_0 < \gamma_1 = 0 < \gamma_2 < \ldots < \gamma_{K-1} < \gamma_K = \infty, so P(Y=k∣x)=Φ(γk−f(x))−Φ(γk−1−f(x))P(Y = k \mid x) = \Phi(\gamma_k - f(x)) - \Phi(\gamma_{k-1} - f(x)). The free thresholds are sampled by a one-at-a-time marginal Metropolis update (latents integrated out) under a log-gap prior N(0,1.52)N(0, 1.5^2); at K=2K = 2 the model is exactly the probit family. y.train should be an ordered factor (is.ordered); its level order defines the category order, and levels(y.train) is captured at fit time and carried on every K-shaped output. Under the default family = "auto", an ordered factor with three or more levels is detected and fit as ordinal, reporting the choice in a one-line message (an unordered factor stays multinomial - the two never overlap, the dispatch key is is.ordered); a two-level ordered factor is binary and resolves to probit. Given explicitly, family = "ordinal" also accepts an unordered factor or character response (with a message that the category order is taken from the level order - usually alphabetical, so order the levels yourself) and a numeric response, whose ordered levels are sort(unique(y.train)). weights are taken as 0 and 1 only, marking rows in and out of the likelihood as on a probit fit (a weighted truncated-normal latent likelihood is not a coherent model); warm.start and n.grow.sweeps are refused with an error naming the limitation. samplerOnly is supported, unlike multinomial: it returns the fitted sampler unrun, the same object fit is under keepSampler. test and keepTrees are supported as for multinomial, and predict replays the saved trees at new predictors, differencing the cumulative probit at the stored per-draw thresholds. xbart does not fit ordinal responses. The fit's class is "bartOrdinal", not "bart": see ‘Value’ below.

family = "nbinom" fits a non-negative integer (count) response by a negative-binomial model on a log link with the Polya-Gamma augmentation (a single forest, like logistic): the forest fits the log mean, log⁡E[yi∣x]=ηi=f(xi)+c+oi\log E[y_i \mid x] = \eta_i = f(x_i) + c + o_i, and the count distribution is yi∼NB(size=r,mu=eηi)y_i \sim \mathrm{NB}(\mathrm{size} = r, \mathrm{mu} = e^{\eta_i}) with shape rr and variance μ+μ2/r\mu + \mu^2 / r, as MASS::glm.nb and Stan's neg_binomial_2 parameterize it. The offset oio_i therefore enters the mean multiplicatively and is a log-exposure (oi=log⁡(exposurei)o_i = \log(\mathrm{exposure}_i)). The constant c=log⁡(∑iyi/∑ieoi)c = \log(\sum_i y_i / \sum_i e^{o_i}) (with the total count floored at 1/2) centers the leaf prior at the data's log rate; it is a data transform, as the response range is for a gaussian fit, so f is zero-centered a priori. Under a k-named leaf prior, k.scale is 3 on the log-mean scale (under an sd-named one it is twice the sd) and k is drawn from chi(1.5, 2) by default, as for probit; see dbartsPriors. y.train must be a non-negative integer count, and family = "nbinom" is always explicit - a count carries no unambiguous class, so it is never inferred under family = "auto" (a numeric response there stays gaussian). The shape r is estimated by default on a capped positive-integer grid ({1,2,3,4,5,6,8,10,12,15,20,30,50}\{1, 2, 3, 4, 5, 6, 8, 10, 12, 15, 20, 30, 50\}) under a renormalized gamma(2,0.1)\mathrm{gamma}(2, 0.1) prior, drawn each sweep from its discrete full conditional given the means; at ordinary counts a shape above about 20 is hard to tell from a larger one, so the posterior there leans on the grid's cap and prior. Passing shape as a positive integer fixes rr instead (a real fixed shape is refused). Like probit, there is no residual scale; weights are observation counts, non-negative whole numbers, a weight of 0 or 1 marking a row out of or in the likelihood (exposure belongs in the offset, not in a weight); warm.start and n.grow.sweeps are refused with an error naming the limitation. samplerOnly is supported, unlike multinomial: it returns the fitted sampler unrun, the same object fit is under keepSampler. test and keepTrees are supported as for ordinal, and predict replays the saved trees at new predictors, reporting mean counts eηe^{\eta}, with type = "ppd" drawing at the stored per-draw shape (a log-exposure offset enters η\eta additively). xbart does not fit count responses. y.train is additionally capped at 10610^6: the shape grid's count histogram is sized from the largest count, so a larger one allocates without bound, and a count above it is refused at creation and at every response swap alike. The fit's class is "bartNegbin", not "bart": see ‘Value’ below.

family = "hazard" and family = "hazard.logistic" fit a discrete-time survival hazard model as ingestion sugar over the binary families - the model adds no engine code ("hazard.probit" is an accepted alias for "hazard"). The response is the same Surv object or two-column (time, status) the "aft" family takes; each subject observed to time tit_i is person-period-expanded into its at-risk rows (one per period k=1,…,tik = 1, \ldots, t_i), each carrying the subject's covariates, an ordinal period column (appended last, so trees split on contiguous periods and borrow strength across time), and the binary indicator yik=statusi⋅1{k=ti}y_{ik} = \mathrm{status}_i \cdot 1\{k = t_i\}. The discrete hazard is h(k∣x)=g(f(x,k)+o)h(k \mid x) = g(f(x, k) + o) for the chosen binary link gg (probit for "hazard", logistic for "hazard.logistic"), and the fit is EXACTLY an ordinary "probit"/"logistic" fit on the expanded rows - a hazard fit is byte-identical, draw for draw, to the binary fit on the hand-expanded design with the same seed and the same n.cuts, the period column's included (see n.cuts). The time grid defaults to the sorted distinct observed times of the subjects in the likelihood, those of positive weight (the BART surv.bart convention; every subject's if none is in, under a warning of class dbartsScaleFallbackWarning); family = hazard(breaks = ) replaces it (a single integer bins at that many quantiles of those times, a boundary vector gives explicit right-closed intervals), and no expansion size is refused: a row takes about 35 KB at the peak of a fit at bart's defaults, most of it the kept draws of the training fits, and a fit whose projected peak exceeds the machine's physical memory warns once per session (class dbartsMemoryWarning) before its rows are built, then runs (see dbartsFamilies). Offsets are on the link scale and replicate per subject; weights replicate and then follow the chosen binary family's policy (probit takes 0 and 1 only, logistic requires whole-number counts); a subject at weight 0 is expanded on that grid, its time in the interval it falls in, and one past the last period is at risk in every period with no event. A Surv response requires the family to be requested explicitly (family = "auto" selects "aft"), on either interface - a Surv left-hand side on formula works too, and both interfaces honor subset (applied before the person-period expansion). A hazard fit whose person-period response holds one class, every subject censored or every subject's event in its first period, is fitted, with one warning saying so; the prior alone then drives the hazards toward 0 or 1, and the survival curves sit where the prior puts them. Both interfaces accept a test set, person-period-expanded on the SAME period grid as training (no event time - every subject expands to every period); survivalProbabilities with sample = "test" then reads its hazards straight off the fit with no keepTrees needed (the call with no newdata is always the training subjects). Any OTHER newdata passed to survivalProbabilities still needs keepTrees. The returned object is an ordinary "bart" fit whose $family records the binary link (so every prediction generic transforms correctly with no special case) and whose $periods element carries the grid; predict/extract return the per-(subject, period) hazards on the expanded rows, and survivalProbabilities produces survival-curve draws S(t∣x)=∏k:periods[k]≤t(1−h(k∣x))S(t \mid x) = \prod_{k : \mathrm{periods}[k] \le t} (1 - h(k \mid x)). Covariates enter as for every other family, factors, ordered factors and sparse columns included; a predictor named period, or a term that reads it, is refused. predict takes person-period rows including a period column, while survivalProbabilities(newdata = ) takes one row per subject. xbart does not fit hazard responses.

family = "hurdle.lognormal" fits a semicontinuous two-part (hurdle) model for a non-negative response with exact zeros: a ZERO-PART probit fit of z=1{y>0}z = 1\{y > 0\} over all n observations, glued at report time to a POSITIVE-PART gaussian fit of log⁡y\log y over the subset {i:yi>0}\{i : y_i > 0\}. The two component fits share no parameters and are composed entirely R-side from two ordinary bart fits at independently derived seeds - no engine code, and no coupling between the parts - so a shared variable-selection prior across the zero and positive parts is foreclosed by this composition, as are a Duan-smearing retransformation and a heteroscedastic positive part. y.train must be non-negative and finite and must carry at least one exact zero and one positive value (a response with no zeros, or none positive, is refused by name). na.action settles the rows before the response is split, so a row it drops is dropped from both parts; a predictor it keeps missing only on zero rows is refused, since the positive part would learn no route for it. A variance forest is refused by name. By default predict/fitted/extract report the NATURAL (response) scale via posterior-predictive Monte Carlo: E[y∣x]=P(y>0∣x) ef(x)+σ2/2E[y \mid x] = P(y > 0 \mid x)\,e^{f(x) + \sigma^2 / 2} computed per posterior draw from the positive part's single σ\sigma per draw, recycled across observations (the positive part is always homoscedastic; a heteroscedastic positive part is not reachable). type = "prob" returns the zero part's own probability π(x)=P(y>0∣x)\pi(x) = P(y > 0 \mid x) through the probit link; type = "link"/"log" the positive part's log-scale linear predictor f(x)f(x); type = "ppd" draws the proper BIMODAL predictive - a Bernoulli(π\pi) spike at zero, else a lognormal draw - which the plain gaussian ppd path cannot produce. Fits take the matrix interface (bart(x.train, y.train, family = "hurdle.lognormal")), a formula (bart(y ~ x1 + x2, data, family = "hurdle.lognormal")) or a dbartsData object, as any other fit does. The predictors, the response and the formula are read once, into one data object that na.action has settled, and the two parts are cut from it by rows, so both parts see the same rows, the same columns and the same factor coding: a level that occurs only on zero rows is coded on the positive part's rows as it is on the zero part's. A data object is taken whole, and an argument written beside it is ignored with the warning every family gives. A sparse design is refused. test is taken as on any other family: both parts are evaluated at its rows, and extract and fitted read them with sample = "test", every type but "loglik", which needs a response. subset removes rows from both parts, as one model frame does in lm (it is applied before na.action). weights are 0 and 1: a 0 holds a row out of both parts' likelihoods and keeps it in both designs, a 1 keeps it, and any other value is refused with the remedy of repeating each row its weight's number of times, which is exact for a probit zero part; a row of weight 0 has NA predictive draws (type = "ppd") and NaN log-likelihood, and its fitted values and residuals are reported. A missing weight is dropped by na.omit and na.exclude on the matrix interface as on the formula one. offset, offset.test and offset() terms are taken (see the offset item). The positive-part fit is given the training x followed by the test rows as its own x.test, so its in-sample fitted values cover the zero rows it never trained on. keepTrainingFits = FALSE is taken where a test set is given: the training fits are dropped, the test draws are those of the default fit, and fitted, residuals, predict with no newdata, extract(type = "loglik") and plot then refuse as a gaussian fit kept so does; without a test set it is refused. predict takes weights after offset: with newdata, a 1 draws a row as a new observation and a 0 holds it out (NA); with no newdata, the weights given replace the fit's own at the training rows for the predictive draws, one value or one per training row. Types that draw nothing read no weight. predict requires keepTrees = TRUE and replays both saved forests at newdata. dbarts() does not fit this family - it composes two samplers, which only bart() builds, so requesting it there is an error directing here. xbart does not fit it either. The fit's class is "bartHurdle", holding both component fits ($zero, a "bart" probit fit of the zero-part indicator; $positive, a "bart" gaussian fit of log⁡y\log y on the positive subset) under their own extract/fitted/predict/residuals/print methods. Both parts take the one leaf.prior, so a leaf prior naming sd is refused: one spread cannot be stated on the probit latent and on log⁡y\log y at once, and it would fix the zero part's drawn default k. Name k, or fit the parts separately - a probit fit of 1{y>0}1\{y > 0\} and a gaussian fit of log⁡y\log y over the positive rows, each with its own sd - which is the same posterior, the parts being independent.

weights.type

How weights are read. Under "precision" a weight scales a row's residual variance, y∣x∼N(f(x),σ2/w)y \mid x \sim N(f(x), \sigma^2 / w), as lm reads weights. Under "frequency" a row of weight ww stands for ww identical observations, so the posterior is the one for the data with each row written out ww times, a real ww raising the row's likelihood to that power; a weight of 0 is a row out of the likelihood under either. NULL (the default) is each family's own reading, which the sampler records: precision where there is a residual scale, and frequency everywhere else, where a weight counts identical observations or, on the families with a latent no weight can scale, marks a row in or out of the likelihood at 0 and 1:

family NULL reads "precision" "frequency"
gaussian, student, a variance forest precision taken, real w≥0w \ge 0 taken, real w≥0w \ge 0
logistic, hazard.logistic, nbinom, multinomial frequency, counts refused whole w≥0w \ge 0
probit, hazard, hazard.probit, ordinal frequency, membership refused 0 and 1 only
hurdle.lognormal frequency, membership refused 0 and 1 only
aft precision, no weights no weights refused

Under "frequency" on a gaussian-type fit, the starting sigma (sigest) is the residual sd of the regression on the rows written out, its degrees of freedom the total weight less the regression's rank, a total within rounding of the rank leaving none, the sd stand-in a weighted one (unweighted where the counts total at most 1); the residual scale's posterior counts ww observations at a row; a row's predictive draw is one observation at sd σ\sigma; its log-likelihood is ww times one observation's; and predict takes weights of 1 and 0 only. Under Student-t, a row's latent precision ($getLatents()) is the composite of its ww copies'. A frequency weight is data, not a design weight: weights rescaled to sum to 1 leave σ\sigma one observation's worth of data, survey or inverse-probability weights are not counts, and ww copies of a continuous response are exact ties, which the fit reads as nearly noiseless data. A 0/1 response's weight is always a count of identical rows. A "hurdle.lognormal" fit reads its 0/1 weights as membership in both parts and refuses "precision". The reading is fixed when the sampler is created: $setModel cannot change it, and $setWeights, $setData and predict read new weights under it.

sigest

For continuous response models, an estimate of the residual standard deviation (residual standard error), σ\sigma, used to calibrate an inverse-chi-squared prior on the error variance. A positive number, or one of "auto", "dense" and "sparse", naming how one is made: each gives the residual standard deviation of the linear regression of the response on the predictors and on each forest's basis (a factor's as the indicator of its second level), factors entering as indicator columns whatever the trees are given, and, where that regression leaves no residual degrees of freedom, counting each row once, not as often as its weight, under weights read as counts, the standard deviation of the response over the observations of positive weight, weighted as the regression is (summary(lm(y ~ 1, weights = weights))$sigma, sd(y) at unit weights; for weights read as counts, the standard deviation of the rows written out, or sd(y) over the observations of positive weight where the counts total at most 1, up to the rounding of their sum), which a line under verbose and one in the fit's summary say, with no warning. (Where rows are out and the observations of positive weight hold fewer than two distinct values of the response, the regression is made on every row instead, under the warning of class dbartsScaleFallbackWarning.) "auto" is lm's own routine ("dense") for a matrix or a data frame and an exact sparse one ("sparse") where the caller supplied a sparse-stored column. NULL (the default) is "auto"; an explicit NA reads as NULL for one release, with a once-per-session warning. dbarts says what the two routines cost, where they differ, and what to pass in place of an expensive estimate, which cannot be interrupted once begun. The prior it calibrates is family = gaussian(sigma = chisq(df, quant)), whose quant is the prior probability that σ\sigma is less than this estimate. Not applicable when yy is binary: under a family with no free residual scale ("probit", "logistic", "ordinal", "nbinom", the hazard families, "multinomial") it is inert and is diagnosed rather than silently dropped, as are the retired resid.prior, sigdf and sigquant, which such a family overwrites with fixed(1) regardless. Same concept as sigest in dbarts and xbart. It is the estimate a chisq residual prior's quantile is calibrated against, so it stands beside family = gaussian(sigma = chisq(df, quant)) and has nothing to calibrate beside family = gaussian(sigma = fixed(value)), which fixes the residual scale outright: no estimate is made there, by any rule, the fit reports the square root of value as its sigest, and a number that differs from it is refused. An estimate that equals that square root (to within a few units in the last place) is accepted with a message saying it has no effect, as 0.9-34 ran it; that is an error from dbarts 1.1-0. Given a data object in place of a formula, including a sampler's data, a new fit calibrates from that data's response: the response's scale and this estimate are derived from it, not read from records the sampler wrote, unless sigest states a number; dbartsSpec reads a data object the same way, and a sampler's copy() is the way to the same model again.

k

For numeric yy, k is the number of prior standard deviations E(Y∣x)=f(x)E(Y|x) = f(x) is away from ±0.5\pm 0.5. The response is internally scaled to range from −0.5-0.5 to 0.50.5. For binary yy fit with the default probit link, k is the number of prior standard deviations f(x)f(x) is away from ±3\pm 3, the probit reference scale; family = "logistic" widens this to ±π3\pm \pi \sqrt{3}, three standard deviations of the standard logistic latent variable. The value can be either a fixed number, or a hyperprior of the form chi(df = 1.5, scale = 2); k = Inf holds every tree at zero, so the fit is the offset, plus on a continuous response the center of the range y - offset spans. The spread can instead be named on the family's own scale, leaf.prior = normal(sd = ); see dbartsPriors. The default, NULL, uses the value 2 for continuous responses and the chi(1.5, 2) hyperprior for binary and "nbinom" ones, which centers the sampled k near the field-standard fixed value of 2 (prior median 1.9) while adapting to the data; pass k = 2 for the fixed BART-package default, or chi(1.5, Inf) for the old improper prior. See bartBT's k item, and the ‘Leaf prior parameter k’ details there, for the full calibration argument and its outlier-sensitivity caveat. In a model of several forests it is that of the forest with no basis stating no sd, or the group's where two or more share one total; where every forest with no basis states one it is refused unless it is the default (see ‘Formula Terms’). A written NULL is the argument left out.

power, base

Real numbers setting the tree prior's probability that a node at a given depth splits, base/(1+depth)powerbase / (1 + depth)^{power}, as in bartBT. A tree prior is written as these and split.probs; bart takes no tree.prior, and given one says what to write. Both are honored on every family, including both component fits of family = "hurdle.lognormal". In a model of several forests they are those of the forest with no basis; see ‘Formula Terms’. A written NULL is refused, saying to leave the argument out for its default.

split.probs

Prior probabilities that each predictor is chosen for a splitting rule: NULL (the default) for equal probabilities, a numeric vector, named or one per model-matrix column, num.vars, which stands for the number of predictors (1 / num.vars), or dart() from dbartsPriors, which runs DART (Linero 2018): the probabilities are drawn given the splits, and the variables the trees use are selected. A named vector reads by column or term name, .default giving the rest, and is refused when it leaves a column with no value, a single named value included. A model of several forests, and family = "multinomial", take a uniform vector and refuse any other, or dart(), by name. These are the mean forest's alone: a variance forest takes none.

leaf.prior

The full dbarts leaf prior object, forwarded unevaluated so a bare dbartsPriors vocabulary name inside it (normal, linear, gp) resolves exactly as it does for dbarts: leaf.prior = linear(columns = 1:3) and gp(...) are reachable this way. NULL (the default) instead builds the leaf prior from k. Supplying an object alongside k is an error naming both. It is honored on every family, including both component fits of family = "hurdle.lognormal", except that a leaf prior naming sd is refused there (see family). The residual prior is not on this list: it is a setting of the families that draw a residual scale and rides the family object instead - family = gaussian(sigma = chisq(3, 0.9)), family = gaussian(sigma = fixed(1)); see family below. In a model of several forests it is that of the forest with no basis stating no sd, taken as one forest takes it: see ‘Formula Terms’. Where two or more share one total it is that total, normal(sd = ) its size and k or a chi() prior on k its k, one for the group. forest(sd = ) is one forest's own size, in the response's units, and where every forest with no basis states one a k or sd here is refused, the default restated taken. A written NULL is the argument left out.

monotone

Optional per-predictor monotonicity constraints, passed through to dbarts; see its monotone argument. A monotone specification, or its directions alone at the default prior, "joint": a named vector selects predictors by model-matrix column name, each direction "increasing" or 1, "decreasing" or -1, or 0 for unconstrained - matching is case-sensitive; only numeric and ordered columns are eligible. A constraint forces birth/death-only proposals and a fixed k, 2 unless another number is given. NULL (the default) fits the unconstrained model. The constructor resolves by bare name inside this argument, whatever the caller has attached, and a bare name the caller has bound to a value is that value; see dbartsForests.

interactions

Optional interaction constraints, passed through to dbarts; see its interactions argument and interactions. Built with interactions(max.order = , groups = , forbid = ): cap the distinct predictors per root-to-leaf path, confine interactions to declared groups, and/or forbid named predictors from co-occurring. NULL (the default) fits the unconstrained model. The constructor resolves by bare name inside this argument, whatever the caller has attached, and a bare name the caller has bound to a value is that value; see dbartsForests. In a model of several forests it constrains the forest with no basis; see ‘Formula Terms’.

blocks

Optional block-additive constraint, passed through to dbarts; see its blocks argument and blocks. Built with blocks(groups = , trees.per.group = ): confine each whole tree to one declared group of predictors so the ensemble is exactly a sum of per-group functions. The groups must form a total, disjoint partition of the predictors, validated at fit time. NULL (the default) fits the ordinary model. The constructor resolves by bare name inside this argument, whatever the caller has attached, and a bare name the caller has bound to a value is that value; see dbartsForests. In a model of several forests it constrains the forest with no basis; see ‘Formula Terms’.

variance

Heteroscedastic BART (Pratola et al. 2020): passed through to dbarts. Declares a second forest modeling the residual variance surface s2(x)s^2(x) as a product of scaled-inverse-chi-squared leaves, coupled to the mean forest through the per-observation precision. Either the plain selector naming which predictors drive the variance - a column selector, TRUE for every predictor, a one-sided formula (~ x1 + x2) read exactly as varianceForest() reads its first argument (terms matched to the fit's predictors, the dot and transformed terms taken, *, : and I() terms refused), or NULL (the default), FALSE, an empty selection (character(0), integer(0), logical(0)) or ~ 1 for a homoscedastic fit - or a varianceForest(vars = , n.trees = , base = , power = ) object, which additionally sets the variance forest's own tree count and tree-structure prior (defaulting to 40 trees and the mean forest's power and base, exactly as the plain selector does). Gaussian and "aft" (survival) responses only - the latent families route their own precisions through the channel it divides into; family = student() residuals are refused with it too (see dbarts). The fit gains s.train/s.test (posterior draws of s(x)s(x)), and predict attaches an "s" attribute carrying s(x)s(x) for new data: its draws, or under ci.level its estimate and credible band per row, as the value carries. s(x)s(x) is the residual scale the reporting channels use: extract(type = "loglik"), the type = "ppd" draws, and summary.bart's mean.s row all read it, and extract and predict return it as type = "sigma"; such a fit has no scalar sigma, and carries no sigma or first.sigma (see dbarts). The constructor resolves by bare name inside this argument, whatever the caller has attached, and a bare name the caller has bound to a value is that value; see dbartsForests.

Sampling run.

n.trees

The number of trees in the sum-of-trees formulation. In a model of several forests it is the count of the forest with no basis, split among several such forests that state none; see ‘Formula Terms’. A written NULL is refused, saying to leave the argument out for its default.

n.samples

The number of posterior samples requested; n.samples %/% n.thin draws are actually kept and returned. This is a SWEEP budget in the BayesTree tradition - the same role bartBT's ndpost plays (ndpost / keepevery are what is actually returned). It differs from dbartsControl's (and the lower-level dbarts's) n.samples, which already counts the draws one run() call returns and is NOT divided by thinning: that layer's sampler can be run() repeatedly with a different count each time, so its n.samples is a per-call return count rather than a one-shot total budget.

n.burn

Number of MCMC iterations to be treated as burn in.

n.chains

Integer specifying how many independent tree sets and fits should be calculated. Default 4; bartBT's default is 1, BayesTree's historical single-chain convention.

n.threads

A positive integer giving a total thread budget, distinct from n.chains: chains run in parallel across it, but tree sampling itself uses at most one thread per chain, so a budget above n.chains buys the sampler's own sweep nothing. The surplus still feeds the test-fit pool and predict's own fan-out, and a fit warns once, naming both counts, when an explicit budget exceeds the chain count. Defaults to guessNumCores capped at n.chains, or to one where the cores cannot be counted; a stated NA is refused.

On predict, n.threads is a per-call worker count for the saved-tree replay, defaulting to the fit's own: the replay is partitioned by (chain, posterior draw), each partition writing its own rows and nothing being reduced across workers, so the answer is identical bit for bit at every value and only the time taken changes.

combineChains

Logical; if TRUE, samples are returned collapsed across chains rather than in a chains-by-samples array. Default TRUE, as for bartBT; the number of chains is tracked regardless on the returned object's n.chains component (see ‘Value’). On extract, predict and survivalProbabilities, FALSE keeps that leading chains margin - length 1 on a one-chain fit - rather than dropping it there; see bartBT's combinechains item.

n.cuts

The maximum number of possible values used in decision rules (see useQuantiles, and bartBT's ‘Decision Rules’ details). A single number applies to every column; a vector gives one per column, in their order, or, named as split.probs is, reads by column or term name with .default for the rest, so c(x1 = 10, .default = 50) gives x1 10 and every other column 50. A name that is no column or term, a named vector leaving a column with no value, and an unnamed vector of any other length are refused. A hazard fit's own period column, appended after the predictors, reads a count only by its own name, c(period = 20, .default = 50), and otherwise has 100, so a single number or a vector of one per predictor leaves it at 100; an unnamed vector with one more value than the predictors gives it the last. Fewer rules may be used if a covariate lacks enough unique values. Factor predictors take no rules from it, of either kind: a factor's grid follows its level table.

useQuantiles

When TRUE, determine tree decision rules using estimated quantiles derived from the predictor variables. When FALSE, splits are determined using values equally spaced across the range of a variable, or, for a variable with fewer distinct values than n.cuts, half-way between neighboring values, each chosen in proportion to its gap's width. See bartBT's ‘Decision Rules’ details.

n.thin

Every n.thin draw is kept to be returned to the user. Useful for “thinning” samples against serial correlation; see n.samples above for how the two combine.

seed

Optional integer specifying the desired pRNG seed. NULL (the default) means not given here and defers to a seed already sitting in control, if any; an explicit NA is a missing value, as in set.seed: it reads as NULL for one release, with a once-per-session warning. A set.seed beforehand suffices for reproducibility when nothing ends up seeded; supplying seed instead gives reproducible results without touching R's stream. See ‘Reproducibility’ below.

warm.start

A previous fit whose forests seed the initial state instead of drawing trees from the prior: either a bart object fit with keepSampler = TRUE or a dbartsSampler-class. The donor must share this fit's predictors. DART weights go only between two DART fits and a variance forest only where both have one: a part only one side has is left behind, or starts as a new fit's. A donor of constant leaves seeds linear ones with slopes of zero, a donor of linear leaves seeds constant ones, or linear ones on other covariates, at each leaf's intercept, and Gaussian-process leaves go only to Gaussian-process leaves fit to the same rows. A donor of fewer trees than this fit is taken whole, the rest of the trees starting as single leaves at zero, and a donor of more gives the trees whose fitted values vary most over this fit's rows. Under blocks each block takes the donor's trees it can hold as they stand, so a donor with the same blocks is taken whole, and where not all go in so, the trees that vary most within it. The fit takes all of the earlier fit that this one can hold: a split that is not on this fit's cut points is moved to the nearest one, a tree this fit cannot hold as it stands is cut back at the split that does not fit, and a monotone tree whose leaf values are out of order is cut back where they are. With verbose = TRUE one line after the setup lines says how many trees were taken, how many were moved or cut back, and what of the donor was left behind or started fresh. Only its trees, and its sigma and k where this fit draws them, carry over: the fit runs under its own prior and fixed values, the donor's leaf values, linear slopes, k and sigma go in as stored on the sampler's internal scale and are not converted to this fit's response or its leaf covariates' centers and scales, which are this fit's own (a donor fitted to a response on another scale, or with a leaf covariate centered and scaled otherwise, seeds the same internal numbers, so the seeded fit starts away from the donor's and the first draws move it where this fit's data say), and each chain starts from a different donor sample so multiple chains stay overdispersed. A warm start biases early draws toward the donor, so it shortens burn-in rather than removing it; keep a non-zero n.burn. Multi-forest samplers refuse it: a fit whose forests carry amplitude bases (a forest() term, or a data object built with bases) errors by name, naming its forest count, because a donor install is not tested at more than one forest; n.grow.sweeps is the initialization such a fit can take. See dbartsSampler-class's installTrees method for finer control.

n.grow.sweeps

A non-negative integer; when positive, the initial forest is built by n.grow.sweeps sweeps of XBART-style grow-from-root (He, Yalov and Hahn 2019) instead of a draw from the prior, an init-then-refine workflow that reaches a good fit in far fewer sweeps before the exact sampler takes over. The default 0L draws trees from the prior, exactly as before. Like warm.start, a grow-from-root start biases the early draws toward the grown fit, so it shortens burn-in rather than removing it; keep a non-zero (if smaller) n.burn. The posterior the sampler targets is unchanged - only the starting point moves. Constant-leaf models only, and mutually exclusive with warm.start (both request an initialization). Unlike warm.start it is available on a multi-forest fit, each forest grown against its own residual inside the sweep. See dbartsSampler-class's growFromRoot method.

samplerOnly

Builds the sampler from its arguments and returns it without running it. Useful to use the bart interface in more complicated models. A fit draws its starting trees from the prior before it runs; to run the returned sampler as bart would at the same seed, call $sampleTreesFromPrior() before $run().

Output.

keepTrainingFits

If TRUE the draws of f(x)f(x) for xx corresponding to the rows of the training data are returned.

printEvery

As the MCMC runs, a message is printed every printEvery draws.

printCutoffs

The number of cutoff rules printed to screen before the MCMC is run. Given a single integer, the same value is used for all variables. If 0, nothing is printed.

verbose

Logical; if FALSE suppress printing, including the one-line message family = "auto" prints naming the family it resolves to (a message of class dbartsAutoFamilyMessage).

keepTrees

A fit that keeps its trees stores its sampler's state at the end of the fit, so a fit saved with saveRDS and read back predicts as the original did; a user who runs the kept sampler further calls fit$fit$storeState() again before saving (see bartBT's ‘Saving’ section). Logical; must be TRUE in order to use predict with the result of a fit. NULL, the default, keeps the trees on a hazard fit, whose survival curves need them, and not otherwise; TRUE or FALSE is taken as given, and keepSampler follows the resolved value. Note that for models with a large number of observations or a large number of trees, keeping the trees can be very memory intensive. The kept sampler, fit$fit, is what predict at new data replays and what print reads its settings from (the tree count and n.burn); every other method, and predict with no newdata, reads the draws stored in the fit, and print counts those. Running the kept sampler further, or giving it another control, is not a supported use of the fit: predict at new data then replays the sampler's current trees, which mix the fit's draws with the new ones, while the other methods keep reading the fit's own.

keepCall

Logical; if FALSE, the returned object has call set to NULL, as a base R fit without a call has, so update refuses it; otherwise the call used to instantiate BART.

keepSampler

Logical that can be used to save the underlying dbartsSampler-class object even if keepTrees is false. The methods read it as keepTrees describes: predict at new data and print's settings from the sampler, the rest from the fit's stored draws; running it further is not a supported use of the fit.

Engine.

storage

Passed through to dbartsControl; a bart formal. A character string selecting the precision of the internal running residual; see dbartsControl's storage for the full description. The default "double" reproduces existing draws bitwise; "single" changes the numbers a fit returns - the sampled values shift slightly - in exchange for a bandwidth-bound speedup, and is currently supported only for continuous (gaussian) responses with constant leaves.

updateState

Passed through to dbartsControl. A logical setting the default behavior for many sampler methods with regards to the immediate updating of the cached state of the object; see dbartsControl's updateState.

keepFits

Passed through to dbartsControl. A logical over EVERY per-observation channel (training, test, heteroscedastic variance, per-forest) at once, defaulting to TRUE except that it becomes FALSE automatically whenever callback is supplied and keepFits is not itself named - an explicit keepFits always wins, so keepFits = TRUE together with callback keeps every channel while still firing the hook. keepTrainingFits is the narrower, longstanding switch over the training channel alone and is unaffected by this one; variable counts and the scalar channels (sigma, k, ...) are kilobytes and are always kept. See dbartsControl's keepFits for what FALSE costs the returned object. multinomial, ordinal, nbinom, and hurdle.lognormal require keepFits = TRUE (their packaging reads the training channel) and refuse an automatic or explicit FALSE by name.

callback

NULL (the default, no hook) or a list with two elements, fn and context, each an R external pointer (externalptr): fn the address of a compiled dbarts_draw_callback (inst/include/dbarts/dbarts.h) and context an opaque pointer handed back to it unchanged, or NULL. Only that both are external pointers is checked - the address is dereferenced exactly as handed, on the worker thread that owns the draw's chain, so the callback and its context must already be alive and of the right shape; nothing here can verify either. Registering one is a compiled task (Rcpp or plain C), not an R closure: see vignette("dbarts-as-a-component") for a worked example and the recipe for building the two pointers. Three warnings. A callback that crashes takes the whole R session down with it - no R condition is raised, there is nothing to tryCatch. An interrupt (Ctrl-C) cannot land while a call is running, so a callback that blocks or loops hangs the session. And the automatic keepFits = FALSE this argument triggers means a fit built with only the default settings and a callback returns NO fitted values at all (no yhat.train, no yhat.test, ...) - whatever the callback itself accumulated is the only answer, unless keepFits = TRUE is also given explicitly. On family = "hazard"/"hazard.probit"/"hazard.logistic", the draw struct's numObservations counts the person-period-EXPANDED rows the R layer builds (one per subject per at-risk period), not the original subjects - the row-to-(subject, period) mapping is R-side and is not carried across to the callback. bartBT (the 0.9-34 legacy door) does not take this argument.

control

A dbartsControl object carrying the sampler and engine settings, including the ones bart spells no flat name for: categoricalExhaustiveCap, testFitParallelCutoff, predictParallelCutoff, sparseDensityThreshold, treeShift, and the tree-move mixture proposal.probs. Precedence, one rule: a flat argument named in the call wins over the control's slot of the same name, and a slot the control speaks for - one its own dbartsControl() call named, or one edited afterwards to differ from a fresh control's - wins over this function's default, while a slot it never spoke for leaves that default standing. A control taken from a fitted sampler carries that fit's run settings and nothing else: it sets no tree count, cut count or quantile rule for this fit, and one that differs from what the call takes draws a warning saying it is not used. For example, control = dbartsControl(categoricalExhaustiveCap = 15) raises the grow-from-root exhaustive-enumeration cap while every other engine setting, and every flat argument here, keeps its own default.

...

Present on the bartMultinomial/bartOrdinal/bartNegbin/bartHurdle methods below for S3 generic compatibility, but not silently discarded: a name foreign to the method called is refused by name, and any other unrecognized name warns. On bart itself ... is instead the transition release's retired-spelling channel, as on dbarts: a retired name (resid.prior, sigdf, and sigquant, which ride family, built with gaussian(sigma = chisq(df, quant)) or gaussian(sigma = fixed(value)); proposal.probs, which rides control, built with dbartsControl(proposal.probs = )) reaches a message naming its successor instead of R's own “unused argument” error, and any other name is refused. Removed in dbarts 1.1-0.

object

An object of class bartMultinomial, bartOrdinal, bartNegbin, or bartHurdle, returned by bart under the corresponding family; for sigma and nobs, any fit bart returns, of class bart too.

newdata

Test data for prediction. Obeys the same rules as data/test; a numeric matrix is taken only where every predictor column is numeric, and is refused by name on a fit with a factor column, which takes a data frame. Left out (or NULL), predict returns each type at the training rows from the draws the fit stored, as extract with sample = "train" does, on every family's fit and without saved trees; an offset given then replaces the fit's own at the training rows (a category offset matrix on a multinomial fit). An unnamed matrix is read in the fit's column order, with no message, and a data frame by name, columns beyond the fit's predictors ignored, on a fit made from a matrix as on one made from a formula. A data-frame column for a predictor that was a factor in training must be a factor or character, matched to the training levels by label; a numeric or logical one is refused, naming it, as predict.lm refuses it.

type

The quantity to return; see ‘Value’ below for what each family's generics accept and produce. As on a "bart" fit (bartBT's type item), "response" is a synonym for "ev" and "link" for "bart", on every method here; a value a method does not offer is an error naming the ones it does, and one it names only to refuse is an error naming the reason.

sample

Either "train" or "test". It is extract's own argument, and fitted's too on every family with a test channel - on bartHurdle the test channel is the rows of a test set, and a fit given none refuses sample = "test"; refused by name on predict, whose stored train and test channels are extract's sample instead. Also refused by name on every model- or predictor-level type these families offer - "varcount", "sigma", "k" and "leaf.prior.sd" on all four, "thresholds" on bartOrdinal, "shape" on bartNegbin - none of them per-observation. On a fit that sampled a parameter these types return its draws; on one that held it fixed, one number (see bartBT's ‘Leaf prior parameter k’). "sigma" is 1 on every one of these families but bartHurdle, whose "sigma" is its positive part's, and "k" and "leaf.prior.sd" on a bartHurdle are lists of its zero and positive parts.

vars

Character vector of fields to gather, as summary.bart's own vars; requested fields absent from object are silently dropped. NULL is vars left out, the default fields. summary.bartOrdinal's "thresholds" contributes one draws variable per sampled threshold γ2,…,γK−1\gamma_2, \ldots, \gamma_{K-1}, the ordinal analog of sigma (the pinned γ1=0\gamma_1 = 0 is named under the table, not tabulated); summary.bartNegbin's "shape" contributes the per-draw shape rr, the count analog of sigma. summary.bartHurdle applies vars separately to its $zero and $positive component fits. summary.bartMultinomial has no vars formal at all: it always pools the per-category mean-probability channel (its only scalar convergence instrument), so a supplied vars is refused by name rather than silently ignored; its table is that channel alone, and a line under it names the k the fit held fixed.

x

An object of one of the four own-class families (bartMultinomial, bartOrdinal, bartNegbin, bartHurdle), as returned by bart under the matching family, for print/plot; an object of class summary.bartHurdle, as returned by summary on a bartHurdle fit, for print.summary.bartHurdle.

cols

For plot.bartMultinomial/plot.bartOrdinal: a vector of colors, one per category, tracing each category's training-mean predicted probability (bartOrdinal's threshold panel, when drawn) or each category's own P2 panel point; NULL (the default) chooses colors automatically. For plot.bartNegbin/plot.bartHurdle: two colors, as bartBT's own cols item - the first for a posterior interval's bars, the second for the reference line.

plquants

For plot.bartOrdinal/plot.bartNegbin/plot.bartHurdle/plot.bartMultinomial, as bartBT's own plquants item: the lower and upper quantiles bounding each posterior-interval panel's bars.

ci.level

For fitted/predict on a bartMultinomial, bartOrdinal, or bartNegbin fit, as bartBT's own ci.level item. On a K-margined type ("ev"/"ppd" for the first two), the result keeps the category margin: an (observation ×\times K ×\times 3) array of est/ci.lower/ci.upper rather than a 3-column matrix, since categories are not poolable. On a non-K-margined type ("bart"; any type for bartNegbin) the result is the ordinary 3-column matrix. bartHurdle's ci.level is documented under bartBT directly, since it never carries a K margin. Refused, by name, on residuals (as bartBT's own ci.level item); on bartMultinomial and bartOrdinal also refused, by name, with type = "class" - a class prediction is a label rather than a quantity with a credible band.

Value

Every fit, of every class below, carries family, the family as specified once "auto" has resolved, and family.spec, the same family with its settings, which family(fit) returns (see bartBT's ‘Value’ section). Ask a fit what it is through these, not through which components are present: a run's options decide which draw channels it keeps.

Every fit answers sigma(fit) and nobs(fit), as an lm or glm fit does. sigma is the posterior mean of the residual sd, mean(extract(fit, type = "sigma")): on a hurdle fit the positive part's sd of log⁡y\log y, on an "aft" fit that of the log time, on a "student" fit the scale of its t errors, and 1 on a family with no residual scale (binary, hazard, multinomial, ordinal and "nbinom" fits), as sigma reads a binomial glm. A fit with a variance forest has a residual sd per row, not one, and sigma refuses it; extract(fit, type = "sigma") gives its draws. nobs counts the rows in the likelihood: those subset and na.action kept, less any of weight 0; a hazard fit's are its person-period rows.

Row names: every output indexed by observation carries the rows' names on its observation margin, on every class below. That covers the stored draws (yhat.train, yhat.test, their means, s.train, s.test, forestFits and the latent channels) and what fitted, residuals, extract, predict and survivalProbabilities return. Training rows are named after subset and na.action: a formula fit names them as its model frame does, "1" to "n" when the data has none, as lm does; the x interface takes rownames(x), a data frame's automatic names counting as "1" to "n", and leaves a matrix without row names unnamed. Test rows and newdata take their own row names the same way. A discrete-time hazard fit names its person-period rows by make.unique over the subject names, so a subject s1 at risk in three periods gives s1, s1.1 and s1.2, and survivalProbabilities names subjects. A fit also keeps the names as row.names.train and row.names.test, absent when the rows are unnamed.

Under the default and bartBT-compatible families ("gaussian", "probit", "logistic", "aft", "hazard" and its aliases), bart returns a list of class "bart", documented in full under bartBT's ‘Value’ section - the same yhat.train/sigma/varcount/... components (but no binaryOffset on a binary fit, which only bartBT returns), including forestFits, glue, bases, n.forests, and "forest.labels" and "forest.unit" attributes when the formula carries a forest() term (‘Formula Terms’ above), the second the unit the forests' sds are stated in, sd(y)\mathrm{sd}(y) as the sd argument of forest takes it or the link's error sd: that term route is the only way bart itself reaches the per-forest channel, since it has no forests = formal of its own. A heteroscedastic fit (variance supplied) additionally carries s.train/s.test, posterior draws of the residual scale s(x)s(x) laid out as yhat.train/yhat.test; see the variance argument above. A discrete-time hazard fit (family = "hazard"/"hazard.logistic") additionally carries periods, the ordered period grid the person-period expansion used; survivalProbabilities dispatches its survival-curve branch on it. Under keepFits = FALSE, yhat.train/yhat.train.mean/yhat.test/yhat.test.mean, s.train/s.test, and forestFits/glue/bases, with the "forest.labels" and "forest.unit" attributes, are all ABSENT (not NULL within the list) rather than present-but-empty; plot/extract/fitted/residuals/predict then name keepFits in their error rather than failing on a bare NULL. The model descriptors - family, family.spec, n.forests, and on a family with a residual distribution resid.scale - are set by the model rather than by run options, so they survive keepFits = FALSE and the fit's own SHAPE stays readable even with every per-observation channel dropped.

The remaining families - "multinomial", "ordinal", "nbinom", and "hurdle.lognormal" - return their own list class instead, never "bart", each with its own generics, described below: precisely so a K-category or two-part fit cannot silently flow through a method that assumes the single-forest shape.

bart(family = "multinomial") returns a different list, of class "bartMultinomial". Components: call, family ("multinomial"), levels (the resolved category names, length K: levels(y.train) for a factor response, or colnames(y.train) - falling back to as.character(seq_len(K)) when unnamed - for a count-matrix response), levels.source ("labels", or "index" when levels were synthesized from a count matrix without column names), K, n.chains, n.trees, y (the original response: the factor y.train, or the validated n x K count matrix when a count response was supplied), offset (when trained with one; see bartBT), leaf.prior and fixed (as on a "bart" fit, the K forests sharing one leaf prior, so one list and one k), and yhat.train - the posterior draws of the K softmax probabilities, an array of dimension (n.chains ×\times, when n.chains > 1 and combineChains = FALSE) n.samples ×\times number of training observations ×\times K, with the resolved category levels as the trailing dimension's names; combineChains = TRUE (the default) folds the chain margin into the samples margin as usual. yhat.train already holds PROBABILITIES, not a latent score - there is no "bart"-scale component to convert, unlike the binary families. When test was supplied, yhat.test is the same K softmax probabilities on the held-out rows, dimensioned like yhat.train with the training-observation margin replaced by the test one. varcount is the per-sample per-category split-usage channel: each category forest's per-draw variable counts, dimensioned like yhat.train but with the number of training predictors in place of the number of observations, and colnames(x.train) (when present) named on that margin. fit is present whenever keepTrees is TRUE or keepSampler is set, independent of keepTrees: it is the dbartsSampler whose K-forest engine actually ran (not the temporary sampler it builds along the way), fully mutable and readable on the channels the softmax gives meaning to - $setResponse with the count matrix, $setCategoryOffset, $setPredictor, $setLeafPrior(normal(k = )), and the rest - and refused by name on the ones it does not ($setResponse given a vector, $setOffset, $setSigma, $setForestWeights); fit$storeState() followed by save/load restores a sampler predict.bartMultinomial can replay through. predict still requires keepTrees = TRUE - a kept fit alone carries no saved trees to replay - and errors otherwise.

Generics for a "bartMultinomial" fit: fitted(object) (type = "ev", the default) returns the posterior-mean n ×\times K probability matrix, columns named by the fit's captured levels; fitted(object, type = "class") returns the argmax of that mean matrix as a factor over the original levels - a classification convenience. extract(object, type = "ev", sample = "train") returns the full yhat.train draws, and sample = "test" returns yhat.test (an error if the fit carries no test channel); extract(object, type = "ppd") draws one category per posterior draw from its probability vector, returned as an integer code (1-based, indexing the fit's captured levels) in an array shaped like "ev" minus the K margin; on a fit whose response is a count matrix, its training rows instead draw a vector of category counts with that row's number of trials, rmultinom(1, n_i, p) per draw and row (all zeros at a row with no trial), in an array shaped like "ev", while its test rows, whose trial counts are unknown, draw a one-trial count vector, the unit vector of a category, in the same shape. A row of weight 0, training or test, has NA draws (see the weights item). extract/fitted/predict with type = "bart", and extract/fitted/predict with type = "forest", error naming the reason: the run records only the identified softmax probabilities, and a category's forest is a latent whose level is reproducibly structured yet not identified (in the same sense as BCF's aa), so a raw replay would read as signal - the identified content is the log-ratio, which the logs of the reported probabilities carry. predict(object, newdata) requires object fit with keepTrees = TRUE (error otherwise); it codes newdata to the training columns exactly as predict.bart does and returns a levels-named (n.chains ×\times) n.samples ×\times number of new observations ×\times K probability array, the yhat.test/yhat.train convention; type = "ppd" draws one category per posterior draw the same way extract(object, type = "ppd") does on a factor response, and on a count-matrix fit a one-trial count vector, since the trial count of a new row is unknown; with weights, each draw is instead the count per category over that many new trials, in an array shaped like "ev", at newdata or, without it, at the training rows in place of their trials, a weight of 0 drawing K zero counts (see the weights item); type = "bart" and type = "forest" are named only to be refused, for the non-identification reason above; type = "class" returns the same argmax factor fitted(object, type = "class") does, over the probability draws predict itself replays; paired with ci.level it is refused by name instead - a class prediction is a label rather than a quantity with a credible band. offset supplies the per-category shift at the new rows, required on a fit trained with an offset and reproducing yhat.train when the training offset is passed back at the training rows. residuals(object) returns an n ×\times K matrix, the observed proportion (an indicator for a factor response, y / rowSums(y) for a count-matrix one, 0 at a row with no trial as glm takes a zero-weight row) minus the fitted probability in fitted(object), per category. extract's combineChains (default TRUE) reshapes "ev"/"ppd"/"loglik" to a combined or per-chain layout, exactly as extract.bart's does; refused by name on fitted and residuals, which always summarize the combined draws. fitted/predict's ci.level returns an (observation ×\times K ×\times 3) array of est/ci.lower/ci.upper instead of a 3-column matrix, since a category margin survives alongside the observation one; refused by name on residuals (as bartBT's own ci.level item). extract(object, type = "loglik") is the multinomial log-density of the observed row (its coefficient included, so it reduces to log⁡pi,yi\log p_{i, y_i} for a one-trial row), extract-only, sample = "test" refused by name, shaped like "ev" minus the K margin - loo/WAIC on it is leave-one-row-out, since the likelihood unit is the whole count row. forest/contribution on extract/predict (outside extract(object, type = "trees"), described below), sample on fitted, type on residuals, and vars on summary are all refused by name rather than silently ignored: none is meaningful on this K-widened, non-identified-latent shape. extract(object, type = "trees") forwards to the K-forest sampler's own dbartsSampler getTrees, exactly as it does for a "bart" fit (see ‘Extracting Trees’ in bartBT): unlike "bart"/"forest" above, a category's TREE STRUCTURE is recorded and identified (only its level is not), so forest selects one of the K category forests instead of being refused. plot(object) adds a second panel to the per-category trace: the posterior median and interval of the predicted probability of each observation's OWN observed category against that median (a count response with multi-trial rows instead plots the observed proportion yik/niy_{ik} / n_i against the interval of the drawn pikp_{ik}, one point per row-category cell). plotTree and survivalProbabilities are refused by name (a multinomial fit's trees live on its sampler; it has no hazard channel). extract(object, type = "varcount") returns the per-category split-usage channel described above. summary(object) pools the per-category mean predicted probability - this family's only scalar posterior parameter - into posterior mean/sd, split-Rhat and bulk/tail ESS, named prob[<level>], the multinomial analog of summary.bart's σ\sigma/k summary.

bart(family = "ordinal") likewise returns its own list, of class "bartOrdinal". Components: call, family ("ordinal"), levels (the ordered category names, length K), K, n.chains, n.trees, y (the observed categories as an ordered factor over levels), yhat.train (and yhat.test when test was supplied) - the posterior draws of the K category probabilities, shaped and levels-named exactly as the multinomial arrays above - latent.train (and latent.test) - the corresponding draws of the latent f(x)f(x) on the unit-variance probit scale, shaped like a binary family's yhat.train - thresholds - the posterior draws of the K - 1 finite thresholds (γ1=0,γ2,…)(\gamma_1 = 0, \gamma_2, \ldots), dimensioned draws ×\times (K - 1), the ordinal analog of gaussian's sigma, from which probabilities at any latent value can be reconstructed - k when the leaf scale is drawn, offset (when trained with one; see bartBT), leaf.prior and fixed as on a "bart" fit (see bartBT), and varcount. thresholds.raw (the per-draw thresholds in the internal layout predict consumes) is present only under keepTrees. fit is present whenever keepTrees is TRUE or keepSampler is set, independent of keepTrees: it is the dbartsSampler whose engine actually ran, fully mutable and readable like any sampler dbarts returns, and fit$storeState() followed by save/load restores a sampler predict.bartOrdinal can replay through. summary(object) reports the sampled thresholds alongside whatever mean-function scale vars finds present, naming the pinned first threshold and any parameter held fixed on a line under the table, pooled into posterior mean/sd, split-Rhat and bulk/tail ESS, the ordinal analog of summary.bart's σ\sigma/k/τ\tau summary.

Generics for a "bartOrdinal" fit: fitted(object) returns the posterior-mean n ×\times K probability matrix (columns named by levels); fitted(object, type = "class") the argmax category of that mean as an ordered factor; fitted(object, type = "bart") the posterior-mean latent. extract(object, type = "ev") returns the probability draws, type = "bart" (alias "link") the latent draws, and type = "ppd" draws one category per posterior draw (1-based codes indexing levels). predict(object, newdata) requires keepTrees = TRUE and returns the probability draws at newdata (type = "bart" the replayed latent; type = "ppd" category draws, or with weights the count per category over that many new trials, as for bartMultinomial; type = "class" the argmax ordered factor fitted(object, type = "class") returns, over the replayed draws; paired with ci.level it is refused by name instead, for the same reason bartMultinomial refuses it); when newdata matches the fit-time test it reproduces yhat.test. residuals(object) returns the n ×\times K matrix of observed-indicator minus fitted probability. extract's combineChains (default TRUE) and fitted/predict's ci.level work as for bartMultinomial above, including the (observation ×\times K ×\times 3) interval shape for a K-margined type, the refusal of both on residuals, and the refusal of combineChains on fitted/residuals. extract(object, type = "loglik") is log⁡P(yi∣η,γ)\log P(y_i \mid \eta, \gamma) - exactly the stored category probability at the observed level, since yhat.train already holds the cumulative-probit difference - extract-only, sample = "test" refused by name, shaped like type = "ppd". forest/contribution on extract/predict and sample on fitted are refused by name (this family has a single forest and fitted is always the training rows). plot(object) traces the free thresholds γ2,…,γK−1\gamma_2, \ldots, \gamma_{K-1} (γ1=0\gamma_1 = 0 is pinned and carries no information; at K = 2 there is none, and the plot degrades to one full-device panel) alongside the per-observation latent interval, observations ordered by median η\eta, colored by observed level, with dashed reference lines at the posterior-median thresholds. plotTree and survivalProbabilities are refused by name. extract(object, type = "thresholds") returns the threshold draws, threshold[1] pinned at 0 through threshold[K - 1], and extract(object, type = "varcount") the per-predictor split-usage channel; summary's own default vars is c("thresholds", "sigma", "k", "leaf.prior.sd"), of which a fit keeps the leaf-scale one it named.

bart(family = "nbinom") likewise returns its own list, of class "bartNegbin". Components: call, family ("nbinom"), n.chains, n.trees, y (the observed counts), yhat.train (and yhat.test when test was supplied) - the posterior draws of the mean counts μ=eη\mu = e^{\eta}, shaped like a binary family's yhat.train - latent.train (and latent.test) - the corresponding draws of the log mean η=f(x)+c+o\eta = f(x) + c + o - shape - the per-draw shape rr, the count analog of gaussian's sigma, absent when the shape is held, whose value is in fixed - k when the leaf scale is drawn, as on a "bart" fit, offset (when trained with one; see bartBT), leaf.prior and fixed (its shape, when held fixed, among them), and varcount. shape.raw (the per-draw rr in the internal layout predict consumes) is present only under keepTrees. fit is present whenever keepTrees is TRUE or keepSampler is set, independent of keepTrees: it is the dbartsSampler whose engine actually ran, fully mutable and readable - $getShape() on it answers with the fit's own rr - and fit$storeState() followed by save/load restores a sampler predict.bartNegbin can replay through. summary(object) reports the shape draws, when the shape was sampled, alongside whatever mean-function scale vars finds present (a shape or k held fixed is named on a line under the table), pooled into posterior mean/sd, split-Rhat and bulk/tail ESS, the count analog of summary.bart's σ\sigma/k/τ\tau summary.

Generics for a "bartNegbin" fit: fitted(object) returns the posterior-mean count per observation; fitted(object, type = "bart") the posterior-mean log mean; fitted(object, type = "ppd") a Monte Carlo mean over extract(object, type = "ppd", sample = "train") draws. extract(object, type = "ev") returns the mean-count draws, type = "bart" the log-mean draws, and type = "ppd" draws one count per posterior draw from NB(size=r,mu=μ)\mathrm{NB}(\mathrm{size} = r, \mathrm{mu} = \mu); sample = "test" selects the test channel. predict(object, newdata) requires keepTrees = TRUE and returns the mean-count draws at newdata (type = "bart" the replayed log mean; type = "ppd" count draws, or with weights the sum of that many new counts, a weight of 0 drawing 0), with an optional log-exposure offset; when newdata matches the fit-time test and no offset is given it reproduces yhat.test. residuals(object) returns the observed count minus the posterior-mean count per observation. extract's combineChains and fitted/predict's ci.level (a plain 3-column matrix here - this family has no K margin) work as for bartBT, including combineChains's refusal on fitted/residuals and ci.level's on residuals. extract(object, type = "loglik") is dnbinom(yi,size=rs,mu=μs,i)\mathrm{dnbinom}(y_i, \mathrm{size} = r_s, \mathrm{mu} = \mu_{s,i}), extract-only, sample = "test" refused by name. forest/contribution on extract/predict and sample on fitted are refused by name. plot(object) traces the integer-gridded shape rr (a step plot; there is no burn-in channel to bridge from, since bart drives one n.burn/n.samples sweep for this family; no trace is drawn for a shape held fixed, which print names instead) alongside bartBT's own gaussian observed-vs-fitted panel, applied to the counts. The shape trace shows the kept draws only; the burn-in draws of the shape are not stored. plotTree and survivalProbabilities are refused by name. extract(object, type = "shape") returns the per-draw shape rr, type = "k" and "leaf.prior.sd" the leaf scale as on a "bart" fit, and extract(object, type = "varcount") the per-predictor split-usage channel; summary's own default vars is c("shape", "sigma", "k", "leaf.prior.sd"), of which a fit keeps the leaf-scale one it named.

bart(family = "hurdle.lognormal") returns its own list, of class "bartHurdle", holding both component fits ($zero, a "bart" probit fit of the zero-part indicator; $positive, a "bart" gaussian fit of log⁡y\log y on the positive subset) plus call and family ("hurdle.lognormal"). extract/fitted/predict/residuals/print methods for "bartHurdle" compose the two components: type = "ev" (the default) is the natural-scale posterior mean or draws described under the family argument above, type = "prob" the zero part's own probability of a positive response, type = "link"/"log" the positive part's log-scale linear predictor, and type = "ppd" the bimodal predictive draw. ci.level on fitted/predict works as for bartBT, including its refusal on residuals; combineChains is likewise refused by name on fitted/residuals, and fitted takes sample as the third argument, after type and before ci.level, as on every class with a test channel; sample = "test" reads the rows of the test set. residuals(object) returns the observed response minus fitted(object) on the natural scale. extract(object, type = "loglik") is the density of yiy_i at its own natural scale (a −log⁡yi-\log y_i Jacobian against the components' log-scale channels, so it is comparable to any other model OF y, and differs from a log-y computation by the constant −∑yi>0log⁡yi-\sum_{y_i > 0} \log y_i): log⁡(1−πs,i)\log(1 - \pi_{s,i}) where yi=0y_i = 0, else log⁡πs,i+dnorm(log⁡yi,fs,i,σs,log⁡=TRUE)−log⁡yi\log \pi_{s,i} + \mathrm{dnorm}(\log y_i, f_{s,i}, \sigma_s, \log = \mathrm{TRUE}) - \log y_i, with NO truncation (the lognormal positive part's support is already (0,∞)(0, \infty), unlike a count hurdle's positive part, which would have to be truncated at zero - the two rules must not be conflated); it is NOT the sum of the two components' own "loglik" channels, extract-only, sample = "test" refused by name. π\pi here is P(Y>0∣x)P(Y > 0 \mid x), the complement of the zero probability other implementations report (brms's hu), so the zero branch is log⁡(1−π)\log(1 - \pi) rather than log⁡hu\log \mathrm{hu}; a formula ported from one of those must be inverted. forest/contribution on extract/predict are refused by name (each component is a single forest). plot(object) draws four panels, three when the positive component held sigma fixed: the positive component's sigma trace (left out in that case); the zero part's probability π(x)\pi(x); the positive part on the scale it fit (log⁡y\log y over the y>0y > 0 rows); and the composed natural-scale mean E[y∣x]=πef+σ2/2E[y \mid x] = \pi e^{f + \sigma^2/2} over all n rows, the only panel showing the model this family exists for. plotTree and survivalProbabilities are refused by name, naming object$zero$fit/object$positive$fit as the route to the trees. extract(object, type = "sigma") returns $positive's sigma draws, the only sigma the composition carries; extract(object, type = "k") and type = "varcount" each return a list, named zero/positive, of that component's own draws - each list holds both components, a component's draws where its k is modeled and one number where it is fixed; type = "leaf.prior.sd" is the same list of each component's own spread (see bart's k item). summary(object) reports both components - $zero's and $positive's own summary.bart tables, under their own headers - rather than pooling them into one, since the two component fits share no parameters.

Fits with nothing to split

bart, bartBT, xbart and rbart_vi refuse a fit in which every predictor holds one value on the rows kept and no forest has a basis, naming the columns: a tree splits a predictor between its values, so the fit would be an intercept-only model under a normal prior. Add a predictor that varies, or drop the term. dbarts takes such a sampler, for code that gives a column its values later with $setPredictor, and so does bart(samplerOnly = TRUE). A fit with a basis forest is not refused.

Formula Terms

A model of several forests is written in bart's formula as a sum of forest() terms, each one function of the predictors named inside it, without a separate dbarts forests = list (the two routes are mutually exclusive: a formula with a forest() term given together with forests = is refused by name):

y ~ forest(x1 + x2) + forest(x1 + x2, basis = z)          # numeric z: one coefficient
y ~ forest(x1 + x2) + forest(x1, basis = factor(z))       # factor z: one coefficient per level
y ~ forest(x1 + x2) + forest(x1, basis = a) + forest(x1, basis = b)   # two columns: a forest each

A forest's multiplier is its basis argument. Every argument of a term but the first is the same argument of a forest in dbarts's forests = list and is checked the same way; the first, the forest's predictors, is read against data in a formula and against the fit's predictors in a list (see forest's vars item). A forest() is not crossed with another term: z:forest(x1 + x2) and z * forest(x1 + x2) are refused, the message giving the term to write, forest(x1 + x2, basis = z).

The forest with no basis is the forest with no multiplier, and takes bart's own leaf prior and k as a single forest does, whatever stands beside it: held at 1, it is the forest bart would fit alone, unless it states sd or amplitude = normal() or student(). It may be left as plain terms, y ~ x1 + x2 + forest(x1 + x2, basis = z), which is the same model as the first line above, draw for draw; and written alone, y ~ forest(x1 + x2) is the single-forest fit y ~ x1 + x2, in every family that takes a formula. Plain predictor terms beside a forest() with no basis are refused, being two readings, one forest or two; write each as a forest(). It is the model's first forest wherever it is written, and bart's own n.trees, power, base, interactions and blocks are its: n.trees, power, base, interactions or blocks stated both on that term and as bart's argument is refused as one thing given twice, a default's own value included. Several forest() terms with no basis, y ~ forest(x1) + forest(x2) + forest(x3), are the first forests, in the order written, and share one prior total, bart's own leaf prior, each an equal part (see forest's Details): the model is bart's one forest with its trees in blocks. They split n.trees as blocks() does, 38 and 37 of 75, a term stating n.trees keeping its own outside the split; bart's n.trees, power and base reach each term that states none and are refused only where every one states its own, and its interactions and blocks are refused, stated on a term instead. The other forests keep the order they are written in, and each has 50 trees under base = 0.25, power = 3 unless it states its own, whichever is written first. In a formula whose forests all have a basis those arguments of bart have no forest to belong to: each one that is stated is refused by name, its default's own value included, as are leaf.prior, k and a control that names n.trees. A leaf.prior or k written as NULL is named, and refused as any other is. State a count and a tree prior on a forest, as forest(x1, basis = z, n.trees = 100, power = 3).

A forest's first argument is the predictors it splits on, written as the right-hand side of a model formula of its own: names joined by +, calls such as log(x1) and factor(g), . for every column of data but the response, and - to remove a term. The fit's predictors are the terms of all of its forests, each once and those of the forest with no basis first, and each forest splits on the columns of its own terms: in y ~ x1 + x2 + forest(x3, basis = z) the fit has the predictors x1, x2 and x3, the first forest splits on x1 and x2 and the second on x3. A forest with no first argument, forest(basis = z), splits on every predictor of the fit. A term that gives several columns - a factor under factors = "indicators", poly(x1, 2) - is all of them. Only the first argument may be given without its name; every other argument is given by name. A forest's basis is read as code, like its predictors (below), and the rest are evaluated where the formula was written, exactly as they are for dbarts's own forests =. Predictors may also be named, as forest(c("x1", "x2")), each name of a column of data being the term the name written out is. An offset() and an intercept term (1, 0 or - 1) are the fit's and are written beside the forests, wherever among them, not inside one. A removal written beside the forests takes its term from the forest with no basis and from no forest that names predictors of its own: the forest with no basis has the terms of the formula with its forest() replaced by what is inside it and every forest with a basis left out, so y ~ forest(.) - x3 + forest(x3, basis = z) and y ~ . - x3 + forest(x3, basis = z) are one model; a removal that leaves that forest no predictor is refused, and one of a term it does not have is passed by, as R passes it by in a plain formula (see forest's vars item).

A forest's basis is what the forest is multiplied by, written as the right-hand side of a model formula without the tilde and meaning what it means in lm, and is one numeric column or two levels: arithmetic is written inside I(), so I(a + b) is one column, the sum; factor(z), a character column and a logical column of two levels give one column for each level; scale(w) and poly(w, 1) are terms as in lm. Several columns, a + b or poly(w, 2), and three or more levels are refused, with the form to write: a forest for each column, or for each level but the first. Its names are found in data and then where the formula was written. It has a value for every row of data and is cut by subset and the na.action with the predictors, scale() taking its center from every row as in lm. The same basis given through dbarts's forests = is the same columns on the same rows. forest's basis item is the full account: what is refused, how the columns are named, and where a name is found in each of the two ways of writing a forest.

A handful of shapes are refused outright rather than silently misinterpreted, each error naming the offending expression: a forest() crossed with another term by : or *; a forest() anywhere other than a top-level additive term (inside I(), a removal, or the formula's left-hand side); a second unnamed argument, a tilde, a position, an offset() or an intercept term in a forest's first argument; in a basis, * between terms, a term multiplied or divided by a number, cbind() and a factor beside other terms, each with what to write in its place; a forest with a basis and no forest beside it; a formula that names no predictors; test given together with a model of several forests (an amplitude-coupled fit has no per-observation test replay); and a model of several forests in a family the multiplier model does not support ("aft", "ordinal", "nbinom", "multinomial", and "hurdle.lognormal" - gaussian, probit, logistic and the hazard families are the only families a forest with a basis can join, a hazard fit's basis having one value per subject). xbart, bartBT, rbart_vi, pdbart, pd2bart and dbartsData take no forest() term and say so. See ‘Value’ below, and extract's type = "forest", for reading the resulting per-forest fits back out.

predict builds a basis again at the new rows as predict does for lm: a call to scale(), poly(), ns() or bs() is centered, scaled or spanned by what it computed on the fitted rows, which are every row of data whatever subset keeps. Arithmetic inside I(), such as I(w - mean(w)), is evaluated on the rows given to predict, as lm evaluates it, and is not refused; see SafePrediction. So forest(x1 + x2, basis = scale(w)) standardizes a multiplier by the fitted rows' mean and sd. A factor level the fit did not have is refused at predict.

Reproducibility

Every chain runs its own pseudo-random generator. A seeded fit never draws from R's stream, though it may still create .Random.seed in a session that has none yet.

set.seed versus seed. Leave seed at its default (NULL) and call set.seed beforehand: each chain's generator is then seeded from R's stream when the sampler is created, one uniform draw per chain in chain order, and running the sampler afterward never advances the stream further. Passing seed instead drives the chain seeds from a separate, dedicated generator and leaves R's stream untouched altogether. A single number named in the call always wins over a seed already sitting in control; NULL means not given here and defers to control's own seed instead, and an explicit NA reads as NULL for one release, with a once-per-session warning; neither discards a control seed. A family = "hurdle.lognormal" fit derives its two component seeds from the one seed in force (the call's, or control's); without one, the two components draw their own chain seeds from R's stream in turn. Do not rely on bart(seed = S) and set.seed(S); bart() giving the same draws. They currently agree under R's default generator, but this is not guaranteed; only seed gives the same draws under any RNGkind.

Warning classes. Only the warnings a caller has a reason to catch or mute apart from the rest carry a class, and every such class inherits dbartsWarning: deprecations (dbartsDeprecatedWarning, which also inherits base R's deprecatedWarning; see dbarts-deprecated), the slow-count warning of a monotone fit (dbartsSlowCountWarning; see monotone), warnings that a supplied input was replaced by another (dbartsFallbackWarning; dbartsGPFallbackWarning for Gaussian-process leaves, see dbartsPriors), the warning that the rows in the likelihood leave nothing to read the response's scale from, so every row is used (dbartsScaleFallbackWarning; see the weights item), and the warning that a hazard fit's projected memory exceeds the machine's (dbartsMemoryWarning; see dbartsFamilies). Every other warning is an ordinary one, matched by its text.

Chains and n.threads. Results never depend on the thread count: a fit, its predict, and samplePriorPredictive all give the same draws whatever n.threads is asked for. A given chain's draws also do not depend on how many other chains ran alongside it - chain 1 of a 1-chain seeded run reproduces chain 1 of a 4-chain run at the same seed, and likewise for any other chain index. Adding a test set, keepTrees, and verbose do not change the draws either; storage = "single", dbartsControl's treeShift, and any change to the model or the data do.

Simulated outcomes. A type = "ppd" draw on predict, extract, or fitted, and samplePriorPredictive's own type = "ppd", adds observation noise drawn from R's stream rather than from the fit's chain generators - even on a fit made with seed. Call set.seed right before such a call to reproduce it; seed does not cover this noise. samplePriorPredictive(type = "ev") only touches R's stream when its control is unseeded (building the private sampler it draws from); with a seeded control it rebuilds the same sampler every time and so returns the same draws on every call - vary the seed, or leave the control unseeded, for different ones.

Continuing, copying, and restoring a sampler. These apply to an embedded dbarts sampler kept with keepSampler or samplerOnly.

  • Calling run() more than once continues its chains' streams exactly: run(50, 20) followed by run(0, 20) matches run(50, 40) bitwise.

  • storeState() (what save needs) and setState() (what restores it, including after load) continue those same streams too: the draws typically agree to the last few digits, not bitwise, since restoring rebuilds the fitted values by re-summing the trees.

  • copy(), deep or shallow, installs the original's current chain, or, where its engine is gone, as after a reload, the state storeState() last captured, so the copy continues the same streams as the original rather than starting an independent chain - again typically to the last few digits, not bitwise; create a new sampler with a different seed for an independent one. A copy of a sampler whose engine is gone and that has no stored state is refused, as its other calls are.

  • An unseeded sampler draws fresh chain seeds from R's stream every time its underlying engine is (re-)created - at copy(), and at the first use after a reload, including a first setState() call - exactly as building a new unseeded sampler would. A seeded sampler never touches R's stream this way.

  • A bart fit made with keepTrees = TRUE does not store its sampler's state automatically: call fit$fit$storeState() before saving so a reload can predict and keep running.

xbart. An xbart call derives every seed it uses - one split seed per replication, one seed per sampler its units create (one per (replication, fold) unit at each distinct tree count) - with sample.int after set.seed(seed), in one pass, in its own process, restoring R's stream afterward; without a seed, set.seed beforehand reproduces the same run. That derivation draws under the CALLER's own RNGkind, so a given seed draws different values, and so gives different results, under a different kind - what stays fixed for a given seed and RNGkind is n.threads. Each unit's sampler takes its seed through control's seed slot exactly as bart's own seed does, driving a dedicated generator that never reads R's stream, so no worker ever reads its own RNGkind() to fit a unit and results are identical at any n.threads. A supplied loss function that draws random numbers draws on the worker running it, from that process's own default generator; at n.threads greater than 1 this makes the run not reproducible, whatever seed xbart itself is given.

What moves .Random.seed. Unseeded, creating a sampler (n.chains uniforms per sampler; a family = "hurdle.lognormal" fit creates two), xbart, and copy() or the first use after a reload of an unseeded sampler, advance R's stream; the simulated-outcome draws above and dbartsDrawLatents always do. Everything else a sampler does after creation draws only from its chains' own generators and leaves R's stream alone.

Across machines and versions. A given seed reproduces the same draws bitwise only on one machine, with one build of the package, on whatever processor features it uses. It is not promised across different machines, operating systems, or compilers: the math library and the compiler's floating-point code can differ in the last bit. Expect the same posterior elsewhere, not the same numbers. It is likewise not promised across dbarts versions - a version that changes the sampler moves the draws - nor against the 0.9-x series, whose engine and RNG were both different.

Author(s)

Hugh Chipman: [email protected], Robert McCulloch: [email protected], Vincent Dorie: [email protected].

References

Chipman, H., George, E., and McCulloch, R. (2010) BART: Bayesian additive regression trees. The Annals of Applied Statistics, 4(1), 266–298. doi:10.1214/09-AOAS285.

He, J., Yalov, S., and Hahn, P.R. (2019) XBART: accelerated Bayesian additive regression trees. Proceedings of the 22nd International Conference on Artificial Intelligence and Statistics (AISTATS), PMLR 89, 1130–1138.

Linero, A.R. (2018) Bayesian regression trees for high-dimensional prediction and variable selection. Journal of the American Statistical Association, 113(522), 626–636.

Pratola, M.T., Chipman, H.A., George, E.I., and McCulloch, R.E. (2020) Heteroscedastic BART via multiplicative regression trees. Journal of Computational and Graphical Statistics, 29(2), 405–417.

See Also

bartBT for the BayesTree-compatible interface and the shared "bart"-class Value/Details (Decision Rules, leaf k, Generics, Saving, Extracting Trees); this page's own ‘Reproducibility’ section above covers bartBT too.

dbarts for the mutable sampler bart builds on, forest for the constructor a forest() formula term calls, and xbart for the other formula-first entry point.

Examples

## binary response with a logistic link
set.seed(0)
n <- 60L
x.bin <- matrix(runif(n * 2), n, 2)
f.bin <- 3 * x.bin[,1] - 1.5
y.bin <- rbinom(n, 1L, plogis(f.bin))
fit.logit <- bart(y.bin ~ x.bin, family = "logistic",
                   n.samples = 20L, n.burn = 20L, n.chains = 1L,
                   n.trees = 20L, n.threads = 1L)

## a shallower tree prior, and DART variable selection
fit.shallow <- bart(y.bin ~ x.bin, power = 3, base = 0.5,
                    n.samples = 20L, n.burn = 20L, n.chains = 1L,
                    n.trees = 20L, n.threads = 1L)
fit.dart <- bart(y.bin ~ x.bin, split.probs = dart(),
                 n.samples = 20L, n.burn = 20L, n.chains = 1L,
                 n.trees = 20L, n.threads = 1L)

## forest() formula terms: a prognostic forest, and a second forest whose
## amplitude is modulated by a treatment of two levels, factor(z) - the
## Bayesian causal forest shape, written in the formula rather than through
## dbarts()'s forests =
set.seed(1)
n <- 60L
x1 <- runif(n); x2 <- runif(n)
z  <- rbinom(n, 1L, 0.5)
y  <- x1 + z * (1 + x2) + rnorm(n, 0, 0.2)
fit.bcf <- bart(y ~ forest(x1 + x2) + forest(x1 + x2, basis = factor(z)),
                 n.samples = 20L, n.burn = 20L, n.chains = 1L,
                 n.trees = 10L, n.threads = 1L)
fit.bcf$n.forests
modulatingFit <- dbarts::extract(fit.bcf, type = "forest", forest = 2L)

Bayesian Additive Regression Trees

Description

BART is a Bayesian “sum-of-trees” model in which each tree is constrained by a prior to be a weak learner.

  • For numeric response y=f(x)+ϵy = f(x) + \epsilon, where ϵ∼N(0,σ2)\epsilon \sim N(0, \sigma^2).

  • For binary response yy, P(Y=1∣x)=Φ(f(x))P(Y = 1 \mid x) = \Phi(f(x)), where Φ\Phi denotes the standard normal cdf (probit link).

  • bartBT is the BayesTree-compatible surface: 0.9-34's argument list exactly, no new features, and no family argument at all - every fit is the default gaussian/probit pair above. bart reaches every other response family - logistic, accelerated failure time, discrete-time survival hazard, K-category multinomial, ordered categorical, negative-binomial counts, and semicontinuous two-part responses - plus its own formula-term multi-forest interface.

Usage

bartBT(
    x.train, y.train, x.test = matrix(0.0, 0, 0),
    sigest = NA, sigdf = 3, sigquant = 0.90,
    k = 2.0,
    power = 2.0, base = 0.95, splitprobs = 1 / numvars,
    binaryOffset = 0.0, weights = NULL,
    ntree = 200,
    ndpost = 1000, nskip = 100,
    printevery = 100, keepevery = 1, keeptrainfits = TRUE,
    usequants = FALSE, numcut = 100, printcutoffs = 0,
    verbose = TRUE, nchain = 1, nthread = 1, combinechains = TRUE,
    keeptrees = FALSE, keepcall = TRUE, sampleronly = FALSE,
    seed = NULL,
    proposalprobs = NULL,
    keepsampler = keeptrees)

## S3 method for class 'bart'
plot(
    x,
    plquants = c(0.05, 0.95), cols = c('blue', 'black'),
    ...)

## S3 method for class 'bart'
predict(
    object, newdata,
    type = c("ev", "ppd", "bart", "forest", "sigma"),
    offset = NULL, weights = NULL,
    combineChains = TRUE,
    ci.level = NULL,
    forest = NULL,
    bases = NULL,
    na.action = dbarts::na.keepPredictors,
    n.threads,
    ...)

## S3 method for class 'bart'
print(x, ...)

extract(object, ...)
## S3 method for class 'bart'
extract(
    object,
    type = c("ev", "ppd", "bart", "loglik", "trees", "forest",
             "sigma", "k", "leaf.prior.sd", "varcount"),
    sample = c("train", "test"),
    combineChains = TRUE,
    forest = NULL,
    contribution = FALSE, ...)

## S3 method for class 'bart'
fitted(
    object,
    type = c("ev", "ppd", "bart", "forest"),
    sample = c("train", "test"),
    ci.level = NULL,
    ...)

## S3 method for class 'bart'
residuals(object, type = "ev", ...)

## S3 method for class 'bart'
family(object, ...)

Arguments

x.train

Explanatory variables for training (in sample) data. May be a matrix or a data frame, with rows corresponding to observations and columns to variables. If a variable is a factor in a data frame, it is replaced with dummies. Note that qq dummies are created if q>2q > 2 and one dummy is created if q=2q = 2, where qq is the number of levels of the factor. A sparse Matrix::dgCMatrix of ordinal predictors is also accepted, as is a data frame mixing ordinary columns with Matrix::sparseVector or dgCMatrix columns; see dbarts.

y.train

Dependent variable for training (in sample) data. If y.train is numeric a continuous response model is fit (normal errors). If y.train is a two-level factor (or logical, or two-level character) or has only values 0 and 1, then a binary response model with a probit link is fit. A factor with three or more levels is an error, whose message names both remedies: bart(x, y, family = "multinomial") for a multinomial fit, or as.integer(y) - 1L to keep the numbers dbarts 0.9-x fit from the level codes.

x.test

Explanatory variables for test (out of sample) data. Should have same column structure as x.train. bartBT will generate draws of f(x)f(x) for each xx which is a row of x.test.

sigest

For continuous response models, an estimate of the residual standard deviation (residual standard error), σ\sigma, used to calibrate an inverse-chi-squared prior on the error variance. A positive number, or one of "auto", "dense" and "sparse", naming how one is made: each gives the residual standard deviation of the linear regression of the response on the predictors, factors entering as indicator columns whatever the trees are given, and, where that regression leaves no residual degrees of freedom, the standard deviation of the response over the observations of positive weight, weighted as the regression is (summary(lm(y ~ 1, weights = weights))$sigma, sd(y) at unit weights), which a line under verbose and one in the fit's summary say, with no warning. (Where rows are out and the observations of positive weight hold fewer than two distinct values of the response, the regression is made on every row instead, under the warning of class dbartsScaleFallbackWarning.) "auto" is lm's own routine ("dense") for a matrix or a data frame and an exact sparse one ("sparse") where the caller supplied a sparse-stored column. NA (the default) is "auto"; the lines under verbose are printed with the rest of this function's output. dbarts says what the two routines cost, where they differ, and what to pass in place of an expensive estimate, which cannot be interrupted once begun. See sigquant for more information. Not applicable when yy is binary. Same concept as sigest in dbarts and xbart.

sigdf

Degrees of freedom for error variance prior. Not applicable when yy is binary. Default 3, Chipman, George, and McCulloch's calibration (see References); an aggressive choice rather than a derived one.

sigquant

The quantile of the error variance prior that the rough estimate (sigest) is placed at. The closer the quantile is to 1, the more aggressive the fit will be as you are putting more prior weight on error standard deviations (σ\sigma) less than the rough estimate. Not applicable when yy is binary. Default 0.90, from the same source as sigdf.

k

For numeric yy, k is the number of prior standard deviations E(Y∣x)=f(x)E(Y|x) = f(x) is away from ±0.5\pm 0.5. The response (y.train) is internally scaled to range from −0.5-0.5 to 0.50.5. For binary yy fit with the default probit link, k is the number of prior standard deviations f(x)f(x) is away from ±3\pm 3, the probit reference scale; family = "logistic" widens this to ±π3\pm \pi \sqrt{3}, which is three standard deviations of the standard logistic latent variable (π/3\pi / \sqrt{3} each), the same three-sd span probit's ±3\pm 3 covers. In both cases, the bigger kk is, the more conservative the fitting will be. The value can be either a fixed number, or a hyperprior of the form chi(df = 1.5, scale = 2). bartBT's own default is the fixed value 2; see bart's k item for its NULL default, a chi(1.5, 2) hyperprior on binary responses. The default of 2 for continuous responses follows Chipman, George, and McCulloch's argument (see References) that with leaf prior standard deviation σμ=0.5/(km)\sigma_\mu = 0.5 / (k \sqrt{m}) for mm trees, kk prior standard deviations of f(x)f(x) span the whole coded response range regardless of mm – so k=2k = 2 places that range at roughly a 95% prior interval. The range scaling itself is an outlier-sensitive convention shared with BayesTree/bartMachine: extreme yy values compress the effective prior on everything else, for which the published workaround is to log-transform or winsorize such values before fitting, or to let k adapt via the chi hyperprior. A written NULL is refused, saying to leave the argument out for its default.

power

Power parameter for tree prior. Default 2, Chipman, George, and McCulloch's empirical recommendation (see References) for the split-probability decay base(1+depth)−powerbase (1 + depth)^{-power}, not derived from a formula. A written NULL is refused, saying to leave the argument out for its default.

base

Base parameter for tree prior. Default 0.95, from the same source as power. A written NULL is refused, saying to leave the argument out for its default.

splitprobs

Prior and transition probabilities of variables used to generate splits. Can be missing/empty/NULL for equiprobability, a numeric vector of length equal to the number variables, or a named numeric vector with only a subset of the variables specified and a .default named value. Values given for factor variables are replicated for each resulting column in the generated model matrix. The symbol numvars is rebound before execution to the number of columns in the model matrix.

binaryOffset

Used for binary yy. When present, the model is P(Y=1∣x)=Φ(f(x)+binaryOffset)P(Y = 1 \mid x) = \Phi(f(x) + \mathrm{binaryOffset}), allowing fits with probabilities shrunk towards values other than 0.50.5. Φ\Phi is the link for the default probit family; a family = "logistic" fit uses plogis instead, as noted in the value section below.

weights

An optional vector of weights to be used in the fitting process. For a gaussian response, BART fits a model with observations y∣x∼N(f(x),σ2/w)y \mid x \sim N(f(x), \sigma^2 / w), where f(x)f(x) is the unknown function. A probit fit (bartBT, or bart with the default binary family) does not support weights, except that weights identically 1 are treated as absent, and weights that are all 0 and 1 name the rows in the data set, a 0 row leaving the likelihood but keeping its leaf occupancy, its latent and its fitted value (the same holds for family = "ordinal"); a family = "logistic" fit treats them as observation counts and requires non-negative whole numbers no larger than 10610^6, as a sweep's time grows with the total count, a count of 0 leaving the row out of the likelihood. A training row's "ppd" draw is one observation like the row, one 0/1 draw on a binary fit whatever its weight; predict's weights on a binary fit are trial counts, drawing Binomial(w,p)\mathrm{Binomial}(w, p) successes with pp the fitted probability, a 0 drawing none (see bart's weights item). A row at weight 0 has NA "ppd" draws on every family and in every route: a training row (extract, fitted(type = "ppd")), a row of the test sample whose test-frame weight is 0, and, on a gaussian or Student-t fit, a row given weights of 0 to predict; an aft fit takes no case weights at fit time, so only predict(weights = ) reaches a weight of 0 on it, with the same result. A weight of 0 holds a row out of the fit, and on a gaussian fit gives it no noise scale, σ/w\sigma / \sqrt{w}, as simulate gives NaN at a weight-0 row of an lm fit; no warning is raised, and every other row's draw is as it would be without the row. To draw such a row as a new observation, state its weight: predict(fit, type = "ppd", weights = 1).

ntree

The number of trees in the sum-of-trees formulation. A data object holding the bases of a sampler of several forests fits one forest here, as dbarts does given no forests. Like every count on this page (nskip, ndpost, numcut, keepevery, printevery, nthread, nchain, printcutoffs), a fractional value is refused, naming the argument, rather than silently truncated; see dbartsControl for the shared whole-number rule. A written NULL is refused, saying to leave the argument out for its default.

ndpost

The number of posterior draws after burn in, ndpost / keepevery will actually be returned.

nskip

Number of MCMC iterations to be treated as burn in.

printevery

As the MCMC runs, a message is printed every printevery draws.

keepevery

Every keepevery draw is kept to be returned to the user. Useful for “thinning” samples.

keeptrainfits

If TRUE the draws of f(x)f(x) for xx corresponding to the rows of x.train are returned.

usequants

When TRUE, determine tree decision rules using estimated quantiles derived from the x.train variables. When FALSE, splits are determined using values equally spaced across the range of a variable, or, for a variable with fewer distinct values than numcut, half-way between neighboring values. See details for more information.

numcut

The maximum number of possible values used in decision rules (see usequants, details). A single number applies to every column; otherwise a vector of length equal to ncol(x.train), or named as bart's n.cuts reads. Fewer rules may be used if a covariate lacks enough unique values.

printcutoffs

The number of cutoff rules to printed to screen before the MCMC is run. Given a single integer, the same value will be used for all variables. If 0, nothing is printed.

verbose

Logical; if FALSE suppress printing.

nchain

Integer specifying how many independent tree sets and fits should be calculated. Default 1 for bartBT, BayesTree's historical single-chain convention; bart's default is 4.

nthread, n.threads

A positive integer giving a total thread budget, distinct from nchain: chains run in parallel across it, but tree sampling itself uses at most one thread per chain, so a budget above nchain buys the sampler's own sweep nothing. The surplus still feeds the test-fit pool and predict's own fan-out, and a fit warns once, naming both counts, when an explicit budget exceeds the chain count. bartBT's default is 1.

On predict, n.threads is a per-call worker count for the saved-tree replay, defaulting to the fit's own: the replay is partitioned by (chain, posterior draw), each partition writing its own rows and nothing being reduced across workers, so the answer is identical bit for bit at every value and only the time taken changes. It is the last positional argument of every predict method, so a caller that passes arguments by position is unaffected by its presence. A value that is not a single positive number is an error rather than a silent fallback.

combinechains, combineChains

Logical; if TRUE, samples from every chain are collapsed into a single matrix/vector of nchain ×\times ndpost rows (see ‘Value’ for the row order); if FALSE, they are kept in arrays of dimensions equal to nchain ×\times ndpost ×\times number of observations. Default TRUE across bartBT and bart; the number of chains is tracked regardless on the returned object's n.chains component (see ‘Value’). On extract, predict and survivalProbabilities, FALSE keeps that leading nchain margin - length 1 on a one-chain fit - rather than dropping it there; a scalar type (sigma, k, a component's shape) is then a 1 x samples matrix instead of a plain vector. A fit's own STORED combinechains = FALSE fields keep 0.9-x's one-chain collapse instead, so $yhat.train and its siblings never gain that margin on their own.

keeptrees

Logical; must be TRUE in order to use predict with the result of a bart fit. Note that for models with a large number of observations or a large number of trees, keeping the trees can be very memory intensive. The methods read the kept sampler as bart's keepTrees item describes; running it further is not a supported use of the fit.

keepcall

Logical; if FALSE, returned object will have call set to NULL, otherwise the call used to instantiate BART.

seed

Optional integer specifying the desired pRNG seed. NULL (the default) leaves the fit unseeded, and an explicit NA is a missing value, as in set.seed: it reads as NULL for one release, with a once-per-session warning; a set.seed beforehand then suffices for reproducibility. Supplying seed instead gives reproducible results without touching R's stream. See the Reproducibility section of bart.

proposalprobs

Named numeric vector or NULL, optionally specifying the proposal rules and their probabilities. Elements should be "birth_death", "swap", "change", "perturb" and "rule_gibbs" to control tree structure proposals, and "birth" to give the relative frequency of birth/death in the "birth_death" step. NULL (the default), or a vector naming none of "birth_death", "swap" and "change", takes BayesTree's mixture for those three, c(birth_death = 0.5, swap = 0.1, change = 0.4), as 0.9-x did (birth defaults to 0.5 either way); any other vector is completed as dbartsControl completes one. bart's default differs: c(birth_death = 0.6, swap = 0, change = 0.4, perturb = 0, rule_gibbs = 0, birth = 0.5). All five structural probabilities zero is the frozen mixture: no structural proposal is made, the tree structures stand where they are, and only the leaf values, sigma and the family's latents keep being drawn, which is how a fitted forest is re-sampled as a fixed basis. Under dbartsControl's default treeShift = "auto" a frozen forest additionally takes the level-shifting Gibbs step each iteration, the leaf values then being the only thing left to move. bartBT has no treeShift formal of its own and always runs at this default; bart and a dbarts sampler's control object can set it to "always" or "never" instead, which changes the sampled values without changing the posterior. A "swap" element exchanges a parent's split rule with a child's; bart ships it at zero because at forests of 75 trees and more dropping it changed accuracy, coverage and mixing little in simulation (see NEWS), and bartBT keeps it at 0.1 to match BayesTree. With n.trees = 1 it is the only move that rotates a rule up the tree. A "perturb" element displaces one node's split point by a single cut position while keeping its variable and the tree's shape; it defaults to zero, and only ordinal (numeric) columns can be perturbed. A "rule_gibbs" element replaces one nog node's rule - a node whose two children are both leaves - with a draw from that rule's own full conditional over the available ordinal variables and their admissible cuts, so its acceptance is one; it defaults to zero, it acts only where the node's own rule is ordinal, and it is inert on an all-categorical design.

keepsampler

Logical that can be used to save the underlying dbartsSampler-class object even if keeptrees is false.

object

An object of class bart, returned from either the function bartBT or bart.

newdata

Test data for prediction. Obeys all the same rules as x.train, except that on a fit with a factor column a numeric matrix is refused by name, and a data frame is given. An unnamed matrix is read in the fit's column order, with no message. Left out (or NULL), predict returns each type at the training rows from the draws the fit stored, as extract with sample = "train" does, and needs no saved trees; an offset given then replaces the fit's own at the training rows, one value or one per training row; weights replace the fit's own weights for the training rows' "ppd" draws, one value or one per training row, acting as they do at newdata for each family (see type); and bases replace the fit's own bases there (see bases). The offset and the weights are checked against the number of training rows, one value or one per row, and weights, here and at newdata, are a vector or a one-column matrix, a matrix of several columns, a data frame or a list being refused. A missing value in a per-row offset or weights is answered by na.action exactly as at newdata: the default and na.fail refuse it, na.pass returns that row with NA draws, na.omit drops the row from the result and na.exclude pads it back as NA; a single missing value is always refused. The weights' values are looked at, as at newdata, by a "ppd" draw alone, which refuses those its family cannot take, and any other type takes whatever they hold. The bases are checked as at newdata. None needs saved trees, and a fit kept without its training draws is refused by name.

offset

For predict: an optional offset for newdata, applied the same way dbarts's offset.test is at fit time. It shifts the PREDICTED rows, not the training ones - a different channel from offset.test, which is why it carries its own name rather than that one's. NULL (the default, when missing) takes the fit's own offset: its binaryOffset, and the offset() terms and offset argument of a formula fit evaluated on newdata, a plain vector for the training rows applying only to a newdata of as many rows. A given offset is added to a binaryOffset. Refused, by name, with type = "forest": an offset shifts the recombination of the forests, never any one forest's own total, so it belongs to the arithmetic under ‘Value’ rather than to what comes back. On an amplitude-coupled fit's combined arms (type = "ev", "ppd", "bart") it is that recombination, and enters the sum of trees before the family's link, exactly as it does for a single forest.

sampleronly

Builds the sampler from its arguments and returns it without running it. Useful to use the bartBT interface in more complicated models.

x

Object of class bart, returned by function bartBT, which contains the information to be plotted.

plquants

In the plots, beliefs about f(x)f(x) are indicated by plotting the posterior median and a lower and upper quantile. plquants is a double vector of length two giving the lower and upper quantiles.

cols

Vector of two colors. First color is used to plot the median of f(x)f(x) and the second color is used to plot the lower and upper quantiles.

type

The quantity to be returned by generic functions. Options are "ev" - samples from the posterior of the individual level expected value, "bart" - the sum of trees component; same as "ev" for linear models but on the latent scale (probit or logistic, matching the fit's family) for binary ones, "ppd" - samples from the posterior predictive distribution, "loglik" - for extract only, the log-likelihood of each training observation at each posterior draw (a row whose weight is a count has its value multiplied by the count; a row with a precision weight of zero, or masked out of the data, is not in the likelihood and is NaN, so drop those columns before handing the matrix to a tool such as loo), "trees" - a data frame with tree information for when model was fit with keepTrees equal to TRUE, and "forest" - for extract, predict and fitted, the per-forest channels of an amplitude-coupled multi-forest fit (see forest, contribution, and the forestFits/glue/bases components under ‘Value’); an error naming the reason on any other fit, a bart multinomial one included, whose K forests are per-category latents rather than additive components of one location. extract(type = "forest") reads the stored in-sample channel, while predict(type = "forest") replays each forest at newdata; both report the raw per-forest total, leaving the recombination to the caller, where the combined arms ("ev", "ppd", "bart") perform it given the bases at those rows (see bases). fitted(type = "forest") is the posterior mean of what extract reports, a rows-by-forests matrix with extract's dimnames, pooled over all samples and chains and refused wherever extract refuses it; it is each forest's own total BEFORE its basis and amplitude multiply it, so it is not that forest's contribution to the fitted value, and residuals refuses it. For "ppd", a weighted logistic fit draws the number of successes among the observation-count weight, Binomial(wi,pi)\mathrm{Binomial}(w_i, p_i) (see weights), and weights given to predict on a probit or logistic fit are likewise trial counts, positive integers, each new row drawing Binomial(wi,pi)\mathrm{Binomial}(w_i, p_i), an aft (survival) fit draws on the log-time scale (the fit models log⁡T\log T), a family = student() fit draws f+σtν/wif + \sigma t_\nu / \sqrt{w_i} at each draw's own σ\sigma and ν\nu (the fit's $resid.df), and a heteroscedastic fit (dbarts's variance) draws its noise at that observation's own s(xi)/wis(x_i)/\sqrt{w_i}. For "loglik", gaussian fits evaluate yi∣xi∼N(f^(xi),σ2/wi)y_i \mid x_i \sim N(\hat{f}(x_i), \sigma^2 / w_i) in logs at each draw of ff and σ\sigma - or, for a heteroscedastic fit, yi∣xi∼N(f^(xi),s2(xi)/wi)y_i \mid x_i \sim N(\hat{f}(x_i), s^2(x_i) / w_i) at each draw of ff and ss, a family = student() fit the corresponding marginal tνt_\nu density at that draw's ν\nu (the fit's $resid.df) rather than the normal one, binary fits evaluate the Bernoulli log-likelihood of the fitted probability, multiplied for a weighted logistic fit by the observation-count weight wiw_i, and an aft fit contributes the log density for an event and the log survival tail log⁡P(T>C)\log P(T > C) for a right-censored observation, both on the log-time scale: an event's term is the density of log⁡T\log T, which exceeds the density of TT by log⁡t\log t, so to compare with a model of TT, subtract log⁡t\log t at each event. When chains are combined the result is a samples-by-observations matrix directly consumable by WAIC/PSIS-LOO implementations such as those in the loo package; the chains-first convention is kept, so a per-chain array (combineChains = FALSE, dimension chains-by-samples-by-observations) is reordered to the draws-by-chains-by-observations that loo::relative_eff expects with aperm(x, c(2, 1, 3)). To synergize with predict.glm, "response" can be used as a synonym for "ev" and "link" can be used as a synonym for "bart"; the bart extended-family methods take the same two synonyms, each against its own set of types. extract also takes "sigma", "k" and "leaf.prior.sd", the residual scale, the leaf prior's k and its standard deviation, and "varcount", the per-predictor split counts shaped as "ev" is with predictors in place of observations - none of them per-observation, so a supplied sample is refused by name on all of them. A parameter the fit sampled comes back as its draws, a chain-combined vector or (combineChains = FALSE) a chains-by-samples matrix; one the fit held fixed comes back as that one number, under either combineChains, and forest selects among the forests of a fit with several (see forest below and the ‘Leaf prior parameter k’ subsection). sigma on a weighted fit is the scale at weight 1 (row i's is σ/wi\sigma / \sqrt{w_i}); on a family = student() fit it is the t scale, not the standard deviation. A fit whose family has no residual scale to estimate - probit, logistic, hazard, and the ordinal, negative-binomial and multinomial fits of bart - answers "sigma" with 1, as sigma does on a binomial glm. A heteroscedastic fit's "sigma" is its per-observation scale s(x)s(x), laid out as "ev" is and taking sample: extract returns the stored s.train or s.test, and predict, which takes "sigma" on such a fit only, evaluates the variance forest at newdata (refusing weights, since a case weight does not change s(x)s(x)). For information on extracting trees, see the subsection below.

sample

Either "train" or "test". "test" is refused, by name, when type is "forest": an amplitude-coupled fit has no test fits (see dbarts's forests =). It is extract's and fitted's own argument - fitted is always the training rows - and is refused by name on predict, whose stored train and test channels are extract's sample instead; also refused by name on extract(type = "sigma")/"k"/"leaf.prior.sd"/"varcount", none of them per-observation ("sigma" excepted on a heteroscedastic fit, where it is).

forest

For extract(type = "forest"), extract(type = "trees") and predict(type = "forest"): which forest(s) to return, by 1-based position, as base R reads a list element by number, or by label (a string; see forest), "forest1", "forest2", ... naming position i when a forest is selected (the margins themselves are named by the forests' labels, as forest<i> for a forest with none); NULL (the default) returns every forest. For type = "forest" the returned array always keeps the trailing forest margin, subset to the requested forests, even when only one is selected; type = "trees" returns a data frame and keeps no such margin. For extract(type = "k") and extract(type = "leaf.prior.sd") on a fit with several forests, it selects among the per-forest entries, which both name by the forests' labels (the entry itself for a single forest). Selecting a forest outside those is refused by name: every other arm has already recombined the forests into the location it reports, except "sigma" (a model parameter with no forest axis) and "varcount" (which already keeps every forest on its own trailing margin), each naming its own reason instead.

bases

For predict on an amplitude-coupled multi-forest fit: the bases each forest's amplitudes multiply AT the predicted rows, which off the training rows only the caller knows. A list with one entry per forest, in the forests' order, or with entries named by the forests' labels (forest<i> also selects position i), entry k either NULL (for a forest that declared no basis, whose amplitude multiplies an implicit all-ones column) or a value of the class the forest was created with, which decides what it multiplies (see forest's basis item) and cannot change. A single string names a column of newdata, bases = "dose" reading newdata$dose, on any number of rows, one included; a level is given as a factor, factor("trt", levels = c("ctl", "trt")) on one row. For a forest of levels, created with a factor, a character vector or a logical vector, hand over a factor, a character vector or a logical vector: its levels are matched to the forest's by name and not by position, a level of the forest that no row has is a column of zeros, and a row at a level the forest does not have, or at NA, is refused. Numbers are refused for such a forest, a factor's indicator columns among them: hand over the factor itself, fit$bases holding it. For a forest of numbers, hand over its one numeric column, a vector or a matrix of one column; several columns, a factor, a character vector and a logical vector are refused (as.numeric() of a logical vector is its 0/1 column). Either way it is required to have nrow(newdata) rows, or as many rows as the fit has training rows when newdata is left out; with no newdata, bases replace the fit's own at the training rows, which is the counterfactual at the rows the fit was made on. The fit is then rebuilt draw by draw from the per-forest channels it stores (forestFits, glue and bases; see ‘Value’), with no saved trees, every type reading off the rebuilt total, and an offset given with them applies as well; a fit kept without those channels (keepFits = FALSE) is refused, saying to refit with keepFits = TRUE. A missing value is refused on a row the prediction keeps and passed by on a row the na.action drops (see na.keepPredictors). A named entry selects the forest whose label it is and an unnamed one the forest at its position, in any order and any subset; a forest no entry names is left as it is, which at newdata is an error for a forest that carries a basis, and two entries for one forest are refused. When exactly one forest carries a basis the bare value may be given on its own, without the list: for a Bayesian causal forest fit with its arm as factor(z), bases = factor(zstar, levels = levels(factor(z))) is the counterfactual arm being predicted under, and bases = fit$bases at the training rows is the training fit, to rounding. With no newdata a NULL entry for a forest that carries a basis is refused, as at newdata, since it does not stand for the fit's own; the message names the way to keep the fit's own bases and change others, b <- fit$bases; b[[2]] <- z1; predict(fit, bases = b). Unlike at fit time, a column of all zeros on a forest of numbers and, on a forest of levels, a factor or a character vector with every row at one of the forest's levels are accepted, since a constant arm is the point of a counterfactual. NULL (the default) builds each basis again from newdata when the fit's forest wrote it as code, in a bart or dbarts formula's forest() term or in a forests list (it then needs the columns of the fit's data that basis names, coded against the fit's own factor levels; see forest's basis item), and is an error naming the forest when the basis was handed over as a value or needs a variable that had a value for every fitted row and is no column of newdata. Refused on a single-forest fit, and with type = "forest", which reports each forest's total before any basis.

contribution

For extract(type = "forest") only: FALSE (the default) returns the raw per-forest total forestFits already carries (see ‘Value’). TRUE instead returns each selected forest's per-observation CONTRIBUTION to the fit, (basisk gluek)×forestFitsk(\mathrm{basis}_k \, \mathrm{glue}_k) \times \mathrm{forestFits}_k, computed on demand from the stored forestFits, glue, and bases rather than stored itself.

na.action

For predict: what to do with the rows of newdata that have missing values, and, with no newdata, the training rows whose per-row offset or weights has one; see ‘At Prediction’ in na.keepPredictors.

ci.level

For fitted and predict, an optional single number in (0,1)(0, 1). When NULL (the default), each generic returns what it always has: fitted the posterior mean, predict the full array of posterior samples (see type above), unsummarized. When given, the result is instead a matrix with one row per observation and columns est (the posterior mean), ci.lower, and ci.upper giving a symmetric credible band at that level, pooled over all samples and chains. The kind of interval follows type: "ev" yields a credible interval for the conditional mean (a probability for binary responses), "ppd" a prediction interval that additionally carries the residual noise (and so is wider), and "bart" a credible interval on the latent scale. A row with no draws, a weight-0 row of a posterior predictive draw (see weights), has NA in all three columns. For fitted(type = "forest") it returns the rows-by-forests-by-3 array of est, ci.lower and ci.upper, as for a multinomial fit; predict(type = "forest") refuses it by name, since that arm reports each forest's own total before any basis. It is also refused on residuals, where it would band a constant minus an increasing triple and so mislabel two of its three columns; take y - fitted(object, ci.level = ) instead, where the reversal is visible at the call site.

...

Additional arguments passed on to plot (via plot.bart), or to the sampler's getTrees method via extract when type is "trees" (chainNums, sampleNums, treeNums, newdata, forest; see ‘Extracting Trees’ below) - the one place a name belonging to a sibling method is still accepted rather than refused. Elsewhere, a name that is a formal on predict, extract, fitted, or residuals but foreign to the method actually called is refused by name rather than silently discarded. Any other unrecognized name warns instead - a warning, not an error, so that a subclass method forwarding its own formals through NextMethod is never refused for an argument its caller legitimately supplied.

Details

A fit in which every predictor holds one value on the rows kept is refused, naming the columns, as by bart; sampleronly = TRUE returns the sampler without the check.

BART is an Bayesian MCMC method. At each MCMC interation, we produce a draw from the joint posterior (f,σ)∣(x,y)(f, \sigma) \mid (x, y) in the numeric yy case and just ff in the binary yy case.

Thus, unlike a lot of other modeling methods in R, bartBT does not produce a single model object from which fits and summaries may be extracted. The output consists of values f∗(x)f^*(x) (and σ∗\sigma^* in the numeric case) where * denotes a particular draw. The xx is either a row from the training data (x.train) or the test data (x.test).

Decision Rules

Decision rules for any tree are of the form x≤cx \le c vs. x>cx > c for each ‘xx’ corresponding to a column of x.train. usequants determines the means by which the set of possible cc is determined. If usequants is TRUE, then the cc are a subset of the values interpolated half-way between the unique, sorted, finite values obtained from the corresponding column of x.train. If usequants is FALSE, the cutoffs are equally spaced across the range of finite values taken on by the corresponding column of x.train; an infinite value falls past an end cutoff, as it does on the quantile grid.

The number of possible values of cc is determined by numcut. If usequants is FALSE, numcut equally spaced cutoffs are used covering the range of values in the corresponding column of x.train; a cutoff is held once, so a column whose range is too narrow to hold that many distinct ones gets fewer, and a constant column gets one, where dbarts 0.9-34 repeated them. A column with at least two and fewer than numcut distinct finite values instead gets one cutoff half-way between each pair of neighboring values, the cutoffs usequants = TRUE gives it, and the tree prior and every proposal choose among them in proportion to the width of the gap each sits in, so a 0/1 column has one cutoff where dbarts 0.9-34 and BayesTree placed numcut; a gap's chance of being split is theirs to within one cutoff's share, but no move is proposed among cutoffs that split the same rows, so such fits draw differently. Where two neighboring values are adjacent doubles, so their half-way value rounds onto one of them, the cutoff is the lower value, under either rule. If usequants is TRUE, then for a variable the minimum of numcut and one less than the number of unique elements for that variable are used. When the half-way values outnumber numcut, the ones used are spread evenly over all of them: with MM half-way values and mm = numcut, cutoff kk, counting from one, is the half-way value at position ⌊(2k−1)M/(2m)⌋+1\lfloor (2k - 1) M / (2m) \rfloor + 1, so the cutoffs reach both ends of the variable. dbarts 0.9-34 and BayesTree stepped through them from the bottom at a fixed stride and could stop well short of the top, leaving that part of the variable without a cutoff; fits with usequants = TRUE on such a variable therefore generally differ from theirs.

Leaf prior parameter k

The amount of shrinkage of the leaf parameters is controlled by k. k can be given as either a fixed, positive number, or as any value that can be used to build a supported hyperprior. At present, only χνs\chi_\nu s priors are supported, where ν\nu is a degrees of freedom and ss is a scale. Both values must be positive, however the scale can be infinite which yields an improper prior, which is interpreted as just the polynomial part of the distribution. If ν\nu is 1 and ss is ∞\infty, the prior is “flat”.

For BART on binary outcomes, the degree of overfitting can be highly sensitive to k so it is encouraged to consider a number of values. The default hyperprior for binary bart/dbarts fits, chi(1.5, 2), centers the sampled k near the field-standard fixed value of 2 (prior median 1.9) while adapting to the data; pass k = 2 for the fixed BART-package default. Crossvalidation may still be helpful, and running for a short time with a flat prior (scale = Inf) can show the range of k values the data are consistent with.

A fit stores the k its sampler recorded, whatever terms the leaf prior was named in (k, or sd through leaf.prior; see dbartsPriors); extract(type = "k") returns it on every fit; on a fit with several forests under a drawn k it is a list named by the forests' labels, the group's draws for each forest sharing a total and 1, the value k is pinned at, for any other, as leaf.prior.sd is. It is relative to the data's scale, which the fit stores as leaf.prior$k.scale, whatever terms the prior was named in: under an sd-named prior it is that scale over the spread, a held sd being stored as the held k that states it. extract(type = "leaf.prior.sd") returns the k.scale over k, or a held sd as it was named: the prior standard deviation of the forest's total, which is the spread the leaf prior states, in the units the forest fits - the response's on a gaussian or Student-t fit, log time on an accelerated failure time fit, the latent scale of the link on a probit, logistic or ordinal fit, and the log mean on a negative-binomial fit. What the standard deviation is the standard deviation of depends on the leaf model: the leaf value for a constant leaf, each coefficient for a linear leaf and the amplitude for a Gaussian-process leaf. Under a monotone constraint the total's prior spread runs a few percent wider than this number. On a fit with several forests it is each forest's sd as the sampler's $getLeafPrior() reported it when the run ended (see dbartsSampler), in the response's units: the number the forest stated, or its default, before its amplitude multiplies the forest, and for a forest on a numeric column per unit of that column, named by it. A forest sharing one prior total under a drawn k has draws there instead, its k.scale over the group's k, and summary tabulates that k, or that leaf.prior.sd where the total was named by an sd. It comes back as a list named by the forests' labels, or as the entry itself that forest selects; k is pinned at 1 on each. A hurdle fit returns a list of its zero and positive parts, each in its own units.

Generics

bartBT supports fitted to return the posterior mean of a predicted quantity, as well as predict to return a set of posterior samples for a different sample. In addition, the extract generic can be used to obtain the posterior samples for the training data or test data supplied during the initial fit.

Using predict with a bart object requires that it be fitted with the option keeptrees/keepTrees as TRUE. Keeping the trees for a fit can require a sizable amount of memory and is off by default.

All generics return values on the scale of expected value of the response by default. This means that predict, extract, and fitted for binary outcomes return probabilities unless specifically the sum-of-trees component is requested (type = "bart"). This is in contrast to yhat.train/yhat.test that are returned with the fitted model.

residuals returns yy minus fitted(object, type = type, sample = "train"); the default type = "ev" gives ordinary response-scale residuals, so for a binary fit this is y−P(Y=1∣x)y - P(Y = 1 \mid x). Binary fits do not have yhat.train.mean/yhat.test.mean components (see ‘Value’); use fitted to obtain the equivalent posterior-mean probabilities directly. residuals is always against the training response, so sample is refused by name; ci.level is refused too (see its own entry above).

Saving

saveing and loading a fitted BART object for use with predict requires that it be fit with keeptrees/keepTrees as TRUE. A fit that keeps its trees stores the sampler's tree and generator state at the end of the fit, so it saves and reloads whole, predict, extract(type = "trees") and plotTree working on the reloaded fit; the same holds for bart's own-class families - family = "multinomial", "ordinal", and "nbinom" - and for each part of a family = "hurdle.lognormal" fit. A user who runs the kept sampler further calls storeState() on it again before saving: bartFit$fit$storeState(). The state duplicates the trees on the R side and can exceed the fit's own sample blocks. A fit whose sampler was saved without a stored state reloads, but predict, extract(type = "trees"), and plotTree all stop identically, each with an error naming storeState().

Reproducibility

See the Reproducibility section of bart: it covers seed versus set.seed, chains and thread count, and continuing, copying, or restoring a sampler, in full for both bartBT and bart.

Extracting Trees

When a model is fit with keeptrees (bartBT) or keepTrees (bart) equal to TRUE, the generic extract can be used to retrieve a data frame containing the tree fit information. In this case, extract will accept the additional, optional arguments: chainNums, sampleNums, and treeNums. Each should be an integer vector detailing the desired trees to be returned. A further optional argument newdata routes a new set of predictors (in the same form accepted by predict) through the frozen trees so that the n column counts those observations instead of the training data. A last optional argument forest - a single position or label, a vector of them, or the default NULL for every forest (a label is a string, as extract(type = "trees", forest = "dose") reads it; see forest) - selects among a fit's forests (only an amplitude-coupled multi-forest fit - one more forest per additional forest() term or forests = entry - or a "bartMultinomial" fit's K categories, carry more than one); see dbartsSampler's forest item.

The result of extract will be a data frame with columns:

  • forest - which forest the row belongs to, a factor whose levels are the forests' labels in forest order (forest<i> for a forest with none, as the fit's other per-forest results are named), so that trees$forest == "z" selects a forest and as.integer(trees$forest) gives its position, and the levels are all of the fit's forests whichever the frame holds; present only on a fit with several forests (a "bartMultinomial" fit, or one declared with forests = naming more than one); a single-forest fit has no such column, and still accepts forest = 1. The sampler's own getTrees numbers the forests from 1 instead

  • chain, sample, tree - index variables; chain is always present, 1 on a single-chain fit, since tree draws cannot be combined across chains (the sampler's own getTrees omits it at one chain)

  • n - number of observations in node, drawn from the training data or from newdata when supplied

  • var - either the index of the variable used for splitting or -1 if the node is a leaf

  • value - either the value such that observations less than or equal to it are sent down the left path of the tree or the predicted value for a leaf node

The order of nodes in the result corresponds to a depth-first traversal, going down the left-side first. The names of variables used in splitting can be recovered by examining the column names of the fit$data@x element of a fitted bartBT or bart model. See the package vignette “Working with dbarts Saved Trees”.

A fit made with keeptrees/keepTrees FALSE but a sampler kept anyway (keepSampler = TRUE, or a bart fit with fit present per ‘Value’ below) still answers extract(fit, "trees"), the same fallback plotTree uses: the frame holds the sampler's CURRENT trees rather than a saved history, so it carries no sample column and reflects whatever predictors and structure the sampler holds at the time of the call, not a fixed draw.

Value

bartBT and bart return lists assigned the class bart for the shared gaussian/probit/logistic/aft/hazard* families (bart reaches further response families under their own list classes and generics; see bart's Value section). For applicable quantities, ndpost / keepevery samples are returned. In the numeric yy case, the list has components:

call

The matched call, or NULL when the fit was made with keepcall/keepCall equal to FALSE.

yhat.train

A array/matrix of posterior samples. The (i,j,k)(i, j, k) value is the jjth draw of the posterior of ff evaluated at the kkth row of x.train (i.e. f∗(xk)f^*(x_k)) corresponding to chain ii. When nchain is one or combinechains is TRUE, the result is collapsed down to a matrix: with m=m =ndpost %/% keepevery draws kept per chain, row rr is chain 1+(r−1)%/%m1 + (r - 1) \%/\% m's draw 1+(r−1)%%m1 + (r - 1) \%\% m - chain 1's whole run first, then chain 2's, and so on (chain-major), not interleaved draw by draw. Every collapsed field a fit returns (sigma, k, varcount, ...) uses this same row order, so row rr of one pairs with row rr of another - e.g. sigma[r] is the residual scale that produced yhat.train[r, ].

yhat.test

Same as yhat.train but now the xxs are the rows of the test data.

yhat.train.mean

Vector of means of yhat.train across columns and chains, with length equal to the number of training observations passed in: on bart, NA at a row dropped for a missing response, which yhat.train leaves out.

yhat.test.mean

Vector of means of yhat.test across columns and chains.

sigma

Matrix of posterior samples of sigma, the residual/error standard deviation; absent on a heteroscedastic fit, which has no scalar residual scale and whose scale draws are s.train/s.test, and on a fit that held sigma, whose value is in fixed. Dimensions are equal to the number of chains times the number of samples unless nchain is one or combinechains is TRUE, in which case it collapses to a vector in the same chain-major order as yhat.train (see above), so combined sigma[r] pairs with combined yhat.train[r, ].

first.sigma

Burn-in draws of sigma; absent where sigma is.

varcount

A matrix with number of rows equal to the number of kept draws and each column corresponding to a training variable. Contains the total count of the number of times that variable is used in a tree decision rule (over all trees). Row order (when combined) is yhat.train's chain-major order (see above).

varprobs

Present only under a DART prior: the sampled split-variable probabilities, in the same layout as varcount. Each draw sums to one across variables.

forestFits, glue, bases

Present only for an amplitude-coupled multi-forest fit: built through dbarts's forests =, or through bart's forest() formula term (see its ‘Formula Terms’ section); not reachable from bartBT directly, which has no multi-forest front door. forestFits is a (n.chains ×\times, when uncombined) n.samples ×\times number of training observations ×\times K array: forest k's own RESPONSE-scale raw total at each draw, i.e. response.scale×fk(x)\mathrm{response.scale} \times f_k(x), with NO amplitude (glue) folded in - the same quantity the sampler's $getForestFits reports, up to that one scalar, a raw total of prior scale the forest's sd, whose coefficient has prior median 1 where it is drawn. The trailing margin is named by the forests' labels (a name in forests, else the text of the forest's basis, else forest<i> for a forest with neither; see dbarts's forests item), as is every per-forest margin or list of the fit and of what extract, fitted and predict return, so one forest has one name everywhere. The labels also ride as a "forest.labels" attribute on the fit object, and beside it a "forest.unit" attribute holds the unit the forests' sds are stated in: sd(y)\mathrm{sd}(y) as the sd argument of forest takes it, or the link's error sd, which the header of the full block names. glue is the ragged (n.chains ×\times, when uncombined) n.samples ×\times sum(q_k) matrix of amplitudes multiplying each forest's basis columns, forest-major (the layout $getForestAmplitudes documents); its "forest" attribute names each column's forest. bases is a length-K list of each forest's basis (no draw axis), one value for each training row the fit kept: for a forest of levels the factor, its levels those recorded when the fit was created, in the order of the forest's coefficients (model.matrix(~ 0 + b) of it is the block of indicator columns the amplitudes multiply, and predict(fit, x, bases = fit$bases) at the training rows is the training fit, to rounding); for a forest of numbers the matrix of its one column; NULL for a forest with no declared basis, whose amplitude then scales an implicit all-ones column. Together, with each factor in bases taken as its indicator columns, they reconstruct the training fit to rounding: y^=response.shift+∑k(basesk gluek)×forestFitsk\hat y = \mathrm{response.shift} + \sum_k (\mathrm{bases}_k \, \mathrm{glue}_k) \times \mathrm{forestFits}_k, with response.scale/response.shift read from the sampler's $getLeafPrior. See extract's type = "forest". predict(object, newdata, type = "forest") reports the same quantity at NEW rows - an (n.chains ×\times, when uncombined) n.samples ×\times nrow(newdata) ×\times K array, same trailing margin, same forest selection - replayed from the saved trees, and so requiring keeptrees/keepTrees. It carries no glue, no response.shift and no offset either, because off the training rows the bases are the caller's, so an offset is refused there rather than folded in and there is no contribution argument for the same reason. The identity itself is what predict(object, newdata, type = "ev") (or "ppd", or "bart") performs at those rows in one call, taking each bases entry's replacement - the basis that forest's amplitudes multiply at the new rows, for a Bayesian causal forest the factor of whichever assignment is being predicted under - through its own bases argument, or built again from newdata for a basis that was written as code. Written out by hand it remains the fallback for a caller holding only these components and no sampler. A fit one of whose bases was written as code, in a forest() term of a formula or in a forests list, additionally carries basis.terms, a length-K list holding for each such basis what builds it again at new rows (R's terms object for it, the levels of its factors, its text and the columns of the fit's data it names) and NULL for a forest with no basis or with one given as a value; it is absent when no basis was written as code.

basis.columns

Present only for an amplitude-coupled multi-forest fit made with keepFits = FALSE, in place of bases: for each forest, NULL where it has no basis, a factor of no rows with the basis's levels, or a list of a numeric basis's mean, sd, range and constant (whether it is constant over the rows in the likelihood), the numbers the printed block and summary read. That is four numbers a forest against one for each observation. Such a fit keeps "forest.labels", "forest.trees" and "forest.unit", so extract names and picks forests by label as on any fit of several forests.

n.forests

The forest count K, on every fit: 1 for a single forest.

row.names.train, row.names.test

The names of the training and test rows, which every per-observation output carries; absent when the rows are unnamed. See the row names paragraph of bart's ‘Value’ section.

sigest, sigest.fallback

The rough error standard deviation (σ\sigma) used in the prior. sigest.fallback is TRUE, and otherwise absent, where that was the standard deviation of the response because the linear regression had no residual degrees of freedom; it carries the attribute weighted, TRUE, where that standard deviation read weights other than 1.

resid.scale, resid.df

resid.scale is present only on a family with a residual distribution ("gaussian", "student", "aft"): the distribution's scale model, "constant" or "forest" for a heteroscedastic fit (variance on bart), whose draws are s.train/s.test. The distribution's shape is the family's own (see dbarts's family = student()). resid.df is present only for a student() fit: the degrees of freedom ν\nu each draw was conditioned on, in sigma's layout - a fixed ν\nu repeats its value, an estimated one gives that draw's grid value. extract(type = "loglik") reads both.

y

The input dependent vector of values for the dependent variable. This is used in plot.bart.

fit

Optional sampler object which stores the values of the tree splits. Required for using predict and only stored if keeptrees or keepsampler is TRUE.

n.chains

Information that can be lost if combinechains is TRUE is tracked here.

k

Optional matrix of posterior samples of k, as the sampler recorded them whatever terms the leaf prior was named in. Only present when k is modeled, i.e. there is a hyperprior. Collapses (when combined) in sigma's chain-major order.

first.k

Burn-in draws of k, if modeled.

leaf.prior

The leaf prior the fit ran under, on every fit: the sampler's own reading as the run ended (dbartsSampler's getLeafPrior), a list holding the prior as it was named, what its standard deviation is the standard deviation of, and k.scale, the value k is relative to. A list of such lists, named by the forests' labels, on a fit with several forests.

fixed

The scalars the sampler held fixed, a named list on every fit, empty when there are none: among sigma, k and resid.df, shape on a negative-binomial fit, and amplitude for each forest whose coefficient is held by amplitude = fixed(), each read from the sampler. A fixed sigma is the sampler's, the square root of the variance fixed() names; a fixed k on a fit with several forests is a vector named by forest, and a held amplitude is 1 for each held forest, named the same way. A held value is stored here and nowhere else: a fit that held sigma or shape has no sigma, first.sigma or shape channel, as one that held k has no k, and plot, summary, extract, the predictive draws, the log-likelihood and predict read the value from this list. A fit whose sigma is missing is therefore not necessarily a binary one: test family (or fixed), not the channel.

binaryOffset

Present only for a binary fit: the offset used, one value per training row.

offset

Present only for a fit trained with an offset: the training offset, one number per training row (or one number). predict with no newdata and survivalProbabilities take the fit's own offset off the stored draws and put the offset they are given on, so they need no saved trees. The same element is stored by every fit class bart returns, the multinomial one's an n x K matrix.

offset.test

Present only for a fit with a test set trained with a test offset: that offset, one number per test row. A discrete-time hazard fit's survivalProbabilities replaces it when given an offset and no newdata.

family

The response family as specified, once "auto" has resolved: "gaussian", "student", "probit", "logistic", "aft", "hazard.probit", or "hazard.logistic" (the bare token "hazard" is recorded as "hazard.probit"). predict, extract, fitted, and plot look its link up from it to transform latent draws to probabilities, and stop on a token they do not know. For an "aft" fit, predictions and fitted values are on the LOG-TIME scale: these functions return the linear predictor E[log⁡T∣x]E[\log T \mid x], exactly as for a gaussian fit of log⁡T\log T, and never the time scale that survreg or flexsurv users might expect. The type aliases "response" and "link" are inert for "aft" - both return the same log-scale linear predictor; neither exponentiates. The posterior-median survival time is exp of the linear predictor, and survivalProbabilities gives survival-probability draws. A discrete-time hazard fit (family = "hazard"/"hazard.logistic", reachable only through bart) records the binary link here ("probit"/"logistic") - the fit IS that binary fit on the expanded rows - and carries a separate $periods element (the ordered period grid); predict/extract return the per-(subject, period) hazard through the link, and survivalProbabilities dispatches its survival-curve branch on the $periods marker.

family.spec

The same family as a family object carrying its settings (a Student-t df, a hazard link and grid, a residual prior), such as student(df = 3) or hazard(link = "probit"). family(object) returns it.

In the binary yy case, the returned list has the components yhat.train, yhat.test, and varcount as above, but not yhat.train.mean/yhat.test.mean or resid.scale - use fitted to get the posterior mean of P(Y=1∣x)P(Y = 1 \mid x) instead. In addition the list has a binaryOffset component giving the value used.

Note that in the binary yy, case yhat.train and yhat.test are f(x)+binaryOffsetf(x) + \mathrm{binaryOffset}. For draws of the probability P(Y=1∣x)P(Y = 1 | x), apply the family's inverse link to these values: the normal cdf (pnorm) for "probit" fits, plogis for "logistic" ones.

For continuous response fits, the plot method sets mfrow to c(1, 2) and makes two plots, unless sigma was held fixed, when it draws only the second. The first plot is the sequence of kept draws of σ\sigma including the burn-in draws. Initially these draws will decline as BART finds a good fit and then level off when the MCMC has burned in. The second plot has yy on the horizontal axis and posterior intervals for the corresponding f(x)f(x) on the vertical axis. For binary response fits, only this second kind of plot is drawn, with the posterior median of P(Y=1∣x)P(Y = 1 \mid x) on the horizontal axis and its posterior interval on the vertical axis.

For print.bart, the fit itself (x), returned invisibly; the call and a short synopsis (family, chain/tree/burn counts, kept-draw count) print to the console as the side effect. A fit of several forests adds a short block of one line for each, its label, what the forest multiplies, a numeric column's mean and sd, and the sd the forest resolved to (for a numeric column, per sd of the column as it now stands), with a last line pointing to summary(), which gives the full block (see the sd argument of forest for what to read in it); a fit made with keepFits = FALSE prints the same block, from its labels and tree counts and, in place of each basis vector, a few numbers it keeps (element basis.columns: a numeric column's mean, sd, range and whether it is constant over the rows in the likelihood, a factor's levels). Such a fit still refuses predict at new rows, which needs the per-forest fits keepFits = FALSE dropped. A fit saved by dbarts 0.9-34 prints its call and then a note, as a message, that it cannot be read by this version and is to be refit; every other use of such a fit that needs its trees or sampler stops with that sentence.

Calling extract

Call it as dbarts::extract. Other packages export a function named extract: rstan, tidyr, terra, raster, magrittr and R.utils. Whichever is attached last masks the others, so a bare extract(fit, ...) may reach the wrong one. The stan4bart package attaches dbarts, so it brings this name in.

Author(s)

Hugh Chipman: [email protected], Robert McCulloch: [email protected], Vincent Dorie: [email protected].

References

Chipman, H., George, E., and McCulloch, R. (2010) BART: Bayesian additive regression trees. The Annals of Applied Statistics, 4(1), 266–298. doi:10.1214/09-AOAS285.

Chipman, H., George, E., and McCulloch R. (2006) Bayesian Ensemble Learning. Advances in Neural Information Processing Systems 19, Scholkopf, Platt and Hoffman, Eds., MIT Press, Cambridge, MA, 265-272. https://www.rob-mcculloch.org

Friedman, J.H. (1991) Multivariate adaptive regression splines. The Annals of Statistics, 19, 1–67.

See Also

bart for the formula-first interface, further response families, and formula-term multi-forest models.

dbartsSampler's $predictForests for the same per-forest replay from a mutable sampler, which is what predict(type = "forest") reads and what extract(type = "forest") reports in sample.

pdbart

dbarts-embedding and vignette("dbarts-as-a-component", package = "dbarts") for using BART as one block of a sampler you write, rather than as the whole fit: these functions own their own MCMC loop, while dbarts returns a dbartsSampler that runs one sweep at a time.

Examples

## simulate data (example from Friedman MARS paper)
## y = f(x) + epsilon , epsilon ~ N(0, sigma)
## x consists of 10 variables, only first 5 matter

f <- function(x) {
    10 * sin(pi * x[,1] * x[,2]) + 20 * (x[,3] - 0.5)^2 +
        10 * x[,4] + 5 * x[,5]
}

set.seed(99)
sigma <- 1.0
n     <- 100

x  <- matrix(runif(n * 10), n, 10)
Ey <- f(x)
y  <- rnorm(n, Ey, sigma)

## run BART
set.seed(99)
bartFit <- bartBT(x, y)

plot(bartFit)

## compare BART fit to linear matter and truth = Ey
lmFit <- lm(y ~ ., data.frame(x, y))

fitmat <- cbind(y, Ey, lmFit$fitted, bartFit$yhat.train.mean)
colnames(fitmat) <- c('y', 'Ey', 'lm', 'bart')
print(cor(fitmat))

## fit with missing predictor values: every split rule learns a
## direction for NAs (MIA, always on; no argument selects it)
set.seed(1)
n <- 60L
x.na <- matrix(runif(n * 2), n, 2)
x.na[1:5, 1] <- NA
y.na <- x.na[,2] + rnorm(n, 0, 0.3)
y.na[is.na(x.na[,1])] <- y.na[is.na(x.na[,1])] + 2
fit.na <- dbarts(y.na ~ x.na, control = dbartsControl(
                   n.samples = 20L, n.burn = 20L, n.chains = 1L, n.threads = 1L),
                   n.trees = 20L)
samples.na <- fit.na$run()

## recipe: between-draws row subsetting on a latent family (e.g. principal
## stratification or mediation, where an outer Gibbs step redraws which rows
## belong to a stratum every iteration). $setActiveRows changes which rows
## are "in" the model from one run() to the next, without rebuilding the
## sampler and without losing any row's fitted value; see the "active" entry
## of \link{dbartsSampler-class} for the full semantics. Unlike zero case
## weights (gaussian, probit, ordinal and nbinom only), this also reaches
## logistic and aft samplers - and an emptied stratum is a legal all-zeros mask
## rather than a case the caller must special-case and skip.
set.seed(3)
n <- 120L
x.strat <- matrix(runif(n * 2), n, 2)
y.strat <- rbinom(n, 1L, plogis(2 * x.strat[,1] - 1))
sampler.strat <- dbarts(x.strat, y.strat, family = "probit",
                        control = dbartsControl(n.chains = 1L, n.threads = 1L,
                                                updateState = FALSE),
                        n.trees = 20L)

stratum <- rbinom(n, 1L, 0.6)  # this iteration's stratum membership
sampler.strat$setActiveRows(stratum)
draws.strat <- sampler.strat$run(20L, 20L)

## the next outer iteration redraws the stratum; even a stratum that empties
## out is accepted and runs, rather than needing to be skipped
stratum <- rep(0, n)
sampler.strat$setActiveRows(stratum)
draws.empty <- sampler.strat$run(0L, 5L)

Block-Additive Constraints for BART

Description

Build 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=∑GfGf = \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.

Usage

blocks(groups, trees.per.group = NULL)

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.trees trees each group receives; the entries must be positive and sum to n.trees. NULL (the default) distributes the trees as evenly as possible, with the first n.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 GG groups takes an equal part, 1/G1/G, of the forest's prior variance, whatever its tree count: a group of mgm_g trees gives each of its leaves the variance s2/(Gmg)s^2 / (G m_g), ss 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).

Value

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

See Also

dbartsForests, interactions, dbarts, bart

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)

Discrete Bayesian Additive Regression Trees Sampler

Description

Creates a sampler object for a given problem which fits a Bayesian Additive Regression Trees model. Internally stores state in such a way as to be mutable.

Usage

dbarts(
    formula, data, test, subset, weights, offset, offset.test = offset,
    verbose = FALSE, n.samples = 800L,
    power = 2, base = 0.95, split.probs = NULL, leaf.prior = normal,
    monotone = NULL,
    interactions = NULL,
    blocks = NULL,
    variance = NULL,
    forests = NULL, n.trees = NULL,
    control = dbarts::dbartsControl(), sigest = NULL, seed = NULL,
    factors = c("categorical", "indicators"),
    n.cuts = NULL, useQuantiles = NULL,
    family = c("auto", "gaussian", "student", "probit", "logistic", "aft",
               "multinomial", "ordinal",
               "nbinom", "hazard", "hazard.probit", "hazard.logistic"),
    weights.type = NULL,
    na.action = dbarts::na.keepPredictors,
    sigma = NULL, node.prior = NULL, tree.prior = NULL, callback = NULL, ...)

Arguments

formula

An object of class formula following an analogous model description syntax as lm. As in lm, an offset() term is added to offset and is evaluated on test (see offset.test), and a data-dependent term such as poly(), splines::ns() or scale() is rebuilt on test and on predict's newdata from the training values, as predict.lm rebuilds it. A fit stores these terms, and the offset expression, without an environment: a name that is a column of data is read from the new rows alone, and every other name is fixed at its value when fitting, so a fit carries no frame of the function that made it. A formula calling a function from no package, such as one defined in the session, is refused, naming it. For backwards compatibility, can also be the bartBT matrix x.train, whose integer and logical values are taken as numbers, as in a data frame, including a sparse Matrix::dgCMatrix (any other sparse Matrix class, or a sparseVector as one column, is converted to one, and a dense Matrix is taken as a plain matrix): its columns enter as ordinal predictors, sufficiently sparse columns are stored in a compact rank-bitmap layout instead of being expanded, and the predictor-mutation surface accepts both whole-matrix replacement, setPredictor(x), and the column-granular setPredictor(x, column = j), which replaces a sparse column whole; a replaced sparse-backed column stays sparse, storing only the replacement's nonzeros, and a replacement's sparse columns are never expanded. Per-observation replacement of a sparse-backed column, and setData, are fixed at creation. Sparse inputs are not supported by the leaf.prior = linear() and gp() leaf models (a sparse-backed test column cannot serve a designated leaf covariate either). A sparse or data-frame test set stays resident (rank-bitmap or dense per column, the same rule as training) rather than densifying at ingestion - a test set of any other sparse Matrix class, such as a dgTMatrix, as the dgCMatrix it holds - and predict and getTrees(newdata = ) route its rows through the trees off that storage rather than densifying it either. A data frame may mix ordinary columns with Matrix::sparseVector or dgCMatrix columns (assign them into the frame; they do not survive data.frame(...) or I()): sparse columns behave as in an all-sparse design, while dense columns keep categorical splits and linear-leaf designation. A sparseFactor column is accepted here (the x/y, data-frame path) exactly as the other sparse columns are; a formula object accepts one too, named like any other column (including through .), since dbartsData lifts it out of data ahead of model.frame (which cannot carry it) and re-attaches it to the assembled predictor matrix afterward. See dbartsData for the full data-frame-to-predictor mapping.

data

An optional data frame, list, or environment containing predictors to be used with the model. For backwards compatibility, can also be the bartBT vector y.train. The response, however supplied, is checked for near-degeneracy at double precision and warns when too few distinct values remain to fit against.

test

An optional matrix or data frame with the same number of predictors as data, or formula in backwards compatibility mode. If column names are present, a matching algorithm is used; when both are named, test's names must cover data's (an error otherwise), and a data frame test may carry other columns, which are ignored, as for a formula fit (a matrix keeps its exact width); an unnamed test is read in the order of data's columns, with no message, and a named test given to an unnamed data is matched by position with a warning.

subset

An optional vector specifying a subset of observations to be used in the fitting process. Each argument that holds rows, the first argument, data, test, subset, weights and offset, is evaluated once for a fit, the first argument before data. So an expression that draws its rows, as data = d[sample(nrow(d)), ], subset = sample(n, 100) or the pair dbarts(x[i <- sample(n, 100), ], y[i]), gives the response, the predictors, the weights, the offset and every forest's basis the same rows.

weights

An optional vector of weights to be used in the fitting process. For a gaussian response, BART fits a model with observations y∣x∼N(f(x),σ2/w)y \mid x \sim N(f(x), \sigma^2 / w), where f(x)f(x) is the unknown function; under weights.type = "frequency" a row of weight ww is instead ww identical observations (see that item). Binary responses differ: a "probit" model does not support a weighted likelihood (a weighted probit has no tractable latent-variable form), except that weights identically 1 are treated as absent. A "probit" or "ordinal" fit does accept weights that are all 0 and 1, as does an "nbinom" fit: those name the rows in the data set rather than a precision, are held in the data object's weights slot and compose with the sampler's active-row mask, a row being in when its weight is 1 and the mask keeps it; a 0 row leaves the likelihood but keeps its leaf occupancy, its latent and its fitted value. For "nbinom" the leaf prior's center, the log of the total count over the total exposure, is taken over the rows in, each counted its weight's number of times, as a gaussian or Student-t fit's response transform is taken over the rows of positive weight (an "aft" fit takes no weights, so every row is in when it is created). A "logistic", "nbinom" or "multinomial" model differs again: it treats them as observation counts and so requires non-negative whole numbers, a count of 0 leaving the row out of the likelihood as on every family (its Polya-Gamma latent for a count ww is a sum of ww unit draws, so a sweep's time grows with the total count, and a count times the row's trials, y+ry + r or row total above 10610^6 is refused); an "nbinom" exposure belongs in the offset, not in a weight. A weight of 0 takes an observation out of the likelihood and out of the residual degrees of freedom but not out of the design: the row still occupies a leaf, which the trees may split around, and still receives a fitted value, so the fit is close to the fit on the remaining rows without being that fit (see the weights item of dbartsSampler; subset drops rows). A row of weight 0 takes no part in the response's scale, which the leaf prior is stated against, in the center of a count fit's leaf prior, or in the default sd of a forest in a model of several forests: they are taken over the rows of positive weight when the sampler is created. The step is at 0 and not at a small weight, and weights or a mask set after creation leave the numbers creation set, so the three ways to leave a row out - weights or a mask at creation, weights or a mask set later, and subset - differ by when the row left. Where rows are out and the rows in hold fewer than two distinct values of the response, every row is used instead, under a warning of class dbartsScaleFallbackWarning. It is warned about unless every weight is 0 or 1 - a vector of nothing but those states which rows are in the data set, and is the membership a "probit", "ordinal" or "nbinom" fit takes; the same class covers weights going unused for test - when the model is not specified as a formula, and when weights names a column test does not carry.

offset

An optional vector specifying an offset from 0 for the relationship between the underlying function, f(x)f(x), and the response yy. Useful for both response families, though the two apply it differently. For a gaussian response, y=f(x)+offset+ϵy = f(x) + \mathrm{offset} + \epsilon: the offset is netted out of yy before BART's internal range-scaling (see ‘Details’), so it acts as a fixed component of the mean rather than a free parameter. For binary responses it enters the link directly: a "probit" fit assumes P(Y=1∣X=x)=Φ(f(x)+offset)P(Y = 1 \mid X = x) = \Phi(f(x) + \mathrm{offset}), where Φ\Phi is the standard normal cumulative distribution function, and a "logistic" fit the analogous model on the logistic link.

offset.test

The equivalent of offset for test observations. By default the expression offset was given as is evaluated on test, as predict.lm evaluates it on new data: a scalar is reused, and a vector given for the training rows applies only to a test set of as many rows, any other length refused. Given explicitly, it is a single number or one value per row of test, any other length refused, and a bare name is looked up in test before data. A formula's offset() terms are evaluated on test, which must then be a data frame carrying their variables, and added to it.

verbose

A logical determining if additional output is printed to the console, including the one-line message family = "auto" prints naming the family it resolves to (a message of class dbartsAutoFamilyMessage, which suppressMessages or a calling handler can mute on its own). See dbartsControl.

n.samples

A non-negative integer (0 accepted) setting the default number of posterior samples to be returned for each run of the sampler. Can be overriden at run-time. See dbartsControl's n.samples item for the full contract.

power, base

Real numbers setting the tree prior's probability that a node at a given depth splits, base/(1+depth)powerbase / (1 + depth)^{power}, as in bart. In a model of several forests they are the tree prior of the forest with no basis, and a forest states its own on the forest, as forest(x1, power = 3); stating one on both the function and that forest is refused, as for n.trees. See forests. A written NULL is refused, saying to leave the argument out for its default.

split.probs

Prior probabilities that each predictor is chosen for a splitting rule: NULL (the default) for equal probabilities, a numeric vector, named or one per model-matrix column, num.vars, which stands for the number of predictors (1 / num.vars), or dart() from dbartsPriors, which runs DART (Linero 2018). A named vector reads by column or term name, .default giving the rest, and is refused when it leaves a column with no value, a single named value included. A column of split probability zero is never split on, just as one a forest's vars leaves out is never split on. A model of several forests, and family = "multinomial", take a uniform vector and refuse any other, or dart(), by name. The mean forest's alone: a variance forest takes none.

leaf.prior

An expression of the form normal or normal(k) that sets the prior used on the leaf values, or a prior object built with dbartsPriors. linear(columns, k) instead fits each leaf with an intercept plus a linear term in the designated continuous predictor columns (character names or numeric indices into the model matrix), standardized internally, all coefficients sharing the normal(k) prior. Each covariate is centered and scaled by its mean and standard deviation over the rows in the likelihood when the sampler is created, those of positive weight, each counting in full, or over every row, under one warning, where fewer than two are in (subjects, for a hazard fit, however many periods they span) or where the response's scale is read from every row because the rows in hold fewer than two distinct values of it; the numbers are held from then on, gp's default lengthscale with them. A covariate those rows hold at one value, or observe at none, a constant column among them, is refused, since no scale can be taken from it, unless its gp leaf states lengthscale: it is then centered at that value and divided by 1. One whose values there have a spread about their center under 64 times machine precision of their size (||z - center|| < 64 * .Machine$double.eps * ||z||), such as 0.3 beside 0.1 * 3, is read as one value, here and wherever a setter derives the center and scale again, and centered at its mean where it takes the placeholder. Values meant to be equal are fixed only by dropping the column; values that truly differ but sit at a large offset, a time in seconds since 1970 varying by under about a tenth of a millisecond say, are fixed by recomputing the column from its source about an origin near its values, since subtracting a constant from the stored values restores no digit they have lost; unordered factor columns cannot be designated. gp(columns, k, lengthscale, max.leaf.size) fits each leaf with a smooth Gaussian-process function of the designated columns under a squared-exponential kernel; leaves larger than max.leaf.size fall back to constant fits. An ordered factor may be designated under either, and enters as its level codes 1, 2, and so on, which treats its levels as equally spaced, as the linear contrast lm gives an ordered factor does; levels spaced otherwise need a numeric column holding their scores. xbart accepts the same specifications through its own leaf.prior argument. See “Response scaling” below for how k interacts with the response's internal scaling. In a model of several forests it is the leaf prior of the forest with no basis stating no sd, taken as one forest takes it; see forests. A forest states its own size as forest(x1 + x2, sd = 2), in the response's units as normal(sd = ) is, and where every forest with no basis does a k or sd here is refused, the default restated taken. The one forest of a model of one forest states its size either way, forest(sd = ) being this prior's normal(sd = ), and not at both. A written NULL is refused, saying to leave the argument out for its default.

monotone

Optional per-predictor monotonicity constraints (monotone BART; Chipman, George, McCulloch, and Shively 2022). The forest is constrained so that the fitted function is monotone increasing or decreasing in each named predictor. Supply a monotone specification, monotone(directions, prior = ), or its directions alone, shorthand for the default prior, "joint": a named vector selecting predictors by model-matrix column name, each element "increasing" or 1, "decreasing" or -1, or 0 for unconstrained - matching is case-sensitive; an unnamed vector of length equal to the number of columns assigns directions positionally. Only numeric and ordered columns are eligible - a direction on a categorical (unordered factor) predictor is an error. A constraint forces birth/death-only tree proposals (a control naming a non-default proposal.probs is then an error) and a fixed leaf scale, k = 2 unless another number is given (a k or sd hyperprior is an error); linear and Gaussian-process leaves are not supported under the constraint. NULL (the default) or an all-zero vector fits the ordinary unconstrained model. The constructor resolves by bare name inside this argument, whatever the caller has attached, and a bare name the caller has bound to a value is that value; see dbartsForests.

interactions

Optional interaction constraints, built with interactions: interactions(max.order = 2) caps the number of distinct predictors that may appear together on any single root-to-leaf path, interactions(forbid = list(c("a", "b"))) bars named predictors from ever sharing a path, and interactions(groups = list(c("a", "b"), "c")) confines interactions to declared groups (named predictors may co-occur only with their group-mates). The three may be combined. Named or indexed predictors resolve against the model matrix at fit time, where an unknown name, an empty group, a max.order below 1, or a reference to a dropped column is an error. NULL (the default) fits the ordinary unconstrained model. The constructor resolves by bare name inside this argument, whatever the caller has attached, and a bare name the caller has bound to a value is that value; see dbartsForests. In a model of several forests it constrains the forest with no basis; see forests.

blocks

Optional block-additive constraint, built with blocks: blocks(groups = list(c("a", "b"), "c")) confines each whole tree to one declared group of predictors, so the ensemble is exactly a sum of per-group functions (a functional-ANOVA / grouped-GAMI decomposition). Unlike interactions(groups = ), which is a per-path allow-list, this is a static per-tree mask, so the groups must form a total, disjoint partition of the predictors - every predictor named exactly once. trees.per.group optionally fixes how many trees each group gets; otherwise the trees are spread as evenly as possible. Validated at fit time (an unpartitioned or doubly-named predictor, or a trees.per.group that does not sum to n.trees, is an error). NULL (the default) fits the ordinary model. May be combined with interactions. See blocks. The constructor resolves by bare name inside this argument, whatever the caller has attached, and a bare name the caller has bound to a value is that value; see dbartsForests. In a model of several forests it constrains the forest with no basis; see forests.

variance

Optional heteroscedastic variance forest (HBART; Pratola, Chipman, George, and McCulloch 2020). When supplied, a second ensemble models the residual variance surface s2(x)s^2(x) as a product of scaled-inverse-chi-squared (multiplicative) leaves, so yi=f(xi)+s(xi)ϵiy_i = f(x_i) + s(x_i)\epsilon_i, coupled to the mean forest through the per-observation precision. variance is either the plain selector naming which predictors drive the variance - a character or integer column selector, TRUE for every predictor, a one-sided formula (~ x1 + x2) read exactly as varianceForest() reads its first argument (terms matched to the fit's predictors, the dot and transformed terms taken, *, : and I() terms refused), or NULL (the default) or FALSE for the ordinary homoscedastic fit, as do an empty selection (character(0), integer(0), logical(0)) and the formula ~ 1, which name no predictor (varianceForest(~ 1) and ~ 0 are refused) - or a varianceForest object, which additionally sets the variance forest's own tree count (default 40) and tree-structure prior (default the mean forest's base and power); a varianceForest with no vars reads every predictor, matching TRUE. Gaussian and "aft" (survival) responses and constant leaves only (a linear() or gp() leaf prior, dbartsPriors, is refused by name); monotone constraints and the latent families ("probit", "logistic", "ordinal", "nbinom"), which route their own precisions through the channel the variance forest divides into, are not supported. Under "aft" the model is log⁡T=f(x)+s(x)ϵ\log T = f(x) + s(x)\epsilon, so the dispersion of log survival time varies with xx and each right-censored observation's latent log-time is redrawn at its own s(xi)s(x_i); survivalProbabilities then divides by that surface rather than a scalar. family = student() residuals are also refused together with variance. The per-tree leaf prior is calibrated from the residual prior's (family = gaussian(sigma = )) hyperparameters so that a constant variance surface reproduces the homoscedastic sigma posterior. With two or more variance trees that calibration matches the prior mean of σ2\sigma^2, which is finite only above df 2, so a chisq() residual prior of df 2 or below is refused there, at creation and by setModel; a variance forest of one tree takes the residual prior itself, at any df. The fit gains posterior draws s.train/s.test of s(x)s(x), and predict attaches an "s" attribute with s(x)s(x) at new predictors (requires keepTrees). s(x)s(x) is the fit's residual scale wherever one is reported or drawn at: extract(type = "loglik") scores at s(xi)/wis(x_i)/\sqrt{w_i}, type = "ppd" draws its noise there, and summary.bart summarizes mean.s in place of sigma; extract and predict return it as type = "sigma". Such a fit carries no sigma or first.sigma, and the sampler's getSigmas() returns NULL: the engine holds the scalar fixed, so it carries no posterior content. The constructor resolves by bare name inside this argument, whatever the caller has attached, and a bare name the caller has bound to a value is that value; see dbartsForests.

forests

Optional list of forest specifications, or a single forest() for a list of one, declaring the ensembles the mean is a weighted sum of, instead of the single ensemble NULL (the default) fits. Each forest carries its own tree count, structure prior, leaf scale, column restriction, interactions/blocks constraints and, where it states them, proposal.probs, n.perturb.cuts and treeShift; a forest given a basis enters the mean multiplied by the amplitudes on that basis's columns. Any number of forests may be declared, each carrying a basis of one numeric column or of two levels (see forest's basis item); the two-forest case with a two-level factor basis has the shape of the Bayesian causal forest y=aμ(x)+bzτ(x)+ϵy = a \mu(x) + b_z \tau(x) + \epsilon: a prognostic forest μ\mu over every predictor and a modulating forest τ\tau over the columns its vars allows, aa being 1 unless μ\mu states amplitude = student(1). Any number of forests may have no basis, at any place in the list; one that states no sd takes this function's leaf prior as a single forest does, held at 1, and two or more of them share it as one prior total, each an equal part of its variance (see forest's Details), which is where leaf.prior, a k prior and a non-default k are taken beside other forests. A forest's default tree count and tree prior go by whether it has a basis: a forest with none takes this function's n.trees, power and base, several stating no count splitting n.trees among them as blocks does, and a forest with one takes 50 trees under base = 0.25, power = 3, wherever each stands. Where every forest has a basis, a stated n.trees and a named power, base, leaf.prior, interactions or blocks have no forest to belong to and are refused, the default's own value included; state them on a forest. Where only some forests have a basis, a power or base stated here and on every forest with none is refused as one thing given twice; beside two or more forests with no basis, interactions and blocks are refused here and stated on a forest. A single declared forest carrying a basis is refused: for varying coefficients declare an intercept forest plus one basis forest per covariate, forests = list(forest(), forest(basis = z1), forest(basis = z2)), or use one forest with linear() leaves. A basis is written as the right-hand side of a model formula, without the tilde, and read as lm reads one: a name of a column of the data is that column, + separates columns, and anything that names no column is what it was where forest() was called; a single string, basis = "z", names column z; see forest's basis item. The data a name is read from first are data, the matrix formula at the matrix interface, by its column names, and beside a dbartsData object what that object holds: the frame it keeps, or the columns it holds, its predictors and response and the bases of a sampler's data by the text each was written as. A basis handed over as a value has one entry for each row of the data handed over, before subset and the na.action, and is cut with them; one of the kept length where rows were dropped is refused. Every forest has a label, fixed when the sampler is created: the name its place in the list has, forests = list(prognostic = forest(), treatment = forest(basis = factor(z))); without one the text of its basis, "factor(z)"; and without that, for a forest with no basis or with one handed over as a value, forest<i> by its position. Two names alike are refused, as is a name of the form forest<i> at another position, and a basis text that repeats an earlier label takes a suffix, dose, dose.1. The labels are attr(fit, "forest.labels") on a bart fit, and $setForest and the sampler's readers select a forest by them or by its position. Gaussian, "probit" and "logistic" responses: under a latent family the forests combine into the index rather than into the mean, on the link's own fixed scale, so every forest's sd is stated in units of the latent index, sigma is pinned and there is no response transform to re-anchor. "aft", "ordinal" and "nbinom" are refused at creation, each naming what it is missing. The control's proposal.probs mixture reaches every forest of the declaration that states none of its own, the frozen mixture included: an all-zero mixture holds those forests' tree structures, and their leaf values move with the per-forest amplitudes, sigma and the family's latents. The result is an ordinary dbartsSampler; per-forest fits and the per-forest amplitudes are read off the sampler rather than from the run's combined train channel. The columns of each basis are stored on the sampler's data object, as data@bases, named as lm would name them, on the rows subset and the na.action keep, and survive a sampler's re-creation. Beside any data, a sampler's data included, the list states the forests in full, as dbartsSpec reads it: a forest declaring no basis has none, a list of forests with no basis gives that many plain forests, and no list gives one forest; a forest keeps a basis a sampler's data hold by writing it as it was written, forest(basis = factor(z)), and keeps with it the scale recorded when the sampler was first created. In a hazard fit a basis has one value per subject, cut by subset and the na.action and repeated over the subject's periods. Options a two-forest model does not read - monotone, variance, a non-uniform split.probs (a vector or dart()), a linear or Gaussian-process leaf prior, a k hyperprior or non-default k where no forests share a total, Student-t residuals, storage = "single", per-column cut counts, and a test set - are refused at creation rather than ignored, as is any declaration the engine cannot honor. The constructors forest, interactions and blocks resolve by bare name inside this argument, whatever the caller has attached, and a bare name the caller has bound to a value is that value; see dbartsForests.

n.trees

The number of trees of the forest with no basis; NULL, the default, leaves it to the forest's own n.trees and otherwise takes 75 trees. Given beside a forest with no basis that states its own, or where every forest has a basis, it is refused by name.

n.cuts, useQuantiles

The maximum number of cut points per predictor and whether to place them at the predictors' quantiles. n.cuts is one number for every column, one per column, or named, as split.probs is, by column or term name with .default for the rest; see bart. NULL, the default, takes what a dbartsData object given as formula holds, and otherwise 100 and uniformly spaced. A value given beside a data object that carries a grid derives the grid again.

control

An object inheriting from dbartsControl, created by the dbartsControl function, holding the run settings. The tree count, the cut count and the quantile rule are not its settings: state them as n.trees, n.cuts and useQuantiles (or on a forest), since a value written on a control is read only with a warning, once per session, and is removed in dbarts 1.1-0. A control taken from a fitted sampler carries its run settings and nothing else into this fit; a count or rule it carries that differs from what this call takes draws a warning, on every call, saying it is not used.

sigest

A positive numeric estimate of the residual standard deviation supplied at creation, or one of "auto", "dense" and "sparse", naming how one is made: each gives the residual standard deviation of the linear regression of the response on the predictors and on each forest's basis (a factor's as the indicator of its second level), factors entering as indicator columns whatever the trees are given, and, where that regression leaves no residual degrees of freedom, counting each row once, not as often as its weight, under weights read as counts, the standard deviation of the response over the observations of positive weight, weighted as the regression is (summary(lm(y ~ 1, weights = weights))$sigma, sd(y) at unit weights; for weights read as counts, the standard deviation of the rows written out, or sd(y) over the observations of positive weight where the counts total at most 1, up to the rounding of their sum), which a line under verbose says, with no warning (the summary of a bart fit says it too). "auto" is lm's own routine ("dense") for a matrix or a data frame and an exact sparse one ("sparse") where the caller supplied a sparse-stored column. NULL (the default) is "auto"; an explicit NA is a missing value and is refused. Given a data object in place of a formula, including a sampler's data, a new fit calibrates from that data's response: the response's scale and this estimate are derived from it, not read from records the sampler wrote, unless sigest states a number; dbartsSpec reads a data object the same way, and a sampler's copy() is the way to the same model again. Spelled the same way on bart, bartBT and xbart; the sampler's own setSigma, which sets the parameter rather than an estimate of it, is a different thing and keeps its own name. "sparse" needs the Matrix package. It agrees with lm to rounding except on nearly dependent columns (a near-copy of another column, a tiny spread beside a large mean), where it may drop a column lm keeps, and on several complete sets of a caller's own one-hot columns in some millions of weighted rows, where it may keep one lm drops; its last digit follows the BLAS library and its thread count, so a seeded fit reproduces at a fixed BLAS and thread count; and it reads a sparseFactor, not a caller's own one-hot columns, as a factor. Pass "sparse" for a data frame with a factor of thousands of levels, and "dense" for lm's handling of nearly dependent columns or for a sparse fit's draws to match its dense twin's. No size turns the estimate off: "sparse" factors a square matrix as wide as the columns left beside the widest factor and can fail to allocate it, "dense" holds rows times columns doubles, and neither can be interrupted once it has begun, so a verbose fit first prints what it is about to compute. For an expensive estimate pass a number instead: sd(y), which is too high where there is linear signal; the residual standard deviation of a regression on a random subset of the rows; or the root of the cross-validated error of a lasso (sqrt(min(glmnet::cv.glmnet(x, y)$cvm))) for a wide or sparse x. It is the estimate a chisq residual prior's quantile is calibrated against, so it stands beside family = gaussian(sigma = chisq(df, quant)) and has nothing to calibrate beside family = gaussian(sigma = fixed(value)), which fixes the residual scale outright: no estimate is made there, by any rule, the fit reports the square root of value as its sigest, and a number that differs from it is refused. An estimate that equals that square root (to within a few units in the last place) is accepted with a message saying it has no effect, as 0.9-34 ran it; that is an error from dbarts 1.1-0.

na.action

A function that filters incomplete rows, as lm takes one. The default na.keepPredictors drops rows with a missing RESPONSE and keeps rows with missing predictors, which every split rule routes by a learned direction; na.omit, na.exclude, na.fail and na.pass keep their usual meaning, and under na.pass a missing response is an error; NULL applies no action, as in lm, on the formula and matrix interfaces alike, so a missing response is an error. A row whose weights or offset is missing is dropped by na.omit and na.exclude as one with a missing predictor is, on the matrix interface as on the formula one; every other action leaves it to the refusal of that argument. See na.keepPredictors.

...

Not used for new code: the channel that lets a retired argument spelling (resid.prior, which now rides family - the residual prior as family = gaussian(sigma = ), which is its one home, so writing it both ways is refused where the two disagree; see dbartsFamilies; and proposal.probs, which now rides control, built with dbartsControl(proposal.probs = )) reach a message naming its successor instead of R's own “unused argument” error. Any other name is refused. Removed in dbarts 1.1-0.

sigma

The 0.9-x spelling of sigest, accepted for one release with a once-per-session warning and removed in dbarts 1.1-0. Supplying both is an error.

node.prior

The 0.9-x spelling of leaf.prior, accepted for one release with a once-per-session warning and removed in dbarts 1.1-0. Supplying both is an error.

tree.prior

The 0.9-x spelling of the tree prior, accepted for one release with a once-per-session warning (class dbartsDeprecatedWarning) and removed in dbarts 1.1-0. The value is used, as the plain arguments it states: tree.prior = cgm(power = 3) is power = 3, cgm(3, 0.5) is power = 3, base = 0.5, and dart(a = 1) is split.probs = dart(a = 1); a prior object, such as one saved by 0.9-34, states its power and base, and its split probabilities where they are not uniform. Given beside power, base or split.probs it is an error. NULL states nothing.

callback

NULL (the default) or a list with two elements, fn and context, each an R external pointer (externalptr): fn the address of a compiled dbarts_draw_callback (inst/include/dbarts/dbarts.h) and context an opaque pointer handed back to it unchanged, or NULL. Only that both are external pointers is checked here - the address is dereferenced exactly as handed, so a malformed pair crashes the session with no condition to catch, once the returned sampler is actually run. dbarts itself never runs the sampler it builds, so this argument has no other effect here beyond that validation; register it again on the actual run call (or use bart, which threads a single callback through both). See bart's callback item for the three warnings and dbartsControl's keepFits for the storage opt-out this argument does not, by itself, set here.

seed

Optional integer seed for the random number generator, a convenience mirror of dbartsControl(seed = ). NULL (the default) means not given here: it leaves control's own seed in force, seeded or not; an NA is a missing value, as in set.seed, and is refused. A single finite number overrides the seed in control. bart and xbart accept the same argument and resolve it identically. See the Reproducibility section of bart.

factors

How factor columns in a data frame enter the model. The default "categorical" keeps each unordered factor as a single predictor whose splits send a subset of its levels (at most 65535) down each branch, and keeps each ordered factor as a single predictor split at a threshold on its level codes, its candidate thresholds the midpoints between consecutive declared levels (at most 65534 levels, one fewer than an unordered factor, and n.cuts does not apply); level tables are retained so that test data are coded identically. A factor's level count, ordered or not, is the declared level table, not the levels the training rows happen to take, so a declared but unobserved level keeps its own bin and test or replacement data carrying it are accepted (droplevels beforehand to model only the observed levels). "indicators" expands each factor into binary indicator columns, as previous versions always did and as bartBT still does; its training levels are kept too, so a test factor is matched to them by label, as in lm, and a level with no training rows, which has no indicator column, is refused by name. Subset splits let a single split separate any grouping of a factor's levels, where indicator columns need a chain of splits to do the same, and they give a factor the prior split probability of one predictor rather than one per level.

family

The response model. "auto" fits gaussian models to continuous responses and probit models to those coded 0/1, as always; a Surv response is fit as "aft", and an n x K matrix (K >= 3) of non-negative whole numbers on the matrix interface as "multinomial" (a formula with a cbind left-hand side is refused here, naming bart; a two-column matrix is refused, naming the readings, successes and failures under family = binomial and (time, status)). A two-level factor, logical, or two-level character response is also detected and fit as probit. Every resolution of "auto" is reported in a one-line message naming the family fit (printed only under verbose = TRUE), while an unordered factor (or character) response with three or more levels is an error directing to bart's family = "multinomial". An explicit family that a factor response cannot support (e.g. "gaussian") is also an error rather than a silent fit of the integer level codes. "gaussian" forces a continuous fit even for a 0/1 numeric response; "probit" and "logistic" require a 0/1 response (one holding a single class is fitted with one warning saying so, the prior alone then driving the fitted probabilities toward 0 or 1) and fit latent-variable models, with fits and predictions on the latent scale. "logistic" uses Polya-Gamma augmentation, and also takes a binomial response, an n x 2 matrix of successes and failures, or cbind(successes, failures) on a formula, as glm does: a row's trials are its row sum, a row of no trials enters no likelihood and is still fitted, and a weight counts the row that many times (see bart). Base R family objects map as glm takes them (binomial is the logit link, so family = binomial is "logistic", not probit) and the rest are refused; see dbartsFamilies.

"aft" fits an accelerated failure time (log-normal) survival model: the response is a Surv object (from the survival package) or a two-column (time, status) matrix or data frame (status 1 an event, 0 right-censored; logical status also works, factor status does not), and survivalProbabilities produces survival-probability draws. Fits and predictions are on the log-time scale (E[log⁡T∣x]E[\log T \mid x]), not the time scale. A Surv response selects "aft" automatically when family is "auto"; an explicitly conflicting family (e.g. "gaussian") with a Surv response is an error. A Surv-like object carrying no type attribute is treated as right-censored; types other than "right" are rejected. The response may also be a Surv left-hand side on formula (e.g. Surv(time, status) ~ .); both interfaces honor subset. Case weights are not supported. See weights for how the families differ in their support for weights.

"multinomial" fits an unordered K-category response by a softmax of KK forests, one per category, with the interleaved one-vs-rest Polya-Gamma augmentation. The response is an n×Kn \times K matrix of non-negative integer counts - column kk holding category kk's successes, with trials ni=∑kyik≥0n_i = \sum_k y_{ik} \ge 0, no larger than 10610^6 since each trial costs a Polya-Gamma draw per category per sweep - or, the single-trial special case, a factor or character vector (a numeric or logical one is refused, as bart refuses it: a number names no category), which is one-hot expanded to exactly that matrix with every trial 1. Column names on the matrix, or the levels of a factor, label the categories. A data frame of numeric columns is read as its matrix, and a one-column character matrix as its vector of labels; a wider character matrix, or a data frame with a column that is not numeric, is refused, as bart refuses it. Under family = "auto" a matrix of three or more columns of non-negative whole numbers is read as this model, but a three-or-more-level factor is not - it is an error directing here, since an unordered categorical response is equally a candidate for several models. The response rides dbartsData's counts argument, and data@y is the derived trials vector; the per-category shift is an n×Kn \times K matrix offset (entering the values before the softmax), never a flat one, which the blend is invariant to and which is therefore refused. Fits and predictions are the KK category probabilities, summing to one across the second dimension. A row with no trial contributes nothing to the likelihood and still receives fitted probabilities, as glm fits a row of zero prior weight; the first such row a sampler takes in a session warns. Like probit there is no residual scale to draw, and weights are not supported: an integer case weight is already row-wise replication in the count response, and a non-integer one has no exact augmentation sampler. The sampler is an ordinary dbartsSampler whose response and per-category offsets are mutable through $setResponse, which takes the count matrix, $setCategoryOffset and $setCategoryTestOffset; see dbartsSampler-class for what the softmax refuses and why. monotone, a non-uniform split.probs (a vector or dart()), a linear or Gaussian-process leaf prior, a k hyperprior, a named prior.scale, variance and storage = "single" are refused at creation rather than dropped, and the response uses the matrix (x.train/y.train) interface.

"ordinal" fits an ordered categorical response by a cumulative probit: a latent z=f(x)+ϵz = f(x) + \epsilon, ϵ∼N(0,1)\epsilon \sim N(0, 1), is cut at ordered thresholds γ1=0<γ2<…<γK−1\gamma_1 = 0 < \gamma_2 < \ldots < \gamma_{K-1} into the KK ordered categories, the free thresholds sampled by a marginal Metropolis update with the latents integrated out. The response should be an ordered factor (is.ordered), whose level order defines the category order; under family = "auto" an ordered factor with three or more levels is detected and fit as ordinal, reporting the choice in a one-line message (a two-level ordered factor is binary and resolves to probit). family = "ordinal" given explicitly also accepts an unordered factor or character response - with a message that the category order is taken from the level order - and a numeric response, whose ordered levels are sort(unique(y)). Like probit, the latent scale is fixed at 1, fits are on the latent scale, and weights are not supported. bart reports ordinal fits as n×Kn \times K category probabilities; see bart.

"nbinom" fits a non-negative integer (count) response by a negative-binomial model on a log link with the Polya-Gamma augmentation: the forest fits the log mean η=f(x)+c+o\eta = f(x) + c + o and y∼NB(size=r,mu=eη)y \sim \mathrm{NB}(\mathrm{size} = r, \mathrm{mu} = e^{\eta}), so the offset enters the mean multiplicatively as a log-exposure; cc, the log of the total count over the total exposure, is a data transform that centers the leaf prior, and fits carry it. The response must be a non-negative integer no larger than 10610^6 (the shape grid's count histogram is sized from the largest count), and "nbinom" is never inferred - a count carries no unambiguous class, so it must be requested explicitly. The shape r is estimated by default (see shape); like probit, there is no residual scale, fits are on the log-mean scale, and weights are accepted only as 0 and 1, marking rows in and out of the likelihood (exposure belongs in the offset). bart reports mean counts; see bart.

"hazard" and "hazard.logistic" fit a discrete-time survival hazard model by person-period expansion ("hazard.probit" is an accepted alias for "hazard"). The response is the same Surv object or two-column (time, status) the "aft" family takes, but each subject observed to time tit_i is expanded into its at-risk rows (one per period k=1,…,tik = 1, \ldots, t_i), each carrying the subject's covariates, an ordinal period column appended last, and the binary indicator yik=statusi⋅1{k=ti}y_{ik} = \mathrm{status}_i \cdot 1\{k = t_i\}; the discrete hazard is then h(k∣x)=g(f(x,k)+o)h(k \mid x) = g(f(x, k) + o) for the chosen binary link gg (probit for "hazard", logistic for "hazard.logistic"), and the fit IS an ordinary "probit"/"logistic" fit on the expanded rows - it adds no engine code. The time grid is the sorted distinct observed times of the subjects in the likelihood, those of positive weight, by default; hazard(breaks = ) replaces it with a given number of quantile bins or with explicit interval boundaries (see dbartsFamilies). The offset is on the link scale and replicates per subject; weights replicate and follow the chosen binary family's policy. A Surv response requires the family to be requested explicitly ("auto" selects "aft"), on either interface - a Surv left-hand side on formula works too, and both interfaces honor subset (applied before the person-period expansion). A hazard fit whose person-period response holds one class, every subject censored or every subject's event in its first period, is fitted, with one warning saying so; the prior alone then drives the hazards toward 0 or 1, and the survival curves sit where the prior puts them. Survival curves come from survivalProbabilities, which requires keepTrees unless reading a stored test set with sample = "test" (below); bart reports the fit with its $periods grid, and its $family records the binary link. Both interfaces accept a test set, person-period-expanded on the SAME period grid as training (no event time - every subject expands to every period); survivalProbabilities with sample = "test" then reads its hazards straight off the fit with no keepTrees needed (the call with no newdata is always the training subjects).

"hurdle.lognormal" fits a semicontinuous two-part (hurdle) model for a non-negative response with exact zeros: a zero-part probit fit of z=1{y>0}z = 1\{y > 0\} over all n observations, glued at report time to a lognormal positive-part fit - an ordinary gaussian fit of log⁡y\log y - over the subset {i:yi>0}\{i : y_i > 0\}; the two parts share no parameters and are composed from two ordinary fits at independently derived seeds, so no engine code is added and a shared variable-selection prior across the parts is not available. y.train must be non-negative and finite and must carry at least one exact zero and one positive value. By default, predictions report the natural (response) scale via posterior-predictive Monte Carlo, E[y∣x]=P(y>0∣x) ef(x)+σ2/2E[y \mid x] = P(y > 0 \mid x)\,e^{f(x) + \sigma^2 / 2}, using the positive part's single σ\sigma per draw (the positive part is always homoscedastic); see bart for the full type options ("prob", "link"/"log", the bimodal "ppd"). bart takes a formula, test, subset, offset and weights of 0 and 1 on this family; see there. dbarts() does not fit this family: it composes two samplers, which only bart builds, so requesting it here is an error directing to bart().

weights.type

How weights are read. Under "precision" a weight scales a row's residual variance, y∣x∼N(f(x),σ2/w)y \mid x \sim N(f(x), \sigma^2 / w), as lm reads weights. Under "frequency" a row of weight ww stands for ww identical observations, so the posterior is the one for the data with each row written out ww times, a real ww raising the row's likelihood to that power; a weight of 0 is a row out of the likelihood under either. NULL (the default) is each family's own reading, which the sampler records: precision where there is a residual scale, and frequency everywhere else, where a weight counts identical observations or, on the families with a latent no weight can scale, marks a row in or out of the likelihood at 0 and 1:

family NULL reads "precision" "frequency"
gaussian, student, a variance forest precision taken, real w≥0w \ge 0 taken, real w≥0w \ge 0
logistic, hazard.logistic, nbinom, multinomial frequency, counts refused whole w≥0w \ge 0
probit, hazard, hazard.probit, ordinal frequency, membership refused 0 and 1 only
aft precision, no weights no weights refused

Under "frequency" on a gaussian-type fit, the starting sigma (sigest) is the residual sd of the regression on the rows written out, its degrees of freedom the total weight less the regression's rank, a total within rounding of the rank leaving none, the sd stand-in a weighted one (unweighted where the counts total at most 1); the residual scale's posterior counts ww observations at a row; a row's predictive draw is one observation at sd σ\sigma; its log-likelihood is ww times one observation's; and predict takes weights of 1 and 0 only. Under Student-t, a row's latent precision ($getLatents()) is the composite of its ww copies'. A frequency weight is data, not a design weight: weights rescaled to sum to 1 leave σ\sigma one observation's worth of data, survey or inverse-probability weights are not counts, and ww copies of a continuous response are exact ties, which the fit reads as nearly noiseless data. A 0/1 response's weight is always a count of identical rows. The reading is fixed when the sampler is created: $setModel cannot change it, and $setWeights, $setData and predict read new weights under it.

Details

A sampler in which every predictor holds one value is created, unlike a bart fit, which refuses one: its trees have no cut point until $setPredictor gives a column values that differ.

“Discrete sampler” refers to that dbarts is implemented using ReferenceClasses, so that there exists a mutable object constructed in C++ that is largely obscured from R. The dbarts function is the primary way of creating a dbartsSampler, for which a variety of methods exist.

Data frame ingestion

Data frame input is stored columnar: no n×pn \times p predictor matrix is retained. Code that previously reached into the sampler's stored data expecting a plain matrix should call extract(sampler, "predictors") - or as.matrix on it - to obtain the numeric predictor matrix, factor columns as their integer codes. See dbartsData for the column-type mapping (numeric, factor, sparse, and sparseFactor).

Test offset synchronization

When offset.test is left at its default and that evaluates to the training offset itself (a scalar, or a vector given for as many rows), the sampler links the two: the sampler's setOffset method re-derives offset.test from each new offset it is given. Calling the sampler's setTestOffset or setTestPredictorAndOffset methods breaks this link – offset.test is set independently from then on, and the link never re-forms, even if the two are later set to equal values.

Response scaling

Continuous responses are range-scaled internally: y (net of offset) is mapped to [−0.5,0.5][-0.5, 0.5] by its observed minimum and maximum, the convention of the entire BART software lineage (BayesTree, BART, bartMachine), which is what lets k (see leaf.prior above) and its defaults transfer across packages and papers. The known caveat is outlier sensitivity: extreme y values stretch the range and compress the effective leaf prior for everything else; the published workaround is to log-transform or winsorize such values before fitting, or to let k adapt via the chi hyperprior (dbartsPriors). The scale is fixed when the sampler is created; the sampler's setResponse, setOffset, setWeights and setActiveRows methods only re-anchor it when called with updateScale = TRUE, intended for burn-in only, since re-anchoring mid-run makes fits across iterations no longer comparable (see dbartsSampler-class).

Naming the leaf prior by k or sd

Because the leaf prior's k is relative to the range of the response the sampler was CONSTRUCTED on, an R program that drives the sampler between sweeps – feeding it latents, residuals, or offsets from an outer model – inherits whatever spread its construction vector happened to imply. leaf.prior = normal(sd = ) names the spread instead, on the family's scale (response units for a continuous response; see dbartsPriors for the table): the prior standard deviation of the forest total's leaf parameter, a number or an invchi hyperprior on it. The prior mean is the response transform's shift ((max(y) + min(y)) / 2, net of offset, for a continuous response; 0 for the latent-scale families). k and sd are exclusive. Unset, nothing changes.

The named sd is the sd of the normal prior on the leaf model's own parameter. It equals the prior standard deviation of f(x)f(x) at every xx for the constant leaf only; under the other leaf models the prior of f(x)f(x) is x-dependent and sd bounds it in a leaf-model-specific direction. Under a linear leaf prior it is a LOWER bound, attained at the standardized covariate origin, with sd(f(x))sd(f(x)) equal to sd times 1+∥z(x)∥2\sqrt{1 + \|z(x)\|^2} for zz the internally standardized leaf covariates (a missing value maps to zj=0z_j = 0, and a constant column contributes 0); the prior mean is exact. Under a gp leaf prior it is an UPPER bound over xx, attained at rows reproducing a leaf member and on leaves past max.leaf.size (which draw as constant leaves); elsewhere the prior variance is sd2c(x)′C−1c(x)sd^2 c(x)' C^{-1} c(x) and decays to 0 as xx leaves the leaf's data cloud, at which point every prior draw equals the prior mean exactly. Under a monotone constraint it is the sd of an unbounded leaf value (dbartsPriors states the construction) and a LOWER bound in the interior – the realized standard deviation runs a few per cent to about 20% above it – and the prior mean is NOT the prior mean of f(x)f(x): the constrained marginal is skew, with an x-dependent mean that tracks the constraint direction and spans several prior standard deviations along the constrained axis (see monotone above).

A named sd is absolute. It is applied at creation and re-derived at every setModel against the response transform then in force, and the sampler restates it after every channel that re-anchors the transform (setResponse, setOffset, setWeights or setActiveRows with updateScale = TRUE, and setData), so a fixed sd means the same spread throughout, and an invchi prior on it the same prior; setLeafPrior changes it, and the restatement then uses the latest write. The current value of a drawn sd is the sampler's k, which a re-anchor leaves, so it lags until its next draw (see dbartsSampler-class). A k, relative to the data, moves with the transform instead. Two-forest (forests) and multinomial models take their forests' leaf scales from their own calibration maps and refuse a named sd rather than drop it; a forest of the first states its own, in the response's units (see forest).

Value

A reference object of dbartsSampler.

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.

Pratola, M.T., Chipman, H.A., George, E.I., and McCulloch, R.E. (2020) Heteroscedastic BART via multiplicative regression trees. Journal of Computational and Graphical Statistics, 29(2), 405–417.

Twala, B.E.T.H., Jones, M.C., and Hand, D.J. (2008) Good methods for coping with missing data in decision trees. Pattern Recognition Letters, 29(7), 950–956.

See Also

dbartsData, extract.dbartsSampler, sparseFactor

Examples

set.seed(8)
n <- 100L
x <- matrix(runif(n * 3L), n, 3L)
y <- 2 * x[, 1L] - x[, 2L] + rnorm(n, 0, 0.2)

control <- dbartsControl(n.chains = 1L, n.threads = 1L, n.burn = 0L,
                         n.samples = 1L, updateState = FALSE)

## The sampler is created once and then run repeatedly, so that BART can act
## as a conditional model inside a larger Gibbs/Metropolis-Hastings sampler.
sampler <- dbarts(y ~ x, control = control, n.trees = 25L)
samples <- sampler$run(numBurnIn = 50L, numSamples = 1L)
str(samples$train)

## an outer step revises the response; the sampler picks it up on the next
## run() without being rebuilt. The prior scale set at creation stays locked
## unless updateScale = TRUE is passed (burn-in only).
sampler$setResponse(y + rnorm(n, 0, 0.05))
samples <- sampler$run()

## priors are given as expressions in dbarts's own vocabulary
sampler <- dbarts(y ~ x, control = control,
                  power = 1.5,
                  leaf.prior = normal(k = chi(1.5, 2)),
                  family = gaussian(sigma = chisq(df = 5)), n.trees = 25L)

## an additive fit that is monotone increasing in the first predictor
sampler <- dbarts(y ~ x, control = control,
                  interactions = interactions(max.order = 1L),
                  monotone = c(1, 0, 0), n.trees = 25L)
samples <- sampler$run(numBurnIn = 20L, numSamples = 5L)

## a non-gaussian family: counts by negative binomial, offset a log-exposure
counts <- rnbinom(n, size = 4, mu = exp(0.5 * x[, 1L]) * 4)
sampler <- dbarts(x, counts, family = "nbinom", control = control, n.trees = 25L)
samples <- sampler$run(numBurnIn = 20L, numSamples = 5L)

Embedding dbarts In A Larger Sampler

Description

Reference for using BART as a conditional model inside a Gibbs or Metropolis-Hastings scheme the caller writes: which channel an outer block writes, which fit it reads back, whose prior is in force after a swap, and how a composition is checked. The runnable set is vignette("dbarts-as-a-component", package = "dbarts"), six named recipes with their output; this page is the rule each of them applies.

Details

A dbartsSampler is created once by dbarts and then run one sweep at a time with run(0L, 1L), its inputs replaced between sweeps. The fitting functions bartBT and bart own their own loop and are not the surface for this; they return fit objects, and the R modeling accessors (fitted, predict, extract) apply to those.

The channels an outer block writes

Each method replaces one input in place, on every chain, taking effect at the next sweep. All of them are documented in dbartsSampler.

method what the outer block owns typical use
$setResponse(y) the regression target a partial residual, a working response, an imputed outcome
$setOffset(o) an additive term BART does not fit another block's linear predictor, a fixed exposure
$setWeights(w) per-observation precision, or under weights.type = "frequency" a count of identical observations a Polya-Gamma precision, a variance mixture; under frequency, fractional counts such as expected memberships
$setSigma(s) the residual standard deviation a scale drawn elsewhere; use with family = gaussian(sigma = fixed()) so the next run() does not redraw it
$setPredictor(x, column) one predictor column a latent covariate, an imputed predictor
$setActiveRows(a) which rows enter the likelihood a subset indicator drawn by another block
$setLeafPrior(normal(sd = )) the leaf prior's spread stating the prior a cold-start vector did not

A predictor moved per observation rather than wholesale takes $setPredictor(x, column, forceUpdate = "partial"), or updatePredictorPerObservationJointly when several samplers share the column. Both return a per-observation install mask, FALSE where the new value would empty a leaf and was rolled back; under a monotone constraint the joint form also declines a value that would leave a tree's leaf values out of order. That mask is part of a Metropolis accept decision, not a diagnostic: a declined observation holds its old value, so the likelihood read after the call is its old likelihood, and treating the resulting ratio as an acceptance leaves the outer sampler's copy of the latent disagreeing with what the samplers hold.

Not every channel is open on every model. A refusal is part of the model rather than a limitation - setSigma on a family that fixes the residual scale by definition, a response swap that would re-anchor a calibration stated at creation - and each names its reason.

When the augmentation variables are drawn

A sampler whose family augments its likelihood (the probit and ordinal latents, the Polya-Gamma precisions of logistic, binomial and nbinom, the Student-t scales, an aft sampler's imputed times) draws those values at the start of each sweep, against the fit the previous sweep left and the inputs in force, and then draws its trees against them. A sweep therefore runs in this order: the augmentation variables, then the trees, then sigma and the other parameters. No setter draws them: $setResponse, $setOffset, $setPredictor, $setSigma, $setWeights, $setActiveRows, $setForestBasis, $setData, $setModel and $setState store what they are given, and the next sweep draws the latents against the change.

Two kinds of outer step are both exact under this order. One conditions on the latent: it runs the sampler, reads $getLatents(), and draws its own quantity given those values. The other integrates the latent out, scoring a proposal with the probit likelihood pnorm(f) of the response, say, and then installing what it accepted; the next sweep draws the latents under the accepted values, so the trees never fit a latent drawn before the change. The order is also what makes a setter call and a restore undo each other exactly: $setWeights with the old weights and $setState with the stored state, in either order, leave the sampler continuing bit for bit as one that installed the stored state under the old weights would.

Which fit to read back

Six methods report a fitted quantity and no two report the same one; the table in ‘Reading the fit’, dbartsSampler, is authoritative. The rule an outer block needs: it conditions on f(xi)f(x_i), so it reads $getFitsWithoutOffset() and adds back whatever offset it installed. run()$train reports the same location with the offset folded in. The location latent of "probit", "ordinal" and "aft" that $getLatents() reports is on that same offset-inclusive scale, z=f(x)+o+ez = f(x) + o + e, so the difference z - train is the residual ee, which carries none of the offset's signal. A block that owns the offset regresses z - $getFitsWithoutOffset(); used the other way, the offset reaches it as a coefficient shrunk toward zero rather than as an error. The latent of "logistic", "nbinom" and a Student-t residual distribution is a precision, a location at no scale, with no offset in it; dbartsWorkingResponse gives the offset-free working response for any of them.

$getLatents() returns the values the last sweep's trees were drawn from, so after a run it and $getFitsWithoutOffset() are a joint draw, the latent being the value the fit was drawn from. Between a setter and the next run it returns the values from before the setter ($setData starts them as creation does, an ordinal or negative-binomial sampler from the kept cutpoints or shape, and an aft $setResponse leaves a censored row at its new bound), not values drawn against the change; the next sweep draws them afresh.

Whose prior is in force

The leaf prior is calibrated once, at creation, from the response the sampler was built on. A per-sweep setResponse deliberately does not re-anchor it (updateScale = FALSE, the default), so that the sweeps are comparable - which also means a sampler built on a cold-start vector keeps that vector's range as its prior scale for the whole run, and its midrange as the prior's center (read back as $getLeafPrior()$prior.mean, which no setter writes except through the offset). State the prior instead of inheriting it: leaf.prior = normal(sd = ) at creation (see dbartsPriors), or $setLeafPrior(normal(sd = )) afterward, with $getLeafPrior() reporting what is actually in force. A caller whose rows enter and leave the likelihood asks for the scale to be taken again from the rows then in with updateScale = TRUE on $setWeights or $setActiveRows, in burn-in only, and a linear or gp leaf's covariate center and scale with updateStandardization = TRUE on the same call; FALSE after burn-in holds both, so every kept draw comes from one prior (see updateStandardization). A named sd is absolute: a channel that does re-anchor the transform leaves it where it was.

A decomposition across KK samplers needs the same care in the other direction. Each carries a prior sized for the whole of ff, so their sum has K\sqrt{K} times the prior standard deviation one sampler would have; dividing each prior.sd by K\sqrt{K} restates them as shares of one budget.

The seeding contract

The value in force during a sweep is the one installed before it. Create the sampler with the outer block's initial value already in place, and write the channel before run, never after: a sweep run against a stale offset, weight or response has drawn from the wrong conditional and nothing later reports it. The mutators store the state after each write when control@updateState is TRUE, the default, so a sampler driven a sweep at a time is built with dbartsControl(updateState = FALSE), as the vignette's recipes are; a per-sweep write then costs nothing beyond the write itself.

Augmentation written in R

The per-observation augmentation a non-gaussian sampler runs internally is callable directly: dbartsDrawLatents draws the latent at a supplied fit and dbartsWorkingResponse turns it into the quantity the outer sampler regresses on. An outer sampler that needs the latent for its own blocks runs the step itself over a gaussian sampler with family = gaussian(sigma = fixed(1)), rather than reimplementing the family. Their fit argument is offset-free, as $getFitsWithoutOffset() reports it.

Driving it from compiled code

A package that runs its outer block in C or C++ declares LinkingTo: dbarts and includes ‘dbarts/dbarts.h’, the flat C API. It builds the sampler in R from its own R code and then reads the handle out of that object's external pointer with R_ExternalPtrAddr ($getPointer() is what hands the pointer down). dbarts takes a formula or a matrix, not a model object, so a consumer starting from its own already-built (control, model, data) triple (dbartsSpec resolves one without constructing a sampler) builds the sampler instead with methods::new("dbartsSampler", control, model, data), then calls $getPointer() on the result. There is no creation entry point and no R type in the header; the handle is the whole boundary.

The handle is valid until the R object is garbage collected or replaces its pointer, which it does whenever it re-creates its engine from a stored state - after a load, or after $setState. Re-read the handle after any such restore, and keep the R object reachable for as long as the C side holds one.

What the header reaches is the per-sweep loop: dbarts_sampler_run into caller-owned buffers, the conditioning channels setResponse, setOffset and setSigma, getLatents, predict, tree storage and printing, and the queries the outer sampler sizes its results struct from, among them dbarts_sampler_numFittedValuesPerObservation and dbarts_sampler_numVariableCountForests, the widths of a multinomial or multi-forest sampler's fits and split counts; a flat run polls for R's interrupt as $run does and, once the workers have joined, raises it as R's interrupt condition (not an error: try() lets it through), leaving the sampler usable, with any saved results of that call to be discarded and a pass over the trees possibly partly applied; it also warns of a slow monotone leaf-order count once per sampler. Everything else in the table above - the predictor and weight channels, the active-row mask, the state round trip, tree extraction, the multi-forest surface - is an R method on the same object, and the two views drive one engine. The setters COPY what they are handed into buffers the sampler owns at creation, so the caller's array is free the moment the call returns and conditioning on new values means calling the setter again rather than writing through the array.

Checking a composition

Recovering a known truth on one simulated data set is weak evidence. dbartsValidateComposition runs simulation-based calibration over the composed one-sweep step and reports, per scalar functional, whether the kernel targets the posterior the stated prior and likelihood imply. It catches the defect class in which a posterior mean is reported where a draw belongs.

See Also

dbartsSampler for every method named here, dbarts for creating one, dbartsAugmentation for the augmentation helpers, dbartsValidateComposition for the calibration check, updatePredictorPerObservationJointly for the shared-predictor sweep, and samplePriorPredictive for inspecting a prior before fitting.


Augmentation Draws For A Composed Sampler

Description

The per-observation data augmentation a non-gaussian dbartsSampler runs inside each sweep, callable from R against R's own random number stream. dbartsDrawLatents draws the augmentation variable at a supplied fit - the quantity getLatents reports for that family - and dbartsWorkingResponse turns a drawn latent into the response the outer sampler regresses on. Neither touches a sampler: an outer sampler writing its own Gibbs step around BART, or around anything else, need not reimplement the family's augmentation.

Usage

dbartsDrawLatents(family, fit, y, weights = NULL, offset = NULL, sigma = NULL,
                  shape = NULL, thresholds = NULL, df = NULL)

dbartsWorkingResponse(family, latent, y, weights = NULL, offset = NULL,
                      shape = NULL)

Arguments

family

One of "probit", "logistic", "ordinal", "aft", "nbinom" or "student", matched by match.arg; there is no default. "student" is the Student-t residual distribution (family = student() in dbarts), a gaussian response under a scale mixture.

fit

A numeric vector of each observation's location without the offset - f(xi)f(x_i), what getFitsWithoutOffset reports, or however the outer sampler computes it. Its length sets nn.

latent

A numeric vector of length nn of drawn latents, as dbartsDrawLatents returns; positive for "logistic" and "nbinom", whose latents are precisions.

y

The response, of length nn, constrained exactly as the sampler constrains it: 0 or 1 for "probit" and "logistic", an integer category index in [1,K][1, K] for "ordinal", a non-negative integer count for "nbinom". For "aft" it is the log observed (censoring) time, the bound the drawn log survival time is truncated below at; "student" constrains nothing.

weights

"logistic" only, refused by name elsewhere: observation counts, positive whole numbers no larger than 10610^6, each entering as the sum of that many independent PG(1,ψ)PG(1, \psi) draws.

offset

A numeric vector of length nn added to fit to form the linear predictor, or NULL for none.

sigma

"aft" and "student" only: the residual standard deviation, in response units.

shape

"nbinom" only, and required there: the current shape rr, a positive whole number no larger than 10610^6, as getShape reports it. An "nbinom" location is a log mean, so the Polya-Gamma draw reads the log-odds ψi=fi+oi−log⁡r\psi_i = f_i + o_i - \log r.

thresholds

"ordinal" only, and required there: the K−1K - 1 strictly increasing category boundaries in force.

df

"student" only, and required there: the degrees of freedom ν\nu.

Details

The offset convention. fit is the location without the offset, the engine's own convention at every augmentation site, and the linear predictor is formed internally as fit + offset. The two arguments are therefore not interchangeable, and the pair of functions is what tells them apart: dbartsDrawLatents(fit = f, offset = o) and dbartsDrawLatents(fit = f + o, offset = NULL) draw from the same distribution and agree, while dbartsWorkingResponse differs between the two, the working response being stated in units the offset has been taken out of. Pass the offset as offset to both.

Why two functions. For "probit", "ordinal" and "aft" the latent is a LOCATION and the working response is that location less the offset. For "logistic" and "nbinom" it is a PRECISION - the Polya-Gamma ωi\omega_i - and what the outer sampler regresses on is wi(yi−1/2)/ωi−oiw_i (y_i - 1/2) / \omega_i - o_i and (yi−r)/(2ωi)+log⁡r−oi(y_i - r) / (2 \omega_i) + \log r - o_i respectively, under per-row precision weights ωi\omega_i. For "student" the latent is the scale-mixing λi\lambda_i, which weights the row rather than entering the response, so the working response is the gaussian one. An outer sampler that regresses on the latent itself is fitting a different model, which is the composition defect these functions exist to prevent.

Random numbers. The draws come from R's own stream, through a generator created and destroyed within the call: set.seed reproduces them, they advance the stream, and they compose with any other R draw. They never touch a sampler's chain generator, which is seeded separately and never advances R's stream. That stream is not thread safe, so these functions must not be called from a worker thread; call them on the main thread and hand the result to the workers.

Value

A numeric vector of length nn. dbartsDrawLatents carries a "quantity" attribute of "location" ("probit", "ordinal", "aft") or "precision" ("logistic", "nbinom", "student"), matching what getLatents reports for that family.

See Also

dbartsSampler, whose getLatents, getFitsWithoutOffset and getShape methods report the same quantities from inside a running sampler.

Examples

set.seed(99)
f <- rnorm(50L)
o <- rep(0.25, 50L)
y <- rbinom(50L, 1L, pnorm(f + o))

# one Albert-Chib step: the truncated-normal latent at the current fit, then
# the response the outer sampler regresses on
z <- dbartsDrawLatents("probit", fit = f, y = y, offset = o)
attr(z, "quantity")
head(dbartsWorkingResponse("probit", latent = z, y = y, offset = o))

# logistic draws a PRECISION, so its working response is a quotient, not the
# latent shifted
w <- dbartsDrawLatents("logistic", fit = f, y = y, offset = o)
head(dbartsWorkingResponse("logistic", latent = w, y = y, offset = o))

Discrete Bayesian Additive Regression Trees Sampler Control

Description

Convenience function to create a control object for use with a dbarts sampler.

Every integer-valued argument here (n.samples, n.cuts, n.burn, n.trees, n.chains, n.threads, n.thin, printEvery, printCutoffs, categoricalExhaustiveCap, testFitParallelCutoff, predictParallelCutoff, n.perturb.cuts, seed) refuses a fractional double, naming the argument, rather than silently truncating it - the same whole-number rule every other count formal in the package follows, since it too is coerced through this construction.

Usage

dbartsControl(
    verbose = FALSE, keepTrainingFits = TRUE, keepFits = TRUE,
    useQuantiles = NULL,
    treeShift = c("auto", "always", "never"),
    keepTrees = FALSE, storage = c("double", "single"),
    n.samples = NULL,
    n.cuts = NULL, n.burn = 200L, n.trees = NULL, n.chains = 4L,
    n.threads = min(dbarts::guessNumCores(), n.chains), n.thin = 1L, printEvery = 100L,
    printCutoffs = 0L,
    categoricalExhaustiveCap = 10L, testFitParallelCutoff = 65536L,
    predictParallelCutoff = 50000L, sparseDensityThreshold = 0.2,
    proposal.probs = c(
        birth_death = 0.6, swap = 0, change = 0.4, perturb = 0,
        rule_gibbs = 0, birth = 0.5),
    n.perturb.cuts = 1L,
    seed = NULL, updateState = TRUE, ...)

Arguments

...

Not used for new code: the channel that lets a retired argument spelling reach a message naming its successor, instead of R's own “unused argument” error. Any other name is refused. Removed in dbarts 1.1-0.

verbose

Logical controlling sampler output to console.

keepTrainingFits

Logical controlling whether or not training fits are returned when the sampler runs. These are always computed as part of the fitting procedure, so disabling will not substantially impact running time.

keepFits

Logical controlling whether every per-observation channel - training fits, test fits, the heteroscedastic variance surface, and per-forest fits - is returned when the sampler runs; keepTrainingFits is the narrower, longstanding switch over the training channel alone, unaffected by this one. FALSE allocates a per-chain one-draw SCRATCH buffer for each opted-out channel instead of an n.samples-wide array, which a per-draw callback (see bart, dbarts, and run) can read as each draw is produced without the run ever materializing the full array; variable counts and the scalar channels (sigma, k, ...) are kilobytes and are always kept, and keepTrees is the separate, unaffected recompute-from-saved-trees path. FALSE is the automatic default of bart (not dbarts) when callback is supplied and keepFits is not itself named. Three warnings apply to callback: a callback that crashes takes down the whole R session with no condition to catch; an interrupt cannot land while a call is running, so a callback that blocks hangs the session; and keepFits = FALSE means the sampler's run() returns those channels as NULL (present in the returned list, holding nothing) rather than omitting them - bart's packaged fit instead OMITS them outright, and its plot/extract/fitted/residuals/predict name keepFits in the resulting error rather than failing on a bare NULL. On a family = "hazard"/"hazard.probit"/"hazard.logistic" fit, a per-draw callback's draw struct counts person-period-EXPANDED rows, not subjects - the mapping back to (subject, period) is done in R and is not available to the callback.

useQuantiles

Deprecated: the rule belongs to the data, stated as useQuantiles on dbarts and dbartsData. A value written here is read, after a warning once per session naming where to state it, and the argument is removed in dbarts 1.1-0. The slot is a copy: a sampler writes it with the rule its data object holds, so reading it gives the rule the sampler runs. A rule on a control taken from a fit is not the next fit's, and one that differs from what a call takes draws a warning on every call saying it is not used. Logical to determine if the empirical quantiles of the columns of predictors should be used to determine the tree decision rules. If FALSE, the rules are spaced uniformly throughout the range of covariate values, except that a numeric predictor with fewer distinct values than n.cuts gets one rule half-way between each pair of neighboring values, chosen in proportion to the gap's width. If TRUE, a numeric predictor's rules lie half-way between its sorted, distinct, finite values: at every such point when there are no more than n.cuts of them, and otherwise at n.cuts of them spread evenly over the whole column. See bartBT's ‘Decision Rules’ details.

treeShift

A string, one of "auto" (the default), "always" or "never", for an extra Gibbs step per sampler iteration, taken before the trees are updated: a constant is added to every occupied leaf of each tree, with the constants summing to zero over the trees. The sum-of-trees function is therefore unchanged - the fits, the residual variance and any latent variables see exactly the state they would have - while the individual leaf values move, which can improve mixing where the ensemble's overall level is split among many trees. The shift is drawn from its exact conditional distribution, so the posterior being sampled is the same either way. Three values: "always" takes the step every iteration, "never" never takes it, and "auto" (the default) takes it for a forest exactly when that forest's tree structures are frozen - every structural element of proposal.probs zero - where the leaf values are the only thing left moving. The decision is made afresh each iteration, so a mixture frozen with $setControl part way through a run switches the step on from there. Where structure is being proposed the default takes no step and draws exactly the values it drew in previous versions. Applies to forests with the default constant leaves (including the monotone constraint and every binary, count, or survival family built on them); linear and Gaussian-process leaves and the heteroscedastic variance forest ignore it. It is the value of every forest that states none of its own (forest), and setControl accepts a changed value between runs, installing it on those forests.

keepTrees

A sampler saved to disk and reloaded needs its state stored first, with storeState(); predict on a sampler reloaded without it refuses, naming storeState() (see dbartsSampler-class's ‘Saving’ section). A logical that determines whether or not trees are cached as they are sampled. In all cases, the current state of the sampler is stored as a single set of n.trees. When keepTrees is TRUE, a set of n.trees * n.samples trees are set aside and populated as the sampler runs. If the sampler is stopped and restarted, samples proceed from the previously stored tree, looping over if necessary. The store costs about 24 bytes per node per tree per draw per chain - 23 MB per chain at 200 trees, 500 draws, and the eight nodes a tree averages at large nn - and does not grow with the number of observations.

storage

A character string selecting the precision of the internal running residual. The default "double" stores it in double precision and produces bitwise-identical draws to previous versions. "single" opts the running residual into single (32-bit) precision, halving the memory traffic of the dominant per-sweep gather for a speedup that is largest where memory bandwidth binds - very large n and multi-chain runs (leaf draws and reductions remain in double precision). Currently supported only for continuous (gaussian) responses with the default constant leaves; other models signal an error. The reduced-precision path changes the sampled values slightly and so is opt-in.

n.samples

A non-negative integer giving the default number of samples to return each time the sampler is run; NULL (the default) means not set, and an explicit NA reads as NULL for one release, with a once-per-session warning. Generally specified by dbarts instead, and can be overridden on a per-use basis whenever the sampler is run. This is a per-run() RETURN count, unaffected by n.thin - unlike bart's (and bartBT's ndpost) same-named argument, which is a one-shot sweep budget divided by thinning; see bart's n.samples item for the full boundary. 0 is accepted here (and by dbarts) - a sampler meant to be driven by an outer sampler's own run() calls rather than this one's; bart and xbart both return posterior draws and refuse a thinned-to-zero budget instead.

n.cuts

Deprecated: the cut count belongs to the data, stated as n.cuts on dbarts and dbartsData. A value written here is read, after a warning once per session naming where to state it, and the argument is removed in dbarts 1.1-0. A control holds the count only until a fit takes it, and a sampler's control has none to read: [email protected] on a control no one wrote a count to is an error. A positive integer or integer vector giving the number of decision rules to be used for each given predictor, read as bart's n.cuts is: one number for every column, one per column, or by column or term name with .default for the rest, anything else being refused when the sampler is built. If for any predictor more values are specified than are coherent, fewer are used: a cut point is held once, so a predictor whose range is too narrow to hold that many distinct equally spaced points gets fewer, and a constant predictor gets one. It does not reach a factor predictor of either kind: an unordered factor splits on level subsets and an ordered one at its declared level midpoints, a factor's grid following its level table rather than a count. See the ‘Decision Rules’ section of bartBT for how the rules themselves are placed.

n.burn

A non-negative integer determining how many samples, if any, are thrown away at the beginning of a run of the sampler.

n.trees

Deprecated: the number of trees belongs to the model, stated as n.trees on dbarts, dbartsSpec and bart, or on a forest. A count written here is read, after a warning once per session naming where to state it, and the argument is removed in dbarts 1.1-0; beside a forest that states its own count it is refused, and where every forest has a basis it has no forest to belong to and is refused. The slot is a copy: a sampler writes it with the count at the fitting function's level, that of the forest with no basis, or of the first forest where every forest has one, so reading it gives what the sampler runs. A control taken from a fit sets no count for the next one, and a count it carries that differs from what the call takes draws a warning on every call saying it is not used. A written NULL is the argument left out, and a fresh control states none.

n.chains

A positive integer detailing the number of independent chains for the sampler to use.

n.threads

A positive integer giving a total thread budget, distinct from n.chains: chains run in parallel across it, but tree sampling itself uses at most one thread per chain, so within-chain parallelism is not shipped and a budget above n.chains buys the sampler's own sweep nothing - it was built and measured (best case about 3 percent faster at four threads on one chain, and slower than serial at two and at eight) and closed rather than shipped. The surplus is not wasted outright: it still feeds the test-fit pool, used at or above testFitParallelCutoff test rows, and predict's own fan-out. Defaults to guessNumCores capped at n.chains, or to one where the cores cannot be counted (a stated NA is refused); a larger, explicit budget is accepted, and dbarts and bart warn once per fit, naming both counts, that the excess goes unused for sampling.

n.thin

A positive integer determining how many iterations the MCMC chain should jump on the decision trees alone before recording a sample. Serves to “thin” the samples against serial correlation. n.samples are returned regardless of the value of n.thin.

printEvery

If verbose is TRUE, every printEvery potential samples (after thinning) will issue a verbal statement. Must be a positive integer.

printCutoffs

A non-negative integer specifying how many of the decision rules for a variable are printed in verbose mode.

categoricalExhaustiveCap

A positive integer of at least 2 and at most 30 giving the number of categories PRESENT at a node up to which the grow-from-root scan (growFromRoot, and bart's n.grow.sweeps) scores every balanced partition of them, 2P−1−12^{P-1} - 1 candidates. Above it the scan scores the P−1P - 1 sorted prefixes instead. This is the one setting here that changes the draws: the proposal family above the cap is a different one. Raising it is affordable in a narrow band and never beyond - the candidate set doubles per level - and cost is not what it protects at its default, where enumerating 511 candidates measures the same as emitting 11 prefixes, the per-proposal cost being the histogram over node members that precedes the enumeration. The Metropolis-Hastings birth move draws its categorical rules from the prior and never enumerates, so this reaches only the grow-from-root path. Fixed when the sampler is created.

testFitParallelCutoff

A positive integer giving the number of test rows at or above which a chain fits its test matrix across its share of the thread budget instead of on its own thread. Time only: the two paths compute in the same order and return bit-for-bit the same fits. The default sits past the measured crossover on the machine it was measured on - four threads win 1.54 times at 65536 rows and 2.97 times at 262144, while the serial path already costs 16.5 msec per iteration at 32768 - so a caller with large test sets and threads to spare may lower it. Requires n.threads above n.chains; with no surplus budget no chain has a pool to route into. Fixed when the sampler is created.

predictParallelCutoff

A positive integer giving the number of tree traversals (rows times trees times draws) at or above which predict spreads a replay over n.threads workers instead of running it inline. Time only: each worker owns its own output range and nothing is summed across workers, so a replay is identical however it is dealt out. The default is calibrated - the crossover measures between 3e4 and 1e5 traversals, the fan-out reaching 1.5 times at 1e5 and saturating near 3.5 times on four threads. Fixed when the sampler is created.

sparseDensityThreshold

A number in [0,1][0, 1] giving the nonzero fraction at or below which a column of a sparse (dgCMatrix) design is stored as a rank bitmap rather than as one code per row. Memory against time: at the default a rank-stored column costs about 38 percent of a sweep in decode and holds about 3.5 times less than the dense layout. The layout changes no proposal - the same splits are drawn either way, and the split counts are identical - but it is not bitwise: a rank-stored column hands a leaf its rows in a different order, so the leaf's sufficient statistic reassociates and fits and sigma can differ in their last bits, by an amount that grows slowly with the number of samples. Which side of that trade is worth taking depends on the design and the machine, which is why it is a setting. Read once, when the sampler's data are built, and fixed thereafter: a change through setControl is refused by name rather than silently relayouting nothing.

proposal.probs

Named numeric vector or NULL, optionally specifying the proposal rules and their probabilities. Elements should be "birth_death", "swap", "change", "perturb" and "rule_gibbs" to control tree structure proposals, and "birth" to give the relative frequency of birth/death in the "birth_death" step; every element must carry one of these names, and an unnamed vector or an unknown name is an error listing them. The five structural probabilities must sum to one. All five structural probabilities zero is the frozen mixture: no structural proposal is made, the tree structures stand where they are, and only the leaf values, sigma and the family's latents keep being drawn, which is how a fitted forest is re-sampled as a fixed basis. Under dbartsControl's default treeShift = "auto" a frozen forest additionally takes the level-shifting Gibbs step each iteration, the leaf values then being the only thing left to move. An unnamed "perturb" or "rule_gibbs" is taken as zero and resolved before the rest; an unnamed "swap" is taken as zero, and a single remaining unnamed element takes the residual, so c(birth_death = 0.7) is birth/death 0.7, swap 0, change 0.3, perturb 0, rule_gibbs 0 and c(birth_death = 0.5, change = 0.4) is swap 0.1; naming only the zero-default moves "swap", "perturb" and "rule_gibbs" leaves the birth/death-versus-change split undetermined and is an error. The default is c(birth_death = 0.6, swap = 0, change = 0.4, perturb = 0, rule_gibbs = 0, birth = 0.5). A "swap" element exchanges a parent's split rule with a child's; it defaults to zero because at forests of 75 trees and more dropping it changed accuracy, coverage and mixing little in simulation (see NEWS), but with n.trees = 1 it is the only move that rotates a rule up the tree, so single-tree fits should set it positive (0.1 was the historical default, and is bartBT's). A "perturb" element displaces one node's split point by at most n.perturb.cuts cut positions, one by default, while keeping its variable and the tree's shape; it defaults to zero, and only ordinal (numeric) columns can be perturbed. A "rule_gibbs" element replaces one nog node's rule - a node whose two children are both leaves - with a draw from that rule's own full conditional over the available ordinal variables and their admissible cuts, so its acceptance is one; it defaults to zero, it acts only where the node's own rule is ordinal, and it is inert on an all-categorical design. Unlike the four engine settings above, this one is not fixed at creation: setControl accepts a changed mixture between runs, installing it on every forest that states none of its own, on every sampler, DART fits, models of several forests and multinomial ones included - with the priors, as at creation, on a sampler whose $setModel takes a model - and a refused install rolls the stored control back. It is the mixture of every forest that states none of its own (forest, varianceForest).

n.perturb.cuts

The most cut positions a perturb proposal moves a split either way: a displacement is drawn uniformly from the cuts within that many positions of the current one, clipped to those the node's ancestors and descendants allow. A whole number from 1 to the cut cap of 65533, or Inf, the explicit window over the node's whole range; a finite value above the cap is refused, the message naming 65533 and Inf as the ways to ask for it. The setting is a maximum, and the window stops at the node's range, so a value under the cap that exceeds a predictor's own number of cuts is taken and means that whole range. The default, 1, is the window the perturb move has always used. It changes how the proposal moves, not the posterior it targets; acceptance falls as the window widens. Like proposal.probs, setControl accepts a changed value between runs, installing it with the mixture. It is the window of every forest that states none of its own (forest, varianceForest).

seed

Random number generator seed. NULL (the default) means not given here and resolves to the slot's unseeded value, which leaves the object unseeded. An explicit NA is a missing value and is refused. Every chain then runs its own generator; a seed given instead drives a dedicated generator that in turn hands each chain its own seed, leaving R's stream untouched. Seeded results do not depend on the thread count, and a single-chain run with a given seed reproduces the first chain of a multi-chain run with the same seed. Unseeded, chain generators are seeded from R's stream at creation, so set.seed beforehand suffices for reproducibility; sampling itself never advances R's stream, though copy() of an unseeded sampler, and the first use of an unseeded sampler reloaded from a saved state, each draw fresh chain seeds from R's stream again. See the Reproducibility section of bart for the full picture.

updateState

Logical setting the default behavior for many sampler methods with regards to the immediate updating of the cached state of the object. A current, cached state is what saving/loading the sampler needs, and it is also the state a setState restores to undo a setWeights or other mutation (see dbarts-embedding).

Value

An object of class dbartsControl. Besides the settings it was given, its n.trees, useQuantiles and binary slots read what the sampler that holds it runs, the model's count, the data's rule and whether the family is binary; they are copies the sampler writes, kept so that code that reads them goes on working, and the family alone decides binary. A control taken from a fit carries its run settings and nothing else into the next fit, through any function that takes a control.

Engine limits

Nine fixed values decide what the engine will represent and where it switches strategy. Each was measured on one machine (arm64 macOS, 10 cores); the five that a workload can profitably move are settings here, and the rest are limits of the representation or of a proposal family, with nothing found that moving would buy. A recommended range is given where a measurement supports one.

Limit Where Default Recommended Settable
Cuts per predictor quantized predictor code 65533 up to the cap no; n.cuts above it is refused
Categorical levels quantized predictor code 65535 any real factor no; a wider factor is refused by name
Ordered-factor levels quantized predictor code 65534 any real factor no; one code goes to the cut grid
Exact categorical enumeration grow-from-root scan 10 present levels 8 to 14 yes, categoricalExhaustiveCap
Perturb window the perturb proposal 1 grid position 1 yes, n.perturb.cuts, up to the cut cap or Inf; acceptance falls with width
Test-fit parallel cutoff test-set fitting 65536 rows 8192 to 65536 yes, testFitParallelCutoff
Predict parallel cutoff predict 50000 traversals 3e4 to 1e5 yes, predictParallelCutoff
Sparse density threshold dgCMatrix storage 0.2 0.05 to 0.5 yes, sparseDensityThreshold
Gaussian-process leaf size gp leaves 256 observations 256 to 512 yes, gp(max.leaf.size = )

Of the settings in this table, the categorical enumeration cap and the Gaussian-process leaf size change what is sampled. The perturb window changes how a proposal moves, so it changes the draws, but not the posterior they target. The two parallel cutoffs buy time and return bit-for-bit the same draws either side of themselves. The density threshold buys memory and draws the same splits either side, but is not bitwise, as its entry above says.

See Also

dbarts

Examples

## a small, single-chain, reproducible control for embedding a sampler in a
## larger Gibbs loop: one sample per run(), no burn-in, state cached on demand
control <- dbartsControl(n.chains = 1L, n.threads = 1L,
                         n.burn = 0L, n.samples = 1L, seed = 7L,
                         updateState = FALSE)
control

n <- 50L
x <- matrix(runif(n * 2L), n, 2L)
y <- x[, 1L] - x[, 2L] + rnorm(n, 0, 0.2)
sampler <- dbarts(y ~ x, control = control, n.trees = 25L)
samples <- sampler$run()
str(samples$train)

Discrete Bayesian Additive Regression Trees Sampler Data

Description

Convenience function to create a data object for use with a dbarts sampler.

Usage

dbartsData(
    formula, data, test, subset, weights,
    offset, offset.test = offset,
    factors = c("categorical", "indicators"),
    na.action = dbarts::na.keepPredictors,
    counts = NULL, n.cuts = NULL, useQuantiles = NULL,
    keep.data = TRUE)

Arguments

formula, data, test, subset, weights, offset, offset.test, factors, na.action

As in dbarts. Retains backwards compatibility with bart, so that formula/data can be a formula/data.frame pair, or a pair of x.train/y.train matrices/vector. offset/offset.test take the matrix interface's shape from whether counts is also supplied: with counts, an n x K (nTest x K) numeric matrix installs the per-category shift described under counts below, and a flat vector is refused; without counts, only a flat vector (or single number) is accepted, and a matrix is refused. formula may itself be a dbartsData object, in which case it is returned as-is; any other argument supplied alongside it is then ignored, with a warning naming each one. weights are held as given, validated here only for length, NA and non-negativity; the family's own rule applies when a sampler is built from the object, where a "probit", "ordinal" or "nbinom" fit accepts only weights of 0 and 1, which name the rows in the data set and compose with the sampler's active-row mask.

n.cuts, useQuantiles

The maximum number of cut points per predictor, one number for every column, one per column, or by column or term name with .default for the rest, as bart's n.cuts reads, and whether to place them at the predictors' quantiles, which the data object then states; see dbarts. NULL, the default, states none. A count is kept as written and read again by the sampler it goes to, over the predictors that sampler holds: handed to a hazard sampler's $setData or to new("dbartsSampler", ...) with a person-period matrix, n.cuts = 7 gives the predictors 7 and the appended period column 100, as dbarts(n.cuts = 7, family = "hazard") does, and period takes a count only by its own name. A count one value short, or by name without period, is kept so a hazard sampler can read it, and any other sampler refuses it when it reads it; dbartsData itself refuses a count no sampler could read. Ignored, with the warning the other arguments draw, when formula is already a data object.

keep.data

Whether an object built from a formula and a data frame or list keeps the frame. TRUE, the default, keeps the frame as given, unless the build draws random numbers (see ‘Data kept’), the positions of the rows kept and what it takes to read the model's variables from them again, and holds no predictors, response, weights or offset: see ‘Data kept’. FALSE keeps the model matrix, the response, the weights and the offset in the object, as it was in 0.9-34, and no frame. An object built from an environment, with no data, or from the matrix interface keeps its matrix either way. formula being a dbartsData object takes the argument quietly.

counts

Optional n x K matrix of non-negative integer counts selecting the multinomial (softmax) model, column k holding category k's successes. A row may carry no trial: it enters no likelihood and still receives fitted probabilities. A row's trials, its count total, may not exceed 10610^6, as each trial costs a Polya-Gamma draw per category per sweep. A row with any NA cell is a missing response, routed through na.action exactly as for every other family (see na.keepPredictors). It is restricted by subset exactly as weights is, and it IS the response: y is derived as its row sums - the trials nin_i - so no separate response need be supplied, and any that is supplied is replaced. At least two categories are required. Column names, when present, label the categories. dbarts(family = "multinomial") writes this argument from a count-matrix or factor response rather than requiring it here. Under family = binomial or "logistic" an n x 2 matrix is instead the binomial response, its columns a row's successes and failures: y is again the row sums, the trials, and the offset is the flat shift on the log-odds a binary logistic fit takes; bart and dbarts write it from a cbind(successes, failures) response. Paired with counts, a matrix offset/offset.test is the per-category shift added to the raw per-category values BEFORE the softmax - which is the only place a shift means anything under one, since the blend is invariant to a common per-observation shift and a flat shift would be added after it. Only the row-centered part is identified: adding a constant to a whole row leaves every reported probability unchanged.

Details

Data kept

Built from a formula and a data frame or list, with keep.data = TRUE, the object keeps data whole (in its frame slot), rows, the positions in it of the rows kept after subset and the na.action, read from the model frame as lm reads them, so an na.action that records nothing of what it drops keeps the rows it returns (NULL when every row is kept in order; a repeated row, and a NA in subset that the na.action keeps, appear as they are), rows.total, the number of rows handed over, which rows are positions within (NULL where rows is), frame.columns, the names of its columns, frame.source, "frame" ("environment" beside the names of an environment the data were read from, and NULL where no data were given), and what reads the formula, weights and offset against the frame again. A caller's variable the formula, weights or offset names is kept as its value at the build, a function of no package among them, with the names it reads, so that a later change to the workspace, a function redefined or removed included, leaves the object unchanged; a function local to a caller's function is kept without the rest of that function's variables, and a package's function by name. A later change to data leaves the object unchanged. The slots x, y, and where they were given weights and offset hold a stand-in that stops, naming model.frame(object), under dim, length, [, as.matrix, as.numeric, arithmetic, sum, mean, c, rep, unique, cbind, rbind and sd; is.na, anyNA and is.finite stop too, rather than answer for values the slot does not hold; var and paste read it in R's own code, which gives no way to stop them, and answer NA with a warning or the slot's name; attr() of one gives NULL, and a weights or offset that was not given is NULL. Read the data with model.frame(object) and nobs(object), which counts the rows in the likelihood (those with a positive weight), as it does for a fit. Every refusal and warning of the build is given at the build.

A sampler, and dbartsSpec's data, are made from the block-holding object that keep.data = FALSE gives, which the fitting functions make from a frame-keeping one by evaluating the formula against the frame again, on the kept rows, with the caller's variables as they were at the build; the sampler's data hold no frame. A frame-keeping object loaded in another session does this at its first fit, so the packages its formula calls must be installed there. A build whose formula, weights or offset draw from R's random-number generator, as rnorm(n) ~ x and y ~ jitter(x) do, keeps no frame and holds the values drawn, as keep.data = FALSE does, so that every fit from the object fits the same values; drawing data or subset does not count, as the frame and the rows are kept. A term drawing from a generator outside R's, which leaves R's stream where it was, is not seen: the object keeps its frame and draws again at each fit.

Data frame ingestion

Data frame columns - through the formula interface or a frame passed as x.train - map to predictors as follows:

  • numeric and logical columns enter as ordinal predictors, as do classed numbers such as Date, POSIXct and difftime, by their numeric value (a POSIXlt column is refused; convert it with as.POSIXct);

  • unordered factors each become a single categorical predictor under the default factors = "categorical", with splits sending a subset of levels down each branch; factors = "indicators" instead expands each factor into binary indicator columns, as previous versions always did - a factor past 100 levels builds this expansion as a sparse (dgCMatrix-backed) block automatically, with no user-facing argument: the tree structure grown is the same as the dense expansion's, though leaf-mean draws can differ from it in the last bit;

  • ordered factors enter as their own predictor kind, coded numerically by level order and split at a threshold on those codes; the split grid is the midpoints between consecutive declared levels, one candidate per level boundary, so n.cuts does not apply to such a column and adjacent levels are always separable;

  • matrix columns (e.g. from poly) splice in as ordinal predictors, one per column;

  • Matrix::sparseVector and dgCMatrix columns (assigned into the frame; they do not survive data.frame(...) or I()) enter as sparse ordinal predictors. Both interfaces accept them for training: a bare S4 column does not survive model.frame, so the formula path lifts any such column out of data before model.frame runs and re-attaches it, row-subset under subset and na.action alike, to the assembled predictor matrix afterward - named in formula like any other column, including through ., with no marker. A sparse name wrapped in poly(), ns(), log(), offset(), or a ':'/'*' interaction is refused by name, as an interaction among dense terms already is. test/x.test accepts them under either interface, since a test set is never run through model.frame;

  • sparseFactor columns enter as a single sparse categorical predictor, coded and binned identically to a dense factor of the same values. Both interfaces accept them, the same pull-out/re-attach the other sparse column kinds get on the formula path.

On the formula path, a sparse column re-attaches after every dense term regardless of where it was named, each in the order its name appears in formula (after . expansion) rather than its position in data; test is matched to x.train by name (or by position when neither carries names), so the two stay aligned regardless of this reordering. Factor level tables are retained so that test data are coded identically, and a factor predictor's level count - ordered or unordered - is the declared level table rather than the levels the training rows happen to take. A level declared but unobserved in training therefore keeps its own bin, and test or replacement data carrying it are accepted at every entrance (creation, setTestPredictor, predict, setPredictor, setData, which reads a factor of the new data by label against the sampler's table whatever levels it declares); conversely a value that is not an existing integer level code is refused at those same entrances, naming the kind, for ordered and unordered factors alike. An unordered factor is limited to 65535 levels and an ordered one to 65534 - one lower, since an ordered factor spends a code on the upper bin of its K−1K - 1 cut grid - and a wider one is an error naming the column. This holds equally for dense factors, sparseFactor columns, and dense factors inside a mixed dense/sparse frame. Drop unused levels before fitting (droplevels) if you would rather they not be modeled. test accepts the same column types as x.train, including sparseFactor and sparse ordinal columns. A sparseFactor or sparse ordinal test column recodes over the training level table and stays resident - through creation and setTestPredictor - rather than densifying at ingestion, the same storage tier rule as training. predict and getTrees(newdata = ) code a test set the same way and then route its rows through the trees off that storage, materializing no dense matrix of their own.

Data frame input is stored columnar: no n×pn \times p double matrix is retained. Code that previously reached into the data object's x slot expecting a plain matrix should call extract(sampler, "predictors") - or as.matrix on the slot - to obtain the numeric predictor matrix, factor columns as their integer codes.

Value

An object of class dbartsData. Its frame, rows, frame.columns and frame.source slots are described under ‘Data kept’. Its rowNames slot records the names of the kept training and test rows, as list(train, test), or NULL when neither is named; a fit carries them on its outputs as the row names paragraph of bart's ‘Value’ section describes. Its bases, basis.levels, basis.written and basis.scale slots are NULL as created: a forest's basis is stated on the forest (see forest), and these slots are written on the data object a sampler of several forests holds. There bases holds each forest's block as the sampler uses it, a factor's level indicators among them; basis.levels records, for each forest of levels, the levels in the order of the block's columns, and NULL for a forest of numbers or with no basis; and basis.written the text each basis written as code was written as, NA for a basis handed over as a value and for a forest with none, by which a forest beside these data keeps the held basis (forest(basis = factor(z)) for one written factor(z)). on the data object a sampler holds it records, for each forest of numbers that states no sd, the standard deviation of its column over the rows in the likelihood when the sampler was first created, which that forest's default sd was taken from (see sd in forest), and a sampler created from such an object is handed it, so a copy, a reload and a sampler made again from its own control, model and data have the creation's prior whatever column is then in force. A forest that names a held basis by its text keeps the entry, wherever it stands in the list, and one given a new value takes the scale of that value; clearing an entry by hand has the next creation take the scale of the column in force. Its missing.seen slot is NULL as created; on the data object a sampler holds it records, once a predictor has been changed, the columns that sampler can hold missing values in, as a logical per predictor column (see ‘Missing values in predictors’ in dbartsSampler), and a sampler created from such an object takes them. Its status slot is NULL as created; on the data object an aft sampler holds it records the censoring status in force, 1 for an event and 0 for a censored row, which setResponse(status = ) rewrites and a copy or a reload is created from. Its useQuantiles slot is NA as created; on the data object a sampler holds it records whether the cut points are placed at the predictors' quantiles (see useQuantiles in dbartsControl), the value the sampler's control then carries.

Four more slots record what a sampler derives from its data; where basis.scale keeps the value of the sampler's first creation, they follow what the sampler holds while the data move. Each is NULL as created: cutPoints, a list with one entry per predictor column, NULL for an unordered factor and otherwise the column's cut points, strictly increasing, with their weights, where they are not equally likely, as the entry's "mass" attribute (an increasing sequence whose successive differences are the weights, as a state's cutMass holds them); response.range, the c(min, max) of the response the leaf prior's scale is taken from, NULL under a family that reads none (probit, logistic, ordinal and multinomial), and under nbinom c(center, center + 1) of the count fit's center, where a pair of another width, as a range recorded under another family is, is read by its first number, the sampler recording it as c(center, center + 1), and an equal pair is refused; forest.calibration, c(anchor = , unit = ) of a model of several forests (see forest), NULL elsewhere; and standardization, for a forest of linear or gp leaves a list with one entry per forest holding list(center = , scale = ), each named by the leaf covariates where each one's column name is present, non-empty and the name of no other column, and otherwise with columns, their column positions, beside them, a scale of NA for a covariate without spread, and beside them, for gp leaves whose model gives no lengthscale, the lengthscale derived with them; NULL as a whole, and not an entry per forest, where no forest's leaves take a covariate. The data object a sampler holds, sampler$data, records them from creation on, and the sampler rewrites them after every call that changes one. A sampler created from a data object by new("dbartsSampler", control, model, data), and the copy and reload of a sampler, which are created from its own, uses each value the object records and derives the others. A new fit, by dbarts, bart or dbartsSpec, takes the cut points and the leaf standardization the object records and derives the response-based values from its response: response.range, forest.calibration and sigma's starting estimate (unless sigest states one), so dbarts(sampler$data) after sampler$setResponse() calibrates to the new response, as a fresh fit does, and sampler$copy() is the way to the same model again. A data object made afresh from the same rows derives its own. No door states a response range: the records are read only from a sampler's own data. A sampler's setData does the same, except that it keeps its own response range where the object records none, unless its updateCutPoints, updateScale or updateStandardization says to derive a value or to keep the sampler's (see dbartsSampler-class), so sampler$setData(sampler$data), the object handed back whole, keeps them. xbart takes cutPoints for every fold and derives the others in each fold, from the fold's training rows, whatever the object records. A record that fits no data - another number of columns, cut points for an unordered factor, on an ordered factor other than those of its levels, repeated or not finite, a range that is not two finite numbers, a standardization whose centers are not finite, whose scales are neither positive nor NA, whose lengthscales are not positive, whose names are missing, empty or repeated, or whose columns are not one position per center - is refused, naming the slot; setting it to NULL derives the value instead. Cut points out of order are sorted. Which covariates the leaves take is the model's, so a standardization is matched to them by its keys, names to leaf columns whose names could key one, the others deriving, columns where a leaf column's name could not, and one with neither by position where the counts agree: an entry for a covariate the leaves do not take is not read, a covariate without one is derived, and a lengthscale the model supplies is used in place of the record's.

See Also

dbarts, model.frame.dbartsData, extract.dbartsSampler, sparseFactor

Examples

set.seed(3)
n <- 60L
df <- data.frame(
  x = runif(n),
  g = factor(sample(c("a", "b", "c"), n, replace = TRUE))
)
df$y <- df$x + 0.5 * (df$g == "b") + rnorm(n, 0, 0.1)

## the formula interface; 'g' enters as one categorical predictor
data <- dbartsData(y ~ x + g, df)
data

## the same data through the backwards-compatible x/y interface, with a
## test set that is coded against the training level table
train <- df[1:40, ]
test  <- df[41:60, c("x", "g")]
data <- dbartsData(train[, c("x", "g")], train$y, test)

## build a sampler on it, rather than letting dbarts() ingest again
sampler <- dbarts(data, control = dbartsControl(
  n.chains = 1L, n.threads = 1L, n.samples = 10L, n.burn = 10L,
  updateState = FALSE), n.trees = 25L)
samples <- sampler$run()
str(samples$test)

Response Family Constructors

Description

A list of constructor functions building the response families that the family argument of bart, dbarts, dbartsSpec and xbart accepts. Bundling them keeps generic names like gaussian and probit out of the search path, where another package - stats::gaussian first among them - could mask them or be masked depending on attach order.

family takes either a token string (family = "gaussian"), meaning that family at its defaults, or one of these calls (family = student(df = 4)), meaning that family with settings. Inside the family argument the constructors resolve by bare name whatever the caller has attached, exactly as the prior vocabulary does inside split.probs, including when a wrapper forwards the argument through its own ...; elsewhere reach them through this list. That vocabulary shadows the caller's own frame for these ten names only, so a variable named gaussian holding student(3) resolves there to the gaussian family, not to its own value; name such a variable something else, or write dbartsFamilies$student(3). A wrapper's named formal that instead forces a bare constructor call before passing it on reaches R's own could-not-find-function error, extended with the same hint naming dbartsFamilies$student(...) and its siblings.

Base R's family objects are accepted as glm takes them. stats::gaussian(), or stats::gaussian(link = "identity"), is the gaussian family (dbarts's own gaussian() below takes no link, since the identity link is the only one it fits, and refuses one by name), binomial(link = "probit") is probit, and binomial(link = "logit") is logistic; the word "binomial" and the bare function binomial mean binomial(), the logit link, so a 0/1 response fit with family = binomial is logistic where "auto" is probit. Any other link of those two, and every other stats, quasi or foreign family (poisson, Gamma, quasibinomial, MASS::negative.binomial, ...), is refused by name.

Every setting that only one family reads rides its family object rather than a formal of the fitting function. That includes the residual scale's own prior, sigma, on the four families that draw a residual scale: it takes a dbartsPriors residual prior, chisq(df, quant) or fixed(value), resolved in the prior vocabulary inside the family call. The retired spellings resid.prior, sigdf and sigquant are accepted for one release with a once-per-session warning and are removed in dbarts 1.1-0; resid.prior is retired that way on dbarts and xbart as well (dbartsSpec refuses it), so the family object is the one home of the residual prior. A call that writes the prior both ways is refused where the two disagree, naming both spellings, and accepted in silence where they say the same thing.

Usage

## S4 method for signature 'dbartsFamily'
show(object)

Arguments

object

A family object, as one of the constructors below returns. Printing one names the call that would build it. A family object carrying a setting its constructor does not take is refused by name.

Format

A list of functions:

gaussian(sigma = NULL)

A continuous response with normal errors; the default for a numeric response under family = "auto". sigma is the prior on the residual scale: NULL is the shipped chisq(3, 0.9), chisq(df, quant) names another scaled-inverse-chi-squared, and fixed(value) pins the residual variance and suppresses the sampler's own draw, which is what an outer sampler owning σ\sigma wants. The former resid.prior, sigdf and sigquant arguments. sigest, the estimate the chisq quantile is calibrated against, is not a family setting and stays a fitting-function argument; it stands beside chisq, and is refused beside fixed, which has no scale to calibrate.

student(df = NULL, sigma = NULL)

A continuous response with outlier-robust Student-t errors, drawn by the Gaussian scale-mixture augmentation. df = NULL estimates the degrees of freedom on a capped grid; a positive number fixes them. sigma is the scale-mixture's own residual prior, as for gaussian.

probit(), logistic()

Binary latent-variable models for a 0/1 response.

multinomial(), ordinal()

Unordered K-category softmax and ordered cumulative-probit models.

nbinom(shape = NULL)

Negative-binomial counts on a log link: the forest models the log of the mean count, and the variance is μ+μ2/r\mu + \mu^2 / r for shape rr. A larger shape is closer to Poisson; rr is size in rnbinom and theta in MASS and mgcv. NULL estimates the shape rr on a capped positive-integer grid; a positive integer fixes it. Each sweep's latent draw costs time in proportion to y+ry + r, so a large fixed rr is slow: at r=104r = 10^4, a thousand sweeps over a thousand observations take about half an hour. By rr in the hundreds the model is already close to a Poisson one. A fixed shape above 10610^6 is refused, as a count above it is.

aft(sigma = NULL)

Accelerated failure time (log-normal) survival. The log-time residual scale is drawn as a gaussian one is, so sigma is its prior, as for gaussian.

hazard(breaks = NULL, link = c("probit", "logistic"))

Discrete-time survival hazard by person-period expansion. breaks sets the period grid: NULL uses the sorted distinct observed times of the subjects in the likelihood (those of positive weight), a single positive integer bins at that many quantiles of those times, and a numeric boundary vector gives explicit right-closed intervals. link selects the binary link the expanded rows are fit under, and is what the tokens "hazard.probit" and "hazard.logistic" name.

A hazard fit keeps its trees by default (keepTrees = NULL in bart), because its survival curves replay them; the trees take about 20 to 27 MB at the defaults, whatever the row count. keepTrees = FALSE drops them, and then survivalProbabilities refuses.

A subject is at risk for one row a period, so on the default grid with distinct times the rows grow as the square of the subjects (1,000 subjects give about 500,000 rows) and on a grid of KK periods as KK times the subjects. Memory, not time, is what a row costs: at bart's defaults (four chains of 500 kept draws, 75 trees) about 35 KB a row at its peak, about 32 KB of which are the kept draws of the training fits (8 bytes a draw a chain in the fit returned, and about 16 while they are copied out), so a million rows take about 35 GB. keepTrainingFits = FALSE leaves about 3 KB a row: about 300 bytes the chains share and about 620 a chain, 8 bytes a tree. A predictor column beyond three adds about 34 bytes a row, and a held-out subject passed as test is expanded to every period. No row count is refused: when the peak projected from these figures exceeds the machine's physical memory, the fit warns once per session, before any row is built, with a warning of class dbartsMemoryWarning that names the rows, the two figures and the ways out (a coarser hazard(breaks = ), keepTrainingFits = FALSE or fewer chains), and then runs; a sampler's $setData warns the same way. The memory read is the smaller of the machine's installed memory and, on Linux, the limit a container or a job scheduler sets on the process (its cgroup's memory.max, or memory.limit_in_bytes in version 1), and the warning says “this process may use” that limit where it is the smaller. Where neither can be read there is no warning.

hurdle.lognormal(sigma = NULL)

A semicontinuous two-part response: a zero-part probit glued to a lognormal positive part. Composed from two samplers, so only bart fits it. sigma is the positive part's residual prior; the zero-part probit has a fixed unit latent scale and takes none.

Details

Which entry points accept which family:

family bart dbarts dbartsSpec xbart
gaussian yes yes yes yes
student yes yes yes no
probit yes yes yes yes
logistic yes yes yes yes
aft yes yes yes no
multinomial yes yes yes no
ordinal yes yes yes no
nbinom yes yes yes no
hazard yes yes no no
hurdle.lognormal yes no no no

A family the entry point does not fit is refused by name. See dbarts's family argument for what each family models and what it supports.

See Also

bart, dbarts, dbartsPriors

Examples

f <- dbartsFamilies$student(df = 4)
f

## the residual prior rides the family too
dbartsFamilies$gaussian(sigma = dbartsPriors$chisq(df = 5, quant = 0.75))

set.seed(99)
n <- 100L
x <- matrix(rnorm(n * 2L), n, 2L)
y <- x[, 1L] + rt(n, 4)

fit <- bart(
  x, y,
  family = student(df = 4),
  n.samples = 50L, n.burn = 50L, n.chains = 1L, verbose = FALSE
)

Forest Specification Constructors

Description

A list of the constructor functions building the forest specifications that the monotone, interactions, blocks, variance and forests arguments of dbarts, dbartsSpec and bart accept. The constructors are not exported, so that names like forest and blocks stay out of the search path, where another package could mask them or be masked depending on attach order.

Inside those arguments, and inside a formula's forest() term, the constructors resolve by bare name: a call is always the constructor, and a bare name the caller has assigned a value to is that value. Anywhere else - a specification built ahead of the call, or an argument a wrapper forces before passing it on - write dbartsForests$interactions(...). forest()'s first argument, the predictors a forest splits on, is read as terms when it names a predictor of the fit and otherwise takes the value it has where and when the constructor is called. Its basis is read the same way: a name of a column of the fit's data is that column, and anything else is what it was where and when the constructor is called; see forest.

Format

A list of functions:

interactions

Interaction constraints; see interactions.

blocks

Block-additive constraints; see blocks.

monotone

Monotone constraints and their prior; see monotone.

forest

One forest of a model, in a forests list or as a term of a formula; see forest.

varianceForest

The heteroscedastic variance forest; see varianceForest.

See Also

dbarts, bart, dbartsPriors, dbartsFamilies

Examples

## built ahead of the call, then passed as a value
constraint <- dbartsForests$interactions(max.order = 1)

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)

fit <- bart(x, y,
             interactions = constraint,
             n.trees = 25L, n.samples = 20L, n.burn = 20L,
             n.chains = 1L, verbose = FALSE)

## the same constraint, written by bare name inside the argument
fit.bare <- bart(x, y,
                  interactions = interactions(max.order = 1),
                  n.trees = 25L, n.samples = 20L, n.burn = 20L,
                  n.chains = 1L, verbose = FALSE)

Mixed Dense/Sparse Predictor Container

Description

The container a data frame's predictor columns assemble into whenever any column is sparse-backed (a sparseFactor column, or a Matrix::sparseVector/dgCMatrix column assigned into the frame): dense columns stay a per-column list and sparse columns stay one shared dgCMatrix, rather than materializing one n×pn \times p dense matrix. makeModelMatrixFromDataFrame returns one whenever x carries a sparse column; dbartsData's x/y interface (and so dbarts's and bart's) returns one under the same condition and stores it in the resulting dbartsData object's x/x.test slot. A fit or sampler made from a formula or a data frame holds one as its data@x whether or not a column is sparse. The formula interface accepts a sparse column too, named like any other (including through .): a bare S4 column cannot survive model.frame, so it is lifted out of data first and re-attached, row-subset under subset and na.action, to the assembled predictor matrix afterward.

Usage

## S3 method for class 'dbartsMixedMatrix'
dim(x)
## S3 method for class 'dbartsMixedMatrix'
dimnames(x)
## S3 method for class 'dbartsMixedMatrix'
x[i, j, drop = TRUE]
## S3 method for class 'dbartsMixedMatrix'
as.matrix(x, ...)
## S3 method for class 'dbartsMixedMatrix'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

x

An object of class dbartsMixedMatrix.

i, j

Row and column indices, as for a matrix. Supplying j densifies (see ‘Details’); i alone keeps the container.

drop

Logical; as for a matrix, only consulted when j is supplied.

row.names

NULL, the default, for a data frame's default row names, or a vector of row names.

optional

Unused.

...

Unused.

Details

dim and dimnames - and so the base nrow, ncol, and colnames, which are defined in terms of them and need no method of their own - read like a matrix's; row names are always NULL. x[, j] (or x[, "name"]) returns the indexed/named column(s) as an ordinary numeric vector or matrix. x[i, ] keeps the container, row-subset. x[i] with j omitted also row-subsets, unlike a plain matrix's single-index linear indexing. as.matrix materializes the whole object to a dense n×pn \times p numeric matrix (a factor column's codes, zero-based) and is the escape hatch for any operation the container itself does not support.

as.data.frame gives the predictors as the model sees them, one column per column of the container, named by colnames(x): numeric columns as numeric, and a factor column as a factor over its declared levels, which keeps a level no row takes. For a fit made from a formula of plain variables, predict and setTestPredictor take that data frame as new data. A formula that transforms or expands a variable (I(z^2), factor(i), a matrix term, poly(z, 2)) names columns that are not the variables it reads, so new data for it is a data frame of those variables, not this one.

What is not supported: matrix-style subassignment (x[i, j] <- value errors). is.matrix(x) is FALSE, and a base function that does not dispatch on the class, such as cbind, does not see a matrix. Code that needs a matrix should call as.matrix(x) first.

Value

dim returns an integer vector of length two. dimnames returns a length-two list, the first element always NULL. [ with j supplied returns a numeric vector or matrix, matching drop; with j missing it returns another dbartsMixedMatrix. as.matrix returns a plain numeric matrix, and as.data.frame a data frame.

See Also

makeModelMatrixFromDataFrame, dbartsData, sparseFactor

Examples

if (requireNamespace("Matrix", quietly = TRUE)) {
  df <- data.frame(a = 1:5)
  df$b <- Matrix::sparseVector(c(1, 2), c(1, 3), length = 5)
  mm <- makeModelMatrixFromDataFrame(df)

  class(mm)
  dim(mm)
  colnames(mm)
  mm[, "a"]
  as.matrix(mm)
}

Prior Specification Constructors

Description

A list of constructor functions building the prior specifications that the split.probs (dart()) and leaf.prior arguments of dbarts and the fitting functions accept. Bundling them keeps generic names like normal out of the search path, where another package could mask them or be masked depending on attach order.

The residual priors chisq and fixed are what a family object's sigma setting takes - family = gaussian(sigma = chisq(3, 0.9)) - which is the one place every entry point reaches the residual prior; this vocabulary resolves by bare name inside that argument too.

Format

A list of functions:

cgm(power = 2, base = 0.95, split.probs = NULL)

The value of the retired tree.prior argument of dbarts and dbartsSpec, which is accepted with a warning until dbarts 1.1-0, when cgm is removed. Write the tree prior as power, base and split.probs instead. A NULL power or base is the default. split.probs weights the choice of split variable: NULL is uniform, a named vector assigns by column or term name (with an optional ".default" element), an unnamed vector assigns by position. Entries must be non-negative and finite, with at least one positive. Named or positional probabilities are matched to the data when a sampler is built. A column of probability zero is never split on, just as one a forest's vars leaves out is never split on, on every path: where the columns of positive probability are used up along a path, the node cannot split. A sampler's $setModel refuses a zero on a column its trees split on.

dart(a = 0.5, b = 1, rho = NULL, alpha = 1, update.alpha = TRUE, update.delay = NULL)

DART (Linero 2018), given as split.probs = dart(): a Dirichlet prior over the split-variable probabilities inducing variable selection. The tree's depth is the fitting function's power and base, as without DART. alpha is the concentration, optionally sampled (update.alpha) on a grid with a Beta(a, b) prior on alpha / (alpha + rho); rho defaults to the number of predictors. NA is a missing value, not a spelling of the default, and is refused for rho and update.delay alike. Updates hold until update.delay iterations have passed (default: half the control's burn-in), so the forest is likelihood-informed when counts first enter the Dirichlet.

normal(k = NULL, sd = NULL)

Normal prior on the leaf values, named one of two ways, never both. Either names the spread of the whole forest - the sum of trees - not of one tree.

k is relative to the scale the data fixes: a positive scalar, a hyperprior on k built with chi, or NULL for the default, 2 for continuous responses and chi(1.5, 2) for binary ones and counts (nbinom). The continuous default follows Chipman, George, and McCulloch's argument that with leaf standard deviation sigma_mu = 0.5 / (k * sqrt(m)) for m trees, k prior standard deviations of f(x)f(x) span the whole response range regardless of m; see dbarts's Details for the response-scaling caveat this relies on. A string such as "chi(1.5)" is kept for 0.9-x. k = Inf is accepted and holds every tree at zero, so the fit is the offset, plus on a continuous response the center of the range y - offset spans.

sd is the standard deviation of the normal prior on the leaf model's own parameter, for the forest total, on the scale the family's forest fits: a positive number, or a hyperprior on the sd itself built with invchi. It takes no string form. The scale and the k.scale k is relative to, per family:

family sd is stated in k.scale at k = 1
gaussian, student response units half the training response range
aft log survival time half the observed log-time range
probit, ordinal probit latent 3
logistic log-odds latent π3\pi\sqrt{3}
nbinom log mean 3
hazard its link's latent 3 or π3\pi\sqrt{3}

so a fixed k is the sd k.scale / k. For the constant leaf sd is exactly the prior standard deviation of f(x)f(x) at every xx; for the other leaf models it is the sd of their parameter, and the prior spread of f(x)f(x) it implies is a consequence stated under each. Under a monotone constraint (see dbarts) sd is the prior sd of a leaf value that no ordered neighbor bounds; a leaf a neighbor bounds is drawn from a normal π/(π−1)\sqrt{\pi / (\pi - 1)} times as wide, truncated to the ordering, which matches its marginal prior variance to sd^2, and sd is a lower bound on the prior sd of f(x)f(x) in the interior. A named sd is absolute, and is another way of writing k: the sampler runs sd = s as k = k.scale / s against the table's k.scale, and sd = invchi(df, s) as k = chi(df, k.scale / s) started at k.scale / s, and restates either whenever the response transform is re-anchored (see dbartsSampler-class), so the sd, or the prior on it, keeps its meaning where a k moves with the data. A drawn sd's current value lags at a re-anchor until its next draw, as a drawn k does. The k.scale a sampler or a fit reports is the table's, however the prior was written. It is refused on multinomial and multi-forest models (whose spreads come from their calibration maps, the latter stated through forest(sd = ), a different quantity), and on a hurdle fit, whose two parts are on different scales. NULL leaves either unnamed; NA is a missing value and is refused, here and in linear and gp. A bare normal() given as a forest's amplitude is something else, a normal prior on that forest's drawn coefficient whose median size is 1 (on a factor, the difference between two levels' coefficients); see forest.

linear(columns, k = NULL, sd = NULL)

Each leaf fits an intercept plus a linear term in the designated continuous predictor columns instead of a constant, so the forest models smoothly-varying coefficients. columns names model matrix columns (character) or indexes them (numeric) and is matched to the data when a sampler is built; unordered factor columns cannot be designated. The covariates are standardized internally and every coefficient shares the normal(k) prior. Reported leaf values keep the intercept; getTrees adds one beta.<column> column per covariate. xbart accepts the same specification through its own leaf.prior argument. k and sd name the spread as they do for normal, sd per standardized covariate: every coefficient, the intercept included, has prior sd sd for the forest total, so the prior sd of f(x)f(x) is sd * sqrt(1 + ||z||^2) at standardized covariates zz, and sd is its lower bound, attained at the covariate means.

gp(columns, k = NULL, lengthscale = NULL, max.leaf.size = 256L, sd = NULL)

Each leaf fits a smooth Gaussian-process function of the designated continuous predictor columns, drawn under a squared-exponential kernel whose prior scale ties to k exactly as the other leaf priors; columns resolves as for linear, and k may be fixed or given the chi hyperprior, sampled from the drawn functions' standardized magnitudes. lengthscale fixes the kernel lengthscales on the standardized covariate scale, one value per column or one recycled scalar; NULL uses the median pairwise-distance heuristic per column. Leaves holding more than max.leaf.size observations fall back to constant fits, confining the cubic kernel cost. Fewer trees are needed than for constant leaves: 10 to 25 is a reasonable range, since each leaf already fits a smooth function, while past about 50 the per-tree shrinkage leaves each function too small to improve on constant fits and the cost, linear in the number of trees and cubic in the leaf size, keeps rising. The two settings interact: a tree typically holds only two or three leaves, so a leaf carries a sizable fraction of the sample and max.leaf.size must be comparable to that fraction for the kernel to be used at all; lowering n.trees grows deeper trees and is the effective way to bring leaves under the cap, whereas lowering max.leaf.size only sends more leaves to the constant fallback. Because that fallback is silent - the fit stays coherent, it is simply not a Gaussian process over the leaves that took it - every leaf evaluation is counted. The counts ride the fit as gp.fallback (a named pair, evaluations and fallbacks), and a run in which more than a quarter of evaluations fell back warns once (class dbartsGPFallbackWarning), giving the share: at the default cap on a design of any size that is the normal outcome, not an error, and the warning is the notice that the cap rather than the kernel is doing the modeling. The remedies are the two the paragraph above names, in the order it names them. Function-valued fits ride prediction only: getTrees reports NA leaf values, and keepTrees storage grows with the leaf sizes. xbart accepts the same specification through its own leaf.prior argument. k and sd name the spread as they do for normal, sd as the amplitude of the forest total's Gaussian process: the prior sd of f(x)f(x) is sd at a leaf's own rows and decays away from them, so sd is its upper bound.

predict at a training row re-krigs the jitter-free posterior mean from the cached kernel and drawn training values, while the fit recorded during sampling includes a small conditioning nugget on the kernel diagonal; the two differ by roughly 2e-3 to 3e-3 at training locations (never during MCMC, which reads the recorded fit directly - only predict and test-data prediction re-krig).

chi(df = 1.5, scale = 2)

Chi hyperprior over k, sampled along with the rest of the model: k is given a chi distribution with df degrees of freedom and scale scale. The default, chi(1.5, 2), centers the sampled k near the field-standard fixed value of 2 (prior median 1.9) while letting it adapt to the data. It is the same prior as sd = invchi(df, k.scale / scale). scale = Inf remains accepted, but the posterior it gives k is improper: with little signal, few trees or many degrees of freedom, k can drift to infinity, where every leaf is zero and the trees add nothing to the fit. The first argument was degreesOfFreedom in 0.9-x; that name is accepted, with a warning, until dbarts 1.1-0.

invchi(df = 1.5, scale)

Scaled inverse chi hyperprior over a leaf prior's sd, on the sd's own scale: sd=scale/χdfsd = scale / \chi_{df}, equivalently sd2sd^2 is scaled inverse chi-square with df degrees of freedom. scale has no default, since a spread on the family's scale has no data-free one; scale = 0 is the improper sd−(df+1)sd^{-(df + 1)} limit. It is the same prior as k = chi(df, k.scale / scale), and chi(df, Inf) is invchi(df, 0); the binary defaults are invchi(1.5, 1.5) on probit and invchi(1.5, pi * sqrt(3) / 2) on logistic. In Stan's terms it is scaled_inv_chi_square(df, scale / sqrt(df)) on the variance, and an inverse gamma with shape df / 2 and scale scale^2 / 2. No other distribution on the sd is offered: this is the one conjugate to the normal leaves, which the sampler draws exactly; a half-t or half-Cauchy would need a non-conjugate update. Refused under a monotone constraint, as a chi on k is.

chisq(df = 3, quant = 0.9)

Chi-squared prior on the residual variance. Its scale is set from sigest, the residual-scale estimate supplied (or derived) at creation: quant is the prior probability that the residual standard deviation is below that estimate, so sigest = 1 gives the prior under which σ\sigma is below 1 with probability quant. df is a single positive finite number and quant a single number between 0 and 1: an infinite df, the limit that holds σ\sigma at a point, is refused, and fixed() states a held value.

fixed(value = 1)

Fixed residual variance, in squared response units. It is the residual scale rather than a distribution over one, so it ignores sigest - which is refused beside it unless it equals the square root of value, when it is accepted with a message and is an error from dbarts 1.1-0 - and suppresses the sampler's own σ\sigma draw. value is a single positive finite number.

student(df = 1)

A Student-t prior with df degrees of freedom, finite and at least 1, on a forest's drawn coefficient, given as a forest's amplitude; see forest. A bare student() means df = 1 here, the half-Cauchy, while the response family of the same name, dbartsFamilies$student, estimates its df when none is given; each is read by where it is written.

Details

Inside the prior arguments of the fitting functions - and inside a family's sigma - the same constructors are available by bare name, so dbarts(..., leaf.prior = normal(chi(1.5))) works regardless of what packages are attached: those arguments are evaluated with this vocabulary layered over the calling environment (for an argument a wrapper forwards through its ..., the one it was written in), along with num.vars, the number of predictor columns. A prior object built ahead of time with dbartsPriors$... can be passed to the same arguments. A wrapper's named formal that forces a bare constructor call before passing it on reaches R's own could-not-find-function error instead, extended with a hint naming dbartsPriors$normal(...) and its siblings.

References

Chipman, H., George, E., and McCulloch, R. (2010) BART: Bayesian additive regression trees. The Annals of Applied Statistics, 4(1), 266–298. doi:10.1214/09-AOAS285.

Linero, A.R. (2018) Bayesian regression trees for high-dimensional prediction and variable selection. Journal of the American Statistical Association, 113(522), 626–636.

Gramacy, R.B. and Lee, H.K.H. (2008) Bayesian Treed Gaussian Process Models With an Application to Computer Modeling. Journal of the American Statistical Association, 103(483), 1119–1130.

See Also

dbarts, bart

Examples

prior <- dbartsPriors$normal(dbartsPriors$chi(1.5))

x <- matrix(runif(200), ncol = 2)
y <- x[, 1] + rnorm(100, 0, 0.5)
sampler <- dbarts(y ~ x, leaf.prior = prior, power = 1.5)

## DART: a Dirichlet prior over split-variable probabilities, useful
## when only a handful of predictors out of many are relevant
set.seed(0)
n <- 60L
x.dart <- matrix(runif(n * 8), n)
y.dart <- 4 * x.dart[, 1] + rnorm(n, 0, 0.2)
fit.dart <- dbarts(y.dart ~ x.dart, split.probs = dart(),
                   control = dbartsControl(n.chains = 1L,
                                            n.threads = 1L), n.trees = 10L)
samples.dart <- fit.dart$run(20L, 20L)

## linear leaves: each leaf fits an intercept plus a slope in x1,
## useful for a function that is smooth and roughly linear in a subset
## of the predictors
set.seed(1)
x1 <- runif(n)
x2 <- runif(n)
y.lin <- 3 * x1 + rnorm(n, 0, 0.2)
df.lin <- data.frame(x1, x2, y.lin)
fit.lin <- dbarts(y.lin ~ x1 + x2, df.lin, leaf.prior = linear("x1"),
                  control = dbartsControl(n.chains = 1L,
                                           n.threads = 1L), n.trees = 10L)
samples.lin <- fit.lin$run(20L, 20L)

## gp leaves: each leaf fits a smooth Gaussian-process function of x1,
## useful for a smoothly-varying, nonlinear function
set.seed(2)
y.gp <- sin(2 * pi * x1) + rnorm(n, 0, 0.2)
df.gp <- data.frame(x1, x2, y.gp)
fit.gp <- dbarts(y.gp ~ x1 + x2, df.gp,
                 leaf.prior = gp("x1", max.leaf.size = 52L),
                 control = dbartsControl(n.chains = 1L,
                                          n.threads = 1L), n.trees = 10L)
samples.gp <- fit.gp$run(20L, 20L)
## the cap of 52 observations per leaf sends some leaves to the constant
## fallback (about a tenth of the evaluations here), counted in gp.fallback;
## a warning comes only when more than a quarter fall back
print(unlist(attr(samples.gp, "gp.fallback")))

Class "dbartsSampler" of Discrete Bayesian Additive Regression Trees Sampler

Description

A reference class object that contains a Bayesian Additive Regression Trees sampler in such a way that it can be modified, stopped, and started all while maintaining its own state.

Usage

## S4 method for signature 'dbartsSampler'
run(
  numBurnIn = NULL, numSamples = NULL, updateState = NULL, ..., callback = NULL
)
## S4 method for signature 'dbartsSampler'
sampleTreesFromPrior(updateState = NULL)
## S4 method for signature 'dbartsSampler'
sampleLeafParametersFromPrior(updateState = NULL)
## S4 method for signature 'dbartsSampler'
sampleVarianceForestFromPrior(updateState = NULL)
## S4 method for signature 'dbartsSampler'
growFromRoot(n.sweeps = 2L, updateState = NULL)
## S4 method for signature 'dbartsSampler'
copy(shallow = FALSE)
## S4 method for signature 'dbartsSampler'
show()
## S4 method for signature 'dbartsSampler'
predict(x.test, offset.test, n.threads = control@n.threads)
## S4 method for signature 'dbartsSampler'
predictForests(
  x.test, offset.test, n.threads = control@n.threads
)
## S4 method for signature 'dbartsSampler'
setControl(newControl)
## S4 method for signature 'dbartsSampler'
setModel(newModel)
## S4 method for signature 'dbartsSampler'
setData(
  newData,
  updateState = NULL,
  updateCutPoints = NULL,
  updateScale = NULL,
  updateStandardization = NULL
)
## S4 method for signature 'dbartsSampler'
setResponse(
  y, updateScale = FALSE, updateState = NULL, status = NULL
)
## S4 method for signature 'dbartsSampler'
setOffset(offset, updateScale = FALSE, updateState = NULL)
## S4 method for signature 'dbartsSampler'
setWeights(
  weights, updateState = NULL, updateScale = FALSE,
  updateStandardization = FALSE
)
## S4 method for signature 'dbartsSampler'
setCategoryOffset(offset, updateState = NULL)
## S4 method for signature 'dbartsSampler'
setCategoryTestOffset(offset.test)
## S4 method for signature 'dbartsSampler'
setActiveRows(
  active, updateState = NULL, updateScale = FALSE,
  updateStandardization = FALSE
)
## S4 method for signature 'dbartsSampler'
setForestWeights(forest, weights, updateState = NULL)
## S4 method for signature 'dbartsSampler'
setForestBasis(forest, basis, updateState = NULL,
    updateBasisScale = FALSE)
## S4 method for signature 'dbartsSampler'
setSigma(sigma, updateState = NULL)
## S4 method for signature 'dbartsSampler'
setPredictor(
  x,
  column,
  forceUpdate,
  updateCutPoints = "none",
  updateState = NULL,
  updateStandardization = FALSE
)
## S4 method for signature 'dbartsSampler'
setCutPoints(cuts, column, updateState = NULL, splits = "position")
## S4 method for signature 'dbartsSampler'
setTestPredictor(x.test, column)
## S4 method for signature 'dbartsSampler'
setTestPredictorAndOffset(x.test, offset.test)
## S4 method for signature 'dbartsSampler'
setTestOffset(offset.test)
## S4 method for signature 'dbartsSampler'
printTrees(treeNums, chainNums, sampleNums)
## S4 method for signature 'dbartsSampler'
getTrees(
  treeNums, chainNums, sampleNums, current = FALSE, newdata = NULL,
  forest = NULL
)
## S4 method for signature 'dbartsSampler'
getSigmas(result)
## S4 method for signature 'dbartsSampler'
getShape()
## S4 method for signature 'dbartsSampler'
getLatents(result)
## S4 method for signature 'dbartsSampler'
getSumsOfSquaredResiduals(result)
## S4 method for signature 'dbartsSampler'
getFitsWithoutOffset()
## S4 method for signature 'dbartsSampler'
getVariance(test = FALSE)
## S4 method for signature 'dbartsSampler'
getForestFits(forest = NULL)
## S4 method for signature 'dbartsSampler'
getForestAmplitudes(forest = NULL)
## S4 method for signature 'dbartsSampler'
getForestVariableCounts(forest = NULL)
## S4 method for signature 'dbartsSampler'
getLeafPrior(forest = NULL)
## S4 method for signature 'dbartsSampler'
getK(forest = NULL)
## S4 method for signature 'dbartsSampler'
setLeafPrior(leaf.prior, updateState = NULL)
## S4 method for signature 'dbartsSampler'
getForest(forest = NULL)
## S4 method for signature 'dbartsSampler'
setForest(forest = NULL, sd = NULL, power = NULL, base = NULL,
    amplitude = NULL, proposal.probs = NULL, n.perturb.cuts = NULL, treeShift = NULL,
    updateState = NULL, n.trees = NULL, vars = NULL, interactions = NULL,
    blocks = NULL, basis = NULL, ...)
## S4 method for signature 'dbartsSampler'
setTreePrior(power = NULL, base = NULL, split.probs = NULL)
## S4 method for signature 'dbartsSampler'
getVarianceForest()
## S4 method for signature 'dbartsSampler'
setVarianceForest(power = NULL, base = NULL,
    proposal.probs = NULL, n.perturb.cuts = NULL, updateState = NULL, n.trees = NULL,
    vars = NULL, ...)
## S4 method for signature 'dbartsSampler'
installTrees(donor, samples = NULL, forceUpdate = FALSE)
## S4 method for signature 'dbartsSampler'
sampleNodeParametersFromPrior(updateState = NULL)
## S4 method for signature 'dbartsSampler'
startThreads(n.threads = control@n.threads)
## S4 method for signature 'dbartsSampler'
stopThreads()
## S4 method for signature 'dbartsSampler'
storeState(ptr = getPointer())
## S4 method for signature 'dbartsSampler'
setState(newState, forceUpdate = FALSE)
## S4 method for signature 'dbartsSampler'
plotTree(
  treeNum, chainNum, sampleNum, forest = NULL, treePlotPars = c(
    nodeHeight = 12, nodeWidth = 40, nodeGap = 8),
  ...
)

Arguments

numBurnIn

A non-negative integer determining how many iterations the sampler should skip before storing results. If NULL (the default), it is filled in from the sampler's control object; an explicit NA reads as NULL for one release, with a once-per-session warning.

numSamples

A positive integer determining how many posterior samples should be returned. If NULL (the default), it is also filled in from the control object; an explicit NA reads as NULL for one release, with a once-per-session warning.

callback

NULL (the default) or a list with two elements, fn and context, each an R external pointer (externalptr): fn the address of a compiled dbarts_draw_callback (inst/include/dbarts/dbarts.h) and context an opaque pointer handed back to it unchanged, or NULL. It fires once per SAVED draw of this call, per chain, on the thread that owns that chain, over const pointers into this run's own result buffers or, for a channel this run does not keep, into a per-chain one-draw scratch buffer the chain's next draw overwrites: the per-observation channels under control@keepFits == FALSE, and always the draw's log-likelihood, which this run never returns and computes only for the callback. A nonzero return aborts the run. A draw's sigma is NaN on a sampler with a variance forest, which reports the variance channels instead. Only that both list elements are external pointers is checked - the address is dereferenced exactly as handed, so a malformed pair or a stale pointer crashes the session with no condition to catch. Registering one is a compiled task (Rcpp or plain C), not an R closure: see vignette("dbarts-as-a-component"). Three warnings. A callback that crashes takes the whole session down with it. An interrupt (Ctrl-C) cannot land while a call is running, so a callback that blocks or loops hangs the session. And under control@keepFits == FALSE the per-observation channels this call returns are NULL - present in the returned list, holding nothing - so whatever the callback itself accumulated is the only record of the run's per-observation fits. On a family = "hazard"/"hazard.probit"/"hazard.logistic" sampler the draw struct's numObservations counts the person-period-EXPANDED rows, one per subject per at-risk period, not the original subjects; the row-to-(subject, period) mapping is built in R and is not carried across to the callback. A hook set through the flat C entry dbarts_sampler_setDrawCallback does NOT fire on this route: bartcore_run (which this method calls) builds its own per-run hook from THIS argument, so the two channels are independent - a C caller mixing both must register the same callback on each to see it fire on both.

updateState

A logical determining if the local cache of the sampler's state should be updated after the call completes. One convention applies to every method that takes this argument - run, sampleTreesFromPrior, sampleLeafParametersFromPrior, sampleVarianceForestFromPrior, growFromRoot, and every mutator (setData, setResponse, setOffset, setWeights, setCategoryOffset, setActiveRows, setForestWeights, setForestBasis, setSigma, setLeafPrior, setPredictor, and setCutPoints): NULL (the default) resolves to the sampler's control object's updateState, and an explicit TRUE or FALSE, or a single number read as as.logical reads it (0 is FALSE), overrides it. Anything else is an error, raised before the sampler changes; an explicit NA, the default of 0.9-x, reads as NULL for one release, with a once-per-session warning. The mutators are typically called once per sweep inside a larger Gibbs/MH loop (as dbartsSampler is designed for); a control with updateState = FALSE keeps such a loop free of the store's cost on every call, while the default TRUE keeps state current after each one. Under control@updateState = TRUE the first read of a state no store has yet filled stores the sampler's current state, so a mutate-then-first-read sequence needs no explicit store; under FALSE that first read is NULL, and $storeState() makes the store. Pass TRUE explicitly to force a store under a control@updateState = FALSE sampler, or FALSE to skip one under control@updateState = TRUE.

shallow

A logical determining if the copy should retain the underlying data of the sampler (TRUE) or have its own copies (FALSE). Either way, the copy keeps the original's model and its data object, on whose record of the cut points, their weights and the response range it is built (see dbartsData). A copy of a sampler whose engine exists in this R session takes that engine's current chain, as stored, converting nothing, whatever the original's state field holds, and the copy's state field is that chain; the original's own field and draws are untouched. A copy of one whose engine is gone, as after a load, installs its stored state as a reload does, and without one is refused, as a reload is (see ‘Saving’). Either way it continues the same generator streams as the original - not an independent chain - typically matching an uninterrupted run to the last few digits, not bitwise; see the Reproducibility section of bart. When n.samples was changed after the chain was stored, the copy's saved-tree store takes the chain's capacity, as a reload does, and keeps the saved trees it holds rather than truncating or resetting them.

newControl

An object inheriting from dbartsControl. When passed to setControl, it cannot change n.chains or seed from the values the sampler was created with, a n.trees, useQuantiles or n.cuts its caller wrote cannot differ from the sampler's, and it cannot set keepTrees = TRUE without also giving n.samples; each is an error. A control taken from another fit that holds another of those three is taken with a warning, and a fresh control silently, the sampler keeping its own. Under treeShift = "auto" the step follows the mixture, which setControl may freeze, on every forest that states no mixture of its own. A proposal.probs or n.perturb.cuts its caller wrote that differs from the one in force is an error where every forest, the variance forest included, states its own, since no forest would take it; the message names $setForest and $setVarianceForest, which change one forest's. A control equal to the one in force, or stating neither, is taken.

newModel

An object inheriting from dbartsModel. When passed to setModel, it changes the numbers inside the sampler's model and is refused, by name and before anything is stored, where it differs in structure: the response family (a Student-t error against a Gaussian one included), the kind of leaf and its covariate columns, a Gaussian-process leaf's max.leaf.size, the interaction limits and blocks, DART against the ordinary tree prior, the columns a forest may split on (its forest vars), the tree count of a forest or the variance forest, and the monotone directions; make a new sampler instead. A count the model does not state, as in dbartsSpec(data, power = 3)$model, leaves the sampler's. It takes power and base, the split probabilities, the leaf scale as k or sd, the residual prior, the Student-t degrees of freedom, a negative-binomial shape, a Gaussian-process lengthscale and DART's own settings. A degrees of freedom, shape or DART alpha handed from held to drawn starts at the value in force, not where a new sampler would start it; a new lengthscale is refused on a sampler holding kept draws, which replay only under the kernel they were drawn with. A model that states no family, degrees of freedom or lengthscale keeps the sampler's. A split probability of zero on a column some chain's trees split on is refused, naming the column. A residual prior other than the sampler's own is refused on a family with no residual scale (probit, logistic, ordinal, negative binomial, hazard), a chisq() residual prior of df 2 or below on a sampler whose variance forest has two or more trees, each tree's prior being calibrated to the prior mean of σ2\sigma^2, which is infinite there, and so is a model whose leaf prior's k or sd does not resolve to the leaf hyperprior and prior scale it carries: setLeafPrior restates a leaf prior. The sampler's own model, as after setResponse or setOffset, is always accepted. On a sampler of several forests or a multinomial one it takes the fitting function's level, as setTreePrior and setLeafPrior write it: a changed power or base reaches the forests with no basis that state none of their own, and, where one forest has no basis, or on a multinomial sampler's category forests, those forests whatever they state; the leaf prior goes where setLeafPrior sends it; and the residual prior is installed as on one forest. A number a forest's record in the model states, a mean forest's own sd, power or base or the variance forest's power or base, is installed where it differs from the sampler's, through the code setForest or setVarianceForest runs on that forest, so the sampler runs as after that call; the later write wins between this and those methods. A number the record does not state is left as it is: dbartsSpec(data, power = 2.5, variance = varianceForest())$model moves the mean forest's depth and leaves the variance forest's, which only copied the mean depth at creation, and a forest that states its own on the sampler keeps it. A forest's coefficient's prior that differs is refused, naming setForest; so is a leaf scale other than the sampler's, split probabilities other than equal ones, and a forest's sd whose sharers' parts of the prior total then differ from the model's. A new fixed negative-binomial shape keeps the latents in force. This draws nothing; the next sweep draws the augmentation variables against the change.

newData

An object inheriting from dbartsData. One that keeps its frame (keep.data = TRUE) is made into the block-holding object the sampler runs on first, as dbarts makes it. The data of a sampler of several forests are taken as its rows, the bases and their records dropped, as dbarts reads them given no forests: the sampler keeps its own forest. A hazard sampler also takes data built from a Surv response (dbartsData(Surv(time, status) ~ x, newData)): its subjects are spread onto the sampler's own periods as dbarts spreads them at creation, one row per period at risk with the period column last, and a time past the last period leaves its subject at risk through every period with no event. Before those rows are built their memory is projected from the sampler's control and trees, as creation projects it, and a projection past the machine's physical memory warns once per session (class dbartsMemoryWarning; see the hazard item of dbartsFamilies); the data are taken either way. A hazard sampler refuses a hand-built person-period matrix whose last column is not named period, at setData and at creation; give it survival data, or fit the rows with family = "binomial", the period a predictor. Columns are matched by name: the new data carry the sampler's names, in any order, and names that are not the sampler's are refused, as predict refuses them, leaving the sampler as it was. A matrix with no column names is read by position, with no message, as is any data handed to a sampler that has none, whose record then takes the data's names, which predict needs; a sampler whose names repeat takes the same names in the same places only. A factor column is read by label against the levels the sampler was created with, which it keeps: fewer levels, the levels in another order and declared levels no row has are taken, each row at its own label; a row, training or test, at a label the sampler never had is refused by name, as predict refuses one, and so is a factor column given as numbers with no level table. A factor whose labels were changed on purpose is relabeled to the sampler's labels first, with levels<-, or given to a new sampler. A column that could hold missing values before the call still can, and one the new data first give a missing value becomes able to, as ‘Missing values in predictors’ in ‘Details’ describes. The cut points, the response range and a linear or gp leaf's covariate standardization follow updateCutPoints, updateScale and updateStandardization; with each left at NULL, a value newData records (its cutPoints, response.range and standardization slots, see dbartsData) is used, a cut grid or standardization it does not record is derived from it, and a response range it does not record is the sampler's own, kept as setResponse keeps it. A cut count or quantile rule newData states wins over the sampler's (see n.cuts and useQuantiles on dbartsData), and the sampler derives by what it takes from then on, in this call and in any later refresh; an object carrying cutPoints brings the count and rule that made them, an unstated rule reading as even; an object stating neither keeps the sampler's, a count stated to dbartsData() is read over the predictors the sampler holds, a hazard sampler's period column among them, which takes a count only by its own name and is otherwise 100, and updateCutPoints = "none" keeps the sampler's whatever the object states. The sampler writes its values into its own data object, so sampler$setData(sampler$data), the object handed back whole, keeps the cut points, the range and the standardization the sampler held, where 0.9-x derived them again; to change a column and keep them, sampler$setPredictor(newValues, 1, forceUpdate = TRUE) takes the values and keeps the cut points and the record; and a data object made by dbartsData records none: it derives the cut points and the standardization, as before, and keeps the sampler's response range and, on a count sampler, its count center, where 0.9-34 derived the scale again from the new response; updateScale = TRUE derives them. Draws the sampler has saved (keepTrees) stay the functions they were, so predict returns the same values for them before and after the call. To that end a linear leaf's coefficients, saved and current, are rewritten into the center and scale the call derives or takes for its leaf covariates, and every saved draw into the response scale it derives or takes; a value kept, or taken equal to the one in force, rewrites nothing. A row whose leaf covariate is missing is read at that covariate's center, so what a linear leaf predicts for it follows the center to the new data's. A standardization the call derives is read over the new data's rows in the likelihood, those of positive weight; where fewer than two rows are in (subjects, for a hazard fit, whose data hold each subject's rows together, at periods 1, 2, 3 and on in order, as dbarts expands them, data laid out otherwise being refused), or the call reads the response's scale from every row because those rows hold fewer than two distinct values of it, the leaf covariates are read from every row, under one warning; where the rows read hold one value of a leaf covariate, or observe none, the call is refused before anything changes, unless a gp leaf states its lengthscale, and updateStandardization = FALSE takes the data under the sampler's own. Under such a family the sampler's own data object carries no weights, so setData(sampler$data) drops the mask in force: hand the 0/1 weights back on the data object, or call setActiveRows after. A leaf covariate that holds a single value is centered at it and divided by 1, so a leaf reads zero for it on every row and its slope adds nothing to the fit. Where a covariate is such a column on one side of the call only, the current coefficients are still rewritten by the formula, with 1 for that side's scale, so each leaf keeps its function of the covariate: onto such a column it takes the value its function has at the new constant, and off one the slope no row informed is carried onto the new data's spread, so the fit may move until the sampler has run on them. Where it is such a column on both sides the current coefficients are left as they are. A column that setPredictor has since given other values is read as what it then holds: one moved to another single value no longer sits at its center and is rewritten as any other column is, by the formula, which keeps the function of the covariate. The data fixed that function at one point only, so new data that spread the covariate widely can carry the current fit far from where it was until the sampler has run on them. Saved draws are rewritten by the formula in every case, with 1 for the scale. The saved draws of a Gaussian-process (gp) leaf cannot be rewritten: a sampler with such leaves that holds saved draws refuses a call that would derive the standardization or the range, as one given a data object that records neither does, or that would take a recorded one other than its own; it takes one that keeps both, as setData(sampler$data) or updateStandardization = FALSE, updateScale = FALSE do, whatever cut points it is given, a saved draw holding its thresholds by value. Pass those two, or make a new sampler. A family with no response range (probit, ordinal, logistic) has none to change. One that holds no saved draw takes any call as any other sampler does. The ordinal cutpoints, the Student-t degrees of freedom and the negative-binomial shape the sampler has drawn are kept, as are its trees, and the latents start as creation starts them, the number of rows possibly differing (an ordinal or negative-binomial sampler from the kept cutpoints or shape); the next sweep draws them from the kept values. This draws nothing; the next sweep draws the augmentation variables against the change.

y

A numeric response vector, or on a count sampler the matrix below, of length equal to that with which the sampler was created, and lying in the response family's support: 0/1 for probit and logistic, an integer category index in [1,K][1, K] for ordinal, and a finite non-negative integer count no larger than 10610^6 for nbinom (the shape grid's count histogram is sized from the largest count, so a larger one allocates without bound). Values off the support are refused, as they are at creation; gaussian and aft (log survival times) constrain nothing. A missing value is refused in every family: to leave a row out of the likelihood mid-chain, mark it inactive with setActiveRows and give it any value in the support, which enters no draw while the row stays inactive unless the call re-anchors the scale (updateScale = TRUE), which reads the rows in the likelihood. On a multinomial (softmax) sampler y is its response as its formula writes it: an n×Kn \times K matrix of non-negative integer counts, column kk holding category kk's successes, with trials ni=∑kn_i = \sum_k y[i, ] at least 0 and no larger than 10610^6: a row with no trial enters no likelihood and still receives fitted probabilities, and the first such row in a session warns. Both nn and KK are fixed at creation - every combiner buffer is sized by nn, and KK is the forest count - so only the values may change; a matrix of the wrong shape is refused naming the count in force. The trees carry over, fitted to the previous counts exactly as setResponse leaves any sampler's, and the next run forms every category's working response against the new matrix. The matrix is written to both the engine and data@counts (its row sums to data@y), so getPointer's transparent re-creation after save and load carries the current response rather than the one the sampler was created with. Cost, not a defect: the sweep draws nin_i Polya-Gamma variates per observation per category, so replacing single-trial labels with grouped counts multiplies sweep cost by mean(n_i). A missing count is refused, as a missing response is; to leave a row out of the likelihood mid-chain, mark it inactive with setActiveRows, as in every family, or write zeros into it, which is the same as far as the likelihood goes. A vector of numbers is refused there, since with each row's trials held it cannot say how they split among the categories. A factor, or a character vector read as one, is taken where every row holds one trial, as in a sampler built from a factor: its labels are matched by name to the categories the sampler records, in any order, a label it lacks is refused by name, the response is then recorded as written as a factor, so predict(type = "ppd") draws categories, and where any row holds more than one trial the factor is refused, naming the count matrix. On a probit or logistic sampler whose response was written as a two-level factor, a factor or character vector is taken the same way, its labels matched by name to the two levels the sampler recorded, the first coded 0 and the second 1 whatever order the new factor lists its levels in (unlike glm, which reads level position, so a releveled factor does not flip the model); a label the sampler lacks is refused by name, and a sampler whose response was written as numbers records no levels and takes only 0 and 1. On a binomial sampler, a logistic one whose data carry the response as counts of successes and failures, y is the n×2n \times 2 matrix of successes and failures, or a vector of successes with each row's trials held, a count above its row's trials refused; setData takes new data whose counts give both, the number of rows free. A count sampler has no response scale to re-anchor and ignores updateScale. This draws nothing; the next sweep draws the augmentation variables against the change.

status

For setResponse on an aft (survival) sampler, a replacement per-observation censoring status: a numeric vector of length equal to that with which the sampler was created, 1 an uncensored event and 0 a right-censored observation whose response value is its truncation lower bound. NULL (the default) leaves the censoring structure in force and is the call every other family makes; a non-null status on any other family is refused by name. The response and the status change in ONE call, and the status is installed first, so a row newly censored is bounded at its own NEW observed log time and held there until the next sweep draws it above that bound against the fit then in force, as setResponse leaves every censored row at its new bound, while a row that becomes an event is restored to that time - data, rather than a draw. A status-only change is setResponse(sampler$data@y, status = s). The number of observations is fixed, the status being stated over it; setData, whose replacement may change it, refuses an aft sampler and names this channel instead. The vector is validated - real, of length nn, every element exactly 0 or 1, NA refused - before anything installs, so a refused call leaves the sampler, data@y and the recorded status exactly as they were; it is written to the sampler's data object only after the engine accepts it, so getPointer's re-creation after save and load carries the current censoring rather than the one the sampler was created with. Under an installed mask (active) the response install is mask-blind but the sweep's draw is not, so an INACTIVE censored row's latent stays at its bound until the mask clears; that is what setResponse leaves such a row at with or without a status.

x

For setPredictor with no column, the whole of the predictors: a data frame, whose columns are matched to the sampler's by name, in any order, a name that is not the sampler's being refused (a sampler with no names reads them by position), and whose factor columns are coded by label as a column update's are, or a numeric matrix, taken only where every predictor column is numeric - on a sampler with a factor column a matrix is refused by name, since its codes could not say which values are labels. A matrix that carries column names is matched by name as a frame is, and one with none is read by position, with no message. Otherwise, a numeric predictor vector of length equal to that with which the sampler was created. Can be of a distinct number of rows for setTestPredictor. A column update (column given) on a column coded from a factor takes that column's labels instead, for setPredictor and setTestPredictor alike: a factor, character vector or sparseFactor, matched by label against the training levels, as a whole data-frame update is coded; several columns take a data frame. A label the column does not declare is refused by name, as is a number, which could only be read as an internal code. A missing label is a missing value: setPredictor takes it whether or not the column has held one, and setTestPredictor refuses a missing value, a label or a number, in a column that has never held one in training, as the whole test set is refused. What a column's first missing value does is under ‘Missing values in predictors’ in ‘Details’. On a hazard fit, setPredictor takes the period column, whole, as a column or row by row ("partial"), only unchanged, refusing any other values before anything moves: the column is the expansion of each subject's time at risk, set with the response, and setData replaces it. setPredictor draws nothing: the next sweep draws the augmentation variables against the accepted predictors.

x.test

A new matrix, data frame, or sparse-bearing test set (the column types accepted by dbartsData), of the number of columns equal to that in the current model; a numeric matrix is taken only where every predictor column is numeric, and is refused by name on a sampler with a factor column, whose test rows come as a data frame (the same holds for predict on a fit). A data-frame/sparse x.test is coded against the training levels; setTestPredictor and setTestPredictorAndOffset then install it as a resident, whole-object replacement of the test set (see column), while predict and predictForests route its rows through the trees off that same storage, retaining nothing.

offset

A numeric vector of length equal to that with which the sampler was created, or NULL. If offset.test was set from offset, will attempt to update that as well.

For setCategoryOffset, a multinomial sampler's per-category shift instead: an n×Kn \times K numeric matrix, or NULL to clear one. The latent becomes fik+oikf_{ik} + o_{ik}, so the shift enters the log-sum-exp margins, every category's working response and the reported probabilities, and never a leaf value. This is the response-side counterpart of setResponse's count matrix rather than of setOffset, whose flat shift is added AFTER the categories are blended - the wrong side of the nonlinearity - and is the softmax's own null direction besides, which is why setOffset itself is refused on such a sampler. Only the row-centered part is identified: adding a constant to a whole row leaves every reported probability unchanged, and the entrance leaves the matrix as given rather than re-centering it. It shifts the TRAINING latent only. Mirrored into [email protected], so a re-created sampler carries it. Column names, when present, are matched to the sampler's category names (the column names of its counts; "1", ..., "K" when it has none): a permutation is reordered by name and other names are refused, except that a sampler without count column names reorders a permutation of its indices and ignores other names. Unnamed columns stay positional. setOffset draws nothing: the next sweep draws the augmentation variables against the new offset, on a logistic sampler as on every other family.

updateScale

Logical indicating whether BART's internal scale should re-anchor to the new offset (setOffset), response (setResponse), weights (setWeights) or active rows (setActiveRows). On the last two it is the argument after updateState, so the positional setWeights(w, TRUE) of earlier releases still names updateState. With TRUE they install the weights or the mask first and then take the response's scale (a count sampler's center) again from the rows then in the likelihood, as creation on those rows would, whether or not the call moved a row in or out; the response and the offset are not changed, and neither is a test offset, a cut point, a covariate standardization or the residual prior. Nothing is taken again by a one-forest probit, ordinal, logistic or hazard sampler, which accepts the argument and ignores it, also with gp leaves holding saved draws, none of which it moves. A call refused for any reason installs nothing; a call that keeps the scale (below) installs the weights or the mask. A stored state does not undo a re-derivation, and with updateState resolving to TRUE the state is stored after it. Defaults to FALSE, locking the scale set at creation; should only be TRUE during burn-in, as re-anchoring mid-run makes the fits across iterations no longer comparable. Draws already saved (keepTrees) are rewritten into the new scale, a heteroscedastic sampler's variance draws included, so predict returns the values it returned before the call; the current fit follows the new scale. TRUE is refused by a sampler with Gaussian-process (gp) leaves that holds saved draws, whatever the new response, offset, weights or mask, where its family has a scale to re-derive (gaussian, student, aft and nbinom): make a new sampler, or leave updateScale at FALSE. A probit, logistic or ordinal sampler has none, so it takes TRUE as it takes it in setData, and its saved draws predict what they did. A draw is saved by every sweep run as a sample while trees are kept, warm-up sweeps included, so such a sampler takes a re-anchor during burn-in only as long as its sweeps are run as burn-in, which saves nothing: run(1, 0) between re-anchors, not run(0, 1). For a survival (aft) sampler the scale is always that of the observed times, a censored row's censoring time among them, and never of a time the sampler has drawn for a censored row. TRUE is refused by a multi-forest (forests) sampler, whose calibration map is pinned at creation - whatever its response family, and whether or not there is a transform to re-anchor - and is never restated; the response and a basis scale may span different rows, which is why. A multinomial sampler takes setActiveRows(updateScale = TRUE) and derives nothing, its leaf scale and center being the same whatever rows are in. A heteroscedastic (variance) sampler takes it: the variance forest's leaf prior is re-derived from the residual prior on the new scale, exactly as creation on the new response would have stated it, and the drawn s2(x)s^2(x) is carried into the same units, so the surface keeps its meaning in response units across the swap. setData carries that restatement too wherever the scale moves. On setData the argument defaults to NULL, which takes the response.range the new data object records and otherwise keeps the sampler's, as setResponse does (0.9-34 derived it again); TRUE derives it from the new data, over its rows in the likelihood as creation would, and FALSE keeps the sampler's, the new response going in under it with no draw rewritten. A sampler made by hand from another's parts takes the record in the same way. Where rows are out and the rows in hold fewer than two distinct values of the response, a setData that derives the scale takes every row, under a warning of class dbartsScaleFallbackWarning; setResponse, setOffset, setWeights and setActiveRows with updateScale = TRUE instead keep the scale and the center in force, as with updateScale = FALSE, and warn with the same class once for a sampler (a copy or a reload is a new sampler, setData is not). On setResponse, supplying this argument positionally (setResponse(y, TRUE)) rather than by name warns once per session - it is the second argument, where a caller porting code written before this order had updateState there instead.

offset.test

A numeric vector of length equal to that of the test matrix, or NULL for no offset; a missing value is refused. Can be missing for setTestPredictorAndOffset. Refused, by name, for predictForests: an offset shifts the combination of the forests, exactly as the response transform's shift does, and neither is any one forest's own total.

For setCategoryTestOffset, a multinomial sampler's ntest×Kn_{\mathrm{test}} \times K per-category test shift, or NULL to clear one: the recorded test channel becomes softmax(ftest+otest)\mathrm{softmax}(f_{\mathrm{test}} + o_{\mathrm{test}}), formed where the training blend forms its own. The test fits enter no likelihood, so this moves the reported test probabilities and nothing else. Its rows are the CURRENT test rows, so replacing those rows while it is installed is refused rather than silently reinterpreted - clear it first - and out-of-sample predict does not read it at all, taking its own matrix for the rows it is given. Mirrored into [email protected]. For predict on a multinomial sampler, likewise a per-category matrix, one row per PREDICTED row: a flat vector is refused there for the same reason, and a sampler holding either resident category offset refuses an unnamed call rather than reporting the offset-free surface, which an explicit all-zero matrix asks for on purpose. Column names, when present, are matched to the sampler's category names (the column names of its counts; "1", ..., "K" when it has none): a permutation is reordered by name and other names are refused, except that a sampler without count column names reorders a permutation of its indices and ignores other names. Unnamed columns stay positional.

n.threads

For predict and predictForests, a per-call worker count that does not persist, defaulting to the sampler's own (the n.threads of its control object, fixed at creation). The replay is partitioned by (chain, saved draw), each partition writing its own rows and nothing being reduced across workers, so the result is identical bit for bit at every value and only the time taken changes. A replay small enough that the partition could not pay for itself runs inline whatever is passed.

These are native threads, so _R_CHECK_LIMIT_CORES_ does not govern them: that variable is read only by parallel:::.check_ncores, which counts simultaneously spawned processes and never sees a thread.

run takes no thread count: a run uses the sampler's own, which setControl changes, and its draws are the same at every count.

sigma

A single positive residual standard deviation, on the original response scale; it is assigned to every chain. setSigma only applies to a sampler whose residual standard deviation is a free parameter: it is refused on a probit-, logistic-, multinomial-, ordinal-, or count-family sampler, which fix it at 1 by the model definition, and on a heteroscedastic (variance) sampler, whose variance forest owns the residual scale. A gaussian sampler with family = gaussian(sigma = fixed()) is not fixed in this sense and is still accepted: suppressing the internal draw so an outer sampler owns sigma is what that prior is for. There the write rewrites the model's fixed value, recorded on the model field, so a copy or a save and load keeps it; a write through the C API reaches the engine alone, and a sampler re-created after one holds the model's value until the next write. This draws nothing; the next sweep draws the augmentation variables against the change.

weights

A numeric vector of case weights, of length equal to that with which the sampler was created. What a weight MEANS is family-specific: for a gaussian-family sampler it is a precision, non-negative, or under weights.type = "frequency" (fixed at creation, see dbarts) a count of identical observations, real and non-negative, and a weight of zero takes an observation out of the likelihood and out of the residual degrees of freedom while keeping it in the design, its place in a leaf and its fitted values (see below); for a logistic-, nbinom- or multinomial-family sampler it is an observation COUNT and must be a non-negative whole number, no larger than 10610^6 times the row's trials, y+ry + r or row total, a count of 0 taking the row out of the likelihood: it consumes no random number, and the row draws as one masked by active does. A zero-weight row is IN THE DESIGN BUT NOT IN THE LIKELIHOOD, and takes no part in the response scale, the count center or a forest's default sd, which are taken over the rows of positive weight when the sampler is created (a row is in when its weight is positive and no mask switches it off) and held when the weights or the mask change, unless the call carries updateScale = TRUE, so the three ways to leave a row out - at creation, by setWeights or setActiveRows, and by subset - differ by when the row left. It counts as a member of its leaf, so the rule that rejects a tree move leaving a leaf empty counts it too: the trees a sampler may hold do not depend on the weights, and a leaf may hold zero-weight rows only, in which case no likelihood term reaches it and its value is a draw from the leaf prior. A fit with zero weights is therefore close to the fit on the remaining rows alone but is not that fit, since the trees can spend splits on regions of zero-weight rows. In one measured case, 300 rows with 50 trees and the cut points held equal and the scale that of the remaining rows: with a random half of the rows at weight zero the posterior mean fit at the remaining rows moved by at most 0.02 of a posterior standard deviation, and with a whole region at weight zero by at most 0.05; the residual standard deviation did not move, and the fit at the zero-weight rows was 1 to 2 percent more variable. dbartsData's subset drops rows outright, and with them their part in the cut points and the response scale. In exchange, an outer sampler that redraws 0/1 weights or active every sweep from its own conditional samples the joint model it assumes, which it would not if the admissible trees moved with the weights. A Student-t sampler holds a scale λi\lambda_i per row, which setWeights leaves as it is: the next sweep draws every scale from its conditional given the fit and the weights then in force, so an outer sampler that draws the weight given the scales and one that draws it with the scales integrated out are both exact. setWeights sets a weighted likelihood on gaussian-, logistic- and nbinom-family samplers. A logistic or nbinom swap is a model change with a defined meaning rather than a reweighting: the counts multiply the shape of the Polya-Gamma latents, which the next sweep draws against the new counts, so an outer sampler can vary exposure between runs. probit, ordinal and aft refuse a weighted likelihood by identification: a weighted probit has no tractable latent-variable form, ordinal inherits that, and aft fixes its censoring structure at creation. On a probit, ordinal or nbinom sampler a vector of 0s and 1s is accepted all the same: it names the rows in the data set rather than a precision, is held in the data object's weights slot, all ones as no weights, and composes with active below, a row being in when its weight is 1 and the mask keeps it; any other value keeps the refusal on probit and ordinal, and is a count on nbinom. setData carries the same rule on the whole-data conduit, the next sweep drawing the latents against the counts the replacement data carries; replacement data given without weights is single-trial, as at creation, so a logistic sampler built with counts and handed weightless data becomes an unweighted one. The weights themselves are not part of the saved state, and the state records nothing of them: the latents it carries are the values its trees were drawn from, which setState installs without drawing, and the next sweep draws them against the weights then in force. A weight change is undone by setWeights with the old weights and setState with the stored state, in either order, the sampler then continuing bit for bit as one that installed the stored state under the old weights would. This draws nothing; the next sweep draws the augmentation variables against the change. See dbarts for the family-specific weight rules that apply at creation time.

For setForestWeights, a distinct per-FOREST case weight on a Bayesian causal forest (built with forests = , see dbarts), refused off one: it composes with weights and active as (wiai)mf2si(w_i a_i) m_f^2 s_i, where mfm_f is the named forest's own multiplier, rather than widening either channel, so s_i = 0 excludes row ii from that forest's own leaf conditionals only - its occupancy, its place in the combination, and the residual degrees of freedom are unaffected, a leaf of that forest may hold such rows only (its value is then a draw from the leaf prior), and the reported location still carries the forest's full contribution even when every row is excluded. The third leg of a three-way degenerate-value contrast: weights at all-ones installs and, on gaussian and logistic, is measurably distinct from carrying none, active at all-ones installs nothing and clears any mask in force, and setForestWeights at all-ones INSTALLS - a round trip reports it - but is bitwise IDENTICAL to carrying no per-forest weight at all, the null gate its multiplicative composition (mf×1=mfm_f \times 1 = m_f) is built to guarantee. The weight does not ride the sampler's saved state - a sampler rebuilt with setState from a stored state silently drops it while statesAgree still reports agreement - so it is additionally mirrored on an R5 field that getPointer, setState, and copy all reinstall on every re-creation; a caller never reinstalls it by hand. setData needs no clearing rule here the way it does for active: it is refused outright on any multi-forest sampler (“a multi-forest sampler fixes its data at creation”), so the two channels never interact.

active

A numeric vector of per-observation 0/1 membership indicators - "row ii is not in the data set for this sampler this sweep" - of length equal to that with which the sampler was created, or NULL. setActiveRows reaches every family, the four that refuse a weighted likelihood included: gaussian, Student-t, probit, ordinal, logistic, nbinom, and aft samplers all accept it, including a multi-forest (forests) sampler, whose forests share one response of whichever family it was built under. It is absolute and independent of weights, composing with it in either call order (wi×aiw_i \times a_i in effect). NULL clears the mask (every row active). Length and NA are validated as for weights; the only legal values are exactly 0 and 1, and a fractional element refuses the WHOLE call and installs nothing. An all-ones vector reports success but installs NOTHING, clearing any previously installed mask - the OPPOSITE of weights on gaussian and logistic, where an all-ones vector installs and is measurably distinct from carrying no weights at all. One channel states membership, the other precision, and the two deliberately carry opposite degenerate-value policies. The response scale, the count center and a forest's default sd are held across a mask as across weights, unless the call carries updateScale = TRUE, and a linear or gp leaf's covariate standardization unless it carries updateStandardization = TRUE. On a probit, ordinal or nbinom sampler, whose 0/1 weights state membership too, activeRows holds only what setActiveRows installed, and a row either channel brings back in draws nothing at the call, the next sweep drawing its latent first.

An inactive row (active[i] == 0) contributes nothing to any leaf sufficient statistic, branch log-likelihood, birth-scan weight total, leaf parameter draw, or family-level parameter update that sums over rows (residual degrees of freedom, a shape statistic, a group's per-group sums, and so on). It still occupies its leaf for COUNT-based accounting - numObservations, the birth scan's own member count, and leaf collapsing, which triggers on member count regardless of weights - and it still receives a fitted value: run()$train, getForestFits, getFitsWithoutOffset, and predict report f(xi)f(x_i) at an inactive row exactly as at an active one, which is what makes this channel worth more than physically dropping the row. The rule that rejects a tree move leaving a leaf empty is count-based too: an inactive row is in the design but not in the likelihood, so a leaf all of whose rows are inactive is legal, takes no likelihood term and has its value drawn from the leaf prior, and the trees a sampler may hold do not depend on the mask. That is what lets a larger sampler that redraws the mask every sweep, from each row's conditional given the fit, sample the joint model it assumes. Its cost is that a fit under a fixed mask is close to the fit on the active rows alone but is not that fit, by the amounts given under weights. With every row inactive every leaf is such a leaf, which is the exact sense in which the forest “sits at its prior” - a distribution over structures, not a frozen one.

An inactive row's own latent draw is SKIPPED - no random numbers are consumed for it - for every family except Student-t, whose per-row λi\lambda_i is drawn unconditionally at every row regardless of the mask; there the mask instead ANNIHILATES its contribution through the composed weight (wiλiaiw_i \lambda_i a_i). For a skipping family, getLatents at an inactive row returns its LAST DRAWN value, which is stale; the correct read at an inactive row is its fit, not its latent. A stale latent does not come back into the likelihood: each sweep draws the latent of every row the mask holds in, for Student-t its λi\lambda_i of every row, from the row's conditional given the fit and before its trees, so a row switched back in is drawn afresh against the current fit with the rest. setActiveRows itself draws nothing and consumes no random numbers, whatever it switches, so a caller that draws the mask from the fit with the latents integrated out (a probit row's membership from its Bernoulli likelihood, say) need not call setResponse to refresh them. A multinomial sampler holds no latent between sweeps. A state installed over a different mask keeps, at rows that were out when it was stored, the latents they left with until the next sweep draws the rows the mask now holds in.

An inactive row's pointwise log-likelihood - the value the flat C API's logLikelihood results field reports (see ‘Mutation cost’ above for the C interface) - is NaN rather than a finite value or -Inf: a row that is not in the model has no likelihood to report.

Three quantities do NOT follow the mask, by design, so a caller wanting them recomputed on the active subset must re-create the sampler instead: the split-candidate cut grid stays the FULL-data grid, holding the tree prior fixed while the row set moves; the response transform and residual prior scale stay creation's calibration (a masked gaussian - and so aft, and any variance decoration - keeps the range and residual-prior scale creation set, which were taken over the rows in the likelihood then, every row when none was out); and an ordinal sampler keeps its FULL-data number of categories, free thresholds, and log-gap prior even when a mask empties a boundary category - only setData changes them. setData also CLEARS an installed mask - the mask is a per-row vector and setData may change the number of rows - so a caller replacing the data must reinstall any mask it wants kept.

The mask does not ride a sampler's saved state - the state carries derived quantities and no raw conditioning vector - so, exactly as setForestWeights's per-forest weight is, it is mirrored on an R5 field that getPointer, setState and copy all reinstall on every re-creation: a masked sampler saved and reloaded goes on masked, and a caller never reinstalls it by hand. What the mirror cannot do is travel with the state itself. Installing a stored state into a DIFFERENT sampler object leaves that object's own mask in force, whatever the donor's was - a destination that never had one stays unmasked and computes different draws while statesAgree still reports agreement - since the state holds no mask for the restore to re-derive against. Conversely, the latents DO ride the state, and under an installed mask they are stale at every inactive row for a skipping family, so two samplers at the same posterior state but different mask histories carry different stored latents and statesAgree correctly reports DISAGREEMENT; a Student-t sampler is affected the same way, since an inactive row's stored λi\lambda_i is drawn from a conditional its own data no longer informs.

basis

The data the named forest's amplitudes multiply, with as many rows as the sampler was created with and one amplitude per column. It is a value, or a one-sided formula, which is read as the basis of a forest is, its names found where the formula was written. A single string is refused, a basis being a column's values here and not its name: hand over the column, or ~dose. It must be of the class the forest was created with, which decides what the forest multiplies and never changes. A forest of levels, created with a factor, a character vector or a logical vector, takes one of those three, matched to the forest's levels by name and not by position: the replacement may list its levels in another order or leave one out, a level of the forest that no row has is a column of zeros, and a row at a level the forest does not have, or at NA, is refused. Coefficient jj multiplies level jj's rows after any swap, whatever the replacement declares. Numbers are refused for such a forest, the level indicators the sampler stores among them: to hand a basis back, hand back the factor. A forest of numbers takes one numeric column, a vector or a matrix of one column, a column of zeros among them, and refuses several columns, a factor, a character vector and a logical vector; as.numeric() of a logical vector is its 0/1 column. A forest created with no basis takes none. The sampler keeps the forest's block, one column for each level of a factor with no reference level dropped, in data@bases[[f]], and its levels in [email protected][[f]], f the forest's position (neither list has names, so a label does not index them), and not the factor it was handed: a caller that will hand a basis back, to restore a proposal it rejected, keeps the factor it handed over. No forest changes width, held or drawn, so the names its columns were created with stay, whatever names the replacement has. The forest's label does not change. Unlike creation, a swap may leave a level of the forest with no row, and a numeric basis may hold a column of all zeros, the amplitude moving under its prior alone until a row takes it again, so a swap inside a larger sampler can leave a level or an arm momentarily unobserved; creation drops a level no row has and refuses a column of zeros. setForestBasis is the sole route by which a basis changes after creation, and it applies only to a sampler whose forests carry amplitudes, built with forests = (see dbarts). The amplitudes are preserved: an install leaves every one of them bitwise. A swap moves the basis and nothing else: no forest's prior moves, so a numeric forest keeps the sd per unit its creation gave it, a default one the scale of the column it was created on ([email protected]), unless updateBasisScale = TRUE takes the default of the new column. A basis that is not one of the canonical shapes (a dense all-ones column, or a complementary 0/1 pair) moves that forest onto the general amplitude conditional, which is a model fact and not revertible by a later data swap. The matrix is written to both the engine and data@bases, so getPointer's transparent re-creation after save/load carries the current assignment rather than the one the sampler was created with; because the bases ride creation, a swap applied after a state restore preserves the restored amplitudes. A state records the levels of each forest a factor multiplies, and setState puts each of its coefficients on this sampler's level of the same name, refusing a state whose names differ (see ‘Saving’). This draws nothing; the next sweep draws the augmentation variables against the change.

updateBasisScale

For setForestBasis, TRUE or FALSE, the default. TRUE, meant for burn-in, also takes the default of a numeric forest that states no sd from the column installed: the column's standard deviation is read over the observations in the likelihood at the call (a positive weight, kept by the active-row mask; a forest's own weights from setForestWeights are not read), and the forest's sd becomes one unit of the response's scale for one standard deviation of the new column, from the next sweep, as for a sampler created on that column over those observations (see sd in forest). The trees, the coefficients and every other forest are left as they are, and no draw is taken. The rows read are those in at the call, which may not be the rows the response's scale was read from at creation, and re-installing the column in force with TRUE is how to take its scale again after the weights or the mask change. The new scale replaces the forest's entry of [email protected], so a copy, a saved and reloaded sampler and a sampler made again from its own control, model and data run the new prior. Where fewer than two observations are in the likelihood, the column takes one value over them, or the weights are counts that total at most 1 over them, the column is installed and the scale in force kept, with a warning the first time the sampler keeps a scale; a sampler created on such a column with no sd is refused. TRUE is refused, before anything is installed, on a forest that states its sd, at creation or through setLeafPrior, and on a forest multiplied by a factor, neither having a default taken from a column.

forest

A single positive integer indexing the forests from 1, or a string, the forest's label (see forest; forest<i> names position i, a sampler of one forest has no labels, and a multinomial one's are the response's levels), or - for getForestFits, getForestAmplitudes, getForestVariableCounts, getLeafPrior, and getK - NULL (the default on all five) for every forest, stacked (see ‘Value’ for each reader's stacked shape). A single-forest sampler's NULL read is bitwise its forest = 1 read, so the default costs nothing on an ordinary sampler. setForestWeights and setForestBasis have no default: a writer names one target rather than reading every one. setLeafPrior takes no forest: a multinomial sampler's normal(k = ) states every category forest, and a sampler whose forests carry amplitudes states one forest's size through setForest. setForest and getForest read their forest as the others do, left out on a sampler of one forest and on a multinomial one, whose setForest refuses a position or a level: its forests take one statement. Declared in that order, a Bayesian causal forest's prognostic forest is 1 and its basis forest 2; setForestWeights and setForestBasis are both refused on a sampler whose forests carry no amplitudes, but not with the same message - setForestWeights names the missing capability, while setForestBasis raises "forest index out of range" - and setForestBasis accepts any forest of one that does. getForestFits and getForestVariableCounts accept forest = 1 on any sampler - it selects the only forest - and refuse only an out-of-range index. getLeafPrior and getK are likewise served on every forest of a multi-forest sampler, and the calibration-map entries are that forest's own. getTrees takes the same forest = NULL default, stacking every forest forest-major with a leading forest column on a sampler with several forests or one declared with forests =, and no such column on any other (see ‘Value’); it additionally accepts a vector of forest indices or of labels, each validated as a lone forest argument is here and stacked in the order given. plotTree takes a single forest, defaulting to the sampler's only one and required when there is more than one.

leaf.prior

For setLeafPrior, a leaf prior specification in the vocabulary a fitting function's leaf.prior takes, resolved inside the call as it is there: normal(sd = ), normal(k = ), normal(sd = invchi(df, scale)), or linear(sd = ) and gp(sd = ) on those leaf models (see dbartsPriors). It must name the sampler's own leaf model - normal for the constant and monotone leaves - and may omit leaf-model details such as a linear leaf's columns; any it states must match. Changing the leaf model, or anything else about the model, is setModel's. A multinomial sampler takes normal(k = ) with a fixed k, Inf included, as its creation does. On any sampler normal(k = Inf) holds every tree at zero, so the fit is the offset, plus on a continuous response the center of the range the response less its offset spans. On a sampler whose forests carry amplitudes it is the fitting function's leaf prior; see ‘Value’.

sd, power, base, amplitude, proposal.probs, n.perturb.cuts, treeShift

For setForest, and of them power, base, proposal.probs and n.perturb.cuts for setVarianceForest, a value in the terms forest takes it, a coefficient's prior resolved inside the call as it is there. For setTreePrior, power and base in the terms a fitting function (dbarts) takes them. NULL, the default, is the same as leaving the name out. See ‘Value’.

split.probs

For setTreePrior, the split probabilities in the terms a fitting function takes them: a vector, 1 for equal probabilities, or on a DART sampler dart(...). NULL, the default, leaves them.

cuts

For setCutPoints, a numeric vector of cut points for the column named, or a list of such vectors, one for each column named; a data frame is taken as the list of its columns. A vector holds no NA or NaN and is sorted if it is out of order. A cut point must be finite; -.Machine$double.xmax separates values at -Inf. A point may appear only once, so a grid with a repeated point is refused; for more splits near a value, give a denser grid around it. No grid a sampler holds repeats a point, so the grids it reports can be handed back to it whole. A grid given here is unweighted, its cut points equally likely, except the grid the column holds handed back bit for bit, which keeps the weights the default rule gives a column with fewer distinct values than n.cuts. With column missing, cuts is a list with one entry for every column of the predictors, and the entries of factor columns are not read, whatever they are. Cut points apply to numeric predictors only: naming a factor column of either kind is refused, naming the kind, its grid following its level table rather than any externally chosen one. A later setState does not undo the change: a state goes onto the cut points the sampler holds (see ‘Saving’). The sampler records a grid set this way in its data object, so a later setData(sampler$data) keeps it; a later setData that derives the cut points, as one given a data object made by dbartsData does, derives every numeric column's cut points again whatever grid was set, at most as many as the n.cuts the sampler was created with: with useQuantiles, a column with no more distinct values than n.cuts gets one cut point fewer than it has distinct values, and a constant column gets one.

column

An integer or character string vector specifying which column/columns of the predictor matrix is to be replaced or for which cuts should be used. When updating predictors, it can be missing and the entire matrix will be substituted; a sparse or mixed dense/sparse design accepts that too, and keeps its storage (the replacement is spliced into the container rather than replacing it with a plain matrix). Such a design may equally be mutated one column at a time by naming column (dense-backed and sparse-backed columns alike, and a single call may name both kinds), which is the cheaper spelling when only a few columns move. A replaced sparse-backed column stays sparse: it stores the replacement's entries that differ from its implicit value (zero, or a sparse factor's reference level), in the storage layout chosen at creation, and a sparse column of the replacement is read as those entries rather than expanded, so for sparse columns the call's memory follows their nonzeros; a dense column of a mixed replacement is copied, as in any dense replacement. A replacement of any other sparse Matrix class is read as the dgCMatrix it holds, as is such a test set. For setTestPredictor, a per-column update reaches a data-frame or sparse test container too: the replacement is spliced into its storage rather than densifying the whole test set.

forceUpdate

For setPredictor, controls how the trees respond to a new predictor that would leave a leaf empty in any tree of any forest of any chain - the ordinary mean forest, and, on a sampler with more than one forest, all of them together: a Bayesian causal forest's second (treatment) forest, a multinomial sampler's per-category forests, and a heteroscedastic (variance) sampler's variance forest are checked on exactly the same terms as the mean forest, not independently (see ‘Multi-forest and heteroscedastic predictor mutation’ below). FALSE rolls the whole update back and leaves the sampler unchanged (rejection sampling); TRUE forces the change, collapsing any empty nodes; the string "partial" installs each observation's new value individually and rolls back only those observations whose value would empty a leaf in any of those trees, returning a per-observation logical of what was installed. Under a monotone constraint a new predictor can also leave a tree's leaf values out of order along a constrained predictor (that page says what this is). TRUE completes such an update, merging that tree's leaves where their order breaks, each merged part one leaf at the mean of the leaves it replaces weighted by their rows, without a message. FALSE refuses it and rolls it back, as for an empty leaf, and "partial" declines each row that would do it. The one unforced change that can do this is an unordered factor column's first missing value, under the sides drawn for the column's rules when it arrives (see monotone). "partial" requires a single column and cannot be combined with updateCutPoints; it also requires a dense-backed column, since a sparse column's storage fixes its nonzero pattern per cell - replace such a column whole instead. When missing, defaults to TRUE when the whole predictor matrix is being replaced (column is missing) and FALSE when a single column is being replaced.

For setState, a single TRUE or FALSE. FALSE, the default, installs a state only where no tree of it has to be changed to fit the sampler, and otherwise leaves the sampler as it was; TRUE installs it, repairing the trees that do not fit (see ‘Saving’). "partial" is not taken.

For installTrees, FALSE (the default) takes the donor only if every tree it gives can stand in this sampler as the donor holds it, and TRUE takes it changing what must be changed (see ‘Warm starts’).

updateCutPoints

For setPredictor, one of "none", "position" or "value", or a unique abbreviation of one. "none", the default, keeps the cut points (split candidate locations) of the replaced column(s) and the weights they carry. The other two derive them again from the new values, as a new sampler would for those values: up to the n.cuts the sampler holds, whatever number the column held, and fewer where the values supply fewer, a constant column getting one, and under the default rule one per gap, weighted by width, on a column with fewer distinct values than n.cuts. They differ in where the splits already on such a column go. Under "position" each keeps its position on the grid, which is what TRUE did in 0.9-x; when the number of cut points changes, the position is rescaled to the new number. Under "value" each moves to the new cut point nearest its old threshold. In either case a split stays between the splits above it in its tree; one left with no cut point there is merged when the update is forced, and otherwise the update is refused and rolled back, trees and cut points included. A later setState does not bring back the cut points a state was stored on (see ‘Saving’). Anything but "none" cannot be combined with forceUpdate = "partial". For setData the same three words, or NULL, the default: "none" keeps the sampler's cut points and their weights, the new values read on them, "position" and "value" derive them from the new data as above, and NULL takes the cutPoints the new data object records, a split on a column whose cut points that changes moving to the nearest of them, and otherwise derives them as "value" does, as setData always did. For setPredictor, a logical is taken until dbarts 1.1-0, TRUE as "position" and FALSE as "none", with a warning once per session (dbarts-deprecated).

updateStandardization

For setPredictor, FALSE, the default, keeps a linear or gp leaf's covariate standardization, each covariate's center and scale and a gp leaf's heuristic lengthscale, whatever values the update installs; TRUE derives it again for the covariates among the columns the update replaces, every column where column is missing, over their new values at the rows in the likelihood under the weights and mask in force, as creation would over them, once the update has gone in, keeps the other covariates', and rewrites a linear leaf's coefficients, current and saved, into it, so that each leaf is the function of the covariate it was and predict returns what it did. A replaced covariate those rows hold at one value, or observe at none, or at values that differ by rounding only (see leaf.prior in dbarts), keeps its numbers, and the call warns, with class dbartsScaleFallbackWarning, on the sampler's first keep, of this or of the response's scale (updateScale); on a hazard fit where fewer than two subjects are in, every replaced covariate keeps, the period among them, the warning counting subjects. For setData, NULL, the default, takes the standardization the new data object records and otherwise derives it from the new data's rows in, TRUE derives it, both reading every row where fewer than two rows are in or the response's scale is read from every row, and refused where two or more rows in hold one value of a covariate, or values that differ by rounding only, unless a gp leaf states its lengthscale, which takes the placeholder (see newData), and FALSE keeps the sampler's, the new rows read under it. A leaf that takes no covariate has nothing to derive. A gp sampler that holds saved draws refuses TRUE on setPredictor, and on setData any call that would change the standardization (see newData). It cannot be combined with forceUpdate = "partial".

For setWeights and setActiveRows, the argument after updateScale: FALSE, the default, keeps the standardization whatever rows the call leaves in; TRUE installs the weights or the mask first and then derives every leaf covariate's center and scale, and a gp leaf's heuristic lengthscale, again over the rows then in the likelihood, as setPredictor with TRUE would on every leaf covariate's values in force, rewriting a linear leaf's coefficients in the same way. A covariate those rows hold at one value, or observe at none, or at values that differ by rounding only, keeps its numbers, the others re-deriving, and the call warns as setPredictor does, once per sampler. On a hazard fit, where fewer than two subjects are in after the call, every covariate keeps its numbers, the period among them, which varies within a subject, under one warning that counts subjects. Where the call also passes updateScale = TRUE and keeps the response's scale, those rows holding fewer than two distinct values of the response, the prior in force is kept whole: every covariate keeps its numbers too, whatever its spread over those rows, and one warning names the response and the covariates, as creation on those rows would read the response's scale and the covariates from every row together. A gp sampler holding saved draws refuses it before anything is installed. A sampler whose leaves take no covariate, one of several forests among them, takes it and has nothing to derive. A probit, ordinal or nbinom sampler's setWeights passes it to setActiveRows with the 0/1 weights.

A loop whose rows in the likelihood change, such as a mixture component or an imputation step, can let the response's scale and the leaf covariates' center and scale follow the rows in during burn-in and then hold them, so every kept draw comes from one prior: pass updateScale and updateStandardization as TRUE on the call that changes the rows while burning in, and FALSE after. A gp leaf that has kept a draw refuses both, so burn in with sweeps that keep nothing:

sampler <- dbarts(y ~ x1 + x2, data, weights = w,
                  leaf.prior = linear("x1"),
                  control = dbartsControl(n.chains = 1L, keepTrees = TRUE))
for (i in seq_len(n.burn + n.keep)) {
  w <- drawMembership(sampler)            # the outer sampler's step
  burning <- i <= n.burn
  sampler$setWeights(w, updateScale = burning,
                     updateStandardization = burning)
  draw <- if (burning) sampler$run(1L, 0L) else sampler$run(0L, 1L)
}

Creation and a setData that derives read every row where fewer than two rows are in, or where the response's scale is read from every row, and refuse two or more rows in that hold one value of a leaf covariate, or values that differ by rounding only, a gp leaf that states its lengthscale taking the placeholder (see newData); these setters keep instead, one row or one subject in included.

splits

For setCutPoints, "position" (the default) or "value", or a unique abbreviation: where the splits already on a column go when its cut points are replaced, as for updateCutPoints. The change is always forced, so a split left with no cut point between the splits above it is merged.

treeNums

An integer vector listing the indices of the trees to print or return.

chainNums

An integer vector listing the chains to return from getTrees. When missing, all chains are returned.

sampleNums

An integer vector listing the saved samples to return from getTrees or print from printTrees. Applies only when keepTrees is TRUE and current is FALSE; otherwise the live working trees have no sample dimension, and supplying it explicitly is ignored, with a warning. Sample numbers address recorded DRAWS on the oldest-first axis predict reports - 1 to the number of draws recorded, at most [email protected] - and not the store's internal slots.

current

For getTrees, a logical; when TRUE the live working trees (the current sampler position) are returned even if keepTrees is TRUE, rather than the saved samples.

newdata

For getTrees, an optional matrix of predictors (in the form accepted by predict). When supplied, its observations are routed through each tree so the n column counts them instead of the training data; the tree structure, splits, and leaf values are unchanged.

result

For getLatents, an optional pre-allocated numeric vector (or, with multiple chains, matrix) that it fills in place and returns instead of allocating a new one; its length must equal the number of observations times the number of chains. Omit it to let getLatents allocate. Refused by name by getSigmas and getSumsOfSquaredResiduals: both readers allocate their own vector, and filling a caller's buffer in place is getLatents's contract alone.

test

For getVariance, a logical; FALSE, the default, reads the variance surface at the training rows and TRUE at the installed test rows.

treeNum

An integer listing the indices of the tree to plot.

chainNum

For plotTree, an integer giving the chain to plot from. Required when the sampler has more than one chain; defaults to 1 when there is only one.

sampleNum

For plotTree, an integer giving the saved sample to plot. Applies only when keepTrees is TRUE, in which case it defaults to the most recently drawn sample; ignored (with the live working trees plotted instead) when keepTrees is FALSE.

treePlotPars

A named numeric vector containing the quantities nodeHeight, nodeWidth, and nodeGap, all of which control aspects of the resulting plot.

donor

For installTrees, the fit whose forests seed this sampler: another dbartsSampler, or a bart object fit with keepSampler = TRUE. The donor must share this sampler's predictors; a donor of more trees gives some of them, and a donor on other cut points has its splits moved onto this sampler's under forceUpdate = TRUE, and needs no move where every split it holds is one of this sampler's cut points, as on a finer grid that holds the donor's; and a different center and scale of a linear leaf's covariates is allowed (see ‘Warm starts’).

samples

For installTrees, an optional integer vector with one entry per chain, each a 1-based index into the donor's pool of samples (its saved trees when it kept them, else its final trees per chain). NULL spreads the chains evenly across the pool.

n.sweeps

For growFromRoot, a single positive integer giving the number of grow-from-root sweeps run in place (default 2L). Each sweep rebuilds every tree in the forest against the current residual, so a small handful reaches a good fit.

ptr

For storeState, the sampler's engine pointer to capture from; defaults to getPointer() and is rarely passed explicitly.

newState

For setState, a state object previously produced by this sampler or another over the same data: its state field, calling storeState() first to refresh it if a later mutation may have gone unstored (storeState itself returns NULL invisibly, so its return value cannot be passed here). A sampler's own state field is never refused for the cut points it records: where a reload is made on other cut points than its stored state records, as after a setCutPoints with no storeState() since (see ‘Saving’), the field holds the state of its engine in place of the stored one. A reload's field is brought to its engine's at first use, and a state read from it before that is the stored one. Must inherit from bartcoreState. setState installs the latents the state carries, the values its trees were drawn from, and draws none.

n.trees, vars, interactions, blocks

For setForest (and n.trees and vars for setVarianceForest), the names forest takes that say what the model is. They are refused by name whatever their value, being part of the model, and are arguments so that a short name matches as it does at creation.

...

For setForest and setVarianceForest, nothing is taken: any name not listed is refused as an unused argument. For plotTree, extra arguments to plot. For run, only 0.9-x's per-call thread count, as n.threads, numThreads or the one unnamed argument after updateState, which is ignored with a once-per-session warning until dbarts 1.1-0 (dbarts-deprecated); anything else is refused. A callback to run must therefore be named.

Details

A dbartsSampler is a mutable object which contains information pertaining to fitting a Bayesian additive regression tree model. The sampler is first created and then, in a separate instruction, run or modified. In this way, MCMC samplers can be constructed with BART components filling arbitrary roles.

Besides dbarts, a sampler is created by new("dbartsSampler", control, model, data, active = NULL) from the list dbartsSpec returns. The list's data object carries the fit's weights, a "probit", "ordinal" or "nbinom" fit's 0/1 weights among them, so a sampler created from it is the sampler dbarts builds (dbartsSpec, data, gives the by-hand route). active is a 0/1 mask installed once the sampler is built, as setActiveRows(active) installs it, composing with the weights; a sampler created with it reads over the rows in, those the weights and the mask both keep, the center of an "nbinom" count, a linear or gp leaf's covariate center and scale, and under "probit" and "logistic" the default sd of a forest on a numeric column that states none.

A sampler made this way takes its tree count from the model and its quantile rule and cut count from the data object, where they state them. A control that is fresh, or copied from a fit, says nothing of them, and a copied count or rule that differs draws a warning saying it is not used. A count or rule written on the control is used where the model or the data object states none and is refused, by name, where it states another, or, for a count, where every forest has a basis. Whether the family is binary is the model's family alone.

Reading the fit

Six methods report a fitted quantity and no two report the same one. They differ along three axes - the SCALE the values live on, whether the installed OFFSET is in them, and whether they answer from the CURRENT state or from stored draws:

method scale offset current or stored
run()$train response (latent under a binary family) included one slab per recorded draw
$getFitsWithoutOffset() response (latent under a binary family) excluded current
$getForestFits(f) internal, and one forest only excluded current
$predict(x) response (latent under a binary family) whatever you pass it the saved samples under keepTrees, else the current trees
$predictForests(x) internal, one channel per forest excluded, and refused if passed the saved samples under keepTrees, else the current trees
$getLatents() the family's own augmentation variable, which is a location for some families and a precision for others not a fit; see ‘Value’ current

A multinomial (softmax) sampler reads and writes a strict subset of this surface, by the model rather than by omission. Its response channels are $setResponse, which takes the n×Kn \times K count matrix, $setCategoryOffset and $setCategoryTestOffset; the predictor family ($setPredictor in all four shapes, $setCutPoints, $setTestPredictor) and the global $setActiveRows, with or without updateScale = TRUE, are open, and $predict answers with the KK category probabilities and takes the matching per-category offset. Everything else on the mutation surface is refused, each by a message naming the capability and, where one exists, the channel that serves the caller instead: $setResponse given a vector of numbers and $setOffset (a flat vector cannot express the matrix, and a flat shift is the softmax's null direction), $setWeights (an integer case weight is already row-wise replication in the count response, and a non-integer one has no exact augmentation sampler), $setSigma (no residual scale), $setData and $setModel (the K category forests fix their data and their calibration at creation), a named sd or a k hyperprior on $setLeafPrior, which takes normal(k = ) with a fixed k (the softmax map owns every category forest's leaf scale), $setForestWeights and $setForestBasis (its forests are its categories, which carry no amplitudes), and $getFitsWithoutOffset (its reported channels are probabilities, not one additive location). Per-forest masking is refused permanently rather than pending: a category's margin is a log-sum-exp over the other K−1K-1, so a mask on one forest alone has no conditional to be a mask of.

The composition rule follows from the table: an outer block conditions on f(xi)f(x_i), so it reads $getFitsWithoutOffset() and adds back whatever offset it installed, rather than differencing $getLatents() against run()$train: a probit, ordinal or aft latent is on the offset-inclusive scale, z=f(x)+o+ez = f(x) + o + e, as run()$train is, so the difference is the residual ee with none of the offset's signal. A block that owns the offset regresses z - $getFitsWithoutOffset(); a precision latent carries no location and no offset, and dbartsWorkingResponse gives the offset-free working response.

Where the boundary runs. These are the methods of the mutable sampler, and their audience is a model writer composing BART into a larger scheme: they return engine primitives on the engine's own terms. The R modeling conventions - fitted, predict, extract - apply to FIT objects instead, the results of bartBT and bart. Those accessors read the stored yhat.train/yhat.test channels the engine already wrote the offset into, and no type arm removes it: type = "bart" returns those draws as they stand, "ev" maps them through the response transform, "ppd" samples from them, and "loglik" evaluates against them - all offset-inclusive. (extract on a dbartsSampler itself takes type = "predictors" only and returns the design matrix; it is not a fitted-value accessor.) So an offset-free fit is available from the sampler surface and nowhere on the fit-object surface, which is the division rather than an omission.

Saving

save-ing and loading a dbarts sampler for future use requires that R's serialization mechanism be able to access the state of the sampler which, for memory purposes, is only made available to R on request. To make it available, call storeState() on the sampler before saving, e.g. for the object sampler, execute sampler$storeState() (a fit of bart that keeps its trees has done so at the end of its fit); this captures the sampler's current state into the serializable state field regardless of the updateState setting.

The state object is opaque and engine-specific, and carries a format version and the package version that wrote it. A state loads only within the format version of the dbarts that wrote it; loading it with an incompatible version refuses cleanly, naming both versions, rather than risk a silent misread. There is no cross-version migration: re-fit the model, or restore the state with the dbarts release that wrote it. A sampler saved by dbarts 0.9-x refuses every method, naming that version and saying to refit it with this one; its data, control and model fields still read.

To restore a saved state into a sampler, call setState(newState) and check what it returns, as in if (!sampler$setState(state)) stop("the state no longer fits"). setState validates that newState inherits from bartcoreState and re-creates the underlying engine if needed: a sampler whose engine is gone, as after a load, is first rebuilt on the cut points, weights, response range and leaf standardization its data object records and from its own saved state, as any other call rebuilds it, so that setState gives what it gives a sampler that was never saved; one with no saved state, or one whose saved state is refused, is created anew on the same record, and newState goes onto its cut points as onto a live sampler's. Then, where every tree of the state fits the sampler as it stands, it installs the state, caches it on the state field and returns TRUE; where one does not, it installs nothing, leaves the sampler, its engine and its state field exactly as they were, and returns FALSE. TRUE does not mean bit for bit. It means the trees and leaf values are the stored ones, and the quantities the sampler draws are the stored ones where the state holds them. Of the kept draws (keepTrees) the newest that fit the sampler's own store are taken, whatever number the state holds. The latent variables it carries go in as stored and none is drawn, the next sweep drawing them against the weights and censoring status then in force, and the chain continues the state's own generator streams from where they left off, typically to the last few digits, not bitwise (see the Reproducibility section of bart).

A tree does not fit, and setState returns FALSE, when it would have to be changed before the sampler could hold it. The trees are judged against the predictors and the cut points the sampler holds at the call and against its own constraints: a split whose threshold is not one of the sampler's cut points for its column; a leaf that no row of those predictors reaches; a split the state holds outside the range the splits above it leave; a rule that records a side for missing values on a column that has never held one in this sampler (see ‘Missing values in predictors’); a split on a column the tree's forest may not use - a forest's vars, a blocks group, a moderator forest's columns or a variance = ~ x1 + x2 variance forest's; a split that breaks the forest's interactions limit; under a monotone constraint, leaf values that are out of order as stored; and, under DART, split weights of 0 on a column the sampler may split on, as a state taken from a sampler whose forest left that column out holds (negative, missing and all-zero weights are errors, forced or not). setState(newState, forceUpdate = TRUE) installs such a state all the same, as a forced setPredictor leaves the trees it meets, and returns NULL invisibly: a split whose threshold is not a cut point moves to the nearest cut point inside the range the splits above it leave, to the upper one of two equally near, and one with no cut point left there becomes a single leaf, along with everything beneath it, at the mean of the leaves it replaces, weighted by the rows each held under the stored thresholds; a split with a side no row reaches becomes a single leaf, along with everything beneath it, at the mean of the leaves it replaces, weighted by their rows; so does a split outside its range; a tree is cut back in the same way at the first split from its root that the forest's columns or its interaction limit do not allow, the splits above it kept; a rule stops recording a side its column cannot use; and a monotone tree whose values are out of order is merged where its order breaks, each merged part one leaf at the mean of the leaves it replaces weighted by their rows. DART's split weights in such a state start fresh, equal over the columns the forest may split on, as installTrees starts them, with a drawn concentration restarted at its initial value and the delay counter restarted, the next sweep drawing the weights from the trees installed. After a forced setState the state field holds the chain the sampler holds after the install, repairs and drawn sides for missing values included, not the state as it was given: installing the field again without forceUpdate returns TRUE, and a copy or a reload starts from the repaired chain. A forced install that repaired nothing stores a state identical to the one given only where the sampler's store of kept draws (keepTrees) holds the same number as the state's; otherwise the newest that fit are kept and the stored state differs in them. An unforced install that went onto the sampler's own cut points and weights keeps the state as given; one that went onto other cut points or weights than it records is not kept, and the field holds what the sampler holds after the install. Likewise after an unforced install that drew a side for missing values (see ‘Missing values in predictors’) the field holds the state as given, without the sides, and installing it again, as a copy or a reload does, draws the same ones. storeState() stores what the sampler now holds. Forcing checks nothing first, so a loop that restores its own state onto rows it has already put back, where nothing can need repair, can pass forceUpdate = TRUE and skip the check, which costs about as much as one iteration of the sampler. To undo a predictor change exactly, put the old predictor back first, with setPredictor(..., forceUpdate = TRUE), and then call setState. An unforced setPredictor can be refused, returning FALSE and leaving the changed predictor in place; setState then judges the state against the changed predictor, as it does when called before the predictor is put back.

Some states are refused, with an error, whether forced or not, and the sampler is left exactly as it was: one that is not a bartcoreState or is of an older encoding, one with another number of chains, forests or trees or another leaf model, one whose recorded levels are not the sampler's (below), and one with a malformed block or tree. A state in which a numeric column's cut points repeat a value is refused, naming the column and the value: no sampler of this version writes one, and with every point held once a stored split's value names one position. A Student-t, logistic or negative-binomial sampler also refuses a state whose latent variables are not all positive and finite. So is one holding a value no chain could run from, which no sampler writes: a sigma that is not positive and finite; a k that is negative, or is 0 or infinite under a prior whose scale could not draw that value (a draw reaches 0 only under a scale below about 3e-145 and infinity only under an infinite scale or one above about 1e146); a response transform that is not finite; a random-number generator state out of range or all zero; DART split weights that are negative, missing, not finite or all zero, or a DART concentration that is not positive and finite; and ordinal cutpoints whose first is not 0 or that do not increase. Beyond that a state is not checked against the response family of the sampler that stored it: one whose contents fit this sampler is installed, and what the sampler then holds of another family's state is not promised. To start a sampler from a fit of another family, use installTrees, which takes the donor's trees and, where this sampler draws them, its sigma, k and DART state, and none of its latent variables. A state's k is installed as recorded, whatever leaf prior this sampler holds; the leaf sd is then k.scale / k against this sampler's k.scale.

Assigning the field directly (sampler$state <- newState) does not restore the sampler - it only overwrites the R-side cache, leaving the engine untouched, so the next run continues from the engine's own state rather than the assigned one. A reload, and a copy of a sampler whose engine is gone, install the field as setState does with forceUpdate = TRUE, having no other state to fall back on: a tree that no longer fits is repaired, and nothing is reported. Such an object whose field holds a state that is refused cannot be copied, and after a reload raises that refusal at each use until a state of its own is assigned; one whose field holds no state is refused the same ways. A copy of a sampler whose engine exists takes its current chain and not the field. Always route a restore through setState.

A state carries no data, a forest's basis among them, but it records the level names of each forest a factor multiplies, as the sampler's data object holds them (the attribute basisLevels, a list with one entry per forest, NULL for a forest of no factor; absent where no forest multiplies a factor). setState, a copy and a reload put each of the state's coefficients on the recipient's level of the same name, so a state installed in a sampler whose factor has the same levels in another order, as after relevel, gives each level its own coefficient; the recipient's levels and block are its own before and after. A state whose names differ from the recipient's, forest by forest - another name, another number of levels, or a factor where the recipient's forest multiplies numbers or nothing - is refused with an error, whatever forceUpdate says, and the sampler is left as it was. A state that records no levels goes in by position.

A state never changes the sampler's model. The leaf prior, its k where fixed, a fixed sigma, Student-t df, negative-binomial shape or DART concentration, a fixed amplitude prior or amplitude, and a supplied Gaussian-process lengthscale are the sampler's own, before and after; a value the sampler draws is installed where the state holds one and kept where it does not, so a state written before these blocks were dropped still installs. The response transform a k-named prior is anchored to, and which every leaf value is stored relative to, is not in the state either: it is derived from the data when the sampler is created and when setResponse or setOffset at updateScale = TRUE, setWeights or setActiveRows at updateScale = TRUE, or a setData that derives it, re-anchors it, and recorded as the response.range of the sampler's data object (see dbartsData), so a copy or a reload is re-created in it. A state goes in as stored: its trees, leaf values, linear slopes, k, sigma and kept draws are numbers on the sampler's internal scale, and an install - setState, copy, a reload - reads them against this sampler's response mapping and leaf standardization and never converts them. A state stored under the mapping in force, as a sampler's own, a copy's or a reload's is unless a re-anchor came between, puts the chain back where it was stored, value for value. A state stored before a re-anchor, or by a sampler on another response, is legal and has no special meaning: the same internal numbers read on this sampler's scale are a position the chain could hold, and the next draws move the parameters where the data say. A response that was only rescaled is then no change at all on the internal scale, the fit, the leaf prior's spread and sigma all rescaling with it; one whose center moved as well is fitted wrongly until the draws catch up. A kept draw restored across mappings predicts on the new scale, where a re-anchor converts the kept draws so that they predict what they did. No leaf model refuses such a state; one whose saved Gaussian-process draws were made under another leaf standardization or other lengthscales than this sampler holds is refused, a saved Gaussian-process draw replaying only under its own. The state records the mapping it was read under, which no install reads. Because a re-anchor is not in the state, restoring a state stored before one does not undo it; to roll a re-anchoring setResponse(y2, updateScale = TRUE) back, re-anchor to the old response with setResponse(y, updateScale = TRUE) and then setState the saved state, so that the response is restored with the state. The cut points and their weights are the sampler's, and setState writes neither: a state records the ones its thresholds were stored on (its cutPoints and cutMass attributes) and goes onto the sampler's. Where every threshold of the state is one of the sampler's cut points, as on a grid that only gained points, the trees are the stored ones and setState returns TRUE if they fit; where one is not, the state is declined or, forced, has that split moved (above). Other weights on equal cut points change no tree: the state goes in, TRUE, and the chain runs on under the sampler's weights, which is not the chain the state was stored from. So restoring a state does not undo a change of cut points made by setCutPoints or by setPredictor(updateCutPoints = ); 0.9-x's setState did. To restore the cut points too, hold the state in a variable, since setCutPoints replaces the state field under updateState, and set them first, the whole set in one call: sampler$setCutPoints(attr(st, "cutPoints")) and then sampler$setState(st). A column whose cut points had been changed and for which attr(st, "cutMass") holds an entry then has its points back and not its weights: setState still returns TRUE, and the chain runs with that column's cut points equally likely. setPredictor(x[, j], j, updateCutPoints = "value") gives back both while the column holds the values its cut points were derived from. A copy and a reload, which create a new engine, take the cut points, weights and leaf standardization the sampler's data object records, which are the ones in force (see dbartsData), and none from a state. A reload of a sampler saved after a change of cut points with no storeState() since has the stored state's splits moved onto the recorded cut points by value, as a forced setState moves them, and its state field then holds what its engine holds; call storeState() before saving after a change of cut points to have it reload as it stands. A copy of a sampler whose engine exists takes its current chain, which is on those cut points already. On a column the sampler holds as an ordered factor, whose cut points its number of levels fixes, a state recording other cut points is refused, by setState, a copy and a reload alike. On a sampler made from a data frame, setData reads the new data's factors by label and records the sampler's own levels, so a copy and a reload hold the levels the sampler was created with and take the state it stored. A linear or Gaussian-process leaf's covariate standardization, each covariate's center and scale and a Gaussian-process leaf's heuristic lengthscale, is data too: derived when the sampler is created, by a setData that derives it and by setPredictor, setWeights or setActiveRows with updateStandardization = TRUE, and recorded as the standardization of the sampler's data object, which a copy and a reload take. A state records the standardization it was stored under, which no install reads: the sampler keeps its own, so kept linear draws restored across a change of standardization predict under the sampler's until the draws replace them, as kept draws restored across a change of response mapping predict on the new scale. A leaf covariate that held a single value when its standardization was derived has no scale: the state and the record hold NA for it, and the covariate is divided by 1.

A state brings back none of these values, so a sampler that changed one and is to go back to a stored state has it put back first. The data object held in a variable before the change, d <- sampler$data, is the general answer: it records every one, the weights of the cut points included, so setData(d) puts back the observations and every derived value with them.

value changed by put back by
cut points setCutPoints; setPredictor(updateCutPoints = ); a setData that derives them setCutPoints(d@cutPoints), the whole set; or setData(d)
their weights the same setPredictor(x[, j], j, updateCutPoints = "value") while column j holds the values they came from; or setData(d)
leaf center, scale, lengthscale updateStandardization = TRUE on setPredictor, setWeights or setActiveRows; a setData that derives them setPredictor of the old values with updateStandardization = TRUE, under the weights and mask they were read over; or setData(d)
response range updateScale = TRUE on setResponse, setOffset, setWeights or setActiveRows; a setData that derives it the same setter on the old response, offset, weights or mask with updateScale = TRUE; or setData(d)
forest anchor and unit nothing -

Then setState(st) of a state st stored before the change installs it and returns TRUE, and the chain is the one stored.

The case weights and an aft sampler's censoring status are not in the state, and the state records nothing of either: the latents it carries are the values its trees were drawn from, setState installs them and draws none, and the next sweep draws them against the weights and censoring status then in force. A weight change is undone by setWeights with the old weights and setState with the stored state, in either order, the sampler then continuing bit for bit as one that installed the stored state under the old weights would, and setState returns TRUE in both. A sampler saved after its weights changed without a store is re-created from the last stored state under the weights it then holds; it is a continuation of the stored chain and not of the live sampler, carrying no sweep made since the store. Call storeState() after the change to have it reload as it stands; a copy of a sampler whose engine exists takes its current chain.

Missing values in predictors

A predictor column can hold missing values from the first time the sampler is given one in it - at creation, or later by setPredictor, setData or updatePredictorPerObservationJointly - and from then on for the life of the sampler, whatever values the column holds afterwards. Each split rule on such a column sends missing values down one side, and the sampler draws that side as part of the model. When a column first becomes able to hold missing values, every rule already on it, in the current trees and in every saved draw (keepTrees), has its side drawn at random, left or right with probability one half each, from each chain's own generator; a change that is refused undoes these draws with the rest of it. A rule on an unordered factor column has its side drawn only where a missing value can reach it: beneath a rule on the same column that sends missing values down the other side none can arrive, and the rule holds no drawn side, exactly as on a sampler whose column held missing values at creation. A saved draw was made when no value in the column was missing, so nothing it was drawn from bears on that side, and one half is that draw's posterior for it. predict then routes a missing value in the column through every saved draw, those made before its first missing value and those made after. A column that has never held a missing value has no side to route by, and predict refuses a missing value in it. copy and a reload keep which columns can hold missing values.

A stored state records which columns could hold a missing value when it was stored. When setState, a copy or a reload installs it into a sampler where a further column can - a state stored before that column's first missing value, or by a sampler whose column never held one - every rule on that column, in the state's current trees and in its saved draws, has its side drawn in the same way before the state is judged, from the generators the state carries; a state stored just before a single setPredictor call gave the column its first missing value, and installed just after it, draws the sides that call drew. setState returns TRUE for such an install unless a drawn side leaves a leaf with no row or a monotone tree out of order, where it returns FALSE as for any state that does not fit (see ‘Saving’). A state stored before this record was kept draws nothing, and its rules on such a column send missing values left. A warm start (installTrees, or warm.start of bart) from a fit whose data could not hold a missing value in a column draws, from each receiving chain's own generator, the side of every rule on that column in the trees it installs.

Mutation cost

Each accepted predictor mutation does two things: the engine updates its internal representation, and the R layer collects the accepted values into the sampler's data object so that replay, saving, and re-quantization see current data. The collection is by reference for data-frame-built samplers (only the affected column changes hands) but requires copying the full predictor matrix when the sampler was built from a matrix, so tight loops that mutate predictors every iteration are better served by data-frame input. The remaining per-call overhead is a few tens of microseconds of R method dispatch and bookkeeping - the price of R-level consistency. Predictor mutation has no counterpart in the flat C interface (dbarts.h), which reaches the per-sweep conditioning channels and leaves every whole-data channel to these methods, so a client that mutates predictors every iteration is served by data-frame input rather than by dropping below R.

Infrastructure methods

getPointer() returns the sampler's underlying engine pointer, checking it for validity first. If the engine the cached pointer refers to is no longer live (typically after a load), it transparently re-creates one from control, model, data and the stored state, reinstalls every recorded forest weight and any recorded active-row mask (see reapplyForestWeights below, since neither rides the saved state) so the replacement matches a freshly built engine, and only then replaces the cached pointer; a re-creation that fails leaves the sampler exactly as it was. reapplyForestWeights(ptr) re-installs every per-forest weight mirrored on the sampler onto a freshly (re-)created ptr, and reapplyActiveRows(ptr) the mirrored active-row mask; they are called only from getPointer, setState and copy, never directly.

getPointer() is the only R-level primitive for exchanging engine pointers with code that drives the engine directly through dbarts.h: it is where a compiled consumer obtains the handle that header's entry points take, since that header declares no creation entry of its own. There is no other R-level path to that boundary: the low-level .Call wrappers this class's methods delegate to are internal to the package and unexported, so a consumer below this reference class has dbarts.h and nothing else.

Multi-forest and heteroscedastic predictor mutation

setPredictor - whole-matrix, single- or multi-column (via column), and per-observation (forceUpdate = "partial") - and updatePredictorPerObservationJointly accept a Bayesian causal forest, a multinomial sampler, and a heteroscedastic (variance) sampler on the same terms as an ordinary single-forest sampler. The acceptance criterion is a single conjunction over every tree of every forest of every chain of the sampler: a treatment forest, a multinomial sampler's per-category forests, and a variance forest are all checked together with the mean forest, never independently, so a change that a mean-forest tree would tolerate can still be rejected because it would empty a leaf in the treatment or variance forest, and vice versa. A rejected transactional whole-matrix or column update rolls every forest back to its pre-call state; under forceUpdate = "partial" the per-observation install mask reflects that same joint criterion, so an observation installs only where it empties no leaf anywhere in the sampler, and a rejected observation is rolled back in every forest, leaving the rest of the run untouched. The one exemption is a forest whose trees never split on the column being changed - a treatment or moderator forest restricted to a column subset, or a variance forest declared over its own predictor subset - which structurally cannot veto a change to a column outside its own reach; nothing needs to be done to obtain that exemption; it falls out of which columns the forest's trees actually use. updatePredictorPerObservationJointly applies the identical per-sampler conjunction across every sampler passed to it as well: an observation installs only where it would remain valid in the union of every sampler's forests, and it is declined in all of them otherwise.

Column names after a whole-matrix replacement: a transactional or forced whole-matrix setPredictor(x, ...) (column missing) carries column names onto the installed sampler$data@x. When x itself has column names they are matched to the sampler's, which it keeps, a name that is not the sampler's being refused, and a sampler with no column names takes x's; when it does not (a bare matrix, or a vector reshaped through dim), the sampler's existing column names are kept instead. Either way, a later by-name column reference on that sampler - setPredictor's own column argument given as a character string, or updatePredictorPerObservationJointly's shared-column match - continues to resolve against colnames(sampler$data@x) as it did before the replacement.

Prior draws

sampleTreesFromPrior and sampleLeafParametersFromPrior are MEAN-forest entries by contract: each leaves the variance forest of a heteroscedastic (variance) sampler exactly as it finds it, along with sigma, k and the family's latent block. sampleVarianceForestFromPrior is the variance forest's own, drawing its tree structures from the tree prior conditioned on carrying no empty leaf - the distribution the variance moves themselves price - and each leaf's factor from the calibrated inverse-chi-squared scale prior, then rebuilding s2(x)s^2(x) from the drawn factors. A caller wanting a whole heteroscedastic chain at its prior calls all three; on a homoscedastic sampler this one draws nothing and returns, so a loop over families needs no guard.

Warm starts

installTrees seeds the sampler's forests from a donor instead of drawing trees from the prior, for scaling to more chains or embedding a fit in a larger sampler. Only the donor's trees, and its sigma, k and DART state where this sampler draws them, transfer: the sampler keeps its own model, as setState does. The donor's trees and leaf values, and its k and sigma where this sampler draws them, go in as stored on the internal scale and are not converted to this sampler's response: a donor fitted to a response on another scale seeds the same internal numbers, which the next draws move where this sampler's data say, and a donor whose response differs only by a rescaling seeds its own fit, rescaled. The predictors' frame goes the same way. A linear leaf's coefficients go in as stored, numbers per unit of this sampler's own centered and scaled covariates, and this sampler keeps its own center and scale, as a Gaussian-process leaf keeps its own center, scale and lengthscale, whichever cut grid the donor is on; the donor's are not read. Where the two standardize a covariate differently the seeded forest is then not the donor's function of it, and the next draws move it where this sampler's data say. A covariate that holds a single value is read at the center it holds, so between two single values the seeded fit is the donor's on the training rows. Each chain keeps its own random-number stream and redraws everything else, so several chains seeded from one donor stay overdispersed. DART weights go only between two DART fits and a variance forest only where both have one: a donor's that this sampler has no place for is left behind, and this sampler's own, where the donor has none or where the donor's hold 0 on a column this sampler's forest may split on, starts as a new fit's once the donor goes in, DART drawing its weights from the trees taken at the first sweep; neither is judged, and a donor that is declined leaves them as they were. A donor holding a value no chain could run from, as setState refuses one, is an error in both forms, and nothing is installed. A donor of constant leaves into linear ones gives each leaf its value as intercept and slopes of zero, the donor as it stands. A donor of linear leaves into constant ones, or into linear ones on another number of covariates, leaves its slopes behind, each leaf starting at the intercept the donor stores. A donor of Gaussian-process leaves where this sampler's are of another kind, or the reverse, or one fit to another number of rows, is an error naming the two, as is a donor fit to another number of predictors or one whose column is an unordered factor where this sampler's is not, or the reverse. A donor of fewer trees than this sampler is taken whole, its trees in its order and the rest starting as single leaves at zero, or at one in a variance forest. Under blocks, whatever the donor's tree count, each block in turn takes, in the donor's order and up to its count, the donor's trees not yet taken that it holds as they stand, the rest of its trees starting as single leaves, and where that leaves a tree out, the same is tried once more with the donor's single leaves offered last; a donor all of whose trees go in so is taken whole, and one fitted with the same blocks and counts goes in tree for tree. A donor of more trees, or under blocks one whose trees do not all go in so, gives those whose fitted values vary most over this sampler's rows, each row weighted by its case weight, in the donor's order, the mean and the variance forest choosing apart and each chain among the trees of the donor sample it takes; under blocks each block in turn takes up to its count of the trees that vary most within it as it holds them, never one it would hold as a single leaf when the donor holds it as more, and starts the rest as single leaves.

installTrees(donor) asks first. A donor every tree of which fits this sampler as stored is installed and the call returns TRUE. One that would have to be changed is not installed: the call returns FALSE and the sampler is as it was, its trees, drawn values, generators, kept draws and state field. A tree has to be changed when a split's threshold is not one of this sampler's cut points, as for a donor fitted to other rows; when a leaf holds none of this sampler's rows; when a split is on a column, or in an interaction, its forest does not allow; when it records a side for missing values on a column that has never held one here; or when a monotone forest's leaf values are out of order. A donor is also declined when it holds more trees than this sampler's forest or, under blocks, trees the blocks cannot take as they stand, when it holds linear slopes this sampler's leaves do not take, constant leaves or linear ones on another number of covariates, and when its Gaussian-process fits were recorded on other cut points. installTrees(donor, forceUpdate = TRUE) installs such a donor and returns NULL invisibly, whether or not anything was changed: a split off the cut points moves to the nearest one inside the range the splits above it leave or, with none left, becomes one leaf with everything beneath it; a split with a side no row reaches, and the first split from the root that its forest does not allow, likewise become one leaf, at the mean of the leaves it replaces weighted by the rows each held; a side is dropped; a monotone tree whose leaf values are out of order is cut back where they are; Gaussian-process fits start at zero; slopes the sampler does not take are left behind; and of a donor holding more trees, or under blocks one whose trees the blocks cannot all take as they stand, the trees whose fitted values vary most go in. The sampler's cut points and their weights are the same before and after. A side drawn for missing values is how a donor is read, not a change to it. On a column this sampler holds as an ordered factor a donor recorded on other cut points, a numeric column or a factor of another number of levels, is an error in both forms. bart's warm.start always forces.

A warm start biases the early draws toward the donor, so it shortens burn-in rather than removing it; keep drawing a non-zero number of burn-in samples before treating the chain as converged. Single-forest samplers only: a sampler carrying two or more forests (a Bayesian causal forest or any other amplitude model, and a multinomial sampler's K category forests) refuses the call by name, reporting its forest count, because the install is not tested at more than one forest - it reassembles the trees from a saved sample but takes the amplitudes from the donor's current state. Use growFromRoot to initialize such a sampler instead. A variance forest is not one of the counted forests, so a heteroscedastic sampler takes a warm start as any single-forest one does.

growFromRoot instead builds the sampler's initial forest by XBART-style root-down stochastic tree construction (He, Yalov and Hahn 2019): each of n.sweeps sweeps rebuilds every tree from the root, sampling each split from the integrated-likelihood weight of every candidate cut under the tree prior. This reaches a good fit in far fewer sweeps than the exact sampler, so it is a fast starting point rather than a posterior sampler - the exact MCMC sweeps own stationarity once run begins, and the posterior is unchanged. It is available for the constant-leaf model only; calling it on a linear or gp leaf prior is an error, not a silent fall-back, so initialize those forests with sampleTreesFromPrior instead. As with installTrees, the grown forest biases the early draws toward its fit, so shorten burn-in rather than skipping it. Each chain grows on its own random-number stream, so the result is independent of n.threads. Unlike installTrees it runs on a multi-forest sampler, each forest grown against its own residual inside the sweep and the forests' amplitudes drawn with them. A composable cross-sampler workflow follows for free: donor$growFromRoot(k) then target$installTrees(donor).

Value

For run, a named-list with contents sigma (absent on a heteroscedastic sampler, below), train, test, and varcount (plus k, when the reported forest draws k in that run and absent when it is fixed, and varprobs when applicable). train is an array of dimension n.obs x n.samples x n.chains, and likewise test (or NULL if the sampler has no test data) and varcount are n.predictors x n.samples x n.chains; sigma is n.samples x n.chains. When n.chains is 1 the trailing chain dimension is dropped, so train is a plain n.obs x n.samples matrix and sigma a plain vector of length n.samples. On a multi-forest (forests) sampler varcount gains a forest axis between the predictors and the samples - n.predictors x n.forests x n.samples x n.chains, forest-major within a draw and the forests in the model's order - so each forest's own per-draw split counts arrive from one call rather than only the reported forest's; a single-forest sampler's array keeps exactly its n.predictors x n.samples x n.chains shape, and the same widening is what a family = "multinomial" sampler's per-category counts ride. This is the RAW run shape; the packaged fit bart builds reshapes it draws-first with the forest names on the trailing margin, as it does for the multinomial channel. $getForestVariableCounts reads the same quantity for the CURRENT state, one forest at a time. A Bayesian causal forest adds two more: forestFits, an n.obs x n.forests x n.samples x n.chains array of each forest's fitted values on the internal scale (the forests in the model's order), and glue, a sum(q) x n.samples x n.chains array of the amplitudes each draw combines them through, stacked forest-major and as wide as each forest's own basis (a Bayesian causal forest's (a,b0,b1)(a, b_0, b_1), three rows), so both surfaces and their recombination come from a single call; train carries the combination aμ(xi)+bziτ(xi)a \mu(x_i) + b_{z_i} \tau(x_i) on the response scale, or on the latent scale when the sampler was built under "probit" or "logistic", and test is filled with NaN (there is no test treatment vector to combine off-sample). No other model reports either element. A "nbinom" sampler adds one of its own: shape, the negative-binomial rr each draw is conditioned on, shaped exactly as sigma (a length n.samples vector at one chain, an n.samples x n.chains matrix otherwise) because it is the count analog of it - fixed at the value the sampler was created with under a fixed shape, and that sweep's grid draw otherwise. It is written from the same state storeState serializes and consumes no random numbers, so reading it costs a run nothing. No other family carries the element at all: it is absent from the list, not NULL within it, so run()$shape is NULL on every non-"nbinom" sampler and a test of the channel must be !is.null(...) rather than a comparison, which NULL would satisfy vacuously. A sampler built with family = student() adds resid.df on exactly the same terms - the degrees of freedom ν\nu each draw is conditioned on, shaped as sigma, written from settled state and consuming no random numbers, absent from the list under any other error distribution - fixed at the value supplied to student(df = ), and that sweep's grid draw when the degrees of freedom are estimated. A heteroscedastic (variance forest) sampler carries no sigma element - absent, as shape is off "nbinom" - since its engine holds the scalar fixed; it adds variance, the per-observation variance surface s2(xi)s^2(x_i) on the original response scale, shaped as train, whose square root is the residual scale, and varianceTest, the same at the test rows (NULL without test data). A run can be interrupted with Ctrl-C: it stops between iterations, or inside an iteration's Polya-Gamma latent draws or a monotone leaf-order count, whose time grows with a logistic, negative-binomial or multinomial fit's counts or with a large tree, joining any worker threads first. It then raises R's interrupt condition, class c("interrupt", "condition"), as base R's own long computations do: nothing is printed as an error, try() and error handlers do not catch it, tryCatch(interrupt = ) does, and calling handlers, on.exit and finally run. A loop of fits inside try() stops at the interrupted one. The call returns no samples. The sampler's chains are left where they stopped and it can be run again; where the stop falls inside a pass over the trees (a slow monotone count, a latent refresh) that pass may be partly applied, each latent at this iteration's draw or the previous one, which is a valid state to run on from. The saved trees the stopped call wrote are dropped: predict and getTrees serve the earlier calls' draws it did not overwrite, oldest first. Unlike a base R interrupt, it offers no "resume" restart: the run is over. Under control@keepFits == FALSE, train, test, and (when the model carries them) the variance and forest channels come back NULL rather than an array - present in the list, holding nothing, unlike shape/resid.df above, which are absent outright when inapplicable; see callback above and dbartsControl's keepFits. A callback that returns nonzero ABORTS the run the same way an interrupt does: the results and the saved trees the call wrote are discarded and run signals an error, naming that a callback stopped it; that is an error, where an interrupt is not.

For setCutPoints, NULL invisibly. The change is always made, as in 0.9-x: there is no unforced form and no forceUpdate argument, and a split left with no cut point between the splits above it is merged, so the trees can change. It sets a grid, typically once before sampling. Inside a larger sampler whose draws move a column's values, let the grid follow them with setPredictor(updateCutPoints = ), which derives the grid a creation would for the new values, up to n.cuts, each time, and whose unforced form is refused, with the sampler as it was, when the trees cannot hold the new grid.

For setPredictor, TRUE if the new predictor was installed and FALSE if it was refused. An unforced update is refused, with no error and no warning, when it would leave a leaf empty in any tree of any forest of the sampler (see ‘Multi-forest and heteroscedastic predictor mutation’) or, under a monotone constraint, leave a tree's leaf values out of order. A refused update is rolled back, whether it named columns or replaced the whole matrix: the sampler's trees, fits, predictors and random number generator are as they were before the call. A forced update always installs and returns NULL invisibly: the value says whether a valid update was made, which has no meaning when it is forced. When forceUpdate is "partial", instead returns a logical vector of length equal to the number of observations, TRUE where that observation's new value was installed and FALSE where it was rolled back to its previous value to keep every tree of every forest valid.

For installTrees, TRUE if the donor was installed and FALSE if it was not, the sampler then being exactly as it was: it is FALSE when a tree a chain would take, or a leaf value, would have to be changed (see ‘Warm starts’). No warning is given. With forceUpdate = TRUE the donor is installed with the changes and the value is NULL, invisibly, whether or not anything was changed.

For setState, TRUE if the state was installed and FALSE if it was not, the sampler then being exactly as it was. It is FALSE when a tree of any chain would have to be changed to fit the sampler: a split whose threshold is not one of the sampler's cut points, a leaf that no row of the current predictors reaches, a split that the state holds outside the range the splits above it leave, a rule with a side for missing values on a column that has never held one, a split its forest's columns or interaction limit do not allow, or monotone leaf values out of order (see ‘Saving’). No warning is given. TRUE means the trees and leaf values are the stored ones. It does not promise the cut points or their weights, which stay the sampler's whatever the state records, so that a chain restored onto other weights or a finer grid is not the stored chain continued; the case weights and an aft censoring status, which stay the sampler's; the generator, which is left as the sampler's own when the state's is of another kind; or every kept draw, of which the newest that fit the sampler's store are taken. Nor does it cover a value the sampler holds fixed, which a state never changes. A state stored under another response mapping is installed as stored and reports TRUE. With forceUpdate = TRUE the state is installed, repaired where it has to be, and the value is NULL, invisibly, whether or not anything was repaired: a caller who needs to know calls without it first. copy and a reload install a state that way and report nothing.

Under keepTrees the draws predict, predictForests, getTrees and printTrees report come out OLDEST FIRST: the store keeps the most recent [email protected] recorded draws, so a sampler driven through several recorded run calls replays them in the order they were drawn and lines up draw for draw with the train/sigma channels those runs returned. A sampler that has recorded fewer draws than that reports only the draws it holds, and one that has recorded none - keepTrees set but nothing run since creation, a setControl that resized the store, or an installTrees warm start - is refused rather than answered from slots nothing has written.

predict keeps the current test matrix in place and uses the current set of tree splits. This function has two use cases. The first is when keepTrees of dbartsControl is TRUE, in which case the sampler should be run to completion and the function can be used to interrogate the existing fit. When keepTrees is FALSE, the function can be used to obtain the likelihood as part of a proposed new set of covariates in a Metropolis-Hastings step in a full-Bayes sampler. This would typically be followed by a call to setPredictor if the step is accepted.

Its return shape mirrors run()'s own train/test channel for a single-forest sampler, with two exceptions. An amplitude-coupled (multi-forest, including a Bayesian causal forest) sampler refuses predict outright rather than answering here - see getFitsWithoutOffset below, which already records the same refusal - so everything that follows describes a single-forest or multinomial sampler only. For a single-forest sampler: with saved trees to replay (keepTrees TRUE and at least one recorded draw), the result is an n.test x n.samples x n.chains array, the trailing chain dimension dropped to a plain n.test x n.samples matrix when n.chains is 1; without saved trees to replay, the CURRENT (live) trees are replayed once per chain instead, with no samples axis at all - a plain vector of length n.test at one chain, an n.test x n.chains matrix otherwise. A family = "multinomial" sampler's surface reports the K category probabilities instead: an n.test x K x n.samples (x n.chains) array, the K axis inserted between the rows and the samples. Unlike the single-forest case, this samples axis is never dropped: it is sized 1 rather than omitted when there are no saved trees to replay. A heteroscedastic (variance forest) single-forest sampler with saved trees to replay returns not a bare array but a named list list(mean = ..., variance = ...), both members the single-forest shape above; without saved trees there is nothing for the variance forest to replay, so the bare mean array returns alone, exactly as a non-heteroscedastic sampler's would.

For getTrees, a data.frame with one row per tree node in depth-first, left-hand-side pre-order, with columns forest (indexed from 1, present only on a sampler with more than one forest - a multinomial one, or one declared with forests = naming several - and then leading every other column, forest-major, at the default forest = NULL or a vector; any other sampler returns no forest column and accepts forest = 1), chain (present only when n.chains > 1), sample (present only for saved samples, and reporting the draw number asked for), tree, n (the number of observations in the node), var (the splitting variable, or -1 at a leaf), and value (the split value, or the leaf prediction). An ordinal rule's value is its cut point and observations with values less than or equal to it go left; on an ordered-factor column that cut point is an exact half-integer at a level boundary, so levels(x)[floor(value) + 1] is the last level going left (the split value is a 0-based code, R's levels is 1-based); a categorical rule carries no data value (its value is NA) and its split is reported in the directions column instead. When the sampler has any categorical predictors the result gains a directions column decoding each categorical rule into one "L"/"R" character per level, in level order (level k goes right when its character is "R"); ordinal rules and leaves are NA. When any predictor contains missing values the result gains a missing column giving the branch ("L"/"R") each rule sends missing values down; rules on complete columns and leaves are NA. Under a linear leaf prior each leaf's value is its intercept and the result gains one beta.<column> column per designated covariate holding that leaf's slope on the internal standardized scale; internal nodes are NA.

For getSigmas, a numeric vector of length equal to the number of chains, giving each chain's current residual standard deviation on the original response scale, or NULL on a heteroscedastic sampler, whose residual scale is the surface getVariance reports.

For getK, each chain's current k, the value run()$k records per draw when k is drawn in that run (a run records no k while it is fixed), read without running, as getSigmas reports sigma: after a run it is bitwise the last draw. A fixed k is reported once per chain, and a forest whose scale a calibration map sets reports 1; a forest with no basis stating neither sd nor a coefficient's prior reports the leaf prior's k, and those that share one prior total (see forest) each the group's one. It is k whatever terms the prior was named in, relative to getLeafPrior()$k.scale: under an sd-named prior, that scale over the spread in force. A numeric vector of length equal to the number of chains at one forest, or, at the default forest = NULL on a multi-forest sampler, an n.forests x n.chains matrix; a single-forest sampler's NULL read is bitwise its forest = 1 read.

For getShape, the shape parameter of the sampler's family currently in force, a numeric vector of length equal to the number of chains, and NULL on a family with none - the count analog of getSigmas. Only the negative-binomial family has one today, its rr: the variance is μ+μ2/r\mu + \mu^2 / r, a larger shape is closer to Poisson, and rr is size in rnbinom and theta in MASS and mgcv. It is the same scalar run()$shape records once per kept draw, read mid-sweep and without serializing state, so an outer sampler driving this one a sweep at a time reads it here; state[[chain]]$shape holds it only where it is drawn. Because the refusal for a family carrying no shape is a NULL and not an error, a caller distinguishing “no shape” from a value must test !is.null(...); comparing to an expected number would pass vacuously.

For getSumsOfSquaredResiduals, a numeric vector of length equal to the number of chains, giving each chain's residual sum of squares ∑(y−y^)2\sum (y - \hat{y})^2 on the original response scale; a binary-response sampler reports on the latent scale instead. On a multi-forest (forests) sampler y^\hat{y} is the COMBINED location ∑fmf(xi)ff(xi)\sum_f m_f(x_i) f_f(x_i) - the same quantity run()$train records - and not any one forest's own total. Two qualifications, both keyed to the response family rather than to the forest count. A logistic sampler's working response is wi(yi−1/2)/ωi−oiw_i(y_i - 1/2)/\omega_i - o_i with ωi\omega_i a Polya-Gamma variate redrawn every sweep, so what it reports is a function of that sweep's auxiliary variables and is not a residual sum of squares in any scale. A multinomial fit reports NaN: its coupling reports a category-by-observation probability slab rather than a location, so no residual sum of squares is defined - the NaN is deliberate, in place of the sum of squared category probabilities a bare substitution would have given.

For getLatents, NULL when the model augments nothing - a plain gaussian response - and, deliberately, on a multinomial one, which augments but reports nothing: its K×nK \times n Polya-Gamma ω\omega matrix is drawn every sweep, but each ωik\omega_{ik} is an interleaved ONE-VS-REST augmentation variable refreshed against a margin that the other K−1K-1 forests move within the same sweep, so the code driving the sampler, reading it between sweeps, reads a quantity whose conditioning it cannot reproduce, and the composition recipes reach the same posterior through the fits and the category offset without touching it. That decline is scoped to the augmentation families whose latent is a PRECISION refreshed against a moving margin; the location-valued latents below - probit's and ordinal's ziz_i, and aft's imputed log survival time - are reported as documented. Otherwise the values the last sweep's trees were drawn from. Each sweep draws them first, after any change made between sweeps and before its trees, so between a setter and the next run they are the values from before the setter (setData starts them as creation does, an ordinal or negative-binomial sampler from the kept cutpoints or shape; an aft setResponse leaves a censored row at its new bound) and the next sweep draws them afresh. They are a plain vector of length equal to the number of observations when there is a single chain, or an observations-by-chains matrix otherwise, written into result when one was supplied. What that variable IS depends on the family and is not uniform. It is a LOCATION, on the sampler's own latent scale, for "probit" (the truncated normal ziz_i), "ordinal" (the same ziz_i under the ordinal thresholds) and "aft" (the imputed log survival time), all of which the code driving the sampler regresses on directly. It is a PRECISION, one per observation, for "logistic" and "nbinom" (the Polya-Gamma ωi\omega_i) and for a Student-t residual distribution (the scale-mixing λi\lambda_i); these WEIGHT a working response and are not on the response scale at all, so differencing them against a fit is meaningless. Note the last case: a sampler whose family is "gaussian" but built with family = student() (see dbarts) does report latents, and they are precisions.

For getFitsWithoutOffset, the sampler's combined per-observation location on the response scale and without the installed offset, an n.observations x n.chains matrix. run()$train reports the same quantity with the offset folded in, so this value plus the installed offset is that one; there is deliberately no with-offset twin, since the offset is the caller's own. It is the read an outer sampler driving this one a sweep at a time needs: an incremental scheme updates its outer block against f(xi)f(x_i), and taking getLatents() minus run()$train instead is BIASED: a location latent is on the offset-inclusive scale, as the training channel is, so that difference is the residual alone and carries none of the offset's signal. A block that owns the offset regresses getLatents() - getFitsWithoutOffset() on its covariate. On a multi-forest (forests) sampler this is the only route, short of running the sampler, from R to the combined fit - getForestFits gives one forest's internal-scale totals and predict is refused. It is refused, naming the reason, on a multinomial sampler, whose reported channels are per-category softmax probabilities rather than one additive location; predict(x) serves that read, but reports the SAVED samples rather than the current state when the sampler was built with keepTrees.

For getVariance, a heteroscedastic (variance forest) sampler's current variance surface s2(xi)s^2(x_i) on the original response scale, an n.observations x n.chains matrix at the default test = FALSE and an n.test x n.chains matrix at test = TRUE. It is the mid-sweep read of the channels run() records as variance and varianceTest: at the state a recorded sweep left, the accessor and the channel agree exactly. What it reports is a VARIANCE, so a residual scale is its square root - it is the surface analog of getSigmas, which reports the scalar σ\sigma a homoscedastic sampler carries. NULL where those channels report nothing: on a homoscedastic sampler, and at test = TRUE with no test rows installed. Unlike predict, which addresses the saved samples, it reads the trees currently in force, so it answers after $sampleVarianceForestFromPrior() and needs no keepTrees.

For getForestFits, a multi-forest sampler's requested forest's current internal-scale fitted values, an n.observations x n.chains matrix, or, at the default forest = NULL, every forest stacked with the forest margin between the observations and the chains, n.observations x n.forests x n.chains (bitwise the forest = 1 read on a single-forest sampler). For getForestAmplitudes, the named forest's amplitudes - one per basis column - as a q x n.chains matrix, or, at the default forest = NULL, every forest's stacked forest-major into a sum(q) x n.chains matrix. A drawn one has prior median size 1, on a factor the difference between two levels' amplitudes, a level's own having 0.71. The vector is ragged: a Bayesian causal forest's forest 1 carries the single aa on its implicit intercept and its forest 2 the pair (b0,b1)(b_0, b_1), so the stacked read is the (a,b0,b1)(a, b_0, b_1) of y=aμ(x)+bzτ(x)+ϵy = a \mu(x) + b_z \tau(x) + \epsilon. For getForestVariableCounts, the requested forest's current per-predictor split counts, an n.predictors x n.chains integer matrix, or, at the default forest = NULL, every forest stacked the same way as getForestFits, n.predictors x n.forests x n.chains; its rows are named by the training matrix's column names when that matrix carries them (on margin 1 in both shapes), and left unnamed otherwise.

For predictForests, the off-sample twin of getForestFits: every forest replayed separately at x.test, as an n.test x n.forests x n.samples (x n.chains) array on the forests' internal scale, forest-major within a draw. It reports the saved samples when the sampler was built with keepTrees, and the current trees otherwise, exactly as predict does. Nothing but the forests' own totals is in it: no amplitude glue, no response transform and no offset, the last refused rather than ignored. That is the point of the channel rather than an omission - an amplitude coupling's location is response.shift + ∑f(Bfaf)×(response.scale×ff)\sum_f (B_f a_f) \times (\mathrm{response.scale} \times f_f), and off the training rows only the caller knows the bases BfB_f, so the whole recombination is theirs, with $getForestAmplitudes() and $getLeafPrior() supplying the rest. At the fit level it is packaged: predict on a bart object with type = "ev", "ppd" or "bart" performs the same recombination off this replay, taking the bases at the predicted rows through its own bases argument. Only a sampler that composes its forests through scalar amplitude glue reports per-forest fits; every other one is refused by name, a multinomial sampler included, whose raw per-category totals are perfectly well defined but whose reported quantity is a softmax probability that predict serves. The refusal is off-sample only: getForestFits is not gated the same way, so those same per-category totals stay readable AT the training rows, for the current trees and one draw, and it is the off-sample replay - which would have to hand back a level nothing identifies at rows the sampler never saw - that has no counterpart.

For getLeafPrior, the leaf prior a forest runs under, alone, as a named list: leaf.prior, the specification in the terms it was named in - a normal(), linear() or gp() object (see dbartsPriors) carrying one of k, a number or a chi() prior, or sd, a number or an invchi() prior, the family default when none was named - which goes back into setLeafPrior or a fitting function's leaf.prior as is; leaf.model, one of "constant", "monotone", "linear", or "gp"; prior.sd.of, what the sd is the sd of: "forest", "coefficient" (linear, per standardized covariate) or "amplitude" (gp); prior.mean; k.scale, the value k is relative to, so the spread in force on each chain is k.scale / getK() - the data's scale, which the family and the response transform fix and no spelling of the prior moves, so that under an sd-named prior k is k.scale over the sd; and response.scale and response.shift. A forest the calibration map does not set also carries, after leaf.prior, sd, its size in force in the response's units - k.scale over k at a fixed k, the number as stated where an sd was, and NA where k is drawn or the sd is under invchi(), which have no one number - and sd.stated, whether the leaf prior is named by an sd, at creation or through setLeafPrior. A fixed k is the one in force, read off the engine; an sd, a number or under invchi(), is reported as it was named. Every chain runs under the sampler's one prior and one response transform, which no state install moves, so every value is shared by the chains. A drawn k is chain state, read by getK. At the default forest = NULL a multi-forest sampler returns a list of one prior per forest, named by the forests' labels, a multinomial sampler's by the response's levels; a single-forest sampler's NULL read is bitwise its forest = 1 read. An NA spread is refused by setLeafPrior, setModel and the fitting functions. On a forest whose scale a multi-forest calibration map sets, k is pinned at 1 and leaf.prior is the statement of the forest's size: forest(sd = v), v the number as it was written, where an sd was stated, and forest() where none was. Its sd is the one setForest states. The list then begins with leaf.prior, sd, the forest's sd in force in the response's units - v itself, bit for bit, or the default's multiple of the response's scale times the unit the sampler derived at creation - sd.stated, TRUE where the size comes from an sd the user wrote at either level, the forest's own forest(sd = ) or, on a forest with no basis that states none, the fitting function's normal(sd = ), and FALSE for the default and for k, multiplier, what the forest multiplies, "none", "factor" or "numeric", and amplitude, fixed() where the forest's coefficient is held, student(df) where it is drawn under the Student-t prior its creation stated, normal() where a forest with no basis is drawn under the normal prior its creation stated, and absent where it is drawn under its default prior. prior.sd.of says what sd is the size of: "forest" for a forest with no basis, "level difference" for a factor and "forest, per unit of basis" for a numeric column, the size exactly where the coefficient is held, with " (at a coefficient of 1)" where it is drawn. A numeric forest's sd is per unit of its column and carries the column's name where the basis has one, and the list adds basis.scale, where the data object records one, the standard deviation of the column the default was taken from at creation, named as sd is. k.scale is the forest's own prior sd before its coefficient, in the response's units: the forest's sd, on every forest but a sharer. A forest with no basis stating neither sd nor a coefficient's prior, alone or sharing one prior total with others (see forest), reads as one forest does, under the fitting function's leaf prior: leaf.prior is that prior as named, sd the forest's part of the total in force, NA where k is drawn, sd.stated TRUE when the fitting function's leaf prior is named by an sd the user wrote, normal(sd = ), as it is on a sampler of one forest, and FALSE for the default and for k, multiplier "none", amplitude fixed(), prior.sd.of "forest" alone and "forest, shared" in a group, one left of a group included, and k.scale over the k its part.

On a forest whose scale the multi-forest CALIBRATION MAP sets, on a sampler built with forests = or a forest() formula term (see forest), k is pinned at 1, k.scale is the map's leaf scale, and the entries above that the map adds are absent (so NULL) on every other forest, a multinomial one included. A drawn coefficient is a multiplier with prior median size 1 - on a factor the difference between two levels' coefficients, a level's own having 0.71 - and on a numeric column through bcf's 0.674.

The spread (k.scale / k) describes the LEAF-PARAMETER scale of the forest total. It equals the prior standard deviation of f(x)f(x) at every xx for the constant leaf only; for the other three the prior of f(x)f(x) is x-dependent and the spread bounds it in a leaf-specific direction. Under "linear" it is a LOWER bound attained at the standardized covariate origin, with sd(f(x))=sd(f(x)) = the spread 1+∥z(x)∥2\sqrt{1 + \|z(x)\|^2} in the internally standardized leaf covariates (a missing value maps to zj=0z_j = 0); prior.mean is exact. Under "gp" it is an UPPER bound over xx, attained at rows that reproduce a leaf member and on over-cap leaves, and elsewhere decaying to zero as xx leaves the leaf's data cloud, where every prior draw equals prior.mean exactly. Under "monotone" it is a LOWER bound in the interior - the realized standard deviation runs a few per cent to about twenty per cent above it - and prior.mean is NOT the prior mean of f(x)f(x) under an active constraint: that marginal is skew, with an x-dependent mean tracking the constraint's direction across several the spread (see monotone in dbarts).

This is the authoritative reader of the prior in force. A named sd is absolute: the sampler holds it as k = k.scale / sd, or as the chi prior on k at that scale, and restates it whenever the response transform is re-anchored - setResponse, setOffset, setWeights or setActiveRows at updateScale = TRUE, setData, and setResponse and setOffset made by compiled code through dbarts.h, which has no entry for the other two - so a fixed sd, and the prior on a drawn one, keep their meaning in response units. A drawn sd's current value is k's: at a re-anchor it stays where it was on the internal scale, stretching with the leaves, and lags until the next draw, as a drawn k does. A k is relative to the response transform recorded at creation or at the last re-anchor, and moves only with it. A state install (setState, installTrees, copy, a reload) leaves the prior as it was.

For setLeafPrior, NULL invisibly. It changes the leaf prior's spread or the hyperprior it is drawn under, on every chain, and nothing else: not the response transform, not sigma (which setModel re-pins on a fixed-sigma gaussian sampler), not the tree prior or a DART split prior. Into a drawn prior - a chi or invchi prior - each chain keeps the spread in force at the call, whatever the prior before it, fixed or drawn and in either the k or the sd form: k.scale is the data's under every prior, so k is not touched, getK does not move, and the new prior acts from the next draw of k. A fixed k or sd stated sets the spread as written, a fixed sd as k = k.scale / sd. Because the write keeps the chains' spread, on a sampler that has not yet run it is not the start that creation under the new prior would make. The write takes effect on the next sweep, reinterpreting no leaf value already drawn; a write that reproduces what is already in force is skipped bitwise, so a read followed by a write cannot perturb a draw. It is total over the four leaf models, and a DART sampler is served. A multinomial sampler takes normal(k = ) and applies the k to every category forest, leaving the softmax map's leaf scale; a named sd or a k hyperprior is refused there, as at creation. On a sampler whose forests carry amplitudes the leaf.prior is the fitting function's, written on the forests it reaches as creation under it gives them. Where one forest has no basis it is written there whatever that forest states, a stated sd going: a k or a named sd as at creation, and on a forest stating a coefficient's prior, which has no k, the size the prior gives at the scale creation set - normal(sd = v) the size v, normal(k = v) that scale over v, a chi() prior on k that scale over its median, once, with no k drawn there - leaving the coefficient's prior and every leaf and coefficient drawn. Where several forests have no basis, those sharing one prior total take it, each keeping the part of it its creation gave it, so after a forest has left the group (see setForest) the sizes no longer add up to it, and those stating their own sd keep it. Where none shares, as where every forest has a basis or every forest with no basis states its sd, the default restated changes nothing and any other leaf.prior is refused, naming setForest(forest, sd = ). Into a drawn k a forest starts at the spread in force. A write changes the model. The write is recorded where re-creation reads it. The map's k.scale is recorded at creation too, so a re-creation after setResponse or setOffset at updateScale = FALSE states every forest against the same k.scale as the live sampler. A value that is not a single positive finite number is an error. A heteroscedastic sampler's variance forest is a separate leaf model, which setLeafPrior does not reach; setVarianceForest changes its settings. setModel changes everything else.

For getForest, every value in force on one forest as a plain named list, no class and no attribute, in setForest's order and with the names its kind takes: sd, the size getLeafPrior reports with no column's name on it, NULL where k is drawn or no one positive number is in force; power and base; amplitude, the coefficient's prior as fixed(), normal() or student(df), a forest with a basis stating none reading normal(), and a forest with no coefficient fixed(); and proposal.probs, n.perturb.cuts and treeShift, a forest stating none reading the control's. A value the forest takes from above reads like any other. do.call(s$setForest, c(list(f), s$getForest(f))) changes nothing, whether the forest states a value included. On a multinomial sampler the list has no sd or amplitude and covers every category forest, whichever is named. Tree counts and columns are not in it: print and getTrees show them.

For setForest, NULL invisibly. It changes the forest named, and on it only the names given, each meaning what it means in forest on that forest at creation. It acts from the next sweep and leaves the trees, leaf values and coefficients already drawn as they are; a write changes the model. A name left out or NULL changes nothing, and so does a value equal to the one in force, which leaves the forest following what it followed: a forest taking its depth from the fitting function goes on taking it, a forest sharing one prior total stays in the group, and a numeric forest's default goes on being read from its column. Each name is compared with the value in force before the call, whatever else the call changes, so an sd handed back beside amplitude = fixed() is no change; to pin a forest at its sd, state a different one or, where k is drawn, the same in a second call. A forest that states its sd or its depth is changed by stating another; nothing returns it to following the fitting function, short of a new sampler.

sd on a model of one forest is its size, written as setLeafPrior(normal(sd = )) writes it, in the terms of its leaf model. On a model of several it sets the forest's trees' scale: its size where the coefficient is held and its size at a coefficient of 1 where it is drawn, on a factor the size of the difference between two levels and on a numeric column the size per unit. A forest with no basis alone under the fitting function's leaf prior leaves that prior at an sd stated for it, its k then pinned at 1. A forest sharing one prior total with others leaves the group the same way, and those still sharing keep their parts of the total, set once at creation, and their sizes; nothing puts a forest back in the group but a new sampler. A multinomial sampler refuses sd as its creation does. power and base are the forest's depth, every category's on a multinomial sampler. amplitude changes the coefficient's prior between held, fixed(), and drawn, normal() or student(df), and between those two, on every chain. A hold sets the coefficient to its held value at the call - 1, or 0 at a factor's first level and 1 at its second - so getForestAmplitudes reads it at once; a release draws it from that value from the next sweep; a Student-t prior's mixing variance starts at the normal prior's and is kept where only the degrees of freedom change. No leaf and no trees' scale moves, except on a forest whose size the fitting function's leaf prior gives: a forest with no basis holding the whole of that prior, released, takes the size creation gives the statement, its k pinned at 1, and held again follows the leaf prior again, a drawn k starting at the spread in force; the last forest left of a group, released, states its part of the total in force as its sd, which getForest then reads. normal() writes a forest with a basis back to its default and fixed() one with no basis. The prior in force changes nothing, and fixed() on a forest with no coefficient, as a model of one forest or a sharer has none. student(df) or normal() is refused as at creation there, a sharer taking it with an sd in the same call, which takes the forest out of the group, and where the leaf prior would give the size and gives none, as a chi() prior on k with an infinite scale. A multinomial sampler takes fixed(), which changes nothing, as its creation does, and refuses student(df) and normal() as its creation does. proposal.probs, n.perturb.cuts and treeShift are the forest's own, and a later setControl leaves them.

vars, n.trees, interactions and blocks are refused by name whatever their value, being part of the model, and basis is refused naming setForestBasis, a basis being data. What creation refuses of a forest's statement is refused here for the same reason. Every check comes before any write, so a refused call changes nothing, its good names included. A multinomial model's forests take one statement: s$setForest(power = 4) reaches every category, with forest left out, and a position or a level is refused. Every change is recorded on the model, as creation with the statement records it, so a copy and a reload run what the sampler runs.

Where setForest and setTreePrior, setLeafPrior or setModel reach one setting of one forest, as on a model of one forest, the later write wins, whatever the forest stated. A heteroscedastic sampler's variance forest takes the mean forest's depth at creation and is on its own after that: setForest and setTreePrior leave it, setVarianceForest changes it, and setModel installs a power or base the model's variance record states as setVarianceForest does. A model records what each forest states, a write here included, so setModel on another sampler installs it.

For setTreePrior, NULL invisibly. It changes the fitting function's tree prior, as power, base and split.probs mean at creation, through setModel's route, so the two cannot differ. A name left out or NULL changes nothing, and so does a value equal to the one in force. power and base reach the forests with no basis that state none of their own and, where one forest has no basis, or on a multinomial sampler's category forests, those forests whatever they state, the later write winning; they make no forest state them, and nothing returns a forest that states its own to following, short of a new sampler. A name that reaches no forest is refused, naming the forests that state it and setForest. A split.probs vector changes the values and 1 restores equal ones; on a DART sampler dart(...) changes DART's settings, a setting left out taking creation's default; dart() on an ordinary sampler and a vector on a DART one change the model's structure and are refused, and a sampler of several forests takes equal probabilities only. A variance forest stays as it is.

For getVarianceForest, every value in force on the variance forest as a plain named list, power, base, proposal.probs and n.perturb.cuts, or NULL on a sampler with none. For setVarianceForest, NULL invisibly. It changes those settings by setForest's rules, each meaning what it means in varianceForest. vars and n.trees are refused by name, and a sampler with no variance forest refuses the call: whether there is one is part of the model.

For storeState, NULL invisibly; it is called for its side effect of capturing the sampler's current engine state into the serializable state field, which save then writes out. See ‘Saving’. What it writes is one draw's trees, about 13 bytes per node per tree per chain, which is 3.5 pct of a single draw's training predictions at 20,000 observations and 75 trees and falls like 1/n1/n; it exceeds those predictions only below a few hundred observations, and it is a small fraction of a whole run's yhat.train, not a multiple of it.

Fields

Read with $, as the methods are called. Treat them as read-only: assigning to a field changes only the R-side copy and leaves the underlying engine untouched, so the sampler's behavior does not follow. Route changes through the set* methods instead.

control

The sampler's dbartsControl, carrying n.chains, n.threads, n.trees, keepTrees, updateState, and the rest. Replace with setControl.

model

A dbartsModel holding the parsed tree, leaf, and residual priors, together with any monotonicity, interaction, and block constraints. Replace with setModel.

data

A dbartsData holding the current predictors, response, test data, weights, and offset. Its x slot is stored columnar for data-frame input and so need not be a plain matrix; use extract(sampler, "predictors") for the numeric predictor matrix, which is what tree replay and getTrees count against. Replace with setData, or a piece at a time with the other set* methods; writing the field (sampler$data <- newData) stops and names setData, as such a write would change the R-side copy and not the sampler.

state

The cached, serializable engine state, or NULL until one is materialized. It holds the chains and not the model: trees, leaf values, the quantities the sampler draws, the cut points the trees' split thresholds were stored on (the attribute cutPoints, a list with one entry per predictor column, NULL for a factor column that splits by subsets of its levels; with their weights, the attribute cutMass, where a column's cut points are not equally likely) and the leaf-covariate standardization they are read through, a record of the response mapping they were read under, which predictor columns could hold a missing value when it was stored, and the levels of each forest a factor multiplies (the attribute basisLevels) - no leaf prior and no value the sampler holds fixed (see ‘Saving’). It also carries each chain's generator state, so restoring it continues the same streams the sampler was drawing from, typically to the last few digits, not bitwise. The saved-tree store's write position and the number of draws it has recorded both ride it, so predict after a setState reports the same draws, in the same order, as before the store. Reading it forces the sampler's current state only the first time, before any value has been materialized; once set, it is a cached snapshot that a later mutation does not refresh automatically - call storeState again, or pass updateState = TRUE to the mutating call (see updateState above), to bring it forward. After a setState that put a state onto cut points, or weights of them, other than the ones the state records, the field holds the sampler's state as storeState() gives it and not the state as it was given, so that a copy or a reload has the sampler's cut points and trees. It is the only field save needs, and restoring one requires setState - see ‘Saving’.

pointer

The external pointer to the C++ engine. Internal; never manipulate it directly.

Note

dbartsSampler is a reference class: its methods are not called as free functions but as $-dispatched calls on a sampler instance, e.g. sampler$run(100, 100) or sampler$setResponse(newY). The S4-method notation in ‘Usage’ below is an artifact of how reference-class methods are documented and does not reflect the calling syntax; see ‘Examples’.

See Also

updatePredictorPerObservationJointly for applying a shared per-observation predictor update across several samplers at once.

samplePriorPredictive for repeated prior draws of the hyperparameters, sampleTreesFromPrior, sampleLeafParametersFromPrior and predict on a private sampler, for calibrating priors before fitting.

dbarts-embedding for which channel an outer block writes, which fit it reads back, and whose prior is in force after a swap, and vignette("dbarts-as-a-component", package = "dbarts") for six worked compositions built from these methods.

Examples

# the embedded-Gibbs pattern: BART as a conditional model inside a larger
# sampler, alternating its own draws with updates to its response between
# calls to run()
n <- 100
x <- matrix(runif(n * 2), n, 2)
y <- x[, 1] - x[, 2] + rnorm(n, 0, 0.1)

sampler <- dbarts(
  y ~ x,
  control = dbartsControl(
    n.chains = 1L,
    n.threads = 1L,
    n.burn = 0L,
    n.samples = 1L,
    updateState = TRUE
  )
)

## first draw: response as given at creation
samples <- sampler$run()
str(samples$train) # a plain n.obs x n.samples matrix (n.chains == 1)

## an outer Gibbs step changes the response (e.g. after updating some
## other part of a joint model); the sampler picks the new target up on
## the next run() without being recreated
newY <- y + rnorm(n, 0, 0.05)
sampler$setResponse(newY)
samples <- sampler$run()
str(samples$train)

Discrete Bayesian Additive Regression Trees Sampler Specification

Description

Resolves the control/model/data triple and family token that describe a sampler, without constructing one. Intended for packages that embed dbarts - in particular LinkingTo: dbarts packages that build a sampler in R from the returned pieces and hold its handle for the C API in ‘dbarts.h’ - and that supply their own design matrix.

Usage

dbartsSpec(
    data, control = dbarts::dbartsControl(),
    power = 2, base = 0.95, split.probs = NULL, leaf.prior = normal,
    proposal.probs = c(
        birth_death = 0.6, swap = 0, change = 0.4, perturb = 0,
        rule_gibbs = 0, birth = 0.5),
    monotone = NULL, interactions = NULL, blocks = NULL,
    variance = NULL,
    forests = NULL, n.trees = NULL,
    sigest = NULL, seed = NULL,
    family = c("auto", "gaussian", "student", "probit", "logistic", "aft",
               "multinomial", "ordinal", "nbinom"),
    weights.type = NULL,
    survival = NULL, tree.prior = NULL,
    parentEnv = parent.frame(), ...)

Arguments

data

A dbartsData object, as built by dbartsData. Unlike dbarts, this function does no response ingestion of its own: the response must already be materialized. A data object carrying an n×Kn \times K counts matrix resolves to family = "multinomial" even from "auto" - the slot IS the declaration - and is refused under any other family. Where family = "auto" resolves, the family is reported in a one-line message when control was built with verbose = TRUE; this function has no verbose argument of its own.

control, power, base, split.probs, tree.prior, leaf.prior, proposal.probs, monotone, interactions, blocks, variance, forests, n.trees, sigest, seed, family, weights.type, ...

As in dbarts (except that proposal.probs, the control's setting, is still accepted here as it is at dbarts: it is used, with a deprecation warning, is refused beside a control whose own call named it, and does not reach a forest that states its own), including the frozen proposal.probs mixture - all five structural probabilities zero, which proposes no structure and draws only the leaf values, sigma and the family's latents. The prior arguments are evaluated in dbarts's own prior vocabulary, so bare expressions such as normal(k = chi(1.25, Inf)) resolve regardless of what the caller has attached; so do the forest constructors inside monotone, interactions, blocks, variance and forests, evaluated in parentEnv (see dbartsForests). The residual prior rides family here as everywhere (family = gaussian(sigma = chisq(df, quant))); the 0.9-x spellings resid.prior, sigma and node.prior were never arguments of this function and are refused by name, naming family = gaussian(sigma = ), sigest and leaf.prior respectively. A forest's basis is read against data as dbarts reads one beside a data object: a name is read from the frame the object keeps, or from the columns it holds, its predictors and response and a sampler's bases by the text each was written as, and otherwise where forest() was called; a value has one entry for each row the object was handed, before its subset and na.action, and is cut with them. The list states the forests in full: what the data object held is replaced, a forest keeping a held basis by writing it as it was written, with its recorded scale, and no list, or a list of one forest with no basis, gives one forest. family's eight-token vocabulary is narrower than dbarts's by design - multinomial's K-forest engine and hurdle.lognormal's two-sampler composition build through bart, never through this construct-only bypass; the wider set lives there.

survival

For family = "aft" only: a vector of per-observation status codes, 1 for an observed event and 0 for a right-censored observation, with the response holding log event/censoring times. dbarts reads this off a Surv or two-column response; a caller supplying log-times directly supplies it here. NULL for every other family.

parentEnv

The environment in which the prior and forest constructor arguments are evaluated; defaults to the caller's frame, which is almost always what is wanted. Pass explicitly when forwarding arguments from another function.

Details

dbarts does two separable things: it ingests a formula or a pair of matrices into a dbartsData, and it then resolves that data into a full sampler specification - choosing the response family, coding the response, applying the family's weight policy, estimating a starting sigma, parsing the priors, and recording on the model and data the monotonicity, interaction and block constraints, the forests and a variance forest, the residual degrees of freedom, and the survival status. dbartsData exposes the first half. This function exposes the second, and returns the pieces rather than a sampler.

Both entry points call the same resolution on the dbartsData they end up with, so a sampler built from this function's output draws the same samples as the equivalent dbarts call given the SAME data object. The two can still resolve a given family differently, because dbarts performs its own response ingestion first - coding a factor response into a count matrix, for instance - while this function does none: a call this function refuses for the raw response dbarts can still accept, by ingesting it into the shape this function requires.

Use with the C API

The family element of the returned list names the family the sampler is built with, and the dbarts_family enumerator dbarts_sampler_family reports for it ("gaussian" names DBARTS_FAMILY_GAUSSIAN, and so on). "auto" asks this function to dispatch on the shape of the response, which is correct for "gaussian", "probit", and "ordinal" - each is inferable from the response coding or from an attribute - but is wrong for "aft" and "logistic", which are indistinguishable by shape from "gaussian" and "probit" respectively, and for "nbinom", which is never inferred (a count vector resolves to "gaussian"). Name the family and the question does not arise.

Differences from dbarts()

sigest defaults to NULL, which like "auto" estimates the starting sigma from the data's response, as dbarts does: a starting estimate or response scale a sampler wrote into the data object is not read, since a new fit is a new model (use the sampler's copy() for the same model again). A number states it, and "dense" or "sparse" names the routine. An explicit NA for sigest is a missing value and is refused. Cut points are taken from control only when the data does not already carry resolved per-column counts.

Families that require ingestion this function does not perform are unavailable: "hazard" needs person-period expansion, and "hurdle.lognormal" describes more than one sampler. "multinomial" is in this function's own vocabulary, but only for a data object whose response is already an n×Kn \times K counts matrix (see data above, and dbartsData's counts argument); given a factor-coded or plain numeric response instead, it is refused with a message naming the counts route, even though dbarts accepts the same factor by coding it into that shape first.

Value

A list with components

control

a dbartsControl, holding the run settings; its n.trees, useQuantiles and binary are copies of the model's and the data's, which a sampler built from the list writes on it.

model

a dbartsModel, carrying the parsed priors, each forest's record and the variance forest's, the category count, the shape setting, the hazard periods, the resolved weights.type (never NA), and any monotone, interaction, block, and residual-degrees-of-freedom attributes.

data

a dbartsData, with the response coded, sigma resolved, and the censoring status and quantile rule recorded. Its weights slot holds the fit's weights, a "probit", "ordinal" or "nbinom" fit's 0/1 weights among them, all ones as none, so new("dbartsSampler", spec$control, spec$model, spec$data) makes the sampler dbarts makes: the response's scale, a count fit's center, a linear or gp leaf's covariate centers and scales and a numeric forest's default sd are read over the rows the weights keep, and the two are identical() in the stored state and every array run() returns from the same seed. A mask handed to that call as active composes with the weights, a row being in when its weight is positive and the mask keeps it. On a gaussian or Student-t list, where the rows the weights keep hold fewer than two distinct values of the response and a forest on a numeric column states no sd, that route warns twice, here for the response's scale and center and at creation for those and the column's scale, where dbarts warns once.

family

the resolved family token, never "auto".

See Also

dbarts, dbartsData, dbartsControl, dbartsPriors

Examples

f <- function(x) {
    10 * sin(pi * x[,1] * x[,2]) + 20 * (x[,3] - 0.5)^2 +
      10 * x[,4] + 5 * x[,5]
}

set.seed(99)
sigma <- 1.0
n     <- 100

x  <- matrix(runif(n * 10), n, 10)
Ey <- f(x)
y  <- rnorm(n, Ey, sigma)

data <- dbartsData(x, y)
control <- dbartsControl(n.chains = 1L, n.samples = 20L, n.burn = 10L, updateState = FALSE)

## an ordinary specification, then the sampler it describes
spec <- dbartsSpec(data, control = control, n.trees = 25L)
spec$family

sampler <- new("dbartsSampler", spec$control, spec$model, spec$data)
samples <- sampler$run()

## additive-only fit, monotone in the fourth predictor
constrained <- dbartsSpec(data, control = control,
                          interactions = interactions(max.order = 1L),
                          monotone = c(rep(0, 3), 1, rep(0, 6)), n.trees = 25L)
attr(constrained$model, "interaction.max.order")

Validate A Composed Sampler By Simulation-Based Calibration

Description

Simulation-based calibration (Talts et al. 2018) over a one-sweep step you supply, for a model you state as a prior draw and a simulation. For each replication it draws θ0\theta_0 from the prior, simulates data at it, runs the step, and ranks each scalar functional's value at θ0\theta_0 among its values over the retained draws. Under a kernel that targets the posterior the prior and simulation imply, those ranks are uniform; a systematic departure means the composition does not sample what it claims to - the defect class in which a posterior mean is reported where a draw belongs. It is a diagnostic, not a fix.

Usage

dbartsValidateComposition(drawPrior, simulate, init, step, functionals,
                          n.replications = 200L, n.draws = 200L,
                          n.thin = 30L, n.burn = 200L, alpha = 0.05,
                          seed = NULL)

Arguments

drawPrior

A function of no arguments returning one draw θ0\theta_0 from the prior, in whatever shape simulate and init expect. Nothing is read out of it by name.

simulate

A function of θ0\theta_0 returning one simulated data set from the likelihood the composition assumes.

init

A function of θ0\theta_0 and the simulated data returning the chain's initial state. It must start the chain at θ0\theta_0: the rank is taken of functionals(init(theta0, data)), so a state built anywhere else ranks the wrong quantity. The state carries whatever step and functionals need, the data included.

step

A function of the state returning the state after one sweep of the composed kernel - the whole Gibbs/Metropolis-Hastings scan, not one block of it.

functionals

A function of the state returning a numeric vector of scalar summaries to rank, the same ones in the same order at every state. They may be derived - a mean fit, a probability, an indicator - and need not be parameters; names, if given, label the report.

n.replications

Number of prior draw / simulation / refit replications. The rank resolution and the band both come from this.

n.draws

Number of draws retained per replication, LL; ranks run over 00 to LL.

n.thin

Sweeps per retained draw. SBC assumes the retained draws are independent, so this should exceed the composition's autocorrelation time; 1 is right only for a step that draws the posterior outright.

n.burn

Sweeps discarded before the first retained draw. The default is not 0: an init that is only approximately at θ0\theta_0 would otherwise be flagged for its early draws. An init that is exact can use 0.

alpha

Level of the uniformity band, Bonferroni-corrected within the call over the number of functionals ranked, so that a whole call passes with probability about 1−α1 - \alpha.

seed

Seeds R's random number stream for the whole run, making it reproducible, and restores the caller's stream on exit, as simulate does; NULL uses the stream as it stands, advancing it. An NA is a missing value and is refused. The band's own stream is fixed internally and restored on exit either way, so a call never leaves that fix behind.

Details

The verdict. The primary statistic is the maximum absolute difference between the ranks' empirical cdf and the uniform one, against a simultaneous band simulated from the null (Talts et al. 2018, fig. 1), which is already corrected for the multiple looks across the rank grid. A chi-square goodness of fit and a jittered Kolmogorov-Smirnov test are reported beside it as secondary signals; the verdict does not hinge on them.

Ties. A rank is the number of draws below θ0\theta_0, which is uniform only for an atomless distribution. Every functional is ranked with the tie-break instead: draws and θ0\theta_0 alike carry an independent uniform tag, so an atom - an indicator, a discrete parameter, a probability that underflows to zero - contributes a uniform increment rather than piling every replication onto one rank. With no ties it is the plain count, exactly.

The blind spot. The validator compares the composition against the model drawPrior and simulate state between them. It cannot detect an outer sampler whose prior draw and simulation disagree with each other: a step that correctly targets the posterior of the wrong model passes, because that model is the one being validated against. Nor does it localize a failure to a block of the sweep; it reports which functionals are miscalibrated, not why.

Value

An object of class dbartsCompositionValidation, a list with components ranks (the n.replications by number-of-functionals integer matrix of ranks, columns named for the functionals), L, n.replications, n.thin, n.burn, alpha, alpha.adjusted (the Bonferroni-corrected level actually used), mean.rank.target (L/2L/2), pass, and verdicts, a data frame of one row per functional carrying its mean rank, ecdf-difference statistic, band, chi-square and KS p-values, and its "PASS" or "FLAG" verdict. print reports the table.

References

Talts, S., Betancourt, M., Simpson, D., Vehtari, A., and Gelman, A. (2018) Validating Bayesian inference algorithms with simulation-based calibration. arXiv preprint arXiv:1804.06788.

See Also

dbartsSampler, the sampler a composition drives, and dbartsAugmentation, the augmentation draws a composed step is built from.

Examples

# a conjugate normal-normal one-sweep step: theta ~ N(0, 1) and
# y_i | theta ~ N(theta, 1) give theta | y ~ N(v * sum(y), v), v = 1 / (1 + n)
n <- 5L
v <- 1 / (1 + n)

drawPrior <- function() c(theta = rnorm(1L))
simulateData <- function(theta0) rnorm(n, theta0[["theta"]], 1)
initState <- function(theta0, data)
  list(theta = theta0[["theta"]], mean = v * sum(data), sd = sqrt(v))
functionals <- function(state)
  c(theta = state$theta, positive = as.numeric(state$theta > 0))

# the step draws the posterior outright, so its states are independent and its
# init is exact at theta0: this call needs neither thinning nor burn-in
stepExact <- function(state) {
  state$theta <- rnorm(1L, state$mean, state$sd)
  state
}
dbartsValidateComposition(drawPrior, simulateData, initState, stepExact,
                          functionals, n.replications = 50L, n.draws = 100L,
                          n.thin = 1L, n.burn = 0L, seed = 8L)

# the defect class this exists to catch: the posterior MEAN reported where a
# draw belongs. 'theta' flags; 'positive' is coarse enough to survive it, power
# being per functional.
stepMean <- function(state) {
  state$theta <- state$mean
  state
}
dbartsValidateComposition(drawPrior, simulateData, initState, stepMean,
                          functionals, n.replications = 50L, n.draws = 100L,
                          n.thin = 1L, n.burn = 0L, seed = 8L)

Extract the Predictor Matrix From a Sampler

Description

Returns the predictor matrix as the sampler currently sees it - one numeric column per predictor, with factor columns as their integer codes. This is the canonical source for tree replay: it is the same matrix getTrees uses to count training observations through saved trees.

Usage

## S3 method for class 'dbartsSampler'
extract(object, type = "predictors", ...)

Arguments

object

A dbartsSampler.

type

A character string; only "predictors" is supported.

...

Unused; included for compatibility with the extract generic.

Details

Data frame input is stored columnar in the sampler's data object, so its x slot need not be a plain matrix. extract materializes the numeric coding regardless of the storage form: numeric and logical columns as doubles, and factor columns - ordered or not - as their integer codes, 0 to one less than the number of levels, in level order. This is the same coding a hand-built predictor matrix supplies. The matrix is for tree replay and inspection: on a fit with a factor column, predict and the sampler's new-predictor entrances take a data frame, and a sampler built from the matrix reads every column as numeric.

After predictor mutation (setPredictor and relatives) the result reflects the sampler's current predictor values, not the originally ingested data. Each mutating call collects the accepted change into the sampler's data object directly; nothing is maintained per iteration, so the returned codes always reflect current values, materialized fresh on every call.

Value

A numeric matrix with one row per training observation and one column per predictor, carrying the predictors' column names.

See Also

dbartsSampler, dbartsData, extract

Examples

df <- data.frame(
  x = runif(50L),
  g = factor(sample(c("a", "b", "c"), 50L, replace = TRUE))
)
df$y <- df$x + 0.5 * (df$g == "b") + rnorm(50L, 0, 0.1)

sampler <- dbarts(y ~ x + g, df, control = dbartsControl(
  n.chains = 1L, n.threads = 1L, updateState = FALSE))
predictors <- dbarts::extract(sampler, "predictors")
str(predictors)
stopifnot(all(predictors[, "g"] == as.integer(df$g) - 1L))

Forest Specification for Multi-Forest Models

Description

One forest of a model of several forests. Such a model fits the mean as a sum of forests, each multiplied by columns of the data: y ~ forest(x1 + x2) + forest(x1 + x2, basis = dose) is a1f1(x)+a2⋅dose⋅f2(x)a_1 f_1(x) + a_2 \cdot \mathrm{dose} \cdot f_2(x), where each ff is a forest and each aa a coefficient the sampler draws. A forest is written as a term of a bart or dbarts formula, as in that example, or as an element of the forests list of dbarts or dbartsSpec: forests = list(forest(), forest(basis = dose)). Either way vars is the predictors the forest splits on and basis is what it is multiplied by. Every setting is per forest and stated on the forest.

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

Usage

forest(
    vars = NULL, basis = NULL, sd = NULL,
    n.trees = NULL, base = NULL, power = NULL, amplitude = NULL,
    interactions = NULL, blocks = NULL,
    proposal.probs = NULL, n.perturb.cuts = NULL, treeShift = NULL)

Arguments

vars

The predictors this forest splits on. In short:

  • It is the one argument given without its name: forest(x1 + x2). Every other argument is given by name.

  • Left out, the forest splits on every predictor of the fit.

  • In a formula it is terms joined by +, as on the right of any model formula: forest(x1 + x2), forest(log(x1) + factor(g)), forest(. - z).

  • In a forests list the same terms select among the fit's predictors, forest(x1 + x3), forest(. - x2); names or positions do too, forest(c("x1", "x3")), forest(c(1, 3)).

  • A one-sided formula is its right-hand side, the tilde accepted and never required: forest(~ x1 + x2), or a formula held in a variable, f <- ~ x1 + x2 and then forest(f). A formula with a left-hand side is refused.

  • A name of a predictor is that predictor. Anything else is read where forest() is called, at that moment.

The rest of this item is the detail of each.

In a formula given to bart or dbarts it is written as the right-hand side of a model formula of the forest's own: forest(x1 + x2), forest(log(x1) + factor(g)), forest(. - z), where . is every column of data but the response and - removes a term. The fit's predictors are the terms of all of its forests, each once, and a forest splits on the columns of its own terms; a term that gives several columns, such as poly(x1, 2) or a factor under factors = "indicators", is all of them. Predictors may also be named, as forest(c("x1", "x2")): a name of a column of data is the term that name written out is, and any other name is a column of the predictors as the fit builds them, one of a factor's indicator columns for instance. A position is not taken in a formula. An offset() and an intercept term (1, 0 or - 1) belong to the fit and are written beside the forests, not inside one. A removal written beside the forests takes its term from the forest with no basis and from no forest that names predictors of its own: the forest with no basis has the terms of the formula with its forest() replaced by what is inside it and every forest with a basis left out. So y ~ forest(.) - x3 + forest(x3, basis = z) and y ~ . - x3 + forest(x3, basis = z) are one model, in which the second forest alone splits on x3; a removal that leaves the first forest no predictor is refused. Written with no first argument, that forest is every predictor the other forests name, less what is removed beside it. A removal of a term the forest with no basis does not have is passed by, as R passes it by in a plain formula: y ~ x1 + x2 + forest(x3, basis = z) - x3 is the model without the removal. update cannot take a term out of a forest(): update(f, . ~ . - x3) returns f unchanged when x3 stands inside one.

In a forests list it selects among the fit's predictors, in one of two ways. When a name in it is a predictor of the fit, it is read as terms in the same way: forest(x1 + x3), forest(. - x2), forest(. - log(x1)). There . is every column of the fit's predictors, and a term names a predictor as the fit holds it, by its term label when the fit has a formula and by its column name when it has a matrix, written as code or as a backticked name; a term that names no predictor is refused, a removed one too. Anything else is a value: it is evaluated once, where forest() is called and at that moment, and gives the predictors' names or their positions among the fit's columns: forest(c("x1", "x3")), forest(c(1, 3)), or a variable holding either. A warning that evaluation raises is kept and raised when a fit uses the value. A name or a position given twice is refused, and so are a logical, a factor and a formula: the multiplier of a forest is its basis, by name. A column with no name is selected by position or by . only, and a name that two columns share is refused. A number is a position only as the whole argument: among terms, as in forest(. - 2), it is refused, and a column named 2 is written backticked. With a factor expanded to indicator columns, removing one of them, as forest(. - g.u), leaves the forest able to separate that level through the others; remove the factor, forest(. - g), to keep it out.

A name of a predictor is that predictor, and anything else is read where forest() is called, at that moment. A forest built in a loop, by lapply(names, forest, basis = z) or by Map() therefore keeps the selection each call was given, whatever its variables hold by the time the model is fitted, and a forest saved to a file carries its selection with it. A variable that does not exist yet when forest() is called is not looked for later. One case needs care: a predictor hides a variable of yours with the same name, so in forest(x1) with a predictor x1 and a variable x1 that holds names, the predictor is meant. Where the two could meet, hand the value over: do.call(forest, list(vars = nms)).

Any forest may be restricted, a single declared forest included: given the same residual scale estimate, that fit is the fit on the named columns alone, and its other columns report no splits. The estimate is taken from every column unless sigest states it, so the two fits agree draw for draw when it does. On a single forest split.probs = dart() beside vars lays its Dirichlet over the named columns, every other column reporting probability 0, and split.probs keeps its ratios among the named columns and must give one of them a positive probability (see dbartsPriors). On every forest of a hazard fit the period column the fit appends is always allowed, named or not: vars restricts the columns the caller supplied. The restriction holds for the sampler's life; $setModel refuses a model that states another, or none.

basis

What the forest is multiplied by. In short:

  • A name of a column of data is that column: basis = dose.

  • A basis is one numeric column, or a factor, a character column or a logical column of two levels, with a coefficient for each level. A number is one column, whatever its values: basis = z for a z of 0s and 1s is one coefficient, and basis = factor(z) is the two levels.

  • I(dose + age) is one column, their sum. Several columns, dose + age, and three or more levels are refused: give each column, or each level but the first, a forest of its own.

  • Anything that is not a column of data is read where forest() is called, at that moment, with or without a tilde written in place: forest(basis = w), forest(basis = ~ w).

  • A formula held in a variable, b <- ~ w and then forest(basis = b), is read the same way, when forest() is called, and is left as you made it.

  • cbind() is refused: write its one column alone, or give each column a forest of its own.

The rest of this item is the detail of each.

What it does. With a basis of columns B1,…,BKB_1, \ldots, B_K the forest ff enters the fit as (∑kakBk(xi))f(xi)(\sum_k a_k B_k(x_i)) f(x_i), each column with a coefficient aka_k of its own, called its amplitude: K=1K = 1 for a numeric column, and the two columns of a factor's levels, K=2K = 2. A forest with no basis is multiplied by a single coefficient. A model may have several forests with no basis, which then share one prior size (see Details), or none; a model whose only forest has a basis is refused.

Writing it. A basis is the right-hand side of a model formula, without the tilde, and means what it means in lm:

  • a name is a column: basis = dose;

  • + separates columns: dose + age is two columns, which this version refuses (below);

  • arithmetic is written inside I(): I(dose + age) is one column, the sum, and I(dose / 30) is dose rescaled;

  • a function of columns is a term, as in lm: log(dose), scale(age) and poly(dose, 1);

  • a factor, a character column or a logical column of two levels gives one column for each, none left out: factor(z) for a z of 0 and 1 is the two columns whose coefficients are (b0,b1)(b_0, b_1), in the order of the levels;

  • dose:age is one column, the product;

  • there is no constant column unless 1 asks for one, and 1 + dose, a column of ones beside dose, is refused, while 0 + dose and dose - 1 are dose.

A basis is either one factor (or character or logical column) or numeric columns; the two are not mixed in one forest. The forest does not center or scale a basis, so a multiplier that should be standardized is written so: basis = scale(age). A numeric column constant over the observations in the likelihood when the sampler is created is refused, sd stated or not: a forest multiplied by a constant is a forest with no basis, written forest(x2) or, for an sd per unit of the column, with the column's size times it: forest(x2, sd = 6) for sd = 2 on a column of 3. A factor, a character or a logical column left with one level on those observations is refused likewise. A later $setForestBasis to such a column is taken.

One size. In this version a basis is one numeric column, or a factor, a character or a logical vector of two levels, counted on the rows the fit keeps once a level they leave empty is dropped. Three or more levels are refused, with the form to write, a forest for each level but the first: forest(x1, basis = arm == "b") + forest(x1, basis = arm == "c"). Several numeric columns are refused however they are written, dose + age, poly(dose, 2), splines::ns(dose, 3), a matrix, or a factor's indicator columns handed over as numbers, with the form to write, a forest for each column: forest(x1, basis = dose) + forest(x1, basis = age); indicator columns are handed over as the factor itself. 1 + dose is refused for its constant column: write basis = dose. Each is refused drawn or held, at every place a basis is given, and a basis handed over as a value is told the form in words.

Which kind it is. The class of the basis decides whether the forest multiplies levels or numbers, the same way at every place a basis is given: forest() written as code or with a value, $setForestBasis and predict's bases. A factor, ordered or not, a character vector and a logical vector are levels, with a coefficient for each: in the order of a factor's levels, in sorted order for a character vector, FALSE then TRUE for a logical vector. An integer or a double is numbers, whatever its values, and a numeric matrix is its columns. The values are never looked at to decide: a column of 0s and 1s is one column with one coefficient, and is two levels only when written factor(z) or as a logical vector. A matrix of characters or of logicals, and a factor matrix, is refused, one of a single column included, since a vector is levels and a matrix is numbers: hand over its column as a vector, cm[, 1]. An array of one dimension is its vector. A data frame and any other class are refused too. Handed over as a value, the refusal names the class; written as code, a class a model frame does not take, a data frame or a list, is refused in R's own words.

The kind is fixed when the forest is created. A forest created with no basis cannot be given one, and a forest of levels keeps the same levels, in the same order, for as long as the sampler lives, so that coefficient jj multiplies level jj's rows after any replacement. See $setForestBasis in dbartsSampler and the bases argument of predict in bartBT for what a replacement takes.

A level that no row the fit keeps has gives no column and no message, written as code or handed over as a value: factor(z, levels = 0:2) of a z with no 2, or a factor of three levels under a subset that leaves two of them, is the two columns of the levels that remain. The count is made after the rows are cut, and fewer than two levels left is refused. A row of weight zero is a row the fit keeps.

A missing value is looked for on the rows the fit keeps, after subset and the na.action, as lm looks for one in its variables. On a kept row it is refused. On a row the fit drops it is not looked at, so a basis fits the same way written as code or handed over as a value. NA is not a level: a factor made with addNA() or exclude = NULL that has a kept row at NA is refused, and the remedy is to give that level a name, as in levels(f)[is.na(levels(f))] <- "none". With no kept row at it the NA level is dropped like any other level no row has.

Some forms a model formula would take are refused, each by name and with what to write instead: * between terms (write I(dose * age) for the product, or give dose, age and I(dose * age) a forest each for all three); a term multiplied or divided by a number (write I(dose / 30)); - between terms, other than - 1; ^, /, %in% and | between terms; .; an offset(); cbind() (write its one column alone, or give each column a forest of its own); and a term that calls one of normal, fixed, student, cauchy, linear, gp, cgm, dart, chisq, chi, invchi, forest or varianceForest, since a prior is not stated on a term of a basis.

Names of the columns. They are named as coef(lm(y ~ 0 + <basis>)) names them: dose; factor(z)0, factor(z)1; and, for a basis of several columns, which is read and named before it is refused and whose refusal quotes the names, dose, age, poly(dose, 2)1, poly(dose, 2)2 and (Intercept) for the column of ones. They are the column names of data@bases[[f]] on the sampler. A forest's label, where its place in a forests list has no name, is the text of its basis, "scale(age)", or forest<i> for a forest with no basis or with one given as a value; see dbarts. Wherever a method or an extract or predict takes a forest, a string is a forest's label (failing an exact match, the label that is the same code, so "I(dose / 30)" finds I(dose/30)), a number is its position as base R reads a list element by number, and forest<i> names position i, though a per-forest margin of a fit is named by the forests' labels. A string is never a position: "2" is a forest labeled "2" or none. A string that is one forest's label and another position's name, or the same code as two labels, is refused. A refusal that names a forest names it by its label, as the fit's results do, at creation and at $setForest alike, and by position (forest 2) where it has no name and no basis text.

Rows. A basis has a value for every row of data, and is cut to the rows the fit keeps: data and subset are each evaluated once, for the fit, and the basis is given the same rows in the same order, less those the na.action drops. So with data = d[sample(nrow(d)), ] or subset = sample(n, 100) the basis has the rows the fit has. scale(), poly() and anything else a term computes across rows, I(age - mean(age)) among it, are computed on every row of data, as in lm, whatever subset keeps. A level of a factor that no kept row has gives no column. Refused are a missing value in a row the fit keeps, where lm would drop the row; a factor, a character column or a logical column with one level on the rows kept; and a numeric column that is zero on all of them.

New rows. predict builds the basis again from the new rows, as predict does for lm. Taken from the fitted rows are the center, scale and knots of scale(), poly(), ns() and bs(), and the levels of a factor. Everything else is computed again on the rows given: I(age - mean(age)) uses the mean of the new rows, and factor(dose > median(dose)) their median; see SafePrediction. Every column of data the basis names must be among the new rows, a factor's columns keep the order of the fit's levels, and a level the fit did not have is refused. A basis given as a value cannot be built again: give it at the new rows through predict's bases argument.

Where a name is found. It depends on who wrote the code.

In a call of forest() that you write, as in a forests list or for a forest built ahead of the fit, a name of a column of data is that column. Every other variable of yours that the code uses is copied when forest() is called. This is so whether or not a tilde is written in place: forest(basis = ~ I(dose + age)) is forest(basis = I(dose + age)). A forest built in a loop therefore keeps what each call was given,

    fs <- list(forest())
    for (k in c(10, 30))
      fs[[length(fs) + 1]] <- forest(x1, basis = I(dose / k))
    

is one forest multiplied by dose / 10 and one by dose / 30, at the fit and at predict, whatever k holds later, and a saved forest carries its numbers with it. A variable that does not exist when forest() is called is not looked for later, and is refused. What R or an attached package supplies, a function such as scale or a constant such as pi, is not copied: a basis that names a column of data looks it up when the model is fitted. With no data frame, as with the matrix interface and dbartsSpec, there is no column to name and every variable is yours.

One case needs care: a column of data hides a variable of yours with the same name, whether that variable holds a column, a set of names or a one-sided formula. Where the two could meet, hand the value over: do.call(forest, list(basis = w)) for a column you hold, list(basis = as.name(nm)) for a column of data by its name, list(basis = f) for a one-sided formula, and list(vars = nms) for predictors by name.

A formula made elsewhere, held in a variable or handed over as above, is read in the same way and at the same moment, when forest() is called: a name of a column of data is that column, and every other variable the formula uses is copied, as it is then, from where the formula was made. What counts is when forest() is called, not when the formula was made. In

    fs <- list(forest())
    for (k in c(10, 30)) {
      f <- ~ I(dose / k)
      fs[[length(fs) + 1]] <- forest(x1, basis = f)
    }
    

each forest has its own k, because forest() is called inside the loop. Formulas made in a loop and given to forest() only after it all see the last k: a formula holds its environment and no value, as everywhere in R. A variable changed after forest() is called changes neither the fit nor a prediction. The formula itself is not touched: it is the formula you made, in its environment, and nothing is assigned there.

A forest() term inside the formula of bart or dbarts is part of that formula and is read with it, as R reads a formula, with a tilde or without: in data and then where the formula was written, when the model is fitted and again by predict. Change a number such a term uses between the fit and the prediction and the prediction changes, with no message.

An argument that lapply(), Map() or another function of base R writes for you, as in lapply(columns, forest, vars = "x1"), is a value handed over, whatever the data's columns are called. A name or a call that such a function is handed and passes on, as in Map(forest, nms, MoreArgs = list(basis = quote(dose))), is code, as it is through do.call().

Code or a single string passed on to forest() through the ... of a function of your own is read where that function's caller wrote it: with myForest <- function(...) forest(n.trees = 50, ...), myForest(basis = "w") written in a function reads that function's w, as myForest(basis = w) does. A function that takes the basis as an argument of its own and calls forest(basis = name) hands over what the argument holds, read where it calls forest(), as is a string passed on through the ... of a call that has returned.

A value. What is handed over as an object, through do.call() or in a call built by a program, is used as it is: a numeric vector or matrix is its columns, and a factor, a character vector or a logical vector is its levels, as written as code. Its column keeps the name it has. Its forest's label is forest<i>. It has one row for every row of data and is cut to the rows the fit keeps; a value already cut to those rows is refused by name. A level that no row the fit keeps has gives no column, whether data, subset or the na.action is what empties it. Beside a data object it has one row for each row the object was handed, before its subset and na.action. A value that the rows kept leave with one level, or one numeric column that is zero on all of them, is refused as the same basis written as code is. A single number is refused. A single string, written in place or held in a variable, names a column: basis = "dose" and nm <- "dose"; forest(basis = nm) are basis = dose, at every place a basis is given and in predict's bases, which reads it from newdata; a character vector of one value per row stays a basis of its levels.

Where a name is read. A name is read from the data first and then where forest() was called, at every place a basis is given: a column of the data frame or list a formula fit is given; a column of the matrix the matrix interface is given; beside a dbartsData object, a column of the frame it keeps, or, where it keeps none (a sampler's data, keep.data = FALSE), a column it holds, its predictors and response, and a basis a sampler's data hold, named by the text it was written as: forest(basis = factor(z)) beside the data of a sampler created with that basis reads the held columns, while forest(basis = z) there is refused, naming the written form. A name of the data such an object was built from that it does not hold is refused, naming the data object built with its frame. Beside a data object built from a formula with no data, a name is read where forest() was called, as beside that formula. Beside any data, a sampler's data included, a forests list states the forests in full: a forest declaring no basis has none, and no list gives one forest. A forest that keeps a held basis keeps the scale recorded for it when the sampler was first created, wherever it stands in the list (see sd); a basis given as a new value takes its scale from that value. After creation a basis is replaced by $setForestBasis, whose formula is read at once, where it was made; see dbartsSampler.

A hazard fit. Under family = "hazard" a basis has one value per subject, cut by subset and the na.action and repeated over the subject's periods, as weights and offsets are; a vector of one value per person-period row is refused, naming the number of subjects.

A lone forest carrying a basis is refused, the coefficients being what distinguish a forest from another. For varying coefficients declare an intercept forest plus one basis forest per covariate, forests = list(forest(), forest(basis = z1), forest(basis = z2)), or use one forest with linear() leaves.

n.trees, base, power

This forest's tree count and tree-structure prior. Each one stated here governs this forest, and each one left out takes the default of the forest's kind, whatever the forest's place. A forest with a basis has 50 trees at base = 0.25, power = 3 - shallower and fewer than a prognostic forest's, the modulating surface normally being the smoother of the two. The forest with no basis has the fitting function's: the n.trees of dbarts or bart, and its power and base. The fitting function and the forest with no basis state one setting between them: bart refuses its own n.trees, power or base beside one stated here, the default's own value included, the two being the same setting, and a count written on a control beside one stated here is refused, since a control holds run settings only. Where every forest has a basis the fitting function's tree count and tree prior have no forest to belong to, and one that is stated is refused, the default's own value included: state it on a forest. The count at the fitting function's level is the model's and not the control's: a sampler's [email protected] is a copy of it, the count of the forest with no basis, or of the first forest where every forest has a basis. Its [email protected] holds the first forest's.

sd

The size of what this forest contributes, in the response's units: the units of yy for a continuous response, and of the latent index under "probit" and "logistic", where the link's own error has standard deviation 1 and π/3\pi/\sqrt{3}. One number; a name on it is ignored. What it is the size of depends on what multiplies the forest. It is a number, not a prior: a function of your own named normal, fixed, student or invchi that you have defined is called there, as in sd = normal(0.5), and where you have defined none the call is refused, those names meaning dbarts's priors only in amplitude (and in leaf.prior at the fitting function). The same holds for the other arguments that take a number.

No basis. The forest enters as a f(x)a\,f(x), and sd is the size of a f(x)a\,f(x).

A factor (a factor, a character vector or a logical vector, of two levels). The forest enters with one coefficient for each level, and sd is the size of the difference between the two: the treatment effect where the levels are control and treated.

A number ww. A column that is an ordinary covariate should be centered: basis = scale(w), or basis = I(w - c) for a reference value cc. The other forests describe the response where ww is 0, and a column that never comes near 0, an age or a year, makes them an extrapolation and the fit poor, with nothing in the chain to show it. A dose or an exposure, where 0 means none, is left as it is. The forest enters as w (a f(x))w\,(a\,f(x)), and sd is the size of a f(x)a\,f(x), the change in the response for one unit of ww; the term at an observation has size ∣w∣|w| sd. The column is used as given: it is never centered and never divided, so a stated sd is per unit of ww, and the same sd with ww in grams and in milligrams states two priors a thousand times apart.

Where the coefficient is held, by amplitude = fixed() or on a forest with no basis that states no prior, it is 1, what it multiplies is the basis, and "size" is the prior standard deviation, exactly. Where it is drawn it is a multiplier whose prior median size is 1 (on a factor, the difference between two levels' coefficients, a level's own being 0.71): the forest's size is the coefficient times sd, uncertain, and a coefficient of size 1 means the size stated.

Not stated, sd for a forest with no basis is the size the fitting function's leaf prior gives the one forest of a fit, beside whatever other forests the model has: by default a quarter of the response's range under a continuous response and, under "probit" and "logistic", the size k gives, k being drawn under chi(1.5, 2). It is sd(y)\mathrm{sd}(y), or one unit of the link's error under "probit" and "logistic", for a factor; and for a number that same size for one standard deviation of the column, sd(y)/sd(w)\mathrm{sd}(y) / \mathrm{sd}(w) per unit, held or drawn. None of these depends on how many forests the model has, save that two or more forests with no basis share the leaf prior's total (see ‘Details’). A default fit is then the same fit whatever units ww is in. sd(y)\mathrm{sd}(y) and sd(w)\mathrm{sd}(w) are taken once, over the observations in the likelihood when the sampler is created (those subset and the missing-value handling keep, with a positive weight, and not masked out), and kept: replacing the column, the weights or the mask later does not move the prior, unless the column is replaced with $setForestBasis(updateBasisScale = TRUE), and a copy, a saved and reloaded sampler and a sampler made again from its own control, model and data keep it. Where those observations hold fewer than two distinct values of the response, both are taken over every observation, under one warning (two by the route of dbartsSpec and new(), see its active). "probit" and "logistic" read no sd(y)\mathrm{sd}(y), and where fewer than two observations are in, sd(w)\mathrm{sd}(w) is taken over every one, under one warning; two or more that hold one value of ww are refused. sd(y)\mathrm{sd}(y) is of the response net of its offset; on a gaussian response that does not vary over those observations it is a quarter of the window of width one the response is then scaled by. sd(w)\mathrm{sd}(w) is kept with the data, in its basis.scale slot (see dbartsData), and $getLeafPrior(f)$basis.scale reports it. A caller who replaces a column during burn-in and wants the default of the new one replaces it with $setForestBasis(f, w.new, updateBasisScale = TRUE), which takes sd(w)\mathrm{sd}(w) again over the observations in the likelihood then (see dbartsSampler). At creation a column constant over those observations is refused. A later swap to one is taken and, with updateBasisScale = TRUE, keeps the scale it had.

A treatment belongs in a factor or a logical vector, where sd is the treatment effect. Written as a 0/1 number it is scaled as any number: sd(z)\mathrm{sd}(z) is 0.5, 0.4 and 0.22 at 50, 20 and 5 percent treated, so the default effect is 2, 2.5 and 4.6 times the one factor(z) gets; sd = sd(y) on the number states the factor's. The same holds for a coding written as a number and held, basis = z - 0.5 with amplitude = fixed().

A held coefficient cannot adapt to an sd that is too small. At the default it is sized for a slope of about one sd(y)\mathrm{sd}(y) per sd(w)\mathrm{sd}(w); where the effect may be larger, under "probit" and "logistic" above all, state sd or let the coefficient be drawn.

A default is not a stated number: $getLeafPrior(f)$sd reports the number of the response's units it comes to, a numeric forest's named by its column, and $getLeafPrior(f)$sd.stated is FALSE. A stated number is kept as written and divided by the unit once, at each creation. A control or a forests list taken to other data states the same numbers in that data's units, and the sampler made from it derives its own. It is one number, positive and finite. A vector of any other length and anything that is not a number are refused. The one forest of a model of one forest takes it as the fitting function's leaf.prior = normal(sd = ), in the same units, and stating the size at both places is refused.

A live sampler restates it through $setForest(forest, sd = ), as it does power, base and the move settings; it states it from then on, unless it is the number in force, which changes nothing, and leaves the recorded sd(w)\mathrm{sd}(w). $getLeafPrior(f)$leaf.prior returns the statement, forest(sd = ) where one was stated and forest() where none was, and forest() written back leaves its forest as it is (see dbartsSampler). A forest's kind is fixed at creation: $setForestBasis refuses to give a basis to a forest created without one, and moves no forest's prior.

print of a fit and show of a sampler give a short block of one line for each forest of a model of several: its label, what it multiplies, for a numeric column the mean and sd it has over the observations in the likelihood as they stand, and the sd the forest resolved to. For a numeric column that is its sd per sd of the column as it now stands, named by the forest's label, the size of the forest's term over one sd of the column in the response's units: for a default it is sd(y)\mathrm{sd}(y) (the link's error sd under "probit" and "logistic") wherever the column, and the observations it is read over, are those the default was taken from, and for a stated sd it is that sd times the column's sd. Where a swap left the column constant it is the sd per unit. For a factor it is the sd between the two levels. The sd per unit of a numeric column, which is what forest(sd = ) states, is in the full block and in the reader. The last line of the short block says where each forest's prior is to be had in full: summary() of a fit, which prints the full block, or $getLeafPrior() of a sampler, which returns it. The summary of a fit and the creation of a sampler with verbose = TRUE give the full block. Its header gives the unit the sds are in: sd(y)\mathrm{sd}(y), as taken above, or the link's error sd. A numeric line gives the sd per unit and per sd of the column and adds the column's range; every line adds whether the sd was stated or is the default, and whether the coefficient is held. A default whose column has another sd over the observations now in the likelihood than the one it was taken from (the column replaced, the weights or the active rows changed, or, under "gaussian", every observation read because those in the likelihood held fewer than two values of the response) says so. A fit made with keepFits = FALSE keeps its labels, tree counts and unit, and in place of each basis the few numbers the block reads (a numeric column's mean, sd, range and whether it is constant over the rows in the likelihood, a factor's levels), so it gives the same block. Two things to look for. The mean of a numeric column, in either block, and its range, in the full one: a mean far from 0 is a column that never comes near 0, an age or a year, and should be centered, unless 0 means none, as for a dose; and one wild value shows in the range, and moves the mean and sd. And the figure per sd of the column, in either block, the size of the forest's term over one sd of the column (sd times the column's sd): for a default it is sd(y)\mathrm{sd}(y) on every numeric line whose column, and the observations it is read over, are those the default was taken from, so a line that differs has had its column or its observations changed, and for a stated sd it is where a number in the wrong units shows. Nothing in the fit warns of either.

interactions, blocks

Optional interactions and blocks constraints on this forest. The arguments of the same names on dbarts are those of the forest with no basis, wherever it stands, so one stated there and on that forest is refused as one constraint given twice. A forest with a basis states its own here, and where every forest has one those arguments of the fitting function are refused. Holding the two forests to different structures is the calibrated-additivity idiom - an additive or low-order modulating forest beside a free prognostic one. A blocks partition covers the columns the forest may split on, i.e. the vars subset when one is given, and the forest's own tree count.

amplitude

The prior on this forest's coefficient: the one a forest with no basis carries, or one for each level of its basis. Left out, it is drawn each sweep under a normal prior on a forest with a basis, and a forest with none is held at 1, its size the sd it states or its leaf prior's. normal() draws it under a normal prior, on a forest with no basis too, and takes no k or sd of its own. student(df) draws it under a Student-t prior with df degrees of freedom, finite and at least 1; student() is student(1), the half-Cauchy. On every kind a drawn coefficient's prior median size is 1, under normal() and student(df), so only the tails move (on a factor it is the difference between two levels' coefficients that has median size 1, a level's own having 0.71): a coefficient ten times its median size has prior probability 0.06 under student(1), 0.005 under student(3) and about 10−1110^{-11} under the normal. That tail lets the coefficient follow a multiplier whose scale is far from what the sd states, at the cost of slower mixing along the ridge the coefficient shares with the forest's leaves. At one sd, a drawn normal's contribution has about 1.48 times the standard deviation of a fixed() forest's, since the coefficient and the trees are both random, and thinner tails than student(df)'s. With no basis sd is the size of the trees or, where none is stated, the size the fitting function's leaf prior gives, its prior median where k has a chi() prior or the sd an invchi() prior, and refused where that prior or k is flat and gives no size. Bayesian causal forests' prognostic prior is written amplitude = student(1), sd = 2 * sd(y), with sd = 1 under "probit" and sd = pi / sqrt(3) under "logistic". The draw is exact: under student(df) a normal coefficient given a variance drawn from its inverse-gamma conditional, under normal() a normal coefficient alone. A forest on a factor, a character or a logical vector has two coefficients, and under student(df) they share one scale, one variance drawn for the pair, so that their difference is itself a Student-t with the median size of the normal's. fixed() holds it at 1 until $setForest(f, amplitude = ) changes it; a held coefficient is 1, and what it multiplies is the basis, so a forest with no basis enters at 1, a forest on a numeric column at the column as given, and a forest on a factor, a character or a logical vector of two levels at 0 for the first level and 1 for the second. The forest is then held out of the first level and enters at full size for the second, so it is the second level's difference from the first. Another coding is another basis, and another size is sd, which a held coefficient makes exact: the forest's contribution then has prior standard deviation sd. A held forest with no basis that states no sd takes the leaf prior bart gives the one forest of an ordinary fit, so fixed() restates what such a forest has with no prior stated. A numeric column held enters as given, its forest at full size wherever the column is 1: basis = z - 0.5 held is the forest times -0.5 and 0.5. A held coefficient cannot adapt to an sd that is too small; where the effect may be larger, state sd or let the coefficient be drawn. fixed alone is taken as fixed(), normal alone as normal() and student alone as student(); no other value is, a response family among them. Outside the argument that takes them the constructors are dbartsPriors$fixed(), dbartsPriors$normal() and dbartsPriors$student(). The prior is stated for a forest of a model of several, at creation; a model of one forest has no coefficient to give a prior, so there fixed() restates the default and normal() and student() are refused, its size being drawn through the fitting function's leaf prior, as leaf.prior = normal(k = chi(1.5, 2)) or normal(sd = invchi(1.5, s)). $getLeafPrior(f)$amplitude reads it back, and a live sampler changes it through $setForest(f, amplitude = ), between held and drawn and between normal() and student(df) (see dbartsSampler).

proposal.probs, n.perturb.cuts, treeShift

This forest's tree moves - its proposal mixture, perturb window and level-shifting step - as dbartsControl describes each. Each one stated here governs this forest and each one left out takes the control's: $setControl changes a forest's setting only where the forest states none, and one stated here is changed by $setForest(forest, proposal.probs = ) and its siblings, not by $setControl, which refuses a mixture or window no forest would take. A stated proposal.probs is a whole mixture, filled against the package defaults as dbartsControl()'s is and not edits to the control's, so an omitted birth is 0.5. A forest frozen by its own mixture is still grown by n.grow.sweeps and replaced by warm.start, as under the control's, and treeShift acts on the constant leaves of two or more trees, as the control's does. n = and p = each abbreviate more than one argument, so write n.trees and power in full.

Details

With two forests, the second carrying a two-level factor basis, this is the shape of the Bayesian causal forest y=a μ(x)+bz τ(x)+ϵy = a\,\mu(x) + b_z\,\tau(x) + \epsilon: a prognostic forest μ\mu over every predictor, a modulating forest τ\tau over the columns vars allows, and the amplitudes (a,b0,b1)(a, b_0, b_1) joining them, read back with $getForestAmplitudes; aa is 1 unless the prognostic forest states amplitude = student(1), as Bayesian causal forests' prior does, or normal(). Gaussian, "probit" and "logistic" responses; under a latent family the combination is the index rather than the mean, on the link's own fixed scale, and "aft", "ordinal" and "nbinom" are refused at creation naming what each is missing.

What the defaults put on the combined location, since under a latent family that location IS the index and no drawn σ\sigma stands between it and the fitted probabilities. At two forests of the shipped shape - one carrying no basis - a probit model's prior puts P(p<0.01 or p>0.99)P(p < 0.01 \mathrm{~or~} p > 0.99) at 0.29, the forest with no basis alone having the shipped single-forest binary default's own 0.238. A forest's default does not depend on how many forests the model has, so each forest added widens the prior on the combined location. When every forest carries a factor the induced prior standard deviation of the index is 1.049K1.049\sqrt{K} latent units, 1.484 at K=2K = 2, which is 0.989 of the classic k=2k = 2 binary leaf-scale budget; a numeric column at its default contributes 1.484 for each standard deviation of the column the row is from 0. When one forest carries none, its prior is the fitting function's leaf prior, whose k is drawn and has no variance to enter that budget with, and the others contribute 1.049K−11.049\sqrt{K - 1}, 0.699 of the budget at K=2K = 2. Where many forests share one index, state their sd. Read the values in force off $getLeafPrior(f)'s sd entry, in the response's units.

Forests with no basis. One beside any other forests takes the fitting function's leaf prior as its one forest does, whole: its k, a chi() prior on k or normal(sd = ), held at 1 and with $getLeafPrior(f) and $getK(f) reading as one forest's, so the forest is what bart would fit, the other forests added. It leaves that prior by stating sd, held at it, or amplitude = normal() or student(), drawn. A model may hold any number, as y ~ forest(x1) + forest(x2) + forest(x3) or a forests list. Two or more of them that state no sd and no amplitude = normal() or student() share one prior total, the size the fitting function gives its one forest: its k or leaf.prior, k = 2 by default under a continuous response and k drawn under chi(1.5, 2) under "probit" and "logistic". Each of the KK forests that share is held at 1 and takes an equal part, 1/K1/K, of the total's variance whatever its number of trees, so the sum has the one forest's prior at every point and each forest 0.71 of its sd at two, 0.58 at three; a drawn k is one k for the group, and a named leaf.prior = normal(sd = ) is the total's size. The model is the one forest with its trees in blocks, a block for each forest. The forests with no basis split the fitting function's n.trees as blocks() splits a forest's trees, the first ones taking one more: 38 and 37 of 75. A forest stating n.trees keeps its own, outside the split, and its count says how finely it divides its part, not how large the part is. The fitting function's n.trees, power and base reach each such forest that states none, and are refused only where every one states its own; its interactions and blocks, a constraint on one forest, are refused and stated on the forest they constrain. A forest that states sd has that size and leaves the share, its coefficient held unless it states amplitude = normal() or student(). amplitude = fixed() on a forest that shares is taken and changes nothing; normal() and student() are refused there, since such a forest has no coefficient of its own. $getLeafPrior(f) on it gives the fitting function's leaf prior as leaf.prior, its part in force as sd (NA where k is drawn) and prior.sd.of "forest, shared", and $getK(f) the group's k. The part of a group is set once, at creation. A forest of a group leaves it by $setForest(forest, sd = ), at that size with its k pinned at 1, and the forests still sharing keep their parts and sizes; nothing puts it back but a new sampler. A total stated later, by $setLeafPrior(leaf.prior) or $setModel, reaches the forests still sharing, each at its creation part, so their sizes no longer add up to it. One forest alone leaves the leaf prior by $setForest(forest, sd = ) as by stating sd at creation, its k then pinned at 1. Printed, a line after the forests' own gives each forest's tree count and their total, and another which forests share, or which one is left of a group.

The leaf scales of a forest with a basis and of one stating sd come from the model's own calibration map rather than from the leaf prior, so a k hyperprior, a non-default k and a named leaf-prior sd are refused where every forest with no basis states its size, as forest(x1 + x2, sd = 2), in the response's units as normal(sd = ) is, and a linear or Gaussian-process leaf prior wherever a second forest is declared. In a model of several forests this sd states one forest's share of the combined location's prior, per unit of a numeric basis, where normal(sd = ) states a single forest's whole spread. Every value here is validated at fit time, and anything today's engine cannot honor is refused there by name rather than dropped.

In a bart or dbarts formula each forest() term is one forest of the model, without a separate forests = list: y ~ forest(x1 + x2) + forest(x1 + x2, basis = z). A term stands at the top of the formula's right-hand side, joined to the others by +; a forest() crossed with another term, as z:forest(x1 + x2) or z * forest(x1 + x2), is refused with the forest() to write in its place. The first forest with no basis is the model's first, wherever it is written; a forest's default tree count and tree prior go by whether it has a basis and not by where it is written. A forest with no basis may be left as plain terms, y ~ x1 + x2 + forest(x1 + x2, basis = z), which is the same model, but a formula's plain predictor terms beside a forest() with no basis are refused, as two readings of one model. Alone, y ~ forest(x1 + x2) is the single-forest fit y ~ x1 + x2, in every family that takes a formula. The other forests keep the order they are written in. forest() may also be written there as dbartsForests$forest(). A term's predictors and its basis are read as code; every other argument is evaluated where the formula was written. The same basis written in a formula's term and in a forests list is the same columns on the same rows, and so the same model.

Value

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

See Also

dbartsForests, dbarts, bart, dbartsSpec, interactions, blocks

bart's ‘Formula Terms’ section is the full term grammar - the forests of a formula, a forest's predictors, and the refusal list - of which the ‘Details’ paragraph above is the constructor-side summary.

Examples

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

sampler <- dbarts(x, y,
                  forests = list(forest(),
                                 forest(x1 + x3, basis = factor(z),
                                        n.trees = 25L, sd = 1.5)),
                  control = dbartsControl(n.chains = 1L,
                                          n.samples = 20L, n.burn = 20L),
                  n.trees = 25L)
samples <- sampler$run(20L, 20L)
amplitudes <- sampler$getForestAmplitudes()

# the induced prior sd of the combined location, read off the sampler rather
# than recomputed from the call: forest 2 is the one carrying a basis
calibration <- sampler$getLeafPrior(2L)
basis <- sampler$data@bases[[2L]]
# its coefficients' prior variance is 1/2 over 0.674^2
indexSd <- sqrt((calibration$k.scale / 0.674)^2 * 0.5 * rowSums(basis^2))

# the same model written in a formula, the first forest written out; the
# columns of a basis are named as lm() would name them
d <- data.frame(y = y, x1 = x[, 1], x2 = x[, 2], x3 = x[, 3], z = z,
                w = 50 + 10 * rnorm(n))
written <- dbarts(y ~ forest(x1 + x2 + x3) +
                    forest(x1 + x3, basis = factor(z), n.trees = 25L, sd = 1.5),
                  d, control = dbartsControl(n.chains = 1L), n.trees = 25L)
colnames(written$data@bases[[2L]])

# a standardized multiplier: predict centers and scales the new rows by the
# training rows' mean and sd of w
fit <- bart(y ~ forest(x1 + x3) +
              forest(x1 + x3, basis = scale(w), n.trees = 10L),
            d, n.trees = 10L, n.samples = 10L, n.burn = 10L,
            n.chains = 1L, n.threads = 1L, keepTrees = TRUE)
predict(fit, d[1:3, ])

# forests built in a loop: each keeps the number its own call was given
forest <- dbartsForests$forest
forests <- list(forest())
for (k in c(25, 100))
  forests[[length(forests) + 1L]] <- forest(x1, basis = I(w / k))
looped <- dbarts(y ~ x1 + x3, d, forests = forests,
                 control = dbartsControl(n.chains = 1L), n.trees = 10L)
vapply(looped$data@bases[-1L], function(basis) basis[1L, 1L], 0) * c(25, 100)

# two columns are a forest each, with a coefficient each; I() holds arithmetic
perColumn <- dbarts(y ~ forest(x1 + x3) + forest(x1, basis = z) +
                      forest(x1, basis = I(w / 50)),
                    d, control = dbartsControl(n.chains = 1L), n.trees = 10L)
lapply(perColumn$data@bases[-1L], colnames)

Guess Number of Cores

Description

Attempts to guess the number of CPU ‘cores’, both physical and logical.

Usage

guessNumCores(logical = FALSE)

Arguments

logical

A logical value. When FALSE, an estimate of the number of physical cores is returned. When TRUE, so-called “logical” cores are also included.

Details

Because of different definitions of cores used by different manufacturers, the distinction between logical and physical cores is not universally recognized. This function will attempt to use operating system definitions when available, which should usually match the CPU itself.

Value

An integer, or NA if no clear answer was obtained. The fitting functions take their default n.threads from this value, and where it is NA the default is one thread, with no message; an n.threads that is stated as NA is refused.

Author(s)

Vincent Dorie: [email protected].

Examples

## physical cores, the default used by dbartsControl(n.threads = )
guessNumCores()

## including hyperthreads
guessNumCores(logical = TRUE)

Interaction Constraints for BART

Description

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=∑GfGf = \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.

See Also

dbartsForests, dbarts, bart, blocks

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)

Make Model Matrix from Data Frame

Description

Converts a data frame with numeric and factor contents into a matrix, suitable for use with bartBT. Unlike in linear regression, factors containing more than two levels result in dummy variables being created for each level.

Usage

makeModelMatrixFromDataFrame(x, drop = TRUE)
makeind(x, all = TRUE)
makeTestModelMatrix(data, newdata)

Arguments

x

Data frame of explanatory variables. A column may be a Matrix::sparseVector, dgCMatrix, or sparseFactor (assigned into the frame; such columns do not survive data.frame(...) or I()); see ‘Value’.

drop

Logical or list controlling whether or not columns that are constants or factor levels with no instances are omitted from the result. When a list, must be of length equal to x. Elements correspond to x according to:

  • vector - single logical

  • matrix - vector of logicals, one per column

  • factor - table of factor levels to be referenced; levels with counts of 0 are to be dropped

A test frame must give each factor the training frame's levels, in their order: the helper codes a factor by position, where the fit's own predict codes by label.

all

Not currently implemented; retained for signature compatibility with BayesTree::makeind.

data

An existing dbartsData object, built with or without its frame.

newdata

Test data frame. makeTestModelMatrix refuses it, naming the column, if it carries NA in a column the fit's training data did not: a split rule learns a route for NA only where its column had missing training values.

Details

Character vectors are included as factors. If you have numeric data coded as characters, convert it using as.numeric first.

Note that if you have train and test data frames, it may be best to rbind the two together, apply makeModelMatrixFromDataFrame to the result, and then pull them back apart. Alternatively, save the drop attribute used in creating the training data and use it when creating a matrix from the test data, as in the example given below.

Use of these functions is not required when using bartBT, bart, or dbartsSampler; they exist to allow the user finer control and to assist with writing packages that separate the creation of training from test data.

Value

A matrix with columns corresponding to the elements of the data frame. If drop = TRUE or is a list, the attribute drop on the result is set to the list used when creating the matrix.

If any column of x is sparse-backed (a Matrix::sparseVector, dgCMatrix, or sparseFactor), the result is instead an object of class dbartsMixedMatrix - not a matrix (is.matrix() is FALSE) - which keeps sparse columns unexpanded rather than densifying them. Call as.matrix on it to obtain an ordinary dense matrix.

Author(s)

Vincent Dorie: [email protected].

Examples

iv <- 1:10
rv <- runif(10)
f <- factor(rep(seq.int(3), c(4L, 4L, 2L)),
            labels = c("alice", "bob", "charlie"))
df <- data.frame(iv, rv, f)

mm <- makeModelMatrixFromDataFrame(df)

## create test and train matrices with disjoint factor levels
train.df <- df[1:8,]
test.df <- df[9:10,]
train.mm <- makeModelMatrixFromDataFrame(train.df)
test.mm <- makeModelMatrixFromDataFrame(test.df, attr(train.mm, "drop"))

The Data of a dbartsData Object

Description

Read the model's variables and the number of rows of a dbartsData object.

Usage

## S3 method for class 'dbartsData'
model.frame(formula, ...)
## S3 method for class 'dbartsData'
nobs(object, ...)

Arguments

formula, object

A dbartsData object.

...

Not used.

Details

model.frame returns the model's variables over the rows in, after subset and the na.action, as model.frame of an lm fit does: the response first, factors as factors, the weights in a (weights) column and the offsets in the offset() and (offset) columns, with a terms record, so that model.response, model.weights and model.offset read them. Its "na.action" attribute is the object's. On an object that keeps its frame it is made from the frame, a poly() term with its coefficients; a sparse column (a sparseVector, sparseFactor or dgCMatrix) comes back as stored, at the rows in, and is never made dense, so the frame holds classes a frame for lm could not.

On an object with no frame (a sampler's data, keep.data = FALSE, the matrix interface, an environment) it is decoded from the block where that is exact: the response is returned in its recorded type and levels (a factor, a logical, a character vector, a Surv response where the object holds its time and status, the count matrix for a multinomial one) and named as the formula wrote it (log(price), and y where no formula did), a factor predictor as a factor over its declared levels, a matrix term such as poly(x, 2) or scale(x) as one matrix column again, named as the formula wrote it, with the column names the term gave (an unnamed matrix of two or more columns is named 1, 2, ..., where the frame lm gives leaves it unnamed), and a column the block holds sparse as a sparse vector, sparse factor or sparse matrix. The columns come in the formula's order, those the block holds sparse after the others, and a column no term of the formula names (a hazard sampler's period) after them. The block holds no more than the values, so a rejoined matrix has none of the attributes poly() or scale() give it (their class, coefficients and centers); the terms record carries them in its predvars, as lm's does. That record is the formula's, each sparse column listed as a term after the others, so that lm on the frame stops at it as it does on the frame a formula and data give; with no formula (the matrix interface), or where a hazard sampler added its period, the frame has none and model.response does not read it: its first column is the response.

nobs counts the rows in with a positive weight, as the build counted them, evaluating nothing again, as nobs of a fit and of an lm fit do; rows of weight 0 stay in the object, and a BART fit holds them in its trees.

Value

A data frame, and a number.

See Also

dbartsData


Monotone Constraints for BART

Description

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.

See Also

dbartsForests, dbartsPriors, dbarts, bart, interactions, blocks

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

## 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)

Drop Rows With A Missing Response, Keep Missing Predictors

Description

The na.action that bart, dbarts and dbartsData default to. It drops the rows whose response is missing and keeps the rows whose predictors are.

Usage

na.keepPredictors(object, ...)

Arguments

object

A model frame, as model.frame hands its na.action; the response is the column the frame's terms attribute names, and a frame with no response loses no rows.

...

Ignored, for compatibility with the other na.action functions.

Details

BART routes a missing predictor value down a learned side of each split rule (“Missingness Incorporated in Attributes”), so an incomplete row is data rather than a hole and dropping it discards information the model can use. A missing response, on the other hand, is nothing to fit. This function is that distinction: na.omit would drop both. rpart's na.rpart is the behavioral precedent.

The dropped rows are recorded exactly as na.exclude records them - a named integer vector of class "exclude" - so the training fits pad back to the caller's own row count through naresid: fitted, residuals and yhat.train.mean on the fit are as long as the data, NA where a row was dropped, while yhat.train and extract hold the kept rows only.

The base functions keep their usual meaning on these entry points: na.omit drops any row with a missing value anywhere and pads nothing, na.exclude drops the same rows and pads, na.fail refuses any missing value, and na.pass keeps every row - after which a missing response is an error, since there is nothing to fit it against.

On the matrix (x.train, y.train) interface, where there is no model frame, the na.action is applied to a frame standing for the (response, predictors) pair, so every one of these functions means on that interface what it means on the formula one.

Value

object with the missing-response rows removed, carrying an "na.action" attribute of class "exclude" naming them; or object unchanged when no response value is missing.

At Prediction

Every predict method on a fit (predict.bart and bart's four own classes) and survivalProbabilities take an na.action for newdata, defaulting to this function; NULL applies no action, which on new data gives the default's result, and getOption("na.action") is never consulted.

A missing value in newdata is routable when its column can hold missing values: it had them in training or, on a sampler, has been given them since (see dbartsSampler). Every split rule on that column then holds a side for them, and the row predicts like any other. On a column that has never held one no rule holds a side, so the value is unroutable. Only the default and na.pass look at this:

  • na.keepPredictors predicts every routable row and refuses an unroutable one, naming its columns;

  • na.pass predicts every routable row and returns NA for an unroutable one;

  • na.omit drops every row with a missing value;

  • na.exclude drops the same rows and pads them back as NA, so the result stays aligned with newdata, as the fit-time record does (predict.lm instead treats it as na.omit on new data);

  • na.fail refuses any missing value, naming its columns.

Any other function is applied to a one-column frame that is NA on the rows with a missing value, on every interface, and the rows it keeps then meet the default's refusal. The result carries newdata's row names and no "na.action" attribute. When no row survives, or newdata has none, the result has the usual draw dimensions and zero rows (NA rows under na.exclude and na.pass), and R's random number stream is left as it was.

A per-row offset, weights or bases must match newdata's rows and loses the rows na.action drops; a single value passes through unaffected. A missing value in a per-row offset or weights (an n x K category shift counts as one, on a multinomial fit) marks its row incomplete exactly as an unroutable predictor does, and every na.action above governs it the same way: the default and na.fail refuse it by name, na.pass returns NA for it, and na.omit/na.exclude drop it (na.exclude padding it back). On a binomial fit given no weights, a predictive draw's missing success or failure count in newdata's response columns marks its row the same way, unless the columns miss a count in every row and so are read as absent (see the family item of bart). A missing value in a single (length-one) offset or weights is always an error, whatever na.action is, since there is then no row for it to mark. A missing value in bases never marks its row: on a row that is incomplete for its predictors, its offset or its weights, which the na.action drops or returns NA for, it is passed by, and on any other row it is an error, whatever na.action is.

With no newdata, predict answers the training rows, which have no predictor to route, and a missing value in a per-row offset or weights marks its row incomplete in the same way: every na.action above governs it as it does at newdata, the default and na.fail refusing it, na.pass returning the row with NA draws, and na.omit and na.exclude dropping it, na.exclude padding it back. Only the rows na.action keeps are read and drawn, as at newdata, so under one seed a posterior predictive draw is that of the call at newdata with the same action, and with the rows dropped it is that of the call on the rows kept (except for a multinomial fit on a matrix of counts, whose own rows draw a count vector each where newdata draws one category), and a single missing value is always an error. survivalProbabilities answers a missing value in the offset it is given for the fit's own subjects in the same way. The sampler's own predict, predictForests and getTrees methods take no na.action, keep the default, and check no per-row offset.test for a missing value at all: an NA there reaches the engine unrouted.

See Also

na.omit, na.exclude, naresid, bart, dbartsData, survivalProbabilities

Examples

df <- data.frame(y = c(1, NA, 3, 4), x = c(1, 2, NA, 4))

# the response row goes, the predictor row stays
model.frame(y ~ x, df, na.action = na.keepPredictors)

# and the fit's training values pad back to the data's own length
fit <- bart(
  y ~ x, df,
  n.samples = 20L, n.burn = 20L, n.chains = 1L, verbose = FALSE
)
length(fitted(fit)) == nrow(df)

Partial Dependence Plots for BART

Description

Fit a model with bart, or take a fit or sampler, and average its predictions over a set of rows with one variable (pdbart) or a pair of variables (pd2bart) set to each of a grid of values, so that a plot can display that variable's effect. By default the averages are on the scale of the model's linear predictor: if yy is binary with P(Y=1∣x)=F(f(x))P(Y=1 | x) = F(f(x)), FF the standard normal cdf, then the plots are on the ff scale; type chooses another.

Usage

pdbart(
    formula, data,
    xind = NULL,
    levs = NULL, levquants = c(0.05, seq(0.1, 0.9, 0.1), 0.95),
    pl = TRUE, plquants = c(0.05, 0.95),
    type = "auto", newdata = NULL,
    n.average.rows = NULL, average.weights = NULL,
    times = NULL,
    ...)

## S3 method for class 'pdbart'
plot(
    x,
    xind = seq_along(x$fd),
    plquants = c(0.05, 0.95), cols = c('blue', 'black'),
    plot.type = c("dependence", "curves"),
    ...)

pd2bart(
    formula, data,
    xind = NULL,
    levs = NULL, levquants = c(0.05, seq(0.1, 0.9, 0.1), 0.95),
    pl = TRUE, plquants = c(0.05, 0.95),
    type = "auto", newdata = NULL,
    n.average.rows = NULL, average.weights = NULL,
    times = NULL,
    ...)

## S3 method for class 'pd2bart'
plot(
    x,
    plquants = c(0.05, 0.95), contour.color = 'white',
    justmedian = TRUE,
    plot.type = c("dependence", "curves"),
    ...)

Arguments

formula

The data to fit, as bart's own formula: a matrix, data frame or formula. Also accepted are a fitted bart model kept with keepTrees = TRUE, or a dbartsSampler, passed first. A bart model kept without its trees or sampler is refit from its stored call by the function that made it, with a warning of class dbartsFallbackWarning, and is refused if no call was kept; a sampler without keepTrees is run, generating fresh samples and changing its state, with the same warning.

data

As bart's data: the response when formula is a matrix, or the data frame in which to evaluate a formula. Not used with a fit or sampler.

xind

Integer, character vector, or the right-hand side of a formula indicating which variables are to be plotted. In a formula fit, these are variables of the data, named, and every term built from one - log(a), poly(a, 2) - moves with it; a column number is refused. Otherwise, in pdbart, corresponds to the variables (columns of the predictor matrix) for which a plot is to be constructed. In plot.pdbart, the positions in the list returned by pdbart, or the names of its variables, for which plots are to be constructed. In pd2bart, the indices of a pair of variables (columns of the predictor matrix) to plot. If NULL a default of all columns is used for pdbart and the first two columns is used for pd2bart.

levs

Gives the values of a variable at which the plot is to be constructed. Must be a list, where the iith component gives the values for the iith variable. In pdbart, it should have same length as xind. In pd2bart, it should have length 2. The values of a factor predictor are level names. See also argument levquants.

levquants

If levs is NULL, the values of each variable used in the plot are set to the quantiles indicated by levquants of its values in the training data, or in newdata when given, missing values left out; a factor predictor takes every level the fit knows. Must be a vector of numeric type.

pl

For pdbart and pd2bart, if TRUE, plot is subsequently made (by calling plot.*).

plquants

In the plots, beliefs about f(x)f(x) are indicated by plotting the posterior median and a lower and upper quantile. plquants is a double vector of length two giving the lower and upper quantiles.

type

The scale averaged on, one of predict's types for the fit (see predict.bart), each row's prediction transformed and then averaged. "auto" is the link scale, "bart" (also spelled "link"), on every family but the hurdle, where it is the mean response, "ev". A gaussian or Student-t fit also takes "ev", "ppd" and, with a variance forest, "sigma"; a probit or logistic fit "ev", the probability, and "ppd"; a negative binomial fit "ev", the mean count, and "ppd"; a hurdle fit "prob", the probability of a positive response, "bart" (also "log"), the positive part's log scale, and "ppd". On an accelerated failure time or hazard fit, "auto" is "survival", the survival probability S(t)S(t) at each of times; "event" is 1−S(t)1 - S(t) and "cumhaz" the cumulative hazard −log⁡S(t)-\log S(t), each computed per subject and averaged last, so that each is the posterior mean of the quantity asked for. A hazard fit takes these three only; an accelerated failure time fit also takes "bart", the log-time scale, and its other predict types, which have no times. A type the family does not take is refused before anything is fit when the family is named. "forest" is refused. A sampler passed in takes only "bart", and a hazard sampler is refused.

type chooses what is computed; the plot methods' plot.type chooses how it is drawn.

times

On a survival type, the times at which survival is read. The usual reason to give them is a fixed horizon, such as 5-year survival. By default, the training data's Kaplan-Meier median survival time, or, when the Kaplan-Meier curve does not reach one half, the median of the observed event times; on a hazard fit the times are read on its period grid. Refused on any other type.

plot.type

On a result with times, "dependence", the partial dependence plot, puts the varied variable on the horizontal axis with one line (plot.pd2bart: one image) per time; "curves", adjusted survival curves or direct adjustment, puts time on the axis with one median curve per grid value and needs at least three times. The dependence view draws the median and the plquants interval at each time, in cols, the times told apart by line type.

newdata

Rows to average over in place of the fit's own, coded as predict codes them, a data frame in a formula fit. The fit's offset is evaluated on them as predict evaluates it; an offset given as a plain vector cannot be, unless newdata has as many rows, and is refused. The default grid is taken from these rows.

n.average.rows

A number of the fit's rows to average over, drawn at random without replacement from those with a positive average.weights (all rows when none are given); set.seed beforehand reproduces it. Refused with newdata.

average.weights

One finite, non-negative weight per row averaged over - per row of the fit, before any it gives a weight of 0 are left out, or per row of newdata - not all zero, for a weighted average; normalized. With n.average.rows, the sampled rows keep their weights, renormalized. Not bart's weights, which go to the fit.

...

In pdbart and pd2bart, arguments of bart, under its names and with its defaults; an argument bart does not take is an error. pdbart sets keepTrees and samplerOnly itself and has no test rows, so keepTrees = FALSE, samplerOnly, test and offset.test are refused; keepSampler = FALSE drops the sampler from the result. With a fit or sampler passed in, only keepSampler is taken, and a sampler takes no newdata, n.average.rows or average.weights. BayesTree's spellings, as bartBT takes them (x.train, y.train, ntree, ndpost, nskip, keepevery, binaryOffset and the rest), are translated to bart's with a once-per-session warning until dbarts 1.1-0, when they are refused; splitprobs becomes split.probs, and proposalprobs the control's proposal.probs. A setting given under both spellings is refused. power and base are bart's own names and are passed through as they are.

In plot.pdbart, arguments are passed on to plot, except type, which is passed to the lines drawn, and xlab and ylab, which replace the method's own labels, the vertical one naming the scale. In plot.pd2bart, they are passed on to image, and a main replaces the panel titles.

x

For plot.*, object returned from pdbart or pd2bart.

cols

Vector of two colors. The first color is for the median of ff, while the second color is for the upper and lower quantiles.

contour.color

Color for contours plotted on top of the image.

justmedian

A logical where if TRUE just one plot is created for the median of f(x)f(x) draws. If FALSE, three plots are created one for the median and two additional ones for the lower and upper quantiles. In this case, mfrow is set to c(1,3).

Details

We divide the predictor vector xx into a subgroup of interest, xsx_s and the complement xc=x∖xsx_c = x \setminus x_s. A prediction f(x)f(x) can then be written as f(xs,xc)f(x_s, x_c). To estimate the effect of xsx_s on the prediction, Friedman suggests the partial dependence function

fs(xs)=1n∑i=1nf(xs,xic)f_s(x_s) = \frac{1}{n}\sum_{i=1}^n f(x_s,x_{ic})

where xicx_{ic} is the iith observation of xcx_c in the data. Note that (xs,xic)(x_s, x_{ic}) will generally not be one of the observed data points. Using BART it is straightforward to then estimate and even obtain uncertainty bounds for fs(xs)f_s(x_s). A draw of fs∗(xs)f^*_s(x_s) from the induced BART posterior on fs(xs)f_s(x_s) is obtained by simply computing fs∗(xs)f^*_s(x_s) as a byproduct of each MCMC draw f∗f^*. The median (or average) of these MCMC draws fs∗(xs)f^*_s(x_s) then yields an estimate of fs(xs)f_s(x_s), and lower and upper quantiles can be used to obtain intervals for fs(xs)f_s(x_s).

In pdbart xsx_s consists of a single variable in xx and in pd2bart it is a pair of variables.

The rows averaged over are the fit's own unless newdata is given: those it was fit to, less any it gives a weight of 0, which for a binary response masks a row out, and less any dropped for a missing response. In a formula fit they are read from the data the fit's call names, re-evaluated, which a fit kept without its call cannot do; give newdata then. Each row's offset is added to its prediction once: the fit's offset expression or offset() term evaluated on the row with the variable set, or, for an offset given as a plain vector, the row's own value. A value is therefore the (weighted) row mean of predict(fit, rows, type = type) with the variable set.

On a hurdle fit the rows averaged over leave out the rows the fit gave a weight of 0, and each part adds its own offset: the zero part's to "prob", the positive part's to "bart", and both to "ev" and "ppd". A part's offset, a plain one entering the positive part, is evaluated on the rows as predict evaluates it; one given as a plain vector cannot be evaluated on newdata of another length, and the refusal names the part.

In pd2bart, when the fit has two predictors and one offset for every row, each grid point is a single row and is predicted once; newdata then gives only the default grid, and n.average.rows and average.weights have no effect, with a warning. type = "ppd", which draws noise for each row, always averages over the rows.

A data call fits through bart at its defaults, keeping trees and sampler, and predicts each grid value from the saved trees, so pdbart(x, y, seed = s) and pdbart(bart(x, y, seed = s, keepTrees = TRUE)) agree. pdbart(bartBT(x, y, keeptrees = TRUE)) gives the model dbarts 0.9-34 fit. The first data call in a session prints a message saying so; a call from package code does not.

pdbart and pd2bart serve gaussian, Student-t, probit, logistic, negative binomial and hurdle fits. Multinomial and ordinal fits, whose prediction is a probability per category, are refused; predict on rows with the variable set gives each category's. On accelerated failure time and hazard fits they average survival, the event probability or the cumulative hazard per subject at chosen times; on a hazard fit each subject's rows are expanded to the periods up to the largest time and replayed in chunks, so memory stays bounded. The work is the number of predictions, one being one person-period row under one draw at one grid value: subjects x periods up to the largest time x draws x grid values. It grows with that count (about ten minutes at 5e9) and no call refuses on it; to shrink it, use a coarser period grid (hazard(breaks = )), fewer subjects (newdata or n.average.rows), fewer grid values (levs or levquants), or an earlier largest time (times). newdata and n.average.rows there are subject rows, and the default time stays the training data's. In a formula hazard fit the subjects are read from the data the call names, as in any formula fit, and coded with their offset at each grid value; the period is never a predictor. Each refusal comes before anything is fit, whether the family is named, resolved by family = "auto" from the response, or that of a fit or sampler passed in.

This is a computationally intensive procedure. For example, in pdbart, to compute the partial dependence plot for 5 xsx_s values, we need to compute f(xs,xc)f(x_s, x_c) for all possible (xs,xic)(x_s, x_{ic}) and there would be 5n5n of these where nn is the sample size. All of that computation would be done for each kept BART draw. For this reason thinning the draws with n.thin larger than 1 (eg. 10) makes the procedure much faster.

Value

The plot methods produce the plots and don't return anything.

pdbart and pd2bart return lists with components given below. The list returned by pdbart is assigned class pdbart and the list returned by pd2bart is assigned class pd2bart. The class carries a plot method only; it is not a fit, so predict, extract, fitted, and residuals are not defined for it (fitted and residuals fall through to stats' defaults and return NULL).

fd

A matrix whose (i,j)(i, j) value is the iith draw of fs(xs)f_s(x_s) for the jjth value of xsx_s. “fd” is for “function draws”.

For pdbart fd is actually a list whose kkth component is the matrix described above corresponding to the kkth variable chosen by argument xind. The number of columns in each matrix will equal the number of values given in the corresponding component of argument levs (or number of values in levquants).

For pd2bart, fd is a single matrix. The columns correspond to all possible pairs of values for the pair of variables indicated by xind. That is, all possible (xi,xj)(x_i, x_j) where xix_i is a value in the levs component corresponding to the first xx and xjx_j is a value in the levs components corresponding to the second one. The first xx changes first.

On a survival type, each matrix is instead an array of draws x times x values, the times margin kept at length one and named by the times.

The draws of every chain are merged, each chain's in turn. When the fit keeps its chains apart (combineChains = FALSE with more than one chain), each matrix gains a leading chain margin, chains x draws x values, as the fit's own components do.

levs

The list of levels used, each component corresponding to a variable. If argument levs was supplied it is unchanged. Otherwise, the levels in levs are as constructed using argument levquants, or a factor predictor's level names. A factor predictor is plotted with one point and interval per level, and without contours in plot.pd2bart.

xlbs

A vector of character strings which are the plotting labels used for the variables.

n.chains

The number of chains.

type

The scale averaged on, as resolved: "bart" for "link", and for "auto" the link scale, the mean response "ev" on a hurdle fit, or "survival" on an accelerated failure time or hazard fit.

family

The fit's family, which with type sets the plot labels.

times

On a survival type, the times survival was read at; NULL otherwise.

The remaining components are passed on from the fit, under bart's own names (see its ‘Value’ section) with one rename and several omissions - the fit's call is under bartcall rather than call, and not every bart component is carried over. For a continuous response the remaining components are bartcall, yhat.train, first.sigma, sigma, yhat.train.mean, sigest, y, and fit, the sampler, which keepSampler = FALSE leaves out. For a binary response only bartcall, yhat.train, y, and fit are present. For a hurdle fit, fit is a list of the two parts' samplers, zero and positive, and no draws are carried over. pd2bart follows the same rules. The function plot.bart can be applied to the object returned by pdbart or pd2bart to examine the BART run.

Author(s)

Hugh Chipman: [email protected].
Robert McCulloch: [email protected].

References

Chipman, H., George, E., and McCulloch, R. (2010) BART: Bayesian additive regression trees. The Annals of Applied Statistics, 4(1), 266–298. doi:10.1214/09-AOAS285.

Chipman, H., George, E., and McCulloch R. (2006) Bayesian Ensemble Learning. Advances in Neural Information Processing Systems 19, Scholkopf, Platt and Hoffman, Eds., MIT Press, Cambridge, MA, 265-272. https://www.rob-mcculloch.org/

Friedman, J.H. (2001) Greedy function approximation: A gradient boosting machine. The Annals of Statistics, 29, 1189–1232.

Examples

## simulate data
f <- function(x)
    return(0.5 * x[,1] + 2 * x[,2] * x[,3])

sigma <- 0.2
n     <- 100

set.seed(27)
x <- matrix(2 * runif(n * 3) - 1, ncol = 3)
colnames(x) <- c('rob', 'hugh', 'ed')

Ey <- f(x)
y  <- rnorm(n, Ey, sigma)


## pdbart: one dimensional partial dependence plot
pdb1 <- pdbart(
    x, y, xind = c(1, 2),
    levs = list(seq(-1, 1, 0.2), seq(-1, 1, 0.2)),
    pl = FALSE, n.thin = 10, n.trees = 100, n.chains = 2, n.threads = 1,
    seed = 99, verbose = FALSE
)

## pd2bart: two dimensional partial dependence plot
pdb2 <- pd2bart(
    x, y, xind = c(2, 3),
    levquants = c(0.05, 0.1, 0.25, 0.5, 0.75, 0.9, 0.95),
    pl = FALSE, n.thin = 10, n.trees = 100, n.chains = 2, n.threads = 1,
    seed = 99, verbose = FALSE)

## the plot methods draw into the current device, so set up the layout and
## put the caller's graphical parameters back afterwards. The first two plot
## regions are for pdbart, the third for pd2bart.
oldpar <- par(no.readonly = TRUE)
par(mfrow = c(1, 3))
plot(pdb1, ylim = c(-0.6, 0.6))
plot(pdb2)
par(oldpar)

## compare BART fit to linear model and truth = Ey
lmFit  <- lm(y ~ ., data.frame(x, y))
fitmat <- cbind(y, Ey, lmFit$fitted, pdb1$yhat.train.mean)
colnames(fitmat) <- c('y', 'Ey', 'lm', 'bart')
print(cor(fitmat))



## example showing the use of a pre-fitted model
df <- data.frame(y, x)
bartFit <- bart(
    y ~ rob + hugh + ed, df,
    n.thin = 10, n.trees = 100, n.chains = 2, n.threads = 1, seed = 99,
    keepTrees = TRUE, verbose = FALSE)
pdb3 <- pdbart(bartFit, xind = rob + ed, pl = FALSE)

## averaged over a subgroup's rows, with the grid from them
pdb4 <- pdbart(bartFit, xind = "rob", newdata = df[df$hugh > 0, ], pl = FALSE)



## survival at three times on a discrete-time hazard fit, drawn both ways
if (requireNamespace("survival", quietly = TRUE)) {
  time <- rexp(n, exp(x[, "rob"]))
  status <- rbinom(n, 1, 0.8)
  hazardFit <- bart(
      x, survival::Surv(time, status),
      family = hazard(breaks = c(0, quantile(time, seq(0.1, 1, 0.1)))),
      n.chains = 2, n.threads = 1, keepTrees = TRUE, verbose = FALSE)
  pdb5 <- pdbart(hazardFit, xind = "rob",
                 times = quantile(time, c(0.25, 0.5, 0.75)), pl = FALSE)
  plot(pdb5)
  plot(pdb5, plot.type = "curves")
}

Plot a Single Tree From a Fitted BART Model

Description

Minimalist visualization of the branching and leaf contents of one tree in a fitted bartBT/bart model, or in a dbartsSampler. A fit-level convenience wrapper around the sampler's plotTree method, so the trees can be plotted without reaching into the sampler stored on the fit.

bart's four own-class fits ("bartMultinomial", "bartOrdinal", "bartNegbin", "bartHurdle") refuse by name instead: their trees live on the sampler(s) those fits carry (object$fit for the first three, object$zero$fit/ object$positive$fit for the hurdle), which plotTree can be called on directly.

Usage

plotTree(object, ...)

## S3 method for class 'bart'
plotTree(
    object, treeNum = 1L, chainNum, sampleNum, forest = NULL, ...)

## S3 method for class 'dbartsSampler'
plotTree(object, ...)

## S3 method for class 'bartMultinomial'
plotTree(object, ...)

## S3 method for class 'bartOrdinal'
plotTree(object, ...)

## S3 method for class 'bartNegbin'
plotTree(object, ...)

## S3 method for class 'bartHurdle'
plotTree(object, ...)

Arguments

object

A fitted model of class bart (from bartBT or bart), or a dbartsSampler. Fits must have been made with the trees kept (keeptrees/keepTrees equal to TRUE).

treeNum

An integer, the index of the tree to plot.

chainNum

An integer, the index of the chain to plot from. For a bart fit with a single chain it may be omitted.

sampleNum

An integer, the index of the saved sample to plot from. When omitted, the last sample is used (or the current working trees when the trees were not kept as samples).

forest

A number, the forest to plot from (1-indexed, as dbartsSampler's getTrees accepts), or a string, its label (see forest). For a sampler with a single forest it may be omitted; a sampler with more than one (a Bayesian causal forest, or a multinomial fit's own sampler) requires it.

...

Additional arguments, including treePlotPars (a named numeric vector controlling nodeHeight, nodeWidth, and nodeGap) and further arguments passed on to plot. sample/chain are refused by name, on every method including dbartsSampler's: they partial-match this method's own sampleNum/chainNum and would otherwise draw a different tree than intended.

Details

The rendering handles constant, linear, and Gaussian-process leaves. For a multiple-chain fit, chainNum selects the chain. Equivalent to calling the plotTree method on the underlying sampler, i.e. object$fit$plotTree(...) for a bart fit.

Value

Invisibly returns NULL; called for the side effect of drawing.

See Also

bart, dbartsSampler

Examples

f <- function(x)
    10 * sin(pi * x[,1] * x[,2]) + 20 * (x[,3] - 0.5)^2 +
        10 * x[,4] + 5 * x[,5]

set.seed(99)
sigma <- 1.0
n     <- 100

x  <- matrix(runif(n * 10), n, 10)
Ey <- f(x)
y  <- rnorm(n, Ey, sigma)

fit <- bart(x, y, n.samples = 40L, n.burn = 10L, n.trees = 25L,
             n.chains = 1L, keepTrees = TRUE, verbose = FALSE)

plotTree(fit, treeNum = 1L, sampleNum = 40L)

Bayesian Additive Regression Trees with Random Effects

Description

Deprecated. rbart_vi and its methods run the implementation from dbarts 0.9-x, kept for one release, and are removed in dbarts 1.1-0. A warning (class dbartsDeprecatedWarning) says so the first time rbart_vi is called in a session. Grouped random effects live in the stan4bart package (stan4bart::stan4bart), whose prior on the group spread differs from the one used here, so a refit there moves the results rather than reproducing them.

Fits a varying intercept/random effect BART model. A fallback this function makes (running single-threaded, disabling verbose output for several threads, recycling group.by, drawing effects for unseen levels, a failed rejection sample) warns with class dbartsFallbackWarning, and the deprecated value argument and type = "post-mean" of predict warn with class dbartsDeprecatedWarning.

Usage

rbart_vi(
    formula, data, test, subset, weights, offset, offset.test = offset,
    group.by, group.by.test, prior = cauchy,
    sigest = NA_real_, sigdf = 3.0, sigquant = 0.90,
    k = 2.0,
    power = 2.0, base = 0.95,
    n.trees = 75L,
    n.samples = 1500L, n.burn = 1500L,
    n.chains = 4L, n.threads = min(dbarts::guessNumCores(), n.chains),
    combineChains = FALSE,
    n.cuts = 100L, useQuantiles = FALSE,
    n.thin = 5L, keepTrainingFits = TRUE,
    printEvery = 100L, printCutoffs = 0L,
    verbose = TRUE,
    keepTrees = TRUE, keepCall = TRUE,
    seed = NA_integer_,
    keepSampler = keepTrees,
    keepTestFits = TRUE,
    callback = NULL,
    ...)

## S3 method for class 'rbart'
plot(
    x, plquants = c(0.05, 0.95), cols = c('blue', 'black'), ...)

## S3 method for class 'rbart'
fitted(
    object,
    type = c("ev", "ppd", "bart", "ranef"),
    sample = c("train", "test"),
    ...)

## S3 method for class 'rbart'
extract(
    object,
    type = c("ev", "ppd", "bart", "ranef", "trees"),
    sample = c("train", "test"),
    combineChains = TRUE,
    ...)

## S3 method for class 'rbart'
predict(
    object, newdata, group.by, offset,
    type = c("ev", "ppd", "bart", "ranef"),
    combineChains = TRUE,
    ...)

## S3 method for class 'rbart'
residuals(object, ...)

## S3 method for class 'rbart'
print(x, ...)

## S3 method for class 'rbart'
sigma(object, ...)

## S3 method for class 'rbart'
nobs(object, ...)

Arguments

group.by

Grouping factor. Can be an integer vector/factor, or a reference to such in data. In predict, a character or numeric vector names its groups by value, as a factor of it does. With a data object in place of a formula and data, group.by is looked up where the call was written; with a formula and data it is looked up in data first (as lm's weights).

group.by.test

Grouping factor for test data, of the same type as group.by. Can be missing.

prior

A function or symbolic reference to built-in priors. A built-in is named by symbol or string (cauchy, "gamma"); any other name refers to the caller's function, and an unknown string is refused. Determines the prior over the standard deviation of the random effects. Supplied functions take two arguments, x - the standard deviation, and rel.scale - the standard deviation of the response variable before random effects are fit. Built in priors are cauchy with a scale of 2.5 times the relative scale and gamma with a shape of 2.5 and scale of 2.5 times the relative scale.

n.thin

The number of tree jumps taken for every stored sample, but also the number of samples from the posterior of the standard deviation of the random effects before one is kept.

keepTestFits

Logical where, if false, test fits are obtained while running but not returned. Useful with callback.

callback

Optional function of trainFits, testFits, ranef, sigma, and tau. Called after every post-burn-in iteration and the results of which are collected and stored in the final object.

formula, data, test, subset, weights, offset, offset.test, sigest, sigdf, sigquant, k, power, base, n.trees, n.samples, n.burn, n.chains, n.threads, combineChains, n.cuts, useQuantiles, keepTrainingFits, printEvery, printCutoffs, verbose, keepTrees, keepCall, seed, keepSampler, ...

Same as in bart, except sigdf and sigquant, which bart no longer takes and which are as in bartBT. k is applied only when supplied; otherwise the defaults are those of dbarts. A sigest that is not a number is estimated once for each chain and once more beforehand, announced under verbose the one time, on one thread. A supplied seed is used for this call only: the caller's random number stream is left as it was found. Unlike bart, the thread count changes the draws: with more than one thread the chains run in worker processes, each seeded from seed or, without one, from R's random number stream, so set.seed reproduces a run at the same n.threads, while one thread runs the chains in turn on R's stream. weights are precisions, so a row's residual variance is σ2/wi\sigma^2 / w_i, and a binary response takes only weights of 0 and 1; other weights are refused. A dbartsData object carrying bases, the data of a sampler of several forests, fits one forest here, the bases left out, as dbarts does given no forests.

object

A fitted rbart model.

newdata

Same as test, but named to match predict generic.

type

One of "ev", "ppd", "bart", "ranef", or "trees" for the posterior of the expected value, posterior predictive distribution, non-parametric/BART component, random effect, or saved trees respectively. The expected value is the sum of the BART component and the random effects, while the posterior predictive distribution is a response sampled with that mean. To synergize with predict.glm, "response" can be used as a synonym for "ev" and "link" can be used as a synonym for "bart". For additional details on tree extraction, see the corresponding subsection in bartBT.

sample

One of "train" or "test", referring to the training or tests samples respectively.

x, plquants, cols

Same as in plot.bart.

Details

A fit in which every predictor holds one value on the rows kept, with no forest having a basis, is refused, naming the columns, as by bart.

Fits a BART model with additive random intercepts, one for each factor level of group.by. For continuous responses:

  • yi∼N(f(xi)+αg[i],σ2)y_i \sim N(f(x_i) + \alpha_{g[i]}, \sigma^2)

  • αj∼N(0,τ2)\alpha_j \sim N(0, \tau^2).

For binary outcomes the response model is changed to P(Yi=1)=Φ(f(xi)+αg[i])P(Y_i = 1) = \Phi(f(x_i) + \alpha_{g[i]}). ii indexes observations, g[i]g[i] is the group index of observation ii, f(x)f(x) and σy\sigma_y come from a BART model, and αj\alpha_j are the independent and identically distributed random intercepts. Draws from the posterior of tautau are made using a slice sampler, with a width dynamically determined by assessing the curvature of the posterior distribution at its mode.

Out Of Sample Groups

Predicting random effects for groups not in the training sample is supported by sampling from their posterior predictive distribution, that is a draw is taken from p(α∣y)=∫p(α∣τ)p(τ∣y)dαp(\alpha \mid y) = \int p(\alpha \mid \tau)p(\tau \mid y)d\alpha. For out-of-sample groups in the test data, these random effect draws can be kept with the saved object. For those supplied to predict, they cannot and may change for subsequent calls.

Data

Data are handled as in dbarts 0.9-x and not as bart does: a factor predictor is expanded to indicator columns, rows with missing values are dropped (na.omit), and the response must be continuous or binary.

Generics

See the generics section of bartBT. sigma(fit) is the posterior mean of the residual standard deviation, mean(fit$sigma), and 1 on a binary response, which has none; nobs(fit) counts the rows in the likelihood, those of positive weight. fitted, residuals, extract, sigma and nobs warn of an argument name they do not take, and then disregard it.

Value

An object of class rbart. Contains all of the same elements of an object of class bart, as well as the elements:

ranef

Samples from the posterior of the random effects. A array/matrix of posterior samples. The (k,l,j)(k, l, j) value is the llth draw of the posterior of the random effect for group jj (i.e. αj∗\alpha^*_j) corresponding to chain kk. When n.chains is one or combineChains is TRUE, the result is a collapsed down to a matrix.

ranef.mean

Posterior mean of random effects, derived by taking mean across group index of samples.

tau

Matrix of posterior samples of tau, the standard deviation of the random effects. Dimensions are equal to the number of chains times the numbers of samples unless n.chains is one or combineChains is TRUE.

first.tau

Burn-in draws of tau.

callback

Optional results of callback function.

Author(s)

Vincent Dorie: [email protected]

See Also

bart, dbarts

Examples

f <- function(x) {
    10 * sin(pi * x[,1] * x[,2]) + 20 * (x[,3] - 0.5)^2 +
        10 * x[,4] + 5 * x[,5]
}

set.seed(99)
sigma <- 1.0
n     <- 100

x  <- matrix(runif(n * 10), n, 10)
Ey <- f(x)
y  <- rnorm(n, Ey, sigma)

n.g <- 10
g <- sample(n.g, length(y), replace = TRUE)
sigma.b <- 1.5
b <- rnorm(n.g, 0, sigma.b)

y <- y + b[g]

df <- as.data.frame(x)
colnames(df) <- paste0("x_", seq_len(ncol(x)))
df$y <- y
df$g <- g

## low numbers to reduce run time
rbartFit <- suppressWarnings(
    rbart_vi(y ~ . - g, df, group.by = g,
             n.samples = 40L, n.burn = 10L, n.thin = 2L,
             n.chains = 1L,
             n.trees = 25L, n.threads = 1L))

R-hat of One Quantity's Draws

Description

The rank-normalized split R-hat (Vehtari, Gelman, Simpson, Carpenter and Buerkner, 2021) of the draws of one quantity from several chains: the larger of the bulk and the folded (tail) values. It is the statistic summary.bart reports, and from four iterations on it returns the value posterior::rhat does for the inputs that function takes (see Details for the inputs where the two differ).

Usage

rhat(x)

Arguments

x

A numeric (or logical) matrix of the draws of one quantity, with a row for each iteration and a column for each chain. A vector is taken as one chain.

Details

Each chain is cut in two, the middle draw of an odd length dropped, and the draws are rank-normalized as one pool; the bulk value compares the half-chains' means and variances, and the tail value does the same on the draws folded about their median. R-hat compares each chain's spread with the pooled spread, so a value above 1 says the chains disagree.

The result is NA, as for posterior::rhat, when x has an NA, NaN or constant draws, or has a single iteration. A non-finite draw other than NA and NaN is ranked, as posterior ranks it. An argument that is not numeric or logical, is an array of more than two dimensions, or has no iteration or no chain is an error. posterior refuses a data frame and a character vector too, but takes a complex vector (and returns an infinite value with a warning for a matrix with no chain); dbarts refuses those, as they are not draws.

With two or three iterations and several chains, posterior (1.7.0) loses the dimension of its one-draw half-chains and treats each iteration as a chain; dbarts returns NA, as a half-chain of one draw has no variance. At four or more iterations the two agree to rounding.

R-hat should be read on the estimand reported: at the defaults BART's chains routinely disagree on sigma, k and single predictions, while averaged estimands, such as a subgroup's mean prediction or a contrast between subgroups, mix far better. See summary.bart.

Value

A single number, NA_real_ where the draws carry no information.

Calling rhat

Call it as dbarts::rhat. Other packages export a function named rhat: posterior and bayesplot (and brms re-exports posterior's), and rstan exports Rhat. Whichever is attached last masks the others, and bayesplot's takes a fitted Stan model, not a matrix. The stan4bart package attaches dbarts, so it brings this name in.

References

Vehtari, A., Gelman, A., Simpson, D., Carpenter, B. and Buerkner, P.-C. (2021) Rank-normalization, folding, and localization: an improved R^\hat{R} for assessing convergence of MCMC. Bayesian Analysis 16(2), 667-718.

See Also

summary.bart, extract

Examples

set.seed(1)
draws <- matrix(rnorm(400), 100L, 4L)
dbarts::rhat(draws)

# four chains that disagree
dbarts::rhat(draws + rep(0:3, each = 100L))

Draw From The BART Prior

Description

Draws repeatedly from the prior a dbartsSampler runs under - the hyperparameters that carry a prior, tree structure, leaf values, and optionally the observation model - and evaluates the resulting forest at x.test. Useful for calibrating priors before ever fitting to data, e.g. inspecting the implied prior on a treatment effect f(x1)−f(x0)f(x_1) - f(x_0). The sampler passed in is never modified.

Usage

samplePriorPredictive(
  sampler, x.test = NULL, n.samples = 200L,
  type = c("ev", "ppd"), offset.test = NULL,
  n.threads = sampler$control@n.threads
)

Arguments

sampler

A dbartsSampler. Left unmodified: the function operates on a freshly constructed private sampler, built from this sampler's control, model, and data, with its own engine state.

x.test

A matrix of predictors at which to evaluate the drawn forests, in the form accepted by predict. NULL (the default) evaluates at the sampler's own training predictors.

n.samples

A positive integer giving the number of independent prior draws to return.

type

"ev" draws E[y∣x]E[y \mid x] under the prior, matching what extract and predict call "ev": the forest sum on the response scale for a gaussian or Student-t sampler; the link-transformed probability for a probit or logistic one; the mean count exp⁡(η)\exp(\eta) for a negative-binomial one, the center and offset.test inside η\eta; the KK category probabilities for an ordinal or multinomial one. "ppd" adds the observation model on top: gaussian noise with sigma freshly drawn from its own prior for each sample; for Student-t, sigma times tνt_\nu noise at the family's df, or at the sample's df drawn from its prior when the df is estimated; a bernoulli draw from the "ev" probabilities for a binary sampler, a binomial one included, one trial per row as predict draws at a new row given no weights; a negative-binomial count at the sample's shape, fixed or drawn; an integer category code 1,…,K1, \ldots, K for an ordinal sampler, and for a multinomial one whose response was written as a factor; a count vector of one trial for a multinomial sampler whose response was written as a count matrix, whatever the rows' trials, as predict draws at a new row. A $setResponse, which on a multinomial sampler takes a count matrix, makes the response one written as a count matrix. On an aft (survival) sampler the draw is on the log-time scale (the model fits log⁡T\log T), and on a heteroscedastic one the noise is drawn at a prior draw of that observation's own s(x)s(x) rather than at a scalar sigma. Unlike extract's posterior "ppd", prior predictive draws are weight-blind: they use unit weights rather than a weighted precision (σ/w\sigma / \sqrt{w} for gaussian), and a row of weight 0 is drawn as every other row is, where the posterior draw at it is NA; each draw is one observation, as a training row's posterior draw is under every reading. Supply any weighted precision downstream.

offset.test

A numeric offset added to the forest sum, as in predict; recycled to the number of rows of x.test if of length 1, or NULL (the default) for none. On a multinomial sampler it is predict's matrix of category offsets, one row per row of x.test and one column per category; a sampler carrying a category offset requires it (an all-zero matrix for the offset-free surface).

n.threads

Forwarded to the underlying predict calls.

Details

Each of the n.samples draws independently redraws the hyperparameters, every tree's structure (sampleTreesFromPrior) and leaf values (sampleLeafParametersFromPrior) from scratch, then evaluates the resulting forest at x.test - there is no MCMC dependence between rows of the result, unlike a posterior sample from run.

The hyperparameters drawn are those the sampler draws: kk from its chi() hyperprior (which normal(sd = invchi()) is), a Student-t df from its prior on the family's grid when the df is estimated, a negative-binomial shape from its prior on its grid when the shape is estimated, and an ordinal sampler's cutpoints (the first at 0, each gap log-normal), one set per sample shared by every row. A fixed kk, df or shape is used as it stands. An improper leaf prior, invchi() with scale 0 or chi() with an infinite scale, has no prior draws and is refused.

Under split.probs = dart() the prior the sampler runs is not the stated Dirichlet on the split probabilities alone: the sampler never holds a tree with an empty leaf, so its prior on the split probabilities and the trees together is the stated one restricted to forests in which no tree has an empty leaf. Each sample draws the concentration and the split probabilities from the stated prior and every tree from the tree prior given them, and redraws the whole, split probabilities included, while any tree has an empty leaf, with no limit on the attempts, so every sample is an exact draw of that prior. How often a whole draw is kept falls with the number of trees and rises with the number of rows: about one in a hundred at 60 rows, 8 columns and 200 trees, where 1,000 samples take a few seconds. With few rows and many trees the draw can take long: at 8 columns, 1,000 samples take about a minute at 60 rows and 500 trees, and one and a half to two and a half hours at 60 rows and 1,000 trees or at 30 rows and 500 trees. Once the attempts made project a call longer than about a minute, a warning, printed when issued, gives the share of draws kept so far and the projected time. The draw can be interrupted as a run is; the sampler passed in is left as it was.

For type = "ppd" on a gaussian sampler, sigma is drawn once per sample from the model's residual-variance prior: a scaled-inverse-chi-squared calibrated so that P(σ<sigest)=quantP(\sigma < \code{sigest}) = \code{quant} when the prior is chisq (see dbartsPriors), or the sampler's fixed value when the prior is fixed.

A heteroscedastic sampler (dbarts's variance) has no single sigma to draw, so the noise is its own surface: each sample additionally redraws the variance forest from its prior (sampleVarianceForestFromPrior) and adds s(x)ϵs(x)\epsilon at the rows being predicted, s2(x)s^2(x) read there through getVariance. The mean draws, and every type = "ev" draw, are unaffected.

Prior draws are chain-free: the private sampler runs one chain whatever sampler's n.chains, since there is no mixing or convergence concept for draws that are already independent by construction.

Seeding follows from the private sampler being constructed fresh on every call. When the control's seed is NULL (the default), the engine RNG is seeded from R's random number stream at construction, so successive calls return independent draws, and a set.seed beforehand makes the whole draw - forests and observation layer alike - reproducible. When the control fixes seed, the engine stream is pinned: every call replays the identical sequence of hyperparameters and forests, with only the R-side "ppd" observation layer (sigma, the noise, counts and categories) still governed by set.seed.

To compare the prior at two or more covariate settings with paired forests - as for a treatment effect - stack the settings as rows of a single x.test and difference the corresponding columns of the result; see ‘Examples’. Two separate calls draw independent sets of forests (unless seed is fixed, as above) and so cannot be differenced meaningfully.

Value

A matrix with n.samples rows and one column per row of x.test (or of the training predictors, when x.test is NULL) - the combined-draws convention extract uses for a single chain, with no chain dimension. For an ordinal or multinomial sampler "ev" is an n.samples by rows by KK array of category probabilities, as is "ppd" on a multinomial sampler whose response was written as a count matrix, holding the counts; category codes are integers.

See Also

dbartsSampler for sampleTreesFromPrior, sampleLeafParametersFromPrior, and predict, the building blocks this function composes. dbarts for creating a sampler. extract for the same "ev"/"ppd" vocabulary applied to posterior draws.

Examples

n <- 100
x <- matrix(runif(n * 2), n, 2)
y <- x[, 1] - x[, 2] + rnorm(n, 0, 0.2)

sampler <- dbarts(y ~ x, control = dbartsControl(n.chains = 1L, n.threads = 1L))

## prior-predictive draws of a treatment effect f(x1) - f(x0), holding the
## other covariate fixed at its midpoint: calibrates the prior before ever
## touching y. Stacking both settings into one x.test pairs the forests, so
## the two columns of the result come from the same drawn function.
xContrast <- rbind(c(0, 0.5), c(1, 0.5))
colnames(xContrast) <- colnames(sampler$data@x)

f <- samplePriorPredictive(sampler, x.test = xContrast, n.samples = 500L)
effect <- f[, 2] - f[, 1]
hist(effect, main = "prior on the treatment effect", xlab = "f(x1) - f(x0)")

Sparse Unordered Factors

Description

Represents an unordered factor sparsely: entries at the given positions carry the supplied levels, while every other position implicitly carries a designated reference level. Analogous to Matrix::sparseVector, whose implicit entry is zero.

Accepted as a predictor by dbartsData through either interface: a data frame passed as x.train may mix dense numeric/factor columns with sparse ordinal columns (Matrix::sparseVector or dgCMatrix) and sparseFactor columns in any combination, and a formula's data accepts one too, named like any other column (including through .): a bare S4 column cannot survive model.frame, so dbartsData lifts it out of data first and re-attaches it, row-subset under subset and na.action, to the assembled predictor matrix afterward. A sparseFactor column enters as one categorical predictor and bins bitwise-identically to a dense factor of the same values.

A test frame (test, or newdata to predict) is read the way a dense-factor frame is: the model's terms are replayed on its dense columns (so a transformed term such as log(z) works and extra columns, the response included, are dropped) and its sparseFactor columns are used by name. The same holds for a test set (test/x.test): a sparseFactor test column is recoded over the training level table and stays resident - through creation and setTestPredictor - rather than densifying at ingestion. predict and getTrees(newdata = ) code it the same way and then route its rows through the trees off that storage, materializing no dense matrix of their own.

A sparseFactor (or any sparse-stored) column changes which routine makes the default starting sigma, not what it estimates: the residual standard deviation of the linear regression on the design, the factor entering as an indicator column for each level, by an exact sparse routine in place of lm's. The two agree to rounding except on nearly dependent columns; sigest = "dense" (dbarts, bart) asks for lm's.

Usage

sparseFactor(x, levels, reference, i, length)

Arguments

x

The stored entries: a factor, a character vector, or integer level codes (which require an explicit levels). A missing value is stored as an explicit entry, never as the reference level, and a vector whose every value is missing needs no levels, as for a factor. When i is omitted, x is the complete (dense) vector and its non-reference entries become the stored ones.

levels

Character vector of factor levels. Defaults to levels(x) for a factor and sort(unique(x)) for a character vector, the factor convention.

reference

The level every unstored position carries. Must be an element of levels (NA when there are none); defaults to levels[1], the baseline-contrast convention. Storage holds the non-reference entries and every missing value, which is always stored, so choosing the most common non-missing level as the reference maximizes the memory win; codes and every draw are identical under any choice of reference, so this is a storage tuning knob, not a modeling one.

i

Optional integer vector of 1-based positions at which the entries of x sit, as in Matrix::sparseVector. When supplied, x and i must have equal length and length is required. Positions need not be sorted; duplicates are an error.

length

Total number of observations. Required alongside i; defaults to length(x) for dense input.

Details

The constructor canonicalizes its input: entries are re-ordered by ascending position, entries whose level equals reference are dropped (they are the implicit value), and positions are stored 0-based in the i slot with 1-based level codes in the values slot. The remaining slots are levels, reference, and length.

show prints the length, the number of stored entries, the level table, and the reference level. length returns the observation count, which lets a sparseFactor be a data.frame column.

A sparseFactor answers the operations a data frame reaches a factor column with as a factor does. x[i] subsets by position (positive, negative, zero, logical and repeated indices) and returns a sparseFactor over the same levels, mapping the stored positions without densifying; drop = TRUE drops the levels no selected row takes, as does droplevels, so a vector of missing values only is left with none. An NA or out-of-range index selects a missing value. x[i] <- value and the double-bracket assignment take labels (as a character vector, factor or sparseFactor) and, as for a factor, store a missing value for NA and for a label that is not a level (with a warning), drop an NA index for a value of length one, and extend the vector past its end with missing values; length<- truncates or pads with missing values; levels(x) <- value renames the levels, the reference with them, merging repeated names as it does for a factor and dropping a level named NA, whose entries become missing. c(x, ...) combines with factors and sparseFactors over the union of their levels. as.character, as.vector and format give the level labels, as.integer the level codes, and levels (read from the class's slot), is.na, anyNA, xtfrm (so order and sort), unique, duplicated, rep, droplevels, summary, == and != (which refuse two factors with different level sets, as for factors) behave as for a factor, and str prints a factor's line. factor, as.factor and table read it through those methods, over the levels present. Together these let a data frame holding one be subset by row, assigned into, printed and str-ed. rbind of such frames returns the column as an ordinary factor; it needs R 4.6.0 or later, since earlier versions of base R's match refuse an S4 object. On any version, lengthening the first frame by row indexing, as in d[rep(seq_len(nrow(d)), 2), ], and assigning the other frames' rows into it binds them and keeps the column a sparseFactor, provided their labels are levels of the first frame's column.

A missing value is an explicit stored entry, and every method answers it as it does for a factor; show counts the missing entries, and a fit reads them as a missing predictor, bitwise as it reads the same rows of a dense factor. The one shape without a level is a vector whose every row is missing; its reference is NA. A level named NA, as addNA makes, is not supported: a missing value is not a level. A character index has no names to match and is refused. Not supported: complete.cases and na.fail on a data frame holding one, which fail in base R for any S4 column, and na.omit on such a frame, which keeps its missing rows (use d[!is.na(d$f), ]); complete.cases of a bare sparseFactor errors as well, while na.omit of one drops the missing entries as it does for a factor; a fit's na.action does handle them. Also not supported: c(f, x) with a factor f first, which c.factor answers with a list (put the sparseFactor first), rank, relevel, as.numeric (as.integer gives the level codes), rep_len and rep.int (rep works), and the exclude argument of droplevels, which is ignored; droplevels on a data frame leaves a sparseFactor column untouched, as base R touches only factor columns, so call it on the column. table drops the declared levels no row takes, where it keeps them for a factor; use levels(x) for the declared table. A data frame holding one cannot grow by assignment past its last row, since base R strips the class before the method is reached.

A Matrix::sparseVector or dgCMatrix column subsets in a data frame through Matrix's own method, but printing such a frame shows a placeholder for the column and warns of a corrupt data frame; that formatting belongs to Matrix. Use as.numeric on the column to display it.

Value

An object of S4 class sparseFactor.

Author(s)

Vincent Dorie: [email protected].

See Also

dbartsData

Examples

f <- factor(c("a", "b", "a", "c", "a", "b"))
sf <- sparseFactor(f, reference = "a")
sf

## equivalently, supply only the non-reference entries and their positions
sparseFactor(c("b", "c", "b"), levels = c("a", "b", "c"), reference = "a",
             i = c(2L, 4L, 6L), length = 6L)

Convergence Diagnostics for BART Fits

Description

Reports a per-variable posterior summary of the scalar parameters (sigma and the leaf prior's k or leaf.prior.sd) of a bartBT/bart fit, along with split-R^\hat{R} and bulk/tail effective sample size, computed by dbarts itself (no posterior dependency). A heteroscedastic fit (dbarts's variance) has no scalar residual scale and reports mean.s in place of sigma; see vars.

bart's four own-class fits ("bartMultinomial", "bartOrdinal", "bartNegbin", "bartHurdle"; see bart) summarize through this same method, each exposing the scalar posterior parameters that family carries rather than its per-observation channels - never yhat.train itself. A chain- separated (rather than pooled) view of these same draws is extract, whose "sigma", "k", "leaf.prior.sd", and other scalar types return a vector or, with combineChains = FALSE, a chains-by-samples matrix. The table holds the parameters the fit sampled; one line under it names each requested parameter the fit held fixed, with its value, in the manner of summary.glm's dispersion line. The summary of a fit of several forests adds the full block of what each forest resolved to, after the table (see the sd argument of forest), and the line under the table then leaves out each forest's leaf.prior.sd, which the block gives. Under the block, each forest with a basis has a line for the effect of one unit of its basis (for a factor, of its second level against its first): its average over the training rows in the likelihood, and its sd across rows, the standard deviation of the effect across those rows, each with its posterior median and the 5% to 95% interval stats uses. Both are computed for each draw and the median taken last, on the scale the forests add on (the response's units, or the probit or logit scale of a binary response), from each forest's own fits times the coefficient on its basis, which is what predict gives with the basis one unit higher less the basis as it stands; a fit that kept no per-forest fits (keepFits = FALSE) says so in one line instead. On a binary (probit or logistic), binomial or discrete-time hazard response, a second line under each effect gives it as a probability: for a factor the change in probability from its first level to its second, for a numeric basis the slope of the probability per unit of the basis (as marginaleffects::avg_slopes reports it), each an average and an sd across rows computed per draw and row from the kept fits and averaged last, so the average is the posterior of the mean change in probability. A 0/1 numeric basis has a slope that is not the 0 to 1 contrast, which factor(z) as the basis gives exactly. A gaussian response has no such line. Where the weights are counts of identical rows (the count families' default, and gaussian with weights.type = "frequency"), the average and the sd across rows, as the forest line's column mean and sd, count each row at its count, as the data written out row by row would. A binomial response, written as two columns, counts each row at its trials times any such weight, and the header then reads “over 371 trials (18 training rows)”.

Usage

## S3 method for class 'bart'
summary(object, vars = c("sigma", "k", "leaf.prior.sd", "resid.df"), ...)
## S3 method for class 'summary.bart'
print(x, ...)

Arguments

object, x

An object of class bart, as returned by bartBT or bart; for the four own-class fits, a bart fit of the matching class.

vars

Character vector of fields to summarize. By default the leaf-scale field follows how the leaf prior was named: k for a fit that named it by k, leaf.prior.sd (the k.scale over k; see bartBT, where on a fit with several forests it is each forest's sd in the response's units, printed in the block after the table) for one that named it by sd, and either can be requested by name, as can first.k, the burn-in draws. A requested parameter the fit held fixed (sigma under fixed(), a fixed k or leaf.prior.sd, a fixed shape or resid.df) is not tabulated but named on the line under the table; with the default vars that includes a fixed Student-t resid.df, and a sampled one is tabulated; other requested fields absent from object are silently dropped. sigma, k and leaf.prior.sd contribute one summarized variable each; any other field (varcount, varprobs, yhat.train, yhat.test) contributes one variable per column, named "field[column]".

On a heteroscedastic fit the sigma token resolves to mean.s: the mean over the training observations of that draw's variance surface s(x)s(x), one value per draw, since such a fit has no scalar sigma; s.train itself is reachable by name, contributing one variable per observation.

For the four own-class fits, vars is scoped to that family's own vocabulary (see bart): a "bartOrdinal" fit's "thresholds" contributes threshold[2] through threshold[K - 1], the first being pinned at 0 and named under the table; a "bartNegbin" fit's "shape" contributes the per-draw shape rr; a "bartMultinomial" fit has no vars argument at all - its only scalar posterior parameter is the per-category mean predicted probability, reported as prob[<level>]; a "bartHurdle" fit applies vars to both components separately.

...

Unused.

Value

An object of class summary.bart with elements call, stats (a data frame with one row per requested sampled scalar, or NULL if none of vars are present on the fit), vars, and fixed, a named list of the requested parameters the fit held fixed and their values (on a fit with several forests a vector with one entry for each forest, k and leaf.prior.sd named by the forests' labels), and, on a fit of several forests that kept its fits, forests, the lines of the full block that the print method gives after the table, and effects, where a forest has a basis, a data frame with a row for each effect (columns forest, label, effect, average, average.q5, average.q95, spread, spread.q5 and spread.q95, and, for a binary, binomial or hazard response, probability.kind ("change" or "slope") and the same six summaries prefixed probability., with the number of rows averaged over and the scale as attributes "rows" and "scale") or the string "dropped" for a fit that kept no per-forest fits. stats has columns variable, mean, median, sd, mad, q5, q95, rhat, ess_bulk, and ess_tail - the same columns posterior::summarise_draws reports for a plain array, computed without that package. Its print method shows each R-hat as a value, with no bar and no note, and dbarts does not refuse to summarize a fit whose chains disagree.

Reading R-hat

R-hat compares each chain's spread with the spread of the chains pooled, so a value above 1 says the chains disagree; pooling them does not cure it. At the defaults BART's chains routinely disagree on sigma, on k and on a single row's prediction, so values above 1 there are expected, and no single bar says whether a fit is usable. Averaged estimands, such as the mean prediction over a subgroup or a contrast between two subgroups, mix far better, so read R-hat on the estimand you report. extract with combineChains = FALSE gives each chain's draws; the example computes R-hat of a contrast this way, with rhat.

See Also

bart, bartBT, extract

Examples

fit <- bart(y ~ x, data.frame(y = rnorm(100), x = rnorm(100)), n.chains = 2L,
             n.samples = 20L, n.burn = 20L, n.trees = 5L, n.threads = 1L,
             verbose = FALSE)
summary(fit)



# R-hat of the estimand reported: the difference between the mean prediction
# for two subgroups, one value per draw and chain
set.seed(1)
n <- 200L
x <- matrix(runif(n * 5L), n, 5L)
y <- 10 * sin(pi * x[, 1L] * x[, 2L]) + 20 * (x[, 3L] - 0.5)^2 +
  10 * x[, 4L] + 5 * x[, 5L] + rnorm(n)
fit <- bart(x, y, n.chains = 4L, n.samples = 500L, n.burn = 100L,
            n.trees = 50L, n.threads = 1L, verbose = FALSE)
# chains by samples by rows
yhat <- dbarts::extract(fit, "ev", combineChains = FALSE)
group <- x[, 1L] > 0.5
contrast <- apply(yhat[, , group, drop = FALSE], 1:2, mean) -
  apply(yhat[, , !group, drop = FALSE], 1:2, mean)
dbarts::rhat(t(contrast)) # rhat() takes iterations by chains

Survival Probability Draws from a Survival Fit

Description

Posterior draws of the survival probability S(t∣x)S(t \mid x) from a survival fit: an accelerated failure time (AFT) log-normal fit produced by bart with family = "aft", or a discrete-time hazard fit produced by bart with family = "hazard" (or "hazard.logistic").

bart's four own-class fits ("bartMultinomial", "bartOrdinal", "bartNegbin", "bartHurdle") refuse by name instead: none of the four is a survival model, so none carries a hazard channel.

Usage

survivalProbabilities(object, ...)

## S3 method for class 'bart'
survivalProbabilities(
  object,
  times,
  newdata = NULL,
  offset = NULL,
  combineChains = TRUE,
  na.action = dbarts::na.keepPredictors,
  sample = c("train", "test"),
  bases = NULL,
  ...
)

## S3 method for class 'bartMultinomial'
survivalProbabilities(object, ...)

## S3 method for class 'bartOrdinal'
survivalProbabilities(object, ...)

## S3 method for class 'bartNegbin'
survivalProbabilities(object, ...)

## S3 method for class 'bartHurdle'
survivalProbabilities(object, ...)

Arguments

object

A fitted bart object from a survival model: an AFT model (its family element equals "aft") or a discrete-time hazard model (it carries a $periods grid; its family records the binary link). A hazard fit must have kept its trees, as bart does for it by default (not with an explicit keepTrees = FALSE), except to read the test subjects a test set that rode the fit call gave it (the matrix interface's own hazard test acceptance, person-period-expanded on the training grid): sample = "test" reads their stored draws and no trees are needed.

times

A numeric vector of times (on the original, non-logarithmic scale) at which to evaluate the survival function. For a discrete-time hazard fit the times are horizons on the period grid, and the default (when times is missing) is the training grid, object$periods.

newdata

Optional predictors at which to evaluate. When NULL the training observations are used, always: a test set that rode the fit call never changes what the call with no newdata returns, and sample = "test" is how to get its subjects. An AFT fit reads the training subjects from its stored draws; a hazard object must have been fit with keepTrees = TRUE to give them.

offset

The offset at the subjects of newdata, as predict takes it: a single value or one per row of newdata, added to the fit's offset() terms and offset argument evaluated on newdata (see offset in bart). For a hazard fit a subject's offset applies at every period. Without newdata an offset replaces the fit's own at the subjects asked for, the training subjects' under sample = "train" and the test subjects' (the offset.test the fit stored) under "test", one value or one per subject of that set. An AFT fit's is read off the stored draws with no trees replayed; so is a hazard fit's at its test subjects, on the latent scale before the link, while a hazard fit replays its trees at the training subjects, as it does for any of them, and needs keepTrees = TRUE.

combineChains

A logical determining whether the chain dimension is collapsed into the draw dimension, as elsewhere in the package.

na.action

What to do with the subjects in newdata that have missing values, resolved per subject before a hazard fit's person-period expansion. With no newdata it answers the subjects whose offset has a missing value, as it does for the rows of newdata: the default and na.fail refuse, na.pass returns the subject with NA curves, na.omit drops it and na.exclude pads it back; a single missing value is always an error. See ‘At Prediction’ in na.keepPredictors.

sample

Either "train" (the default) or "test", as extract's and fitted's sample are. With no newdata, "train" gives the training subjects and "test" the subjects of the test set that rode the fit call, read from the draws the fit stored, with no trees: a hazard fit's stored test grid, an AFT fit's stored test fit and, on a heteroscedastic fit, its stored test scale. Refused, by name, together with newdata, which gives other subjects: either value named beside newdata, "train" as well as "test", is an error, since sample chooses among the fit's own subjects; leave it out to read newdata's. Also refused on a fit that carries no test set or whose test draws keepFits = FALSE dropped, the message naming both causes and, on a fit kept without trees, a test set at the fit or the trees as what would answer it.

bases

For a fit of several forests with a basis, the basis at the subjects, as predict takes bases but one value per subject (a hazard subject's value applies at every period, as its offset does), where predict takes one per row of the person-period newdata: a list with an entry per forest, a bare value when one forest carries a basis, or the name of a column of newdata. Left out, the basis is read from newdata by the fit's forest() terms, and with no newdata the training subjects keep their own. Refused on a fit that has one forest.

...

Not a formal on the method: a name belonging to a sibling generic (type, ci.level, weights, n.threads, forest, contribution) is refused by name rather than silently ignored, since this method returns the draws of S(t∣x)S(t \mid x) at times alone.

Details

Under the log-normal AFT model log⁡T=f(x)+σϵ\log T = f(x) + \sigma \epsilon with ϵ∼N(0,1)\epsilon \sim N(0, 1), the survival function is

S(t∣x)=1−Φ(log⁡t−f(x)σ),S(t \mid x) = 1 - \Phi\left(\frac{\log t - f(x)}{\sigma}\right),

where f(x)f(x) is the linear predictor E[log⁡T∣x]E[\log T \mid x] - the log-time-scale quantity that predict and extract return for an "aft" fit, the offset included - and σ\sigma the residual standard deviation. The probability is evaluated at every posterior draw of f(x)f(x) and σ\sigma, following the package's convention that draw-level functions return draws: take means or quantiles over the draw margin for point estimates and credible bands.

For a discrete-time hazard fit, the survival function is the cumulative product

S(t∣x)=∏k : periods[k]≤t(1−h(k∣x)),S(t \mid x) = \prod_{k \,:\, \mathrm{periods}[k] \le t} (1 - h(k \mid x)),

where h(k∣x)=g(f(x,k)+o)h(k \mid x) = g(f(x, k) + o) is the per-period hazard through the fit's binary link gg and oo the subject's offset: the fit's own on the training subjects, and on newdata the one formed from offset as above. Because the training design is ragged (each subject carries only its at-risk rows), the method ALWAYS re-expands its subjects onto the full grid and replays the trees - so it requires keepTrees = TRUE even for the training data (newdata = NULL). With newdata, each new subject is expanded to one row per period and its curve evaluated the same way. The one exception: a test set that rode the fit call (the matrix interface's own hazard test acceptance) was already person-period-expanded on the SAME training grid at fit time, so its hazards are stored on the fit already - sample = "test" on such a fit reads them directly with no re-expansion and no trees needed. The call with no newdata is the training subjects whether or not the fit carries a test set.

Value

An array of survival probabilities. With combineChains = TRUE the dimensions are draws ×\times times ×\times observations; with combineChains = FALSE a chain dimension precedes them (chains ×\times draws ×\times times ×\times observations), length 1 on a one-chain fit rather than dropped, as extract and predict keep theirs. Observations are those of newdata, or the training data when newdata is NULL, or with sample = "test" the test set.

Author(s)

Vincent Dorie: [email protected].

See Also

bart, predict, extract

Examples

set.seed(42)
n <- 100L
x <- matrix(runif(n * 2L), n, 2L)
eventTime <- exp(x[, 1L] + 0.5 * rnorm(n))
censorTime <- exp(x[, 1L] + 0.25 + 0.5 * rnorm(n))
status <- as.numeric(eventTime <= censorTime)
observedTime <- pmin(eventTime, censorTime)

fit <- bart(
  x,
  cbind(observedTime, status),
  family = "aft",
  n.trees = 25L,
  n.burn = 50L,
  n.samples = 100L,
  n.chains = 1L,
  verbose = FALSE
)

surv <- survivalProbabilities(fit, times = c(0.5, 1, 2))
dim(surv) # draws x times x observations

## posterior-mean survival curve and 90% band for the first observation
apply(surv[, , 1L], 2L, mean)
apply(surv[, , 1L], 2L, quantile, probs = c(0.05, 0.95))

Jointly Update a Shared Predictor per Observation Across Samplers

Description

Applies a “partial” (per-observation) update of a single shared column to several dbartsSampler objects at once, installing an observation's new value only when it keeps every leaf node non-empty in every tree of every sampler.

Usage

updatePredictorPerObservationJointly(samplers, x, column, updateState = NULL)

Arguments

samplers

A dbartsSampler, or a list of dbartsSampler objects, that share the same (index-aligned) observations. The samplers are treated as peers; none is privileged.

x

The new values for the shared column, one per observation. For a numeric column, numbers; a factor, or text that is not numerals, is refused for it. For a column the samplers hold as a factor or an ordered factor, its labels: a factor, a character vector or a sparseFactor, matched to the column's levels by name, as setPredictor takes them for a named column. The order of the levels of the factor given does not matter; a label the column does not have is refused by name. A missing label is a missing value, taken whether or not the column has held one. Numbers are refused for such a column, as setPredictor refuses them for a named column, even where the labels are numerals. One value is one level in every sampler only if they hold the column with the same levels in the same order, so samplers that hold it as a factor with different levels are refused; update them in separate calls. Labels are also refused when one sampler holds the column as a number.

column

A single integer or character string identifying the shared column; it cannot be missing. The column is matched by name across all samplers, so the shared variable may sit at different column positions in each. When given as an integer, it indexes the columns of the first sampler and the corresponding name is used to locate the column in the rest.

updateState

A logical determining if the local cache of each sampler's state should be updated after the update completes. If NULL (the default), each sampler's own control default is used; TRUE or FALSE overrides it and anything else is an error. An explicit NA reads as NULL for one release, with a once-per-session warning.

Details

This is the multi-sampler analog of the forceUpdate = "partial" mode of setPredictor. A single sequential sweep installs each observation in every sampler at once, and only if its new value keeps every leaf non-empty in every tree of every forest of every chain of every sampler; otherwise that observation is rolled back to its previous value in all of them. Under a monotone constraint a row that brings an unordered factor column its first missing value is declined, in every sampler, where the sides drawn for the column's rules would leave a tree's leaf values out of order in any of them; a numeric column's first missing value breaks no order. A hazard fit's period column, its expansion of each subject's time at risk, set with the response, is taken only unchanged, and refused otherwise before anything moves; setData replaces it. Any of the samplers may itself carry more than one forest - a Bayesian causal forest, a multinomial sampler, or a heteroscedastic (variance) sampler - and each of its forests is checked on the same terms as an ordinary single-forest sampler's mean forest (see ‘Multi-forest and heteroscedastic predictor mutation’ in dbartsSampler). Like the single-sampler partial mode, the update never changes tree structure – it only re-routes observations.

This supports embedding several BART components that condition on a common latent predictor (for example, a shared ability or trait in an item-response model) within a larger Gibbs/Metropolis sampler.

A whole-matrix setPredictor call on one of the samplers, made earlier in the same script, keeps that sampler's column names (see ‘Multi-forest and heteroscedastic predictor mutation’, dbartsSampler), so this function's by-name column matching continues to resolve against it afterward.

Value

A logical vector of length equal to the number of observations, TRUE where the observation's new value was installed and FALSE where it was rolled back to keep every tree valid. The same accept/reject decision is applied to every sampler, so an installed observation takes the new value in all of them; a rejected observation reverts to each sampler's own previous value. When the samplers agreed on the shared column before the call, they therefore continue to agree afterward.

See Also

dbarts, dbartsSampler

Examples

## two BART components conditioning on a common latent predictor 'theta',
## as an item-response model would: both must accept an observation's new
## value, or neither does
set.seed(5)
n <- 80L
theta <- rnorm(n)
w <- runif(n)

df1 <- data.frame(theta = theta, w = w)
df1$y <- theta + rnorm(n, 0, 0.2)
df2 <- data.frame(v = runif(n), theta = theta)
df2$y <- 0.5 * theta + rnorm(n, 0, 0.2)

control <- dbartsControl(n.chains = 1L, n.threads = 1L, n.burn = 0L,
                         n.samples = 1L, updateState = FALSE)
s1 <- dbarts(y ~ theta + w, df1, control = control, n.trees = 25L)
s2 <- dbarts(y ~ v + theta, df2, control = control, n.trees = 25L)
invisible(s1$run())
invisible(s2$run())

## 'theta' sits in a different column of each sampler; it is matched by name
proposal <- theta + rnorm(n, 0, 0.1)
installed <- updatePredictorPerObservationJointly(
  list(s1, s2), proposal, column = "theta")
table(installed)

Variance Forest Specification for Heteroscedastic BART

Description

Build the specification of the heteroscedastic variance forest (HBART; Pratola, Chipman, George, and McCulloch 2020). Pass the result as the variance argument of dbarts, dbartsSpec, or bart - the same argument that already accepts the plain selector (NULL/FALSE for none, TRUE/a one-sided formula/a character or integer column selector for the predictors driving the variance). This constructor is the other accepted type of that one argument, adding the variance forest's own tree count and structure prior alongside the column selection.

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

Usage

varianceForest(
    vars = NULL, n.trees = NULL, base = NULL, power = NULL,
    proposal.probs = NULL, n.perturb.cuts = NULL)

Arguments

vars

Which predictors drive the variance surface, written as forest's vars is: bare terms (x1 + x2), a one-sided formula in place or held in a variable (~ x1 + x2, the tilde accepted and never required), or a character or integer column selector (a bare factor term name expands to its indicator columns). NULL (the default) reads every predictor - the object's own “unrestricted” reading, distinct from variance = NULL, which declares no variance forest at all.

n.trees

The number of variance trees. NULL (the default) takes the variance forest's own default of 40, the same value variance = TRUE and the other plain-selector forms use. Two or more trees need a chisq() residual prior with df above 2: each tree's prior is calibrated to the residual prior's mean of σ2\sigma^2, which is infinite at df 2 or below. One tree takes the residual prior itself, at any df.

base, power

The variance forest's tree-structure prior. NULL (the default) inherits the mean forest's base and power, those of the fitting function or the lone mean forest's own.

proposal.probs, n.perturb.cuts

The variance forest's proposal mixture and perturb window, as dbartsControl describes each. Each one stated here governs the variance forest and each one left out takes the control's: $setControl changes it only where none is stated here, and one stated here is changed by $setVarianceForest, not by $setControl. A stated proposal.probs is a whole mixture, filled against the package defaults as dbartsControl()'s is, and a positive "rule_gibbs" share is refused: that move does nothing on the variance forest's leaves. n = and p = each abbreviate more than one argument, so write n.trees and power in full.

Details

A second ensemble models the residual variance surface s2(x)s^2(x) as a product of scaled-inverse-chi-squared (multiplicative) leaves, so yi=f(xi)+s(xi)ϵiy_i = f(x_i) + s(x_i)\epsilon_i, coupled to the mean forest through the per-observation precision. Gaussian and "aft" (survival) responses and constant leaves only - the latent families route their own precisions through the same channel; monotone constraints are not supported. Under "aft" the surface is the dispersion of log survival time, and a right-censored observation's latent log-time is redrawn at its own s(xi)s(x_i). Every value is validated when a sampler is built.

Value

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

References

Pratola, M.T., Chipman, H.A., George, E.I., and McCulloch, R.E. (2020) Heteroscedastic BART via multiplicative regression trees. Journal of Computational and Graphical Statistics, 29(2), 405–417.

See Also

dbartsForests, dbarts, dbartsSpec, bart

Examples

set.seed(0)
n <- 200L
x <- matrix(runif(n * 2), n, 2, dimnames = list(NULL, c("x1", "x2")))
s <- ifelse(x[, 1] > 0.5, 0.3, 1.2)
y <- 2 * x[, 1] + s * rnorm(n)

## every predictor drives the variance, 20 variance trees
fit <- bart(x, y,
             variance = varianceForest(n.trees = 20L),
             n.trees = 25L, n.samples = 20L, n.burn = 20L,
             n.chains = 1L, verbose = FALSE)

## restricted to x1, with its own tree-structure prior
fit.restricted <- bart(x, y,
                        variance = varianceForest(vars = ~x1, n.trees = 20L,
                                                  base = 0.9, power = 1.5),
                        n.trees = 25L, n.samples = 20L, n.burn = 20L,
                        n.chains = 1L, verbose = FALSE)

dbartsForests$varianceForest(vars = ~x1, n.trees = 20L, base = 0.9, power = 1.5)

Crossvalidation For Bayesian Additive Regression Trees

Description

Fits the BART model against varying k (or sd), power, base, and n.trees parameters using KK-fold or repeated random subsampling crossvalidation, sharing burn-in between parameter settings. Results are returned as an array of evaluations of a loss function on the held-out sets.

Usage

xbart(
    formula, data, subset, weights, offset, verbose = FALSE, n.samples = 200L,
    method = c("k-fold", "random subsample"), n.test = c(5, 0.2),
    n.reps = 40L, n.burn = c(200L, 150L),
    loss = c("rmse", "log", "mcr"), n.threads = dbarts::guessNumCores(), n.trees = 75L,
    k = NULL, sd = NULL, power = 2, base = 0.95,
    split.probs = NULL, drop = TRUE,
    sigest = NULL,
    seed = NULL,
    factors = c("categorical", "indicators"),
    family = c("auto", "gaussian", "probit", "logistic"),
    weights.type = NULL,
    leaf.prior = NULL, n.cuts = 100L, useQuantiles = FALSE, n.thin = 1L,
    storage = c("double", "single"),
    parallel = getOption("dbarts.parallel", "auto"), cl = NULL,
    control = dbarts::dbartsControl(), sigma = NULL, ...)

Arguments

sigma

The 0.9-x spelling of sigest, accepted for one release with a once-per-session warning and removed in dbarts 1.1-0. Supplying both is an error.

...

Not used for new code: the channel that lets a retired argument spelling (resid.prior, now family = gaussian(sigma = ), its one home, so writing it both ways is refused where the two disagree) reach a message naming its successor, instead of R's own “unused argument” error. Any other name is refused. Removed in dbarts 1.1-0.

control

A dbartsControl object carrying the sampler and engine settings, including the ones xbart spells no flat name for: categoricalExhaustiveCap, testFitParallelCutoff, predictParallelCutoff, sparseDensityThreshold, treeShift, and the tree-move mixture proposal.probs. Precedence, one rule: a flat argument named in the call wins over the control's slot of the same name, and a slot the control speaks for - one its own dbartsControl() call named, or one edited afterwards to differ from a fresh control's - wins over this function's default, while a slot it never spoke for leaves that default standing. The fields a sweep forces - n.chains, the control's own n.threads, keepTrees, keepTrainingFits, updateState, verbose - are applied after both, and n.burn and n.threads here are the sweep's own grid axis and worker count rather than the control fields of the same name. A control taken from a fitted sampler carries that fit's run settings and nothing else: it sets no tree count, cut count or quantile rule for this fit, and one that differs from what the call takes draws a warning saying it is not used.

formula

An object of class formula following an analogous model description syntax as lm. For backwards compatibility, can also be the bartBT matrix x.train. See dbarts. A dbartsData object carrying bases, the data of a sampler of several forests, is cross-validated as a model of one forest, the bases left out, as dbarts reads it given no forests: xbart cross-validates single-forest models.

data

An optional data frame, list, or environment containing predictors to be used with the model. For backwards compatibility, can also be the bartBT vector y.train.

subset

An optional vector specifying a subset of observations to be used in the fitting process.

weights

An optional vector of weights to be used in the fitting process. For a gaussian response, BART fits a model with observations y∣x∼N(f(x),σ2/w)y \mid x \sim N(f(x), \sigma^2 / w), where f(x)f(x) is the unknown function. Binary responses differ: a "probit" model does not support weights (a weighted probit has no tractable latent-variable form), except that weights identically 1 are treated as absent and weights all 0 and 1 name the rows in the data set, as in dbarts: a fold's training rows of weight 0 are out of its likelihood and its held-out rows of weight 0 out of its loss, as on every family; a "logistic" model treats them as observation counts and so requires non-negative whole numbers, a 0 out of the likelihood (its Polya-Gamma latent for a count ww is a sum of ww unit draws, so a sweep's time grows with the total count, and a count above 10610^6 is refused). A gaussian row of weight 0 takes no part in a fold's response scale or starting sigma: each fold reads the rows of positive weight among its training rows, and where those hold fewer than two distinct values of the response it reads every training row, one warning of class dbartsScaleFallbackWarning being raised for the whole call when that is so of all rows.

offset

An optional vector specifying an offset from 0 for the relationship between the underlying function, f(x)f(x), and the response yy. Useful for all three response families, though each applies it differently: for a gaussian response, y=f(x)+offset+ϵy = f(x) + \mathrm{offset} + \epsilon, a fixed component of the mean (see dbarts for the interaction with BART's internal range-scaling); for binary responses it enters the link directly, P(Y=1∣X=x)=Φ(f(x)+offset)P(Y = 1 \mid X = x) = \Phi(f(x) + \mathrm{offset}) for a "probit" fit and the analogous model on the logistic link for "logistic".

verbose

A logical determining if additional output is printed to the console, including the one-line message family = "auto" prints, once per call, naming the family it resolves to.

n.samples

A positive integer, setting the number of posterior samples drawn for each fit of training data and used by the loss function.

method

Character string, either "k-fold" or "random subsample".

n.test

For each fit, the test sample size or proportion. For method "k-fold", is expected to be the number of folds, and in [2,n][2, n]. For method "random subsample", can be a real number in (0,1)(0, 1) or a positive integer in (1,n)(1, n). When a given as proportion, the number of test observations used is the proportion times the sample size rounded to the nearest integer.

n.reps

A positive integer setting the number of cross validation steps that will be taken. For "k-fold", each replication corresponds to fitting each of the KK folds in turn, while for "random subsample" a replication is a single fit.

n.burn

Unlike the single-scalar n.burn of dbarts and bart, here it is one or two non-negative integers, specifying 1) the burn-in when a chain is freshly started against a data split and 2) the burn-in when moving from one parameter setting to another over the same split. A longer vector is an error naming the argument rather than being silently truncated to its first two entries; dbarts 0.9-x read a third element as a per-replication burn-in, which no longer exists. Chains are never carried between data splits or folds - the held-out observations of one were training observations of the previous, so continuing a chain lets slowly-mixing settings score against data they have effectively seen.

loss

Either one of the pre-set loss functions as character-strings (the default is "rmse" for a continuous response and "log" for a binary one; mcr - misclassification rate for binary responses, rmse - root-mean-squared-error for continuous response), log - negative log-loss for binary response (rmse serves this purpose for continuous responses), a function, or a function-evaluation environment list-pair. A function keeps its own environment, so a closure reads what it captured; the list form calls the function from the given environment. Functions should have prototypes of the form function(y.test, y.test.hat, weights), where y.test is the held out test subsample, y.test.hat is a matrix of dimension length(y.test) ×\times n.samples, and weights are an optional vector of user-supplied weights. See examples.

n.threads

Every (replication, fold) pair is an independent unit of work, and for n.threads > 1 the units are divided into approximately equal chunks and executed on that many parallel workers (see parallel). A k-fold run of a single replication therefore uses up to k workers. The default uses guessNumCores, which should work across the most common operating system/hardware pairs, and is one where the cores cannot be counted; a stated NA is refused. Warnings raised while fitting or scoring, including by a supplied loss function, are collected from every unit and signaled in the calling session once all units have finished, in unit order and each distinct warning once, so the same warnings are seen at any n.threads.

parallel

One of "auto", "fork" or "socket", and by default getOption("dbarts.parallel", "auto"). "fork" runs the workers as forked copies of the calling session, which is fast to start and shares the data; "socket" starts separate R sessions (a makeCluster cluster) that each load dbarts and receive their own copy of the data, which costs roughly 80 MB per worker beyond the data itself. "auto" forks unless the platform is Windows, the session runs under RStudio or Positron, or R.app, in which case it uses sockets. "fork" is an error on Windows. Forking can hang or crash when the calling session has already used a library that is not fork-safe, such as a multithreaded BLAS; if so, set parallel = "socket" or options(dbarts.parallel = "socket"). Results do not depend on the kind of worker. Ignored when cl is given or only one worker is used.

cl

NULL or a cluster from the parallel package that the caller has already started, used instead of starting workers whatever parallel says. The units are divided into min(n.threads, length(cl)) chunks, and xbart does not stop the cluster. The workers must load the same dbarts version as the calling session, since the work function is sent by reference and each worker runs its own installed dbarts. A one-node cl, like n.threads = 1, runs the units in the calling session.

n.trees

A vector of positive integers setting the BART hyperparameter for the number of trees in the sum-of-trees formulation. See bart. A written NULL is refused, saying to leave the argument out for its default.

k

The grid for the BART hyperparameter setting the leaf-mean prior standard deviation: a vector of positive real numbers, each a cell of its own, or a list whose entries are positive numbers and k hyperpriors (dbartsPriors), so that k = list(1, 2, chi()) sweeps two fixed values against the modeled one. A modeled cell holds its hyperprior and DRAWS k every sweep, so its loss is computed under a shrinkage that moves within the fit rather than under a named value; it is labeled in the result by the constructor call that rebuilds it. If NULL, one cell is run at the default bart would fit for the response type: fixed 2 for a continuous response and chi(1.5, 2) for a binary one. A k carried by a supplied leaf.prior stands in for a missing argument. Fixed cells are always swept largest to smallest, with a modeled cell last, and the reported k axis is un-permuted back to the order given, so results do not depend on the order k is listed in; cells still warm-start off the previous one, so this is order-invariance, not an unbiased estimate for each cell taken alone. A written NULL is the argument left out.

sd

The same grid axis stated in absolute spreads instead, exclusive with k: a vector of leaf-prior sds on the family's scale (see normal(sd = ) in dbartsPriors), or a list mixing them with invchi priors. Each spread is held fixed across folds, where a k is relative to each fold's own training range; on a binary family, whose k.scale is a constant of the latent scale, a grid of fixed cells is the same sweep either way (sd = k.scale / k); a modeled cell is not, since invchi(df, c) starts its chain at the spread c where chi(df, k.scale / c) starts at k.scale / 2. Those starts are the first cell's: each later cell of the warm sweep starts at the spread the previous cell ended on, whichever of k and sd the grid is stated in. A k inside leaf.prior beside an sd grid is refused, as an sd there is beside either grid. The cells are swept most shrunk first - the smallest sd - with the warm starts and unit parallelism the k grid has, and the result's axis is labeled sd.

power

A vector of positive real numbers, setting the BART hyperparameter for the tree prior's growth probability, given by base/(1+depth)power{base} / (1 + depth)^{power}. A written NULL is refused, saying to leave the argument out for its default.

base

A vector of real numbers in (0,1)(0, 1), setting the BART hyperparameter for the tree prior's growth probability. A written NULL is refused, saying to leave the argument out for its default.

split.probs

Prior probabilities that a variable is used in a splitting rule, as in bart. A single value or NULL yields the uniform default; a named or unnamed vector assigns per-column probabilities; num.vars stands for the number of predictors; and dart() from dbartsPriors runs DART (Linero 2018) in every cell. Fixed for the whole crossvalidation, not part of the swept grid. xbart takes no tree.prior: power and base are grid axes, and given a tree.prior it refuses, naming the plain spelling.

drop

Logical, determining if dimensions with a single value are dropped from the result.

sigest

A positive numeric estimate of the residual standard deviation; one of "auto", "dense" and "sparse", naming how one is made; or a function that makes one. Each name gives the residual standard deviation of the linear regression of the response on the predictors, factors entering as indicator columns whatever the trees are given, and, where that regression leaves no residual degrees of freedom, counting each row once, not as often as its weight, under weights read as counts, the standard deviation of the response over the observations of positive weight, weighted as the regression is (summary(lm(y ~ 1, weights = weights))$sigma, sd(y) at unit weights; for weights read as counts, the standard deviation of the rows written out, or sd(y) over the observations of positive weight where the counts total at most 1, up to the rounding of their sum), which a line under verbose says, with no warning. "auto" is lm's own routine ("dense") for a matrix or a data frame and an exact sparse one ("sparse") where the caller supplied a sparse-stored column. NULL (the default) is "auto"; an explicit NA is a missing value and is refused. The estimate is made separately for each fold on that fold's training rows, so no fold's prior reads its held-out responses; it is made on all rows once beforehand, to raise any refusal once, to print its lines under verbose and to settle the routine every fold runs, a fold taking its own response's standard deviation where all rows, or its own, leave no residual degrees of freedom; where all rows allow the regression and some folds' rows do not, one more line under verbose gives, for each standard deviation taken, the number of (replication, fold) units that took it. A function is called once for each fold in place of any of that, as function(x, y, weights, offset) or in loss's list form with an environment, on the worker that runs the fold and so under what loss and seed say of workers and random numbers. x is the fold's training rows of the design "auto" would read, a numeric matrix or for a sparse x a dgCMatrix, built only if the function reads it; y, weights and offset are those rows', NULL where the call has none; the value must be one positive finite number. function(x, y, weights, offset) sd(y) skips an expensive estimate, and the alternatives dbarts lists for one can be written the same way. Every entry point spells this sigest - xbart, bartBT/bart and the sampler constructors dbarts/dbartsSpec alike; sigma is the retired 0.9-x spelling on dbarts and on xbart itself (dbartsSpec refuses it); a family object's own sigma is the prior this estimate calibrates, not the estimate. It is the estimate a chisq residual prior's quantile is calibrated against, so it stands beside family = gaussian(sigma = chisq(df, quant)) and has nothing to calibrate beside family = gaussian(sigma = fixed(value)), which fixes the residual scale outright: no estimate is made there, by any rule, and a number that differs from the square root of value, or a function, is refused.

seed

Optional integer specifying the desired pRNG seed. NULL (the default) means not given here and defers to a seed already sitting in control, if any; an NA is a missing value, as in set.seed: it reads as NULL for one release, with a once-per-session warning. From the seed in force, xbart draws a split seed for each replication and a seed for each sampler its units create - one per (replication, fold) unit at each distinct tree count - with sample.int, in one pass, under the caller's own RNGkind: a given seed therefore draws different values, and so gives different results, under a different kind. Each unit's sampler then takes its seed through control's seed slot, exactly as bart's own seed does, driving a dedicated generator that never reads R's stream, so results are reproducible at any n.threads for a given seed and RNGkind. A supplied loss function that draws random numbers draws on the worker running it, from that process's own default generator; at n.threads greater than 1 this makes the run not reproducible, whatever seed xbart itself is given. The caller's random stream is left untouched when a seed is given, and advanced only by that derivation when one is not; without a seed, set.seed beforehand suffices. See the Reproducibility section of bart.

factors

How factor columns in a data frame enter the model; as in dbarts.

family

The response model, resolved as in dbarts: "auto" fits gaussian models to continuous responses and probit models to those coded 0/1, "gaussian" forces a continuous fit, and "probit" and "logistic" require a 0/1 response, family = binomial or "logistic" also taking a binomial response, cbind(successes, failures), as bart does. A two-level factor, logical, or two-level character response is detected and fit as probit; a factor with three or more levels is an error, as xbart does not cross-validate the multinomial model, and neither is another matrix response (per-category counts or a (time, status) pair), which is refused naming bart. A survival response - a Surv object or two-column (time, status) pair, on formula or as data directly - is likewise an error naming bart/dbarts with family = "aft"/"hazard": xbart does not cross-validate a survival model. The built-in binary losses transform test predictions through the family's link. This vocabulary is narrower than bart's by design - xbart cross-validates a single scalar loss per fold, which the own-class families' K-forest or two-part fits have no single counterpart of; the wider family set lives on bart. Base R family objects map as glm takes them (binomial is the logit link, so family = binomial is "logistic", not probit) and the rest are refused; see dbartsFamilies.

weights.type

How weights are read, as in dbarts: NULL (the default) is precision on a gaussian fit and frequency on a probit or logistic one, "precision" is refused on those two, and "frequency" on a gaussian fit reads a row of weight ww as ww identical observations, each fold's starting sigma being the residual sd of the regression on its training rows written out that many times.

leaf.prior

An optional expression of the form normal(k), linear(columns, k), or gp(columns, k, ...) selecting the leaf model, as in dbarts. The default fits constant leaves. A k given inside the prior stands in for a missing k argument; the k argument otherwise drives the crossvalidation grid as usual. Each fold centers and scales a linear or gp leaf's covariates over its own training rows of positive weight, as a fit on those rows would. Where those rows hold fewer than two distinct values of a gaussian response, the fold reads its response's scale and the covariates over every training row; otherwise a fold whose such rows hold one value of a covariate, or values that differ by rounding only, refuses the call, unless its gp leaf states lengthscale. A written NULL is the argument left out.

A named sd inside the prior (normal(sd = ), and likewise for linear and gp) stands in for a missing sd argument, as a one-cell sd axis. Beside a k or sd grid it is refused, since both would state the spread: name the spreads in the sd grid. Two calls with the same seed use the same folds whatever their spreads, so one call per sd reproduces each cell a grid's fresh start would.

n.cuts

The number of decision rules used for each predictor, as bart's n.cuts reads: one positive integer for every column, one per column, or by column or term name with .default for the rest. A dbartsData object given as formula keeps its own, and a grid it carries, its cutPoints, is the one every fold takes, as dbarts takes it; stating n.cuts or useQuantiles derives the grid again.

useQuantiles

Logical; as in bart, determines whether decision rules are placed at the empirical quantiles of each predictor's values rather than spaced uniformly through its range. Either way a fold takes the full data's rules and their weights, so on a predictor with fewer distinct values than n.cuts it holds a rule between held-out values as well.

n.thin

A positive integer; as in dbartsControl, thins each cell's chain against serial correlation. n.samples are still returned regardless.

storage

A character string selecting the precision of the internal running residual, spelled and defaulted as in dbartsControl. Every cell's sampler is created over a shared per-fold data handle, a path the engine keeps in double precision regardless of family or leaf model; "single" is refused rather than silently ignored.

Details

A fit in which every predictor holds one value on the rows kept, with no forest having a basis, is refused, naming the columns, as by bart.

Crossvalidates n.reps replications against the crossproduct of given hyperparameter vectors n.trees ×\times k ×\times power ×\times base. For each fit, either one fold is withheld as test data and n.test - 1 folds are used as training data or n * n.test observations are withheld as test data and n * (1 - n.test) used as training. A replication corresponds to fitting all KK folds in "k-fold" crossvalidation or a single fit with "random subsample". The training data is used to fit a model and make predictions on the test data which are used together with the test data itself to evaluate the loss function.

loss functions are either the default of average negative log-loss for binary outcomes and root-mean-squared error for continuous outcomes, misclassification rates for binary outcomes, or a function with arguments y.test, y.test.hat and weights. y.test.hat is of dimensions equal to length(y.test) ×\times n.samples, on the latent scale for binary outcomes. For a binary outcome the built-in "rmse" compares the response with the posterior mean probability (the link applied to each draw, then averaged), as "log" and "mcr" do, while a supplied function receives the latent draws. A third option is to pass a list of list(function, evaluationEnvironment), so as to provide default bindings. The binary losses "log" and "mcr" cannot apply to continuous responses. On a binomial response a row is read as its trials: y.test is its observed proportion k/nk / n (0 at a row of no trials), weights are its trials times its weight, and the built-in losses read each row so weighted, "log" as −[ylog⁡p+(1−y)log⁡(1−p)]-[y \log p + (1 - y) \log(1 - p)] and "mcr" as the share of the row's trials on the wrong side of 0.5, which is what both losses give on the rows written out one trial each; "rmse" compares the proportion with the probability, a row weighted by its trials, and on the rows written out would add a term that depends on the data alone. A supplied function receives the same y.test and weights, and the latent draws.

Value

An array with up to six dimensions, in order rep (length n.reps), n.trees, k (or sd), power, base, and loss. rep is always present. n.trees, k, power, and base are each omitted when drop is TRUE and the corresponding grid has length 1; with drop = FALSE they are always present, an absent k included, whose single cell is then named for the default it ran at. The trailing loss dimension, sized to however many values a single call to loss returns, is present only when that count is greater than one - independent of drop entirely; the default losses and an ordinary scalar-returning custom loss never contribute it. When none of the above survive, the result collapses to a plain vector of length n.reps. When the result remains an array, its dimnames name the swept values on each surviving hyperparameter axis - exact integer labels for n.trees, values rounded to 2 significant digits for the double-valued k/power/base axes, and the constructor call for a modeled k cell; the loss axis, when present, carries no per-slot names, and neither does rep.

For method "k-fold", each element is an average across the KK fits. For "random subsample", each element represents a single fit.

The result is a bare array with no class, so the fit generics - predict, extract, fitted, residuals - do not apply to it; it is a table of losses, not a fit.

Author(s)

Vincent Dorie: [email protected]

See Also

bart, dbarts

Examples

f <- function(x) {
    10 * sin(pi * x[,1] * x[,2]) + 20 * (x[,3] - 0.5)^2 +
        10 * x[,4] + 5 * x[,5]
}

set.seed(99)
sigma <- 1.0
n     <- 100

x  <- matrix(runif(n * 10), n, 10)
Ey <- f(x)
y  <- rnorm(n, Ey, sigma)

mad <- function(y.test, y.test.hat, weights) {
    # note, weights are ignored
    mean(abs(y.test - apply(y.test.hat, 1L, mean)))
}



## low iteration numbers to to run quickly
xval <- xbart(x, y, n.samples = 15L, n.reps = 4L, n.burn = c(10L, 3L),
              n.trees = c(5L, 7L),
              k = c(1, 2, 4),
              power = c(1.5, 2),
              base = c(0.75, 0.8, 0.95), n.threads = 1L,
              loss = mad)