Skip to contents

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

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

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

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

Usage

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

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

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

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

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

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

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

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

Arguments

x.train

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

y.train

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

x.test

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

sigest

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

sigdf

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

sigquant

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

k

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

power

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

base

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

splitprobs

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

binaryOffset

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

weights

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

ntree

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

ndpost

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

nskip

Number of MCMC iterations to be treated as burn in.

printevery

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

keepevery

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

keeptrainfits

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

usequants

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

numcut

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

printcutoffs

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

verbose

Logical; if FALSE suppress printing.

nchain

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

nthread, n.threads

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

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

combinechains, combineChains

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

keeptrees

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

keepcall

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

seed

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

proposalprobs

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

keepsampler

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

object

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

newdata

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

offset

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

sampleronly

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

x

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

plquants

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

cols

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

type

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

sample

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

forest

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

bases

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

contribution

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

na.action

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

ci.level

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

...

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

Details

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

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

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

Decision Rules

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

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

Leaf prior parameter k

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

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

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

Generics

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

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

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

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

Saving

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

Reproducibility

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

Extracting Trees

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

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

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

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

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

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

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

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

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

Value

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

call

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

yhat.train

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

yhat.test

Same as yhat.train but now the \(x\)s are the rows of the test data.

yhat.train.mean

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

yhat.test.mean

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

sigma

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

first.sigma

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

varcount

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

varprobs

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

forestFits, glue, bases

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

basis.columns

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

n.forests

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

row.names.train, row.names.test

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

sigest, sigest.fallback

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

resid.scale, resid.df

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

y

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

fit

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

n.chains

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

k

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

first.k

Burn-in draws of k, if modeled.

leaf.prior

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

fixed

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

binaryOffset

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

offset

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

offset.test

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

family

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

family.spec

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

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

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

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

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

References

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

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

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

Calling extract

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

Author

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

See also

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

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

pdbart

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

Examples

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

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

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

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

## run BART
set.seed(99)
bartFit <- bartBT(x, y)
#> estimating the starting sigma by a dense linear regression on 100 rows and 10 columns; see 'sigest'
#> 
#> Running BART with numeric y
#> 
#> number of trees: 200
#> 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.002181
#> 	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.50, swap 0.10, change 0.40, perturb 0.00, rule_gibbs 0.00; birth 0.50; perturb window 1
#> data:
#> 	number of training observations: 100
#> 	number of test observations: 0
#> 	number of explanatory variables: 10
#> 	init sigma: 2.756573, curr sigma: 2.756573
#> 
#> Cutoff rules c in x<=c vs x>c
#> Number of cutoffs: (var: number of possible c):
#> (1: 100) (2: 100) (3: 100) (4: 100) (5: 100) 
#> (6: 100) (7: 100) (8: 100) (9: 100) (10: 100) 
#> 
#> Running mcmc loop:
#> iteration: 100 (of 1000)
#> iteration: 200 (of 1000)
#> iteration: 300 (of 1000)
#> iteration: 400 (of 1000)
#> iteration: 500 (of 1000)
#> iteration: 600 (of 1000)
#> iteration: 700 (of 1000)
#> iteration: 800 (of 1000)
#> iteration: 900 (of 1000)
#> iteration: 1000 (of 1000)
#> total seconds in loop: 0.121901
#> 
#> Tree sizes, last iteration:
#> [1] 2 3 3 2 2 2 2 2 4 2 3 3 3 1 2 1 2 3 
#> 2 2 4 2 2 3 3 2 2 2 2 3 2 2 2 1 3 3 2 2 
#> 2 2 3 4 2 2 2 4 3 2 2 3 1 2 3 2 2 3 3 2 
#> 3 2 2 2 2 3 2 2 3 2 2 2 2 2 2 2 2 3 2 2 
#> 2 2 2 2 3 5 2 2 3 2 2 2 1 3 2 2 2 3 2 2 
#> 1 2 5 1 3 3 3 4 2 2 2 2 3 2 2 2 2 2 2 1 
#> 2 4 2 2 2 2 3 2 2 2 2 4 2 2 3 2 2 2 2 3 
#> 2 3 2 2 2 2 2 1 2 4 4 3 2 4 4 3 2 1 2 3 
#> 3 4 3 2 3 2 2 2 2 2 2 4 2 3 2 3 3 2 2 2 
#> 3 2 2 3 2 2 2 4 4 2 3 1 3 2 2 2 1 3 2 4 
#> 2 2 
#> 
#> Variable Usage, last iteration (var:count):
#> (1: 34) (2: 29) (3: 29) (4: 30) (5: 25) 
#> (6: 25) (7: 36) (8: 21) (9: 28) (10: 16) 
#> 
#> DONE BART
#> 

plot(bartFit)


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

fitmat <- cbind(y, Ey, lmFit$fitted, bartFit$yhat.train.mean)
colnames(fitmat) <- c('y', 'Ey', 'lm', 'bart')
print(cor(fitmat))
#>              y        Ey        lm      bart
#> y    1.0000000 0.9847984 0.8841787 0.9984931
#> Ey   0.9847984 1.0000000 0.9009389 0.9886903
#> lm   0.8841787 0.9009389 1.0000000 0.8975062
#> bart 0.9984931 0.9886903 0.8975062 1.0000000

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

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

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

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