Bayesian Additive Regression Trees with Extended Response Families
bart.RdBART 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
formulafollowing an analogous model description syntax aslm, including itsoffset()terms and data-dependent terms such aspoly()(seedbarts'sformulaitem), optionally written as a sum offorest()terms, each one forest of a model of several (see ‘Formula Terms’ below). For backward compatibility, can also be thebartBTmatrixx.train(datathen plays the role ofy.train); seedbarts'sformulaitem for the full data-frame-to-predictor mapping, including sparseMatrix::dgCMatrixandsparseFactorcolumns.- data
An optional data frame, list, or environment containing predictors, used together with a formula
formula. For backward compatibility, can also be thebartBTvectory.train.- test
An optional matrix or data frame with the same number of predictors as
data, orformulain 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, whenformulawrites a model of several forests (‘Formula Terms’): an amplitude-coupled fit has no per-observation test replay. A formula whose oneforest()has nobasisis a single-forest fit and takestest.- 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 ofdata, is cut to the same rows (‘Formula Terms’), as is a basis given throughdbarts'sforests =(seeforest'sbasisitem).- 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 classdbartsScaleFallbackWarning. 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'sweightsitem has the figures.subsetdrops rows, and with them their part in the cut points and the response scale. How a weight is read isweights.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, andbartBT'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 forfamily = "ordinal". Afamily = "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 hasNA"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 givenweightsof 0 topredict; anaftfit takes no case weights at fit time, so onlypredict(weights = )reaches a weight of 0 on it, with the same result. A credible band (ci.level) over such a row isNAin 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}\), assimulategivesNaNat a weight-0 row of anlmfit; 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
weightsexpression evaluated onteston 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,NAat 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 thefamilyitem). 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\); thereextract(sample = "test")agrees withpredict(newdata = test)given no weights, where the formula fit's weights name a column oftestthat holds a 0 (both giveNAthere), and on a gaussian, Student-t or aft fit withpredictgiven the test weights.For
predict, the weights of the rows drawn bytype = "ppd", one value or one per row. On a gaussian, Student-t or aft fit they are precisions, a 0 givingNA; underweights.type = "frequency"predicttakes 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 trialsnewdata's response columns give where it carries them, and at one trial where it was fit through the matrix interface (see thefamilyitem); 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, soweights = 1on 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 ofnewdata. With nonewdata, 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 itsNAdraws whenpredictis given no weights. The types that draw nothing read no weight, and a missing weight followsna.action. Afamily = "hurdle.lognormal"fit takes weights of 0 and 1 on both its parts, with the same rows and the same result (see thefamilyitem). Where the fit took its weights from a column of its data on the formula interface (weights = wor an expression of columns, not a vector) andpredictis givennewdatathat hold those columns and noweights, the column is read fromnewdataalone, 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, sopredict(fit, d, type = "ppd")on the training framedequals the same call withweights = 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 underna.pass, givesNAdraws with no warning, every other draw unchanged. A missing weight in the column is answered byna.actionas a missingweightsis.newdatawithout the column, and a fit whose weights were a vector, draw as with noweights: at weight 1, a binomial fit at the trials its response columns give wherenewdatacarry 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 fromtest, or givepredictthe rows withna.action = na.pass.- offset
An additive offset entering the family's mean or link, applied to training data; see
dbarts'soffsetitem for the exact per-family formula. The same concept asbartBT'sbinaryOffset(which only ever applies to that function's probit/logistic default family). Can be missing. A formula'soffset()terms are added to it, as inlm, and a family that refuses an offset refuses them alike.For
predicton abartfit, the offset at the predicted rows: a single value, or one per row ofnewdata. The fit'soffset()terms andoffsetargument are evaluated onnewdata, aspredict.lmevaluates them, and added to it, sonewdatamust then be a data frame carrying their data columns; every other name in them was fixed at its value when fitting. Anoffsetargument given as a plain vector for the training rows applies only to anewdataof as many rows, as inlm; on any othernewdatapredictrefuses unless given anoffset, which takes its place. The same holds forpredicton abartOrdinalfit, whose latent is shifted by the offset before the thresholds are applied, and forsurvivalProbabilities.For
predicton abartMultinomialfit, the same name carries a different shape: the per-category shift at the PREDICTED rows, annrow(newdata)x K numeric matrix entering the K raw fits before the softmax, in the same layout asbart's own train-sideoffsetabove. It is never taken from the fit - these rows are not the fit's rows - so a fit trained with anoffsetREQUIRES 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 reproducesyhat.train. A missing value in one of its rows is governed byna.action(see ‘At Prediction’ inna.keepPredictors); a scalarNAis 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
predicton abartNegbinfit, 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 thebartparagraph above states: the fit'soffset()terms andoffsetargument evaluated onnewdata, and a plain vector for the training rows applying only to anewdataof 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 ofnewdata, and a missing value there is governed byna.action(see ‘At Prediction’ inna.keepPredictors).On a
family = "hurdle.lognormal"fit a plain offset, the argument or anoffset()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, sopredictcan evaluate it onnewdata).offset.testtakes the same forms and defaults tooffset, each element evaluated on the test frame, or reused where the rows match, or refused asking foroffset.test. This differs from pscl'shurdle, wherey ~ x + offset(log(t))reaches both parts: here it reaches the positive part only, and a zero-part offset is writtenoffset = 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 followsna.actionas a missing weight does. Forpredicton abartHurdlefit, each part's recorded offset is evaluated onnewdataand 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 nonewdataan 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
offsetfor test observations (forfamily = "multinomial", an m x K matrix, seefamily). Defaults to theoffsetargument evaluated ontest, aspredictevaluates it onnewdata, plus the formula'soffset()terms evaluated there: a scalar is reused,offset = log(exposure)readstest'sexposure, 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 intestbeforedata, andoffsetnamed in it is the argument's own value, the formula'soffset()terms being evaluated ontestand added to it. Seedbarts'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
lmtakes one. The defaultna.keepPredictorsdrops 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, assurvregandcoxphtake it.NULLapplies no action, as inlm, on the formula and matrix interfaces alike. A row whoseweightsoroffsetis missing is dropped byna.omitandna.excludeon the matrix interface as on the formula one,na.excludepadding it back; every other action leaves it to the refusal of that argument. Seena.keepPredictors.For
predict, what to do with the rows ofnewdatathat have missing values, and, with nonewdata, the training rows whose per-rowoffsetorweightshas one; see ‘At Prediction’ inna.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 thanbartBT's, which always expands every factor into indicator columns;"indicators"instead expands each factor into binary indicator columns, matchingbartBT, 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 asdbarts; 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 acbind(c1, ..., cK)left-hand side, or held as one data-frame column, is read as per-category counts and fit as multinomial (anNAcell marks a missing row, as it does forfamily = "multinomial"). Every resolution of"auto"- gaussian, probit, multinomial, ordinal, aft for aSurvresponse - is reported once per call in a one-line message naming the family fit (suppressed byverbose = FALSE; an explicitly named family prints nothing). An n x 2 matrix under"auto"is an error naming its readings, successes and failures (addfamily = binomial), per-category counts (addfamily = "multinomial") and a (time, status) pair (use aSurvresponse orfamily = "aft"/"hazard"), and so is an n x K matrix with negative or fractional entries. A multinomial response is read alike here and indbarts: 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.bartBTtakes nofamilyargument at all: every fit it makes is the default gaussian/probit pair. Base R family objects map asglmtakes them (binomialis the logit link, sofamily = binomialis"logistic", not probit) and the rest are refused; seedbartsFamilies.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.dbartsFamilieslists 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 = ), andhurdle.lognormal(sigma = )(the positive part's), wheresigmais adbartsPriorsresidual prior,chisq(df, quant)orfixed(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 nosigmaargument 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 asglmwrites 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 asdbartsData(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 tona.action; \(n\) times the row's weight is capped at \(10^6\). The fit reports on two scales, asglmdoes: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, sofitted(type = "ppd")estimates \(n p\) and its residual is \(k - n p\).fit$ykeeps the two columns as written. At new rowspredict(type = "ppd")draws \(\mathrm{Binomial}(w, p)\) with \(w\) from itsweights, as on a 0/1 fit; where no weights are given andnewdatacarries 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 unlesspredictis givenweights, 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 drawsNAunderna.action = na.pass, dropped underna.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, aspredictdoes, 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 inglm'slogLik, 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 asweights, is refused with a message showing thecbindform, 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.xbarttakes the binomial response asbartdoes.family = "multinomial"fits a K-category softmax classifier: K forests, one per category, coupled through an interleaved Polya-Gamma one-vs-rest augmentation. Whenformulais a formula,datais required (not optional as for every other family):bart(y ~ x1 + x2, family = "multinomial", ...)with nodataerrors by name rather than resolvingy/x1/x2from the calling environment.y.trainmust be a factor (or character, coerced withfactor) with at least two levels and noNAlevels; a missing label, or - for the count-matrix form below - a row with anyNAcell, is a missing response, routed throughna.actionexactly as for every other family (seena.keepPredictors);K = nlevels(y.train)is inferred, never given explicitly, andlevels(y.train)is captured at fit time and carried on every K-shaped output (yhat.train's trailing dimension,fitted's columns, thefitted(type = "class")factor). Alternatively,y.trainmay 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 arecolnames(y.train)when present, otherwiseas.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, asglmfits a row of zero prior weight, and the first such row in a session warns; itsresidualsare the negated fitted probabilities (observed 0,glm's response residual there), and itsextract(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 acbind(c1, ..., cK) ~ xleft-hand side (the same idiomglm's binomial family uses) routes to the count-matrix response above,Kand the levels taken from thecbindcolumn names; the right-hand side is coded exactly as it is for every other family's formula fit, includingpredicton a data framenewdata. Under the defaultfamily = "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 (acbind(c1, ..., cK) ~ xleft-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 needsfamily = "multinomial"(or aSurvresponse) to be fit.weightsare observation counts, non-negative whole numbers (see theweightsitem), 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-uniformsplit.probs(a vector ordart()),monotone, andvarianceare 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).offsetis 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-matrixy.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.testtakes an m x K numeric matrix for the mtestrows, in the same column layout asoffset; omitted, it defaults tooffsetwhen the row counts match, and anoffsetbeside atestset of another length is refused by name asking foroffset.test. An explicitoffset.test = NULLmeans no test offset. A reused default is a copy taken at fit time: on a kept sampler, neither$setOffsetnor$setCategoryOffsetmoves it (seedbarts's ‘Test offset synchronization’, which describes a directly built sampler). A data frame is accepted foroffsetandoffset.testalike, 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), forpredict'soffsetas well. A flatoffset.testis refused like a flatoffset, and a missing or non-finite value is refused as inoffset.yhat.testthen carries the test offset and equalspredict's replay attestgivenoffset = offset.test.testis supported: anx.testof the same column structure asx.trainreports the K-category softmax probabilities on the held-out rows asyhat.test, shaped and levels-named exactly likeyhat.train(see ‘Value’).keepTreesis supported too: it retains every one of the K forests' trees sopredictcan replay them at new predictors afterward, reproducingyhat.testbitwise whennewdatamatches the fit-timetest; withoutkeepTrees,predicterrors. A fit trained with anoffsetreplays as well, givenpredict'soffsetat 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);kis 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 theextract/fitted/predictmethods forbartMultinomialobjects.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.trainshould be an ordered factor (is.ordered); its level order defines the category order, andlevels(y.train)is captured at fit time and carried on every K-shaped output. Under the defaultfamily = "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 isis.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 aresort(unique(y.train)).weightsare 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.startandn.grow.sweepsare refused with an error naming the limitation.samplerOnlyis supported, unlike multinomial: it returns the fitted sampler unrun, the same objectfitis underkeepSampler.testandkeepTreesare supported as for multinomial, andpredictreplays the saved trees at new predictors, differencing the cumulative probit at the stored per-draw thresholds.xbartdoes 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\), asMASS::glm.nband Stan'sneg_binomial_2parameterize 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, sofis zero-centered a priori. Under ak-named leaf prior,k.scaleis 3 on the log-mean scale (under ansd-named one it is twice thesd) andkis drawn fromchi(1.5, 2)by default, as for probit; seedbartsPriors.y.trainmust be a non-negative integer count, andfamily = "nbinom"is always explicit - a count carries no unambiguous class, so it is never inferred underfamily = "auto"(a numeric response there stays gaussian). The shaperis 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. Passingshapeas a positive integer fixes \(r\) instead (a real fixed shape is refused). Like probit, there is no residual scale;weightsare 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.startandn.grow.sweepsare refused with an error naming the limitation.samplerOnlyis supported, unlike multinomial: it returns the fitted sampler unrun, the same objectfitis underkeepSampler.testandkeepTreesare supported as for ordinal, andpredictreplays the saved trees at new predictors, reporting mean counts \(e^{\eta}\), withtype = "ppd"drawing at the stored per-draw shape (a log-exposure offset enters \(\eta\) additively).xbartdoes not fit count responses.y.trainis 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"andfamily = "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 sameSurvobject 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 samen.cuts, the period column's included (seen.cuts). The time grid defaults to the sorted distinct observed times of the subjects in the likelihood, those of positive weight (the BARTsurv.bartconvention; every subject's if none is in, under a warning of classdbartsScaleFallbackWarning);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 atbart'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 (classdbartsMemoryWarning) before its rows are built, then runs (seedbartsFamilies). Offsets are on the link scale and replicate per subject;weightsreplicate 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. ASurvresponse requires the family to be requested explicitly (family = "auto"selects"aft"), on either interface - aSurvleft-hand side onformulaworks too, and both interfaces honorsubset(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 atestset, person-period-expanded on the SAME period grid as training (no event time - every subject expands to every period);survivalProbabilitieswithsample = "test"then reads its hazards straight off the fit with nokeepTreesneeded (the call with nonewdatais always the training subjects). Any OTHERnewdatapassed tosurvivalProbabilitiesstill needskeepTrees. The returned object is an ordinary"bart"fit whose$familyrecords the binary link (so every prediction generic transforms correctly with no special case) and whose$periodselement carries the grid;predict/extractreturn the per-(subject, period) hazards on the expanded rows, andsurvivalProbabilitiesproduces 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 namedperiod, or a term that reads it, is refused.predicttakes person-period rows including aperiodcolumn, whilesurvivalProbabilities(newdata = )takes one row per subject.xbartdoes 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 ordinarybartfits 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.trainmust 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.actionsettles 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 defaultpredict/fitted/extractreport 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 adbartsDataobject, as any other fit does. The predictors, the response and the formula are read once, into one data object thatna.actionhas 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.testis taken as on any other family: both parts are evaluated at its rows, andextractandfittedread them withsample = "test", everytypebut"loglik", which needs a response.subsetremoves rows from both parts, as one model frame does inlm(it is applied beforena.action).weightsare 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 hasNApredictive draws (type = "ppd") andNaNlog-likelihood, and its fitted values and residuals are reported. A missing weight is dropped byna.omitandna.excludeon the matrix interface as on the formula one.offset,offset.testandoffset()terms are taken (see theoffsetitem). The positive-part fit is given the trainingxfollowed by the test rows as its ownx.test, so its in-sample fitted values cover the zero rows it never trained on.keepTrainingFits = FALSEis taken where atestset is given: the training fits are dropped, the test draws are those of the default fit, andfitted,residuals,predictwith nonewdata,extract(type = "loglik")andplotthen refuse as a gaussian fit kept so does; without a test set it is refused.predicttakesweightsafteroffset: withnewdata, a 1 draws a row as a new observation and a 0 holds it out (NA); with nonewdata, 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.predictrequireskeepTrees = TRUEand replays both saved forests atnewdata.dbarts()does not fit this family - it composes two samplers, which onlybart()builds, so requesting it there is an error directing here.xbartdoes 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 ownextract/fitted/predict/residuals/printmethods. Both parts take the oneleaf.prior, so a leaf prior namingsdis 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 defaultk. Namek, 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 ownsd- which is the same posterior, the parts being independent.- weights.type
How
weightsare read. Under"precision"a weight scales a row's residual variance, \(y \mid x \sim N(f(x), \sigma^2 / w)\), aslmreads 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:family NULL reads "precision""frequency"gaussian, student, a variance forestprecision taken, real \(w \ge 0\) taken, real \(w \ge 0\) logistic, hazard.logistic, nbinom, multinomial frequency, counts refused whole \(w \ge 0\) probit, hazard, hazard.probit, ordinal frequency, membership refused 0 and 1 only hurdle.lognormal frequency, membership refused 0 and 1 only aft precision, no weights no weights refused Under
"frequency"on a gaussian-type fit, the starting sigma (sigest) is the residual sd of the regression on the rows written out, its degrees of freedom the total weight less the regression's rank, a total within rounding of the rank leaving none, the sd stand-in a weighted one (unweighted where the counts total at most 1); the residual scale's posterior counts \(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; andpredicttakes 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:$setModelcannot change it, and$setWeights,$setDataandpredictread 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, orsd(y)over the observations of positive weight where the counts total at most 1, up to the rounding of their sum), which a line underverboseand one in the fit'ssummarysay, 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 classdbartsScaleFallbackWarning.)"auto"islm'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 explicitNAreads asNULLfor one release, with a once-per-session warning.dbartssays 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 isfamily = gaussian(sigma = chisq(df, quant)), whosequantis 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 retiredresid.prior,sigdfandsigquant, which such a family overwrites withfixed(1)regardless. Same concept assigestindbartsandxbart. It is the estimate achisqresidual prior's quantile is calibrated against, so it stands besidefamily = gaussian(sigma = chisq(df, quant))and has nothing to calibrate besidefamily = gaussian(sigma = fixed(value)), which fixes the residual scale outright: no estimate is made there, by any rule, the fit reports the square root ofvalueas itssigest, 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'sdata, 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, unlesssigeststates a number;dbartsSpecreads a data object the same way, and a sampler'scopy()is the way to the same model again.- k
For numeric \(y\),
kis 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,kis 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 formchi(df = 1.5, scale = 2);k = Infholds every tree at zero, so the fit is the offset, plus on a continuous response the center of the rangey - offsetspans. The spread can instead be named on the family's own scale,leaf.prior = normal(sd = ); seedbartsPriors. The default,NULL, uses the value 2 for continuous responses and thechi(1.5, 2)hyperprior for binary and"nbinom"ones, which centers the sampledknear the field-standard fixed value of 2 (prior median 1.9) while adapting to the data; passk = 2for the fixed BART-package default, orchi(1.5, Inf)for the old improper prior. SeebartBT'skitem, and the ‘Leaf prior parameterk’ 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 nobasisstating nosd, or the group's where two or more share one total; where every forest with nobasisstates one it is refused unless it is the default (see ‘Formula Terms’). A writtenNULLis 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 andsplit.probs;barttakes notree.prior, and given one says what to write. Both are honored on every family, including both component fits offamily = "hurdle.lognormal". In a model of several forests they are those of the forest with nobasis; see ‘Formula Terms’. A writtenNULLis 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), ordart()fromdbartsPriors, 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,.defaultgiving the rest, and is refused when it leaves a column with no value, a single named value included. A model of several forests, andfamily = "multinomial", take a uniform vector and refuse any other, ordart(), by name. These are the mean forest's alone: a variance forest takes none.- leaf.prior
The full
dbartsleaf prior object, forwarded unevaluated so a baredbartsPriorsvocabulary name inside it (normal,linear,gp) resolves exactly as it does fordbarts:leaf.prior = linear(columns = 1:3)andgp(...)are reachable this way.NULL(the default) instead builds the leaf prior fromk. Supplying an object alongsidekis an error naming both. It is honored on every family, including both component fits offamily = "hurdle.lognormal", except that a leaf prior namingsdis refused there (seefamily). 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)); seefamilybelow. In a model of several forests it is that of the forest with nobasisstating nosd, taken as one forest takes it: see ‘Formula Terms’. Where two or more share one total it is that total,normal(sd = )its size andkor achi()prior onkitsk, one for the group.forest(sd = )is one forest's own size, in the response's units, and where every forest with nobasisstates one akorsdhere is refused, the default restated taken. A writtenNULLis the argument left out.- monotone
Optional per-predictor monotonicity constraints, passed through to
dbarts; see itsmonotoneargument. Amonotonespecification, or itsdirectionsalone at the default prior,"joint": a named vector selects predictors by model-matrix column name, each direction"increasing"or1,"decreasing"or-1, or0for unconstrained - matching is case-sensitive; only numeric and ordered columns are eligible. A constraint forces birth/death-only proposals and a fixedk, 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; seedbartsForests.- interactions
Optional interaction constraints, passed through to
dbarts; see itsinteractionsargument andinteractions. Built withinteractions(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; seedbartsForests. In a model of several forests it constrains the forest with nobasis; see ‘Formula Terms’.- blocks
Optional block-additive constraint, passed through to
dbarts; see itsblocksargument andblocks. Built withblocks(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; seedbartsForests. In a model of several forests it constrains the forest with nobasis; 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,TRUEfor every predictor, a one-sided formula (~ x1 + x2) read exactly asvarianceForest()reads its first argument (terms matched to the fit's predictors, the dot and transformed terms taken,*,:andI()terms refused), orNULL(the default),FALSE, an empty selection (character(0),integer(0),logical(0)) or~ 1for a homoscedastic fit - or avarianceForest(vars = , n.trees = , base = , power = )object, which additionally sets the variance forest's own tree count and tree-structure prior (defaulting to40trees and the mean forest'spowerandbase, 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 (seedbarts). The fit gainss.train/s.test(posterior draws of \(s(x)\)), andpredictattaches an"s"attribute carrying \(s(x)\) for new data: its draws, or underci.levelits estimate and credible band per row, as the value carries. \(s(x)\) is the residual scale the reporting channels use:extract(type = "loglik"), thetype = "ppd"draws, andsummary.bart'smean.srow all read it, andextractandpredictreturn it astype = "sigma"; such a fit has no scalarsigma, and carries nosigmaorfirst.sigma(seedbarts). 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; seedbartsForests.
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 writtenNULLis refused, saying to leave the argument out for its default.- n.samples
The number of posterior samples requested;
n.samples %/% n.thindraws are actually kept and returned. This is a SWEEP budget in the BayesTree tradition - the same rolebartBT'sndpostplays (ndpost / keepeveryare what is actually returned). It differs fromdbartsControl's (and the lower-leveldbarts's)n.samples, which already counts the draws onerun()call returns and is NOT divided by thinning: that layer's sampler can berun()repeatedly with a different count each time, so itsn.samplesis 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 aboven.chainsbuys the sampler's own sweep nothing. The surplus still feeds the test-fit pool andpredict's own fan-out, and a fit warns once, naming both counts, when an explicit budget exceeds the chain count. Defaults toguessNumCorescapped atn.chains, or to one where the cores cannot be counted; a statedNAis refused.On
predict,n.threadsis 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. DefaultTRUE, as forbartBT; the number of chains is tracked regardless on the returned object'sn.chainscomponent (see ‘Value’). Onextract,predictandsurvivalProbabilities,FALSEkeeps that leading chains margin - length 1 on a one-chain fit - rather than dropping it there; seebartBT'scombinechainsitem.- n.cuts
The maximum number of possible values used in decision rules (see
useQuantiles, andbartBT's ‘Decision Rules’ details). A single number applies to every column; a vector gives one per column, in their order, or, named assplit.probsis, reads by column or term name with.defaultfor the rest, soc(x1 = 10, .default = 50)givesx110 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 ownperiodcolumn, 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. WhenFALSE, splits are determined using values equally spaced across the range of a variable, or, for a variable with fewer distinct values thann.cuts, half-way between neighboring values, each chosen in proportion to its gap's width. SeebartBT's ‘Decision Rules’ details.- n.thin
Every
n.thindraw is kept to be returned to the user. Useful for “thinning” samples against serial correlation; seen.samplesabove 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 incontrol, if any; an explicitNAis a missing value, as inset.seed: it reads asNULLfor one release, with a once-per-session warning. Aset.seedbeforehand suffices for reproducibility when nothing ends up seeded; supplyingseedinstead 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
bartobject fit withkeepSampler = TRUEor adbartsSampler-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. Underblockseach 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. Withverbose = TRUEone 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 itssigmaandkwhere this fit draws them, carry over: the fit runs under its own prior and fixed values, the donor's leaf values, linear slopes,kandsigmago 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-zeron.burn. Multi-forest samplers refuse it: a fit whose forests carry amplitude bases (aforest()term, or a data object built withbases) errors by name, naming its forest count, because a donor install is not tested at more than one forest;n.grow.sweepsis the initialization such a fit can take. SeedbartsSampler-class'sinstallTreesmethod for finer control.- n.grow.sweeps
A non-negative integer; when positive, the initial forest is built by
n.grow.sweepssweeps 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 default0Ldraws trees from the prior, exactly as before. Likewarm.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 withwarm.start(both request an initialization). Unlikewarm.startit is available on a multi-forest fit, each forest grown against its own residual inside the sweep. SeedbartsSampler-class'sgrowFromRootmethod.- samplerOnly
Builds the sampler from its arguments and returns it without running it. Useful to use the
bartinterface in more complicated models. A fit draws its starting trees from the prior before it runs; to run the returned sampler asbartwould at the same seed, call$sampleTreesFromPrior()before$run().
Output.
- keepTrainingFits
If
TRUEthe 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
printEverydraws.- 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
FALSEsuppress printing, including the one-line messagefamily = "auto"prints naming the family it resolves to (a message of classdbartsAutoFamilyMessage).- keepTrees
A fit that keeps its trees stores its sampler's state at the end of the fit, so a fit saved with
saveRDSand read back predicts as the original did; a user who runs the kept sampler further callsfit$fit$storeState()again before saving (seebartBT's ‘Saving’ section). Logical; must beTRUEin order to usepredictwith the result of a fit.NULL, the default, keeps the trees on a hazard fit, whose survival curves need them, and not otherwise;TRUEorFALSEis taken as given, andkeepSamplerfollows 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 whatpredictat new data replays and whatprintreads its settings from (the tree count andn.burn); every other method, andpredictwith nonewdata, reads the draws stored in the fit, andprintcounts those. Running the kept sampler further, or giving it another control, is not a supported use of the fit:predictat 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 hascallset toNULL, as a base R fit without a call has, soupdaterefuses it; otherwise the call used to instantiate BART.- keepSampler
Logical that can be used to save the underlying
dbartsSampler-classobject even ifkeepTreesis false. The methods read it askeepTreesdescribes:predictat new data andprint'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; abartformal. A character string selecting the precision of the internal running residual; seedbartsControl'sstoragefor 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 manysamplermethods with regards to the immediate updating of the cached state of the object; seedbartsControl'supdateState.- keepFits
Passed through to
dbartsControl. A logical over EVERY per-observation channel (training, test, heteroscedastic variance, per-forest) at once, defaulting toTRUEexcept that it becomesFALSEautomatically whenevercallbackis supplied andkeepFitsis not itself named - an explicitkeepFitsalways wins, sokeepFits = TRUEtogether withcallbackkeeps every channel while still firing the hook.keepTrainingFitsis 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. SeedbartsControl'skeepFitsfor whatFALSEcosts the returned object.multinomial,ordinal,nbinom, andhurdle.lognormalrequirekeepFits = TRUE(their packaging reads the training channel) and refuse an automatic or explicitFALSEby name.- callback
NULL(the default, no hook) or a list with two elements,fnandcontext, each an R external pointer (externalptr):fnthe address of a compileddbarts_draw_callback(inst/include/dbarts/dbarts.h) andcontextan opaque pointer handed back to it unchanged, orNULL. 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: seevignette("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 totryCatch. An interrupt (Ctrl-C) cannot land while a call is running, so a callback that blocks or loops hangs the session. And the automatickeepFits = FALSEthis argument triggers means a fit built with only the default settings and acallbackreturns NO fitted values at all (noyhat.train, noyhat.test, ...) - whatever the callback itself accumulated is the only answer, unlesskeepFits = TRUEis also given explicitly. Onfamily = "hazard"/"hazard.probit"/"hazard.logistic", the draw struct'snumObservationscounts 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
dbartsControlobject carrying the sampler and engine settings, including the onesbartspells no flat name for:categoricalExhaustiveCap,testFitParallelCutoff,predictParallelCutoff,sparseDensityThreshold,treeShift, and the tree-move mixtureproposal.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 owndbartsControl()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/bartHurdlemethods 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. Onbartitself...is instead the transition release's retired-spelling channel, as ondbarts: a retired name (resid.prior,sigdf, andsigquant, which ridefamily, built withgaussian(sigma = chisq(df, quant))orgaussian(sigma = fixed(value));proposal.probs, which ridescontrol, built withdbartsControl(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, orbartHurdle, returned bybartunder the correspondingfamily; forsigmaandnobs, any fitbartreturns, of classbarttoo.- 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 (orNULL),predictreturns eachtypeat the training rows from the draws the fit stored, asextractwithsample = "train"does, on every family's fit and without saved trees; anoffsetgiven 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, aspredict.lmrefuses it.- type
The quantity to return; see ‘Value’ below for what each family's generics accept and produce. As on a
"bart"fit (bartBT'stypeitem),"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 isextract's own argument, andfitted's too on every family with a test channel - onbartHurdlethe test channel is the rows of atestset, and a fit given none refusessample = "test"; refused by name onpredict, whose stored train and test channels areextract'ssampleinstead. 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"onbartOrdinal,"shape"onbartNegbin- 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 (seebartBT's ‘Leaf prior parameterk’)."sigma"is 1 on every one of these families butbartHurdle, whose"sigma"is its positive part's, and"k"and"leaf.prior.sd"on abartHurdleare lists of its zero and positive parts.- vars
Character vector of fields to gather, as
summary.bart's ownvars; requested fields absent fromobjectare silently dropped.NULLisvarsleft out, the default fields.summary.bartOrdinal's"thresholds"contributes one draws variable per sampled threshold \(\gamma_2, \ldots, \gamma_{K-1}\), the ordinal analog ofsigma(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 ofsigma.summary.bartHurdleappliesvarsseparately to its$zeroand$positivecomponent fits.summary.bartMultinomialhas novarsformal at all: it always pools the per-category mean-probability channel (its only scalar convergence instrument), so a suppliedvarsis refused by name rather than silently ignored; its table is that channel alone, and a line under it names thekthe fit held fixed.- x
An object of one of the four own-class families (
bartMultinomial,bartOrdinal,bartNegbin,bartHurdle), as returned bybartunder the matchingfamily, forprint/plot; an object of classsummary.bartHurdle, as returned bysummaryon abartHurdlefit, forprint.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. Forplot.bartNegbin/plot.bartHurdle: two colors, asbartBT's owncolsitem - the first for a posterior interval's bars, the second for the reference line.- plquants
For
plot.bartOrdinal/plot.bartNegbin/plot.bartHurdle/plot.bartMultinomial, asbartBT's ownplquantsitem: the lower and upper quantiles bounding each posterior-interval panel's bars.- ci.level
For
fitted/predicton abartMultinomial,bartOrdinal, orbartNegbinfit, asbartBT's ownci.levelitem. On a K-marginedtype("ev"/"ppd"for the first two), the result keeps the category margin: an (observation \(\times\) K \(\times\) 3) array ofest/ci.lower/ci.upperrather than a 3-column matrix, since categories are not poolable. On a non-K-marginedtype("bart"; any type forbartNegbin) the result is the ordinary 3-column matrix.bartHurdle'sci.levelis documented underbartBTdirectly, since it never carries a K margin. Refused, by name, onresiduals(asbartBT's ownci.levelitem); onbartMultinomialandbartOrdinalalso refused, by name, withtype = "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 eachA 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 byrun(0, 20)matchesrun(50, 40)bitwise.storeState()(whatsaveneeds) andsetState()(what restores it, including afterload) 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 statestoreState()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 differentseedfor 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 firstsetState()call - exactly as building a new unseeded sampler would. A seeded sampler never touches R's stream this way.A
bartfit made withkeepTrees = TRUEdoes not store its sampler's state automatically: callfit$fit$storeState()before saving so a reload canpredictand 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)