Skip to contents

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 \mid x \sim N(f(x), \sigma^2 / w)\), where \(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 \(w\) standing for \(w\) 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 + r\) (nbinom) or times the row total (multinomial) is refused above \(10^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 \(\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, \(\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 + 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 \(w\) stands for \(w\) 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: \(\mathrm{Binomial}(w, p)\) successes on a binary fit, \(p\) 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 \(w\) new counts, one \(\mathrm{NB}(\mathrm{size} = w r, \mathrm{mu} = w \mu)\) draw; on an ordinal or multinomial fit the count per category over \(w\) 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^{\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 \(k\) successes in \(n\) trials is one logistic row of \(n\) trials, drawn as its \(n\) 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; \(n\) times the row's weight is capped at \(10^6\). The fit reports on two scales, as glm does: fitted(type = "ev") is the probability \(p\) and its residual \(k / n - p\); the predictive draws are counts, \(\mathrm{Binomial}(n, p)\) at a training row, so fitted(type = "ppd") estimates \(n p\) and its residual is \(k - n p\). fit$y keeps the two columns as written. At new rows predict(type = "ppd") draws \(\mathrm{Binomial}(w, p)\) with \(w\) 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 \(\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 \(w\) counts copies of the row: the row stands for \(w n\) trials in the likelihood, its log-likelihood is \(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, \(\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\), 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) \(n_i \ge 0\): category k's count is then a binomial(\(n_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 \(n_i = 1\)) is the same model as the factor response above, reproduced bit for bit. A row with \(n_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 \(w\) the row written out \(w\) times; on a count fit that is its counts times \(w\). 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 \(\pi\sqrt{3}\) divided by \(\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) + \epsilon\) with \(\epsilon \sim N(0, 1)\) is cut at ordered thresholds \(-\infty = \gamma_0 < \gamma_1 = 0 < \gamma_2 < \ldots < \gamma_{K-1} < \gamma_K = \infty\), so \(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.5^2)\); at \(K = 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[y_i \mid x] = \eta_i = f(x_i) + c + o_i\), and the count distribution is \(y_i \sim \mathrm{NB}(\mathrm{size} = r, \mathrm{mu} = e^{\eta_i})\) with shape \(r\) and variance \(\mu + \mu^2 / r\), as MASS::glm.nb and Stan's neg_binomial_2 parameterize it. The offset \(o_i\) therefore enters the mean multiplicatively and is a log-exposure (\(o_i = \log(\mathrm{exposure}_i)\)). The constant \(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\}\)) under a renormalized \(\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 \(r\) 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^{\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 \(10^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 \(t_i\) is person-period-expanded into its at-risk rows (one per period \(k = 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 \(y_{ik} = \mathrm{status}_i \cdot 1\{k = t_i\}\). The discrete hazard is \(h(k \mid x) = g(f(x, k) + o)\) for the chosen binary link \(g\) (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 \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\}\) over all n observations, glued at report time to a POSITIVE-PART gaussian fit of \(\log y\) over the subset \(\{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 \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 \(\pi(x) = P(y > 0 \mid x)\) through the probit link; type = "link"/"log" the positive part's log-scale linear predictor \(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\) 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\) 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\}\) and a gaussian fit of \(\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 \mid x \sim N(f(x), \sigma^2 / w)\), as lm reads weights. Under "frequency" a row of weight \(w\) stands for \(w\) identical observations, so the posterior is the one for the data with each row written out \(w\) times, a real \(w\) 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:

familyNULL reads"precision""frequency"
gaussian, student, a variance forestprecisiontaken, real \(w \ge 0\)taken, real \(w \ge 0\)
logistic, hazard.logistic, nbinom, multinomialfrequency, countsrefusedwhole \(w \ge 0\)
probit, hazard, hazard.probit, ordinalfrequency, membershiprefused0 and 1 only
hurdle.lognormalfrequency, membershiprefused0 and 1 only
aftprecision, no weightsno weightsrefused

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 \(w\) observations at a row; a row's predictive draw is one observation at sd \(\sigma\); its log-likelihood is \(w\) 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 \(w\) 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 \(w\) 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 \(y\) 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 \(y\), k is the number of prior standard deviations \(E(Y|x) = f(x)\) is away from \(\pm 0.5\). The response is internally scaled to range from \(-0.5\) to \(0.5\). For binary \(y\) fit with the default probit link, k is the number of prior standard deviations \(f(x)\) is away from \(\pm 3\), the probit reference scale; family = "logistic" widens this to \(\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)^{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 \(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)\)), and predict attaches an "s" attribute carrying \(s(x)\) for new data: its draws, or under ci.level its estimate and credible band per row, as the value carries. \(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)\) for \(x\) 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 \(\gamma_2, \ldots, \gamma_{K-1}\), the ordinal analog of sigma (the pinned \(\gamma_1 = 0\) is named under the table, not tabulated); summary.bartNegbin's "shape" contributes the per-draw shape \(r\), 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.

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.

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\), 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, \(\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)\) 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 \(a\)), 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 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 \(y_{ik} / n_i\) against the interval of the drawn \(p_{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)\) on the unit-variance probit scale, shaped like a binary family's yhat.train - thresholds - the posterior draws of the K - 1 finite thresholds \((\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(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 \(\gamma_2, \ldots, \gamma_{K-1}\) (\(\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 \(\mu = e^{\eta}\), shaped like a binary family's yhat.train - latent.train (and latent.test) - the corresponding draws of the log mean \(\eta = f(x) + c + o\) - shape - the per-draw shape \(r\), 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 \(r\) 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 \(r\) - 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 \(\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 \(\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 \(r\) (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 \(r\), 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\) 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 \(y_i\) at its own natural scale (a \(-\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 \(-\sum_{y_i > 0} \log y_i\)): \(\log(1 - \pi_{s,i})\) where \(y_i = 0\), else \(\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, \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 \mid x)\), the complement of the zero probability other implementations report (brms's hu), so the zero branch is \(\log(1 - \pi)\) rather than \(\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 \(\pi(x)\); the positive part on the scale it fit (\(\log y\) over the \(y > 0\) rows); and the composed natural-scale mean \(E[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.

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.

Author

Hugh Chipman: hugh.chipman@gmail.com, Robert McCulloch: robert.mcculloch1@gmail.com, Vincent Dorie: vdorie@gmail.com.

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)
#> 
#> Running BART with binary y
#> 
#> number of trees: 20
#> number of chains: 1, default number of threads 1
#> tree thinning rate: 1
#> Prior:
#> 	prior on k: chi with 1.500000 degrees of freedom and 2.000000 scale
#> 	power and base for tree prior: 2.000000 0.950000
#> 	use quantiles for rule cut points: false
#> 	level fiber gibbs step: auto
#> 	proposal probabilities: birth/death 0.60, swap 0.00, change 0.40, perturb 0.00, rule_gibbs 0.00; birth 0.50; perturb window 1
#> data:
#> 	number of training observations: 60
#> 	number of test observations: 0
#> 	number of explanatory variables: 2
#> 
#> Cutoff rules c in x<=c vs x>c
#> Number of cutoffs: (var: number of possible c):
#> (1: 59) (2: 59) 
#> Running mcmc loop:
#> total seconds in loop: 0.001190
#> 
#> Tree sizes, last iteration:
#> [1] 3 3 3 4 3 2 2 4 2 1 2 4 4 2 3 3 3 3 
#> 2 4 
#> 
#> Variable Usage, last iteration (var:count):
#> (1: 21) (2: 16) 
#> DONE BART
#> 

## 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)
#> family = "auto": 0/1 response detected, fitting family = "probit"; set 'family' to override
#> 
#> Running BART with binary y
#> 
#> number of trees: 20
#> number of chains: 1, default number of threads 1
#> tree thinning rate: 1
#> Prior:
#> 	prior on k: chi with 1.500000 degrees of freedom and 2.000000 scale
#> 	power and base for tree prior: 3.000000 0.500000
#> 	use quantiles for rule cut points: false
#> 	level fiber gibbs step: auto
#> 	proposal probabilities: birth/death 0.60, swap 0.00, change 0.40, perturb 0.00, rule_gibbs 0.00; birth 0.50; perturb window 1
#> data:
#> 	number of training observations: 60
#> 	number of test observations: 0
#> 	number of explanatory variables: 2
#> 
#> Cutoff rules c in x<=c vs x>c
#> Number of cutoffs: (var: number of possible c):
#> (1: 59) (2: 59) 
#> Running mcmc loop:
#> total seconds in loop: 0.000553
#> 
#> Tree sizes, last iteration:
#> [1] 2 2 2 3 2 1 2 1 1 2 2 1 1 1 2 2 2 2 
#> 1 2 
#> 
#> Variable Usage, last iteration (var:count):
#> (1: 7) (2: 7) 
#> DONE BART
#> 
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)
#> family = "auto": 0/1 response detected, fitting family = "probit"; set 'family' to override
#> 
#> Running BART with binary y
#> 
#> number of trees: 20
#> number of chains: 1, default number of threads 1
#> tree thinning rate: 1
#> Prior:
#> 	prior on k: chi with 1.500000 degrees of freedom and 2.000000 scale
#> 	power and base for tree prior: 2.000000 0.950000
#> 	use quantiles for rule cut points: false
#> 	level fiber gibbs step: auto
#> 	proposal probabilities: birth/death 0.60, swap 0.00, change 0.40, perturb 0.00, rule_gibbs 0.00; birth 0.50; perturb window 1
#> data:
#> 	number of training observations: 60
#> 	number of test observations: 0
#> 	number of explanatory variables: 2
#> 
#> Cutoff rules c in x<=c vs x>c
#> Number of cutoffs: (var: number of possible c):
#> (1: 59) (2: 59) 
#> Running mcmc loop:
#> total seconds in loop: 0.000849
#> 
#> Tree sizes, last iteration:
#> [1] 2 2 2 2 3 3 2 4 2 2 3 2 2 2 2 3 3 2 
#> 2 2 
#> 
#> Variable Usage, last iteration (var:count):
#> (1: 18) (2: 9) 
#> DONE BART
#> 

## 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)
#> estimating the starting sigma by a dense linear regression on 60 rows and 3 columns; see 'sigest'
#> family = "auto": continuous response detected, fitting family = "gaussian"; set 'family' to override
#> 
#> Running BART with numeric y
#> 
#> number of trees: 10
#> number of chains: 1, default number of threads 1
#> tree thinning rate: 1
#> Prior:
#> 	k prior fixed to 2.000000
#> 	degrees of freedom in sigma prior: 3.000000
#> 	quantile in sigma prior: 0.900000
#> 	scale in sigma prior: 0.000970
#> 	power and base for tree prior: 2.000000 0.950000
#> 	use quantiles for rule cut points: false
#> 	level fiber gibbs step: auto
#> 	proposal probabilities: birth/death 0.60, swap 0.00, change 0.40, perturb 0.00, rule_gibbs 0.00; birth 0.50; perturb window 1
#> data:
#> 	number of training observations: 60
#> 	number of test observations: 0
#> 	number of explanatory variables: 2
#> 	init sigma: 0.227728, curr sigma: 0.227728
#> 
#> Cutoff rules c in x<=c vs x>c
#> Number of cutoffs: (var: number of possible c):
#> (1: 59) (2: 59) 
#> forests, sd in the response's units (sd(y) 0.899):
#>   1 forest1: no basis; sd 0.8068 (default)
#>   2 factor(z): factor basis, 2 levels; sd 0.899 between the two levels (default)
#>   trees: 10, 50; 60 in all
#> Running mcmc loop:
#> total seconds in loop: 0.001217
#> 
#> Tree sizes, last iteration:
#> [1] 1 2 2 2 2 2 2 3 3 2 
#> 
#> Variable Usage, last iteration (var:count):
#> (1: 6) (2: 5) 
#> DONE BART
#> 
fit.bcf$n.forests
#> [1] 2
modulatingFit <- dbarts::extract(fit.bcf, type = "forest", forest = 2L)