Discrete Bayesian Additive Regression Trees Sampler
dbarts.RdCreates a sampler object for a given problem which fits a Bayesian Additive Regression Trees model. Internally stores state in such a way as to be mutable.
Usage
dbarts(
formula, data, test, subset, weights, offset, offset.test = offset,
verbose = FALSE, n.samples = 800L,
power = 2, base = 0.95, split.probs = NULL, leaf.prior = normal,
monotone = NULL,
interactions = NULL,
blocks = NULL,
variance = NULL,
forests = NULL, n.trees = NULL,
control = dbarts::dbartsControl(), sigest = NULL, seed = NULL,
factors = c("categorical", "indicators"),
n.cuts = NULL, useQuantiles = NULL,
family = c("auto", "gaussian", "student", "probit", "logistic", "aft",
"multinomial", "ordinal",
"nbinom", "hazard", "hazard.probit", "hazard.logistic"),
weights.type = NULL,
na.action = dbarts::na.keepPredictors,
sigma = NULL, node.prior = NULL, tree.prior = NULL, callback = NULL, ...)Arguments
- formula
An object of class
formulafollowing an analogous model description syntax aslm. As inlm, anoffset()term is added tooffsetand is evaluated ontest(seeoffset.test), and a data-dependent term such aspoly(),splines::ns()orscale()is rebuilt ontestand onpredict'snewdatafrom the training values, aspredict.lmrebuilds it. A fit stores these terms, and theoffsetexpression, without an environment: a name that is a column ofdatais read from the new rows alone, and every other name is fixed at its value when fitting, so a fit carries no frame of the function that made it. A formula calling a function from no package, such as one defined in the session, is refused, naming it. For backwards compatibility, can also be thebartBTmatrixx.train, whose integer and logical values are taken as numbers, as in a data frame, including a sparseMatrix::dgCMatrix(any other sparseMatrixclass, or asparseVectoras one column, is converted to one, and a denseMatrixis taken as a plain matrix): its columns enter as ordinal predictors, sufficiently sparse columns are stored in a compact rank-bitmap layout instead of being expanded, and the predictor-mutation surface accepts both whole-matrix replacement,setPredictor(x), and the column-granularsetPredictor(x, column = j), which replaces a sparse column whole; a replaced sparse-backed column stays sparse, storing only the replacement's nonzeros, and a replacement's sparse columns are never expanded. Per-observation replacement of a sparse-backed column, andsetData, are fixed at creation. Sparse inputs are not supported by theleaf.prior = linear()andgp()leaf models (a sparse-backed test column cannot serve a designated leaf covariate either). A sparse or data-frame test set stays resident (rank-bitmap or dense per column, the same rule as training) rather than densifying at ingestion - a test set of any other sparseMatrixclass, such as adgTMatrix, as thedgCMatrixit holds - andpredictandgetTrees(newdata = )route its rows through the trees off that storage rather than densifying it either. A data frame may mix ordinary columns withMatrix::sparseVectorordgCMatrixcolumns (assign them into the frame; they do not survivedata.frame(...)orI()): sparse columns behave as in an all-sparse design, while dense columns keep categorical splits and linear-leaf designation. AsparseFactorcolumn is accepted here (the x/y, data-frame path) exactly as the other sparse columns are; aformulaobject accepts one too, named like any other column (including through.), sincedbartsDatalifts it out ofdataahead ofmodel.frame(which cannot carry it) and re-attaches it to the assembled predictor matrix afterward. SeedbartsDatafor the full data-frame-to-predictor mapping.- data
An optional data frame, list, or environment containing predictors to be used with the model. For backwards compatibility, can also be the
bartBTvectory.train. The response, however supplied, is checked for near-degeneracy at double precision and warns when too few distinct values remain to fit against.- test
An optional matrix or data frame with the same number of predictors as
data, orformulain backwards compatibility mode. If column names are present, a matching algorithm is used; when both are named,test's names must coverdata's (an error otherwise), and a data frametestmay carry other columns, which are ignored, as for a formula fit (a matrix keeps its exact width); an unnamedtestis read in the order ofdata's columns, with no message, and a namedtestgiven to an unnameddatais matched by position with a warning.- subset
An optional vector specifying a subset of observations to be used in the fitting process. Each argument that holds rows, the first argument,
data,test,subset,weightsandoffset, is evaluated once for a fit, the first argument beforedata. So an expression that draws its rows, asdata = d[sample(nrow(d)), ],subset = sample(n, 100)or the pairdbarts(x[i <- sample(n, 100), ], y[i]), gives the response, the predictors, the weights, the offset and every forest's basis the same rows.- weights
An optional vector of weights to be used in the fitting process. For a gaussian response, BART fits a model with observations \(y \mid x \sim N(f(x), \sigma^2 / w)\), where \(f(x)\) is the unknown function; under
weights.type = "frequency"a row of weight \(w\) is instead \(w\) identical observations (see that item). Binary responses differ: a"probit"model does not support a weighted likelihood (a weighted probit has no tractable latent-variable form), except that weights identically 1 are treated as absent. A"probit"or"ordinal"fit does accept weights that are all 0 and 1, as does an"nbinom"fit: those name the rows in the data set rather than a precision, are held in the data object's weights slot and compose with the sampler's active-row mask, a row being in when its weight is 1 and the mask keeps it; a 0 row leaves the likelihood but keeps its leaf occupancy, its latent and its fitted value. For"nbinom"the leaf prior's center, the log of the total count over the total exposure, is taken over the rows in, each counted its weight's number of times, as a gaussian or Student-t fit's response transform is taken over the rows of positive weight (an"aft"fit takes no weights, so every row is in when it is created). A"logistic","nbinom"or"multinomial"model differs again: it treats them as observation counts and so requires non-negative whole numbers, a count of 0 leaving the row out of the likelihood as on every family (its Polya-Gamma latent for a count \(w\) is a sum of \(w\) unit draws, so a sweep's time grows with the total count, and a count times the row's trials, \(y + r\) or row total above \(10^6\) is refused); an"nbinom"exposure belongs in the offset, not in a weight. A weight of 0 takes an observation out of the likelihood and out of the residual degrees of freedom but not out of the design: the row still occupies a leaf, which the trees may split around, and still receives a fitted value, so the fit is close to the fit on the remaining rows without being that fit (see theweightsitem ofdbartsSampler;subsetdrops rows). A row of weight 0 takes no part in the response's scale, which the leaf prior is stated against, in the center of a count fit's leaf prior, or in the default sd of a forest in a model of several forests: they are taken over the rows of positive weight when the sampler is created. The step is at 0 and not at a small weight, and weights or a mask set after creation leave the numbers creation set, so the three ways to leave a row out - weights or a mask at creation, weights or a mask set later, andsubset- 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. It is warned about unless every weight is 0 or 1 - a vector of nothing but those states which rows are in the data set, and is the membership a"probit","ordinal"or"nbinom"fit takes; the same class coversweightsgoing unused fortest- when the model is not specified as a formula, and whenweightsnames a columntestdoes not carry.- offset
An optional vector specifying an offset from 0 for the relationship between the underlying function, \(f(x)\), and the response \(y\). Useful for both response families, though the two apply it differently. For a gaussian response, \(y = f(x) + \mathrm{offset} + \epsilon\): the offset is netted out of \(y\) before BART's internal range-scaling (see ‘Details’), so it acts as a fixed component of the mean rather than a free parameter. For binary responses it enters the link directly: a
"probit"fit assumes \(P(Y = 1 \mid X = x) = \Phi(f(x) + \mathrm{offset})\), where \(\Phi\) is the standard normal cumulative distribution function, and a"logistic"fit the analogous model on the logistic link.- offset.test
The equivalent of
offsetfor test observations. By default the expressionoffsetwas given as is evaluated ontest, aspredict.lmevaluates it on new data: a scalar is reused, and a vector given for the training rows applies only to a test set of as many rows, any other length refused. Given explicitly, it is a single number or one value per row oftest, any other length refused, and a bare name is looked up intestbeforedata. A formula'soffset()terms are evaluated ontest, which must then be a data frame carrying their variables, and added to it.- verbose
A logical determining if additional output is printed to the console, including the one-line message
family = "auto"prints naming the family it resolves to (a message of classdbartsAutoFamilyMessage, whichsuppressMessagesor a calling handler can mute on its own). SeedbartsControl.- n.samples
A non-negative integer (
0accepted) setting the default number of posterior samples to be returned for each run of the sampler. Can be overriden at run-time. SeedbartsControl'sn.samplesitem for the full contract.- power, base
Real numbers setting the tree prior's probability that a node at a given depth splits, \(base / (1 + depth)^{power}\), as in
bart. In a model of several forests they are the tree prior of the forest with nobasis, and a forest states its own on the forest, asforest(x1, power = 3); stating one on both the function and that forest is refused, as forn.trees. Seeforests. 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). 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 column of split probability zero is never split on, just as one a forest'svarsleaves out is never split on. A model of several forests, andfamily = "multinomial", take a uniform vector and refuse any other, ordart(), by name. The mean forest's alone: a variance forest takes none.- leaf.prior
An expression of the form
normalornormal(k)that sets the prior used on the leaf values, or a prior object built withdbartsPriors.linear(columns, k)instead fits each leaf with an intercept plus a linear term in the designated continuous predictor columns (character names or numeric indices into the model matrix), standardized internally, all coefficients sharing thenormal(k)prior. Each covariate is centered and scaled by its mean and standard deviation over the rows in the likelihood when the sampler is created, those of positive weight, each counting in full, or over every row, under one warning, where fewer than two are in (subjects, for a hazard fit, however many periods they span) or where the response's scale is read from every row because the rows in hold fewer than two distinct values of it; the numbers are held from then on,gp's default lengthscale with them. A covariate those rows hold at one value, or observe at none, a constant column among them, is refused, since no scale can be taken from it, unless itsgpleaf stateslengthscale: it is then centered at that value and divided by 1. One whose values there have a spread about their center under 64 times machine precision of their size (||z - center|| < 64 * .Machine$double.eps * ||z||), such as 0.3 beside0.1 * 3, is read as one value, here and wherever a setter derives the center and scale again, and centered at its mean where it takes the placeholder. Values meant to be equal are fixed only by dropping the column; values that truly differ but sit at a large offset, a time in seconds since 1970 varying by under about a tenth of a millisecond say, are fixed by recomputing the column from its source about an origin near its values, since subtracting a constant from the stored values restores no digit they have lost; unordered factor columns cannot be designated.gp(columns, k, lengthscale, max.leaf.size)fits each leaf with a smooth Gaussian-process function of the designated columns under a squared-exponential kernel; leaves larger thanmax.leaf.sizefall back to constant fits. An ordered factor may be designated under either, and enters as its level codes 1, 2, and so on, which treats its levels as equally spaced, as the linear contrastlmgives an ordered factor does; levels spaced otherwise need a numeric column holding their scores.xbartaccepts the same specifications through its ownleaf.priorargument. See “Response scaling” below for howkinteracts with the response's internal scaling. In a model of several forests it is the leaf prior of the forest with nobasisstating nosd, taken as one forest takes it; seeforests. A forest states its own size asforest(x1 + x2, sd = 2), in the response's units asnormal(sd = )is, and where every forest with nobasisdoes akorsdhere is refused, the default restated taken. The one forest of a model of one forest states its size either way,forest(sd = )being this prior'snormal(sd = ), and not at both. A writtenNULLis refused, saying to leave the argument out for its default.- monotone
Optional per-predictor monotonicity constraints (monotone BART; Chipman, George, McCulloch, and Shively 2022). The forest is constrained so that the fitted function is monotone increasing or decreasing in each named predictor. Supply a
monotonespecification,monotone(directions, prior = ), or itsdirectionsalone, shorthand for the default prior,"joint": a named vector selecting predictors by model-matrix column name, each element"increasing"or1,"decreasing"or-1, or0for unconstrained - matching is case-sensitive; an unnamed vector of length equal to the number of columns assigns directions positionally. Only numeric and ordered columns are eligible - a direction on a categorical (unordered factor) predictor is an error. A constraint forces birth/death-only tree proposals (acontrolnaming a non-defaultproposal.probsis then an error) and a fixed leaf scale,k = 2unless another number is given (akorsdhyperprior is an error); linear and Gaussian-process leaves are not supported under the constraint.NULL(the default) or an all-zero vector fits the ordinary unconstrained model. The constructor resolves by bare name inside this argument, whatever the caller has attached, and a bare name the caller has bound to a value is that value; seedbartsForests.- interactions
Optional interaction constraints, built with
interactions:interactions(max.order = 2)caps the number of distinct predictors that may appear together on any single root-to-leaf path,interactions(forbid = list(c("a", "b")))bars named predictors from ever sharing a path, andinteractions(groups = list(c("a", "b"), "c"))confines interactions to declared groups (named predictors may co-occur only with their group-mates). The three may be combined. Named or indexed predictors resolve against the model matrix at fit time, where an unknown name, an empty group, amax.orderbelow 1, or a reference to a dropped column is an error.NULL(the default) fits the ordinary unconstrained model. The constructor resolves by bare name inside this argument, whatever the caller has attached, and a bare name the caller has bound to a value is that value; seedbartsForests. In a model of several forests it constrains the forest with nobasis; seeforests.- blocks
Optional block-additive constraint, built with
blocks:blocks(groups = list(c("a", "b"), "c"))confines each whole tree to one declared group of predictors, so the ensemble is exactly a sum of per-group functions (a functional-ANOVA / grouped-GAMI decomposition). Unlikeinteractions(groups = ), which is a per-path allow-list, this is a static per-tree mask, so the groups must form a total, disjoint partition of the predictors - every predictor named exactly once.trees.per.groupoptionally fixes how many trees each group gets; otherwise the trees are spread as evenly as possible. Validated at fit time (an unpartitioned or doubly-named predictor, or atrees.per.groupthat does not sum ton.trees, is an error).NULL(the default) fits the ordinary model. May be combined withinteractions. Seeblocks. 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; seeforests.- variance
Optional heteroscedastic variance forest (HBART; Pratola, Chipman, George, and McCulloch 2020). When supplied, a second ensemble models the residual variance surface \(s^2(x)\) as a product of scaled-inverse-chi-squared (multiplicative) leaves, so \(y_i = f(x_i) + s(x_i)\epsilon_i\), coupled to the mean forest through the per-observation precision.
varianceis either the plain selector naming which predictors drive the variance - a character or integer 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) orFALSEfor the ordinary homoscedastic fit, as do an empty selection (character(0),integer(0),logical(0)) and the formula~ 1, which name no predictor (varianceForest(~ 1)and~ 0are refused) - or avarianceForestobject, which additionally sets the variance forest's own tree count (default40) and tree-structure prior (default the mean forest'sbaseandpower); avarianceForestwith novarsreads every predictor, matchingTRUE. Gaussian and"aft"(survival) responses and constant leaves only (alinear()orgp()leaf prior,dbartsPriors, is refused by name); monotone constraints and the latent families ("probit","logistic","ordinal","nbinom"), which route their own precisions through the channel the variance forest divides into, are not supported. Under"aft"the model is \(\log T = f(x) + s(x)\epsilon\), so the dispersion of log survival time varies with \(x\) and each right-censored observation's latent log-time is redrawn at its own \(s(x_i)\);survivalProbabilitiesthen divides by that surface rather than a scalar.family = student()residuals are also refused together withvariance. The per-tree leaf prior is calibrated from the residual prior's (family = gaussian(sigma = )) hyperparameters so that a constant variance surface reproduces the homoscedasticsigmaposterior. With two or more variance trees that calibration matches the prior mean of \(\sigma^2\), which is finite only abovedf2, so achisq()residual prior ofdf2 or below is refused there, at creation and bysetModel; a variance forest of one tree takes the residual prior itself, at anydf. The fit gains posterior drawss.train/s.testof \(s(x)\), andpredictattaches an"s"attribute with \(s(x)\) at new predictors (requireskeepTrees). \(s(x)\) is the fit's residual scale wherever one is reported or drawn at:extract(type = "loglik")scores at \(s(x_i)/\sqrt{w_i}\),type = "ppd"draws its noise there, andsummary.bartsummarizesmean.sin place ofsigma;extractandpredictreturn it astype = "sigma". Such a fit carries nosigmaorfirst.sigma, and the sampler'sgetSigmas()returnsNULL: the engine holds the scalar fixed, so it carries no posterior content. The constructor resolves by bare name inside this argument, whatever the caller has attached, and a bare name the caller has bound to a value is that value; seedbartsForests.- forests
Optional list of
forestspecifications, or a singleforest()for a list of one, declaring the ensembles the mean is a weighted sum of, instead of the single ensembleNULL(the default) fits. Each forest carries its own tree count, structure prior, leaf scale, column restriction,interactions/blocksconstraints and, where it states them,proposal.probs,n.perturb.cutsandtreeShift; a forest given abasisenters the mean multiplied by the amplitudes on that basis's columns. Any number of forests may be declared, each carrying a basis of one numeric column or of two levels (seeforest'sbasisitem); the two-forest case with a two-level factor basis has the shape of the Bayesian causal forest \(y = a \mu(x) + b_z \tau(x) + \epsilon\): a prognostic forest \(\mu\) over every predictor and a modulating forest \(\tau\) over the columns itsvarsallows, \(a\) being 1 unless \(\mu\) statesamplitude = student(1). Any number of forests may have nobasis, at any place in the list; one that states nosdtakes this function's leaf prior as a single forest does, held at 1, and two or more of them share it as one prior total, each an equal part of its variance (seeforest's Details), which is whereleaf.prior, akprior and a non-defaultkare taken beside other forests. A forest's default tree count and tree prior go by whether it has abasis: a forest with none takes this function'sn.trees,powerandbase, several stating no count splittingn.treesamong them asblocksdoes, and a forest with one takes 50 trees underbase = 0.25, power = 3, wherever each stands. Where every forest has abasis, a statedn.treesand a namedpower,base,leaf.prior,interactionsorblockshave no forest to belong to and are refused, the default's own value included; state them on a forest. Where only some forests have a basis, apowerorbasestated here and on every forest with none is refused as one thing given twice; beside two or more forests with no basis,interactionsandblocksare refused here and stated on a forest. A single declared forest carrying a basis is refused: for varying coefficients declare an intercept forest plus one basis forest per covariate,forests = list(forest(), forest(basis = z1), forest(basis = z2)), or use one forest withlinear()leaves. Abasisis written as the right-hand side of a model formula, without the tilde, and read aslmreads one: a name of a column of the data is that column,+separates columns, and anything that names no column is what it was whereforest()was called; a single string,basis = "z", names columnz; seeforest'sbasisitem. The data a name is read from first aredata, the matrixformulaat the matrix interface, by its column names, and beside adbartsDataobject what that object holds: the frame it keeps, or the columns it holds, its predictors and response and the bases of a sampler's data by the text each was written as. A basis handed over as a value has one entry for each row of the data handed over, beforesubsetand thena.action, and is cut with them; one of the kept length where rows were dropped is refused. Every forest has a label, fixed when the sampler is created: the name its place in the list has,forests = list(prognostic = forest(), treatment = forest(basis = factor(z))); without one the text of its basis,"factor(z)"; and without that, for a forest with no basis or with one handed over as a value,forest<i>by its position. Two names alike are refused, as is a name of the formforest<i>at another position, and a basis text that repeats an earlier label takes a suffix,dose,dose.1. The labels areattr(fit, "forest.labels")on abartfit, and$setForestand the sampler's readers select a forest by them or by its position. Gaussian,"probit"and"logistic"responses: under a latent family the forests combine into the index rather than into the mean, on the link's own fixed scale, so every forest'ssdis stated in units of the latent index,sigmais pinned and there is no response transform to re-anchor."aft","ordinal"and"nbinom"are refused at creation, each naming what it is missing. Thecontrol'sproposal.probsmixture reaches every forest of the declaration that states none of its own, the frozen mixture included: an all-zero mixture holds those forests' tree structures, and their leaf values move with the per-forest amplitudes,sigmaand the family's latents. The result is an ordinarydbartsSampler; per-forest fits and the per-forest amplitudes are read off the sampler rather than from the run's combinedtrainchannel. The columns of each basis are stored on the sampler's data object, asdata@bases, named aslmwould name them, on the rowssubsetand thena.actionkeep, and survive a sampler's re-creation. Beside any data, a sampler's data included, the list states the forests in full, asdbartsSpecreads it: a forest declaring no basis has none, a list of forests with no basis gives that many plain forests, and no list gives one forest; a forest keeps a basis a sampler's data hold by writing it as it was written,forest(basis = factor(z)), and keeps with it the scale recorded when the sampler was first created. In a hazard fit a basis has one value per subject, cut bysubsetand thena.actionand repeated over the subject's periods. Options a two-forest model does not read -monotone,variance, a non-uniformsplit.probs(a vector ordart()), a linear or Gaussian-process leaf prior, akhyperprior or non-defaultkwhere no forests share a total, Student-t residuals,storage = "single", per-column cut counts, and atestset - are refused at creation rather than ignored, as is any declaration the engine cannot honor. The constructorsforest,interactionsandblocksresolve 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.- n.trees
The number of trees of the forest with no
basis;NULL, the default, leaves it to the forest's ownn.treesand otherwise takes 75 trees. Given beside a forest with nobasisthat states its own, or where every forest has abasis, it is refused by name.- n.cuts, useQuantiles
The maximum number of cut points per predictor and whether to place them at the predictors' quantiles.
n.cutsis one number for every column, one per column, or named, assplit.probsis, by column or term name with.defaultfor the rest; seebart.NULL, the default, takes what adbartsDataobject given asformulaholds, and otherwise 100 and uniformly spaced. A value given beside a data object that carries a grid derives the grid again.- control
An object inheriting from
dbartsControl, created by thedbartsControlfunction, holding the run settings. The tree count, the cut count and the quantile rule are not its settings: state them asn.trees,n.cutsanduseQuantiles(or on aforest), since a value written on a control is read only with a warning, once per session, and is removed in dbarts 1.1-0. A control taken from a fitted sampler carries its run settings and nothing else into this fit; a count or rule it carries that differs from what this call takes draws a warning, on every call, saying it is not used.- sigest
A positive numeric estimate of the residual standard deviation supplied at creation, or one of
"auto","dense"and"sparse", naming how one is made: each gives the residual standard deviation of the linear regression of the response on the predictors and on each forest's basis (a factor's as the indicator of its second level), factors entering as indicator columns whatever the trees are given, and, where that regression leaves no residual degrees of freedom, counting each row once, not as often as its weight, under weights read as counts, the standard deviation of the response over the observations of positive weight, weighted as the regression is (summary(lm(y ~ 1, weights = weights))$sigma,sd(y)at unit weights; for weights read as counts, the standard deviation of the rows written out, 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 underverbosesays, with no warning (thesummaryof abartfit says it too)."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 explicitNAis a missing value and is refused. 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. Spelled the same way onbart,bartBTandxbart; the sampler's ownsetSigma, which sets the parameter rather than an estimate of it, is a different thing and keeps its own name."sparse"needs the Matrix package. It agrees withlmto rounding except on nearly dependent columns (a near-copy of another column, a tiny spread beside a large mean), where it may drop a columnlmkeeps, and on several complete sets of a caller's own one-hot columns in some millions of weighted rows, where it may keep onelmdrops; its last digit follows the BLAS library and its thread count, so a seeded fit reproduces at a fixed BLAS and thread count; and it reads asparseFactor, not a caller's own one-hot columns, as a factor. Pass"sparse"for a data frame with a factor of thousands of levels, and"dense"forlm's handling of nearly dependent columns or for a sparse fit's draws to match its dense twin's. No size turns the estimate off:"sparse"factors a square matrix as wide as the columns left beside the widest factor and can fail to allocate it,"dense"holds rows times columns doubles, and neither can be interrupted once it has begun, so averbosefit first prints what it is about to compute. For an expensive estimate pass a number instead:sd(y), which is too high where there is linear signal; the residual standard deviation of a regression on a random subset of the rows; or the root of the cross-validated error of a lasso (sqrt(min(glmnet::cv.glmnet(x, y)$cvm))) for a wide or sparsex. 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.- 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 every split rule routes by a learned direction;na.omit,na.exclude,na.failandna.passkeep their usual meaning, and underna.passa missing response is an error;NULLapplies no action, as inlm, on the formula and matrix interfaces alike, so a missing response is an error. A row whoseweightsoroffsetis missing is dropped byna.omitandna.excludeas one with a missing predictor is, on the matrix interface as on the formula one; every other action leaves it to the refusal of that argument. Seena.keepPredictors.- ...
Not used for new code: the channel that lets a retired argument spelling (
resid.prior, which now ridesfamily- the residual prior asfamily = gaussian(sigma = ), which is its one home, so writing it both ways is refused where the two disagree; seedbartsFamilies; andproposal.probs, which now ridescontrol, built withdbartsControl(proposal.probs = )) reach a message naming its successor instead of R's own “unused argument” error. Any other name is refused. Removed in dbarts 1.1-0.- sigma
The 0.9-x spelling of
sigest, accepted for one release with a once-per-session warning and removed in dbarts 1.1-0. Supplying both is an error.- node.prior
The 0.9-x spelling of
leaf.prior, accepted for one release with a once-per-session warning and removed in dbarts 1.1-0. Supplying both is an error.- tree.prior
The 0.9-x spelling of the tree prior, accepted for one release with a once-per-session warning (class
dbartsDeprecatedWarning) and removed in dbarts 1.1-0. The value is used, as the plain arguments it states:tree.prior = cgm(power = 3)ispower = 3,cgm(3, 0.5)ispower = 3, base = 0.5, anddart(a = 1)issplit.probs = dart(a = 1); a prior object, such as one saved by 0.9-34, states itspowerandbase, and its split probabilities where they are not uniform. Given besidepower,baseorsplit.probsit is an error.NULLstates nothing.- callback
NULL(the default) 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 here - the address is dereferenced exactly as handed, so a malformed pair crashes the session with no condition to catch, once the returned sampler is actually run.dbartsitself never runs the sampler it builds, so this argument has no other effect here beyond that validation; register it again on the actualruncall (or usebart, which threads a singlecallbackthrough both). Seebart'scallbackitem for the three warnings anddbartsControl'skeepFitsfor the storage opt-out this argument does not, by itself, set here.- seed
Optional integer seed for the random number generator, a convenience mirror of
dbartsControl(seed = ).NULL(the default) means not given here: it leavescontrol's own seed in force, seeded or not; anNAis a missing value, as inset.seed, and is refused. A single finite number overrides the seed incontrol.bartandxbartaccept the same argument and resolve it identically. See the Reproducibility section of bart.- factors
How factor columns in a data frame enter the model. The default
"categorical"keeps each unordered factor as a single predictor whose splits send a subset of its levels (at most 65535) down each branch, and keeps each ordered factor as a single predictor split at a threshold on its level codes, its candidate thresholds the midpoints between consecutive declared levels (at most 65534 levels, one fewer than an unordered factor, andn.cutsdoes not apply); level tables are retained so that test data are coded identically. A factor's level count, ordered or not, is the declared level table, not the levels the training rows happen to take, so a declared but unobserved level keeps its own bin and test or replacement data carrying it are accepted (droplevelsbeforehand to model only the observed levels)."indicators"expands each factor into binary indicator columns, as previous versions always did and asbartBTstill does; its training levels are kept too, so a test factor is matched to them by label, as inlm, and a level with no training rows, which has no indicator column, is refused by name. Subset splits let a single split separate any grouping of a factor's levels, where indicator columns need a chain of splits to do the same, and they give a factor the prior split probability of one predictor rather than one per level.- family
The response model.
"auto"fits gaussian models to continuous responses and probit models to those coded 0/1, as always; aSurvresponse is fit as"aft", and an n x K matrix (K >= 3) of non-negative whole numbers on the matrix interface as"multinomial"(a formula with acbindleft-hand side is refused here, namingbart; a two-column matrix is refused, naming the readings, successes and failures underfamily = binomialand (time, status)). A two-level factor, logical, or two-level character response is also detected and fit as probit. Every resolution of"auto"is reported in a one-line message naming the family fit (printed only underverbose = TRUE), while an unordered factor (or character) response with three or more levels is an error directing tobart'sfamily = "multinomial". An explicit family that a factor response cannot support (e.g."gaussian") is also an error rather than a silent fit of the integer level codes."gaussian"forces a continuous fit even for a 0/1 numeric response;"probit"and"logistic"require a 0/1 response (one holding a single class is fitted with one warning saying so, the prior alone then driving the fitted probabilities toward 0 or 1) and fit latent-variable models, with fits and predictions on the latent scale."logistic"uses Polya-Gamma augmentation, and also takes a binomial response, an n x 2 matrix of successes and failures, orcbind(successes, failures)on a formula, asglmdoes: a row's trials are its row sum, a row of no trials enters no likelihood and is still fitted, and a weight counts the row that many times (seebart). Base R family objects map asglmtakes them (binomialis the logit link, sofamily = binomialis"logistic", not probit) and the rest are refused; seedbartsFamilies."aft"fits an accelerated failure time (log-normal) survival model: the response is aSurvobject (from the survival package) or a two-column(time, status)matrix or data frame (status 1 an event, 0 right-censored; logical status also works, factor status does not), andsurvivalProbabilitiesproduces survival-probability draws. Fits and predictions are on the log-time scale (\(E[\log T \mid x]\)), not the time scale. ASurvresponse selects"aft"automatically whenfamilyis"auto"; an explicitly conflicting family (e.g."gaussian") with aSurvresponse is an error. ASurv-like object carrying notypeattribute is treated as right-censored;types other than"right"are rejected. The response may also be aSurvleft-hand side onformula(e.g.Surv(time, status) ~ .); both interfaces honorsubset. Case weights are not supported. Seeweightsfor how the families differ in their support for weights."multinomial"fits an unordered K-category response by a softmax of \(K\) forests, one per category, with the interleaved one-vs-rest Polya-Gamma augmentation. The response is an \(n \times K\) matrix of non-negative integer counts - column \(k\) holding category \(k\)'s successes, with trials \(n_i = \sum_k y_{ik} \ge 0\), no larger than \(10^6\) since each trial costs a Polya-Gamma draw per category per sweep - or, the single-trial special case, a factor or character vector (a numeric or logical one is refused, asbartrefuses it: a number names no category), which is one-hot expanded to exactly that matrix with every trial 1. Column names on the matrix, or the levels of a factor, label the categories. A data frame of numeric columns is read as its matrix, and a one-column character matrix as its vector of labels; a wider character matrix, or a data frame with a column that is not numeric, is refused, asbartrefuses it. Underfamily = "auto"a matrix of three or more columns of non-negative whole numbers is read as this model, but a three-or-more-level factor is not - it is an error directing here, since an unordered categorical response is equally a candidate for several models. The response ridesdbartsData'scountsargument, anddata@yis the derived trials vector; the per-category shift is an \(n \times K\) matrixoffset(entering the values before the softmax), never a flat one, which the blend is invariant to and which is therefore refused. Fits and predictions are the \(K\) category probabilities, summing to one across the second dimension. A row with no trial contributes nothing to the likelihood and still receives fitted probabilities, asglmfits a row of zero prior weight; the first such row a sampler takes in a session warns. Like probit there is no residual scale to draw, and weights are not supported: an integer case weight is already row-wise replication in the count response, and a non-integer one has no exact augmentation sampler. The sampler is an ordinarydbartsSamplerwhose response and per-category offsets are mutable through$setResponse, which takes the count matrix,$setCategoryOffsetand$setCategoryTestOffset; seedbartsSampler-classfor what the softmax refuses and why.monotone, a non-uniformsplit.probs(a vector ordart()), a linear or Gaussian-process leaf prior, akhyperprior, a namedprior.scale,varianceandstorage = "single"are refused at creation rather than dropped, and the response uses the matrix (x.train/y.train) interface."ordinal"fits an ordered categorical response by a cumulative probit: a latent \(z = f(x) + \epsilon\), \(\epsilon \sim N(0, 1)\), is cut at ordered thresholds \(\gamma_1 = 0 < \gamma_2 < \ldots < \gamma_{K-1}\) into the \(K\) ordered categories, the free thresholds sampled by a marginal Metropolis update with the latents integrated out. The response should be an ordered factor (is.ordered), whose level order defines the category order; underfamily = "auto"an ordered factor with three or more levels is detected and fit as ordinal, reporting the choice in a one-line message (a two-level ordered factor is binary and resolves to probit).family = "ordinal"given explicitly also accepts an unordered factor or character response - with a message that the category order is taken from the level order - and a numeric response, whose ordered levels aresort(unique(y)). Like probit, the latent scale is fixed at 1, fits are on the latent scale, and weights are not supported.bartreports ordinal fits as \(n \times K\) category probabilities; seebart."nbinom"fits a non-negative integer (count) response by a negative-binomial model on a log link with the Polya-Gamma augmentation: the forest fits the log mean \(\eta = f(x) + c + o\) and \(y \sim \mathrm{NB}(\mathrm{size} = r, \mathrm{mu} = e^{\eta})\), so the offset enters the mean multiplicatively as a log-exposure; \(c\), the log of the total count over the total exposure, is a data transform that centers the leaf prior, and fits carry it. The response must be a non-negative integer no larger than \(10^6\) (the shape grid's count histogram is sized from the largest count), and"nbinom"is never inferred - a count carries no unambiguous class, so it must be requested explicitly. The shaperis estimated by default (seeshape); like probit, there is no residual scale, fits are on the log-mean scale, and weights are accepted only as 0 and 1, marking rows in and out of the likelihood (exposure belongs in the offset).bartreports mean counts; seebart."hazard"and"hazard.logistic"fit a discrete-time survival hazard model by person-period expansion ("hazard.probit"is an accepted alias for"hazard"). The response is the sameSurvobject or two-column(time, status)the"aft"family takes, but each subject observed to time \(t_i\) is 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, and the binary indicator \(y_{ik} = \mathrm{status}_i \cdot 1\{k = t_i\}\); the discrete hazard is then \(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 an ordinary"probit"/"logistic"fit on the expanded rows - it adds no engine code. The time grid is the sorted distinct observed times of the subjects in the likelihood, those of positive weight, by default;hazard(breaks = )replaces it with a given number of quantile bins or with explicit interval boundaries (seedbartsFamilies). The offset is on the link scale and replicates per subject; weights replicate and follow the chosen binary family's policy. ASurvresponse requires the family to be requested explicitly ("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. Survival curves come fromsurvivalProbabilities, which requireskeepTreesunless reading a storedtestset withsample = "test"(below);bartreports the fit with its$periodsgrid, and its$familyrecords the binary link. 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)."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 lognormal positive-part fit - an ordinary gaussian fit of \(\log y\) - over the subset \(\{i : y_i > 0\}\); the two parts share no parameters and are composed from two ordinary fits at independently derived seeds, so no engine code is added and a shared variable-selection prior across the parts is not available.y.trainmust be non-negative and finite and must carry at least one exact zero and one positive value. By default, predictions report the natural (response) scale via posterior-predictive Monte Carlo, \(E[y \mid x] = P(y > 0 \mid x)\,e^{f(x) + \sigma^2 / 2}\), using the positive part's single \(\sigma\) per draw (the positive part is always homoscedastic); seebartfor the fulltypeoptions ("prob","link"/"log", the bimodal"ppd").barttakes a formula,test,subset,offsetandweightsof 0 and 1 on this family; see there.dbarts()does not fit this family: it composes two samplers, which onlybartbuilds, so requesting it here is an error directing tobart().- 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 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. The reading is fixed when the sampler is created:$setModelcannot change it, and$setWeights,$setDataandpredictread new weights under it.
Details
A sampler in which every predictor holds one value is created, unlike a bart fit, which refuses one: its trees have no cut point until $setPredictor gives a column values that differ.
“Discrete sampler” refers to that dbarts is implemented using ReferenceClasses, so that there exists a mutable object constructed in C++ that is largely obscured from R. The dbarts function is the primary way of creating a dbartsSampler, for which a variety of methods exist.
Data frame ingestion
Data frame input is stored columnar: no \(n \times p\) predictor matrix is retained. Code that previously reached into the sampler's stored data expecting a plain matrix should call extract(sampler, "predictors") - or as.matrix on it - to obtain the numeric predictor matrix, factor columns as their integer codes. See dbartsData for the column-type mapping (numeric, factor, sparse, and sparseFactor).
Test offset synchronization
When offset.test is left at its default and that evaluates to the training offset itself (a scalar, or a vector given for as many rows), the sampler links the two: the sampler's setOffset method re-derives offset.test from each new offset it is given. Calling the sampler's setTestOffset or setTestPredictorAndOffset methods breaks this link – offset.test is set independently from then on, and the link never re-forms, even if the two are later set to equal values.
Response scaling
Continuous responses are range-scaled internally: y (net of offset) is mapped to \([-0.5, 0.5]\) by its observed minimum and maximum, the convention of the entire BART software lineage (BayesTree, BART, bartMachine), which is what lets k (see leaf.prior above) and its defaults transfer across packages and papers. The known caveat is outlier sensitivity: extreme y values stretch the range and compress the effective leaf prior for everything else; the published workaround is to log-transform or winsorize such values before fitting, or to let k adapt via the chi hyperprior (dbartsPriors). The scale is fixed when the sampler is created; the sampler's setResponse, setOffset, setWeights and setActiveRows methods only re-anchor it when called with updateScale = TRUE, intended for burn-in only, since re-anchoring mid-run makes fits across iterations no longer comparable (see dbartsSampler-class).
Naming the leaf prior by k or sd
Because the leaf prior's k is relative to the range of the response the sampler was CONSTRUCTED on, an R program that drives the sampler between sweeps – feeding it latents, residuals, or offsets from an outer model – inherits whatever spread its construction vector happened to imply. leaf.prior = normal(sd = ) names the spread instead, on the family's scale (response units for a continuous response; see dbartsPriors for the table): the prior standard deviation of the forest total's leaf parameter, a number or an invchi hyperprior on it. The prior mean is the response transform's shift ((max(y) + min(y)) / 2, net of offset, for a continuous response; 0 for the latent-scale families). k and sd are exclusive. Unset, nothing changes.
The named sd is the sd of the normal prior on the leaf model's own parameter. It equals the prior standard deviation of \(f(x)\) at every \(x\) for the constant leaf only; under the other leaf models the prior of \(f(x)\) is x-dependent and sd bounds it in a leaf-model-specific direction. Under a linear leaf prior it is a LOWER bound, attained at the standardized covariate origin, with \(sd(f(x))\) equal to sd times \(\sqrt{1 + \|z(x)\|^2}\) for \(z\) the internally standardized leaf covariates (a missing value maps to \(z_j = 0\), and a constant column contributes 0); the prior mean is exact. Under a gp leaf prior it is an UPPER bound over \(x\), attained at rows reproducing a leaf member and on leaves past max.leaf.size (which draw as constant leaves); elsewhere the prior variance is \(sd^2 c(x)' C^{-1} c(x)\) and decays to 0 as \(x\) leaves the leaf's data cloud, at which point every prior draw equals the prior mean exactly. Under a monotone constraint it is the sd of an unbounded leaf value (dbartsPriors states the construction) and a LOWER bound in the interior – the realized standard deviation runs a few per cent to about 20% above it – and the prior mean is NOT the prior mean of \(f(x)\): the constrained marginal is skew, with an x-dependent mean that tracks the constraint direction and spans several prior standard deviations along the constrained axis (see monotone above).
A named sd is absolute. It is applied at creation and re-derived at every setModel against the response transform then in force, and the sampler restates it after every channel that re-anchors the transform (setResponse, setOffset, setWeights or setActiveRows with updateScale = TRUE, and setData), so a fixed sd means the same spread throughout, and an invchi prior on it the same prior; setLeafPrior changes it, and the restatement then uses the latest write. The current value of a drawn sd is the sampler's k, which a re-anchor leaves, so it lags until its next draw (see dbartsSampler-class). A k, relative to the data, moves with the transform instead. Two-forest (forests) and multinomial models take their forests' leaf scales from their own calibration maps and refuse a named sd rather than drop it; a forest of the first states its own, in the response's units (see forest).
Value
A reference object of dbartsSampler.
References
Chipman, H.A., George, E.I., McCulloch, R.E., and Shively, T.S. (2022) mBART: multidimensional monotone BART. Bayesian Analysis, 17(2), 515–544.
Pratola, M.T., Chipman, H.A., George, E.I., and McCulloch, R.E. (2020) Heteroscedastic BART via multiplicative regression trees. Journal of Computational and Graphical Statistics, 29(2), 405–417.
Twala, B.E.T.H., Jones, M.C., and Hand, D.J. (2008) Good methods for coping with missing data in decision trees. Pattern Recognition Letters, 29(7), 950–956.
Examples
set.seed(8)
n <- 100L
x <- matrix(runif(n * 3L), n, 3L)
y <- 2 * x[, 1L] - x[, 2L] + rnorm(n, 0, 0.2)
control <- dbartsControl(n.chains = 1L, n.threads = 1L, n.burn = 0L,
n.samples = 1L, updateState = FALSE)
## The sampler is created once and then run repeatedly, so that BART can act
## as a conditional model inside a larger Gibbs/Metropolis-Hastings sampler.
sampler <- dbarts(y ~ x, control = control, n.trees = 25L)
samples <- sampler$run(numBurnIn = 50L, numSamples = 1L)
str(samples$train)
#> num [1:100, 1] 0.1826 0.3443 1.2289 0.8974 -0.0939 ...
## an outer step revises the response; the sampler picks it up on the next
## run() without being rebuilt. The prior scale set at creation stays locked
## unless updateScale = TRUE is passed (burn-in only).
sampler$setResponse(y + rnorm(n, 0, 0.05))
samples <- sampler$run()
## priors are given as expressions in dbarts's own vocabulary
sampler <- dbarts(y ~ x, control = control,
power = 1.5,
leaf.prior = normal(k = chi(1.5, 2)),
family = gaussian(sigma = chisq(df = 5)), n.trees = 25L)
## an additive fit that is monotone increasing in the first predictor
sampler <- dbarts(y ~ x, control = control,
interactions = interactions(max.order = 1L),
monotone = c(1, 0, 0), n.trees = 25L)
samples <- sampler$run(numBurnIn = 20L, numSamples = 5L)
## a non-gaussian family: counts by negative binomial, offset a log-exposure
counts <- rnbinom(n, size = 4, mu = exp(0.5 * x[, 1L]) * 4)
sampler <- dbarts(x, counts, family = "nbinom", control = control, n.trees = 25L)
samples <- sampler$run(numBurnIn = 20L, numSamples = 5L)