| Title: | Discrete Bayesian Additive Regression Trees Sampler |
|---|---|
| Description: | Fits Bayesian additive regression trees (BART; Chipman, George, and McCulloch (2010) <doi:10.1214/09-AOAS285>) while allowing the updating of predictors or response so that BART can be incorporated as a conditional model in a Gibbs/Metropolis-Hastings sampler. Supports continuous, probit, logistic, multinomial, ordinal, negative-binomial, semicontinuous two-part, and survival (accelerated failure time and discrete-time hazard) responses, robust Student-t errors, heteroscedastic variance forests, monotonicity and interaction constraints, variable selection through 'DART' priors, missing-value incorporation, categorical and sparse predictors, and linear or Gaussian-process leaf models. Also provides a BayesTree-compatible interface. |
| Authors: | Vincent Dorie [aut, cre] (ORCID: <https://orcid.org/0000-0002-9576-3064>), Hugh Chipman [aut], Robert McCulloch [aut], R Core Team [ctb] (basis of RNG), Guido U Draheim [ctb] (ax_check_compile_flag.m4), Maarten Bosmans [ctb] (ax_check_compile_flag.m4), Christophe Tournayre [ctb] (ax_compiler_ext.m4), Michael Petch [ctb] (ax_compiler_ext.m4), Rafael de Lucena Valle [ctb] (ax_compiler_ext.m4), Steven G. Johnson [ctb] (ax_compiler_vendor.m4, ax_pthread.m4, ORCID: <https://orcid.org/0000-0001-7327-4967>), Matteo Frigo [ctb] (ax_compiler_vendor.m4), John Zaitseff [ctb] (ax_compiler_vendor.m4), Daniel Richard G. [ctb] (ax_pthread.m4) |
| Maintainer: | Vincent Dorie <[email protected]> |
| License: | GPL (>= 2) |
| Version: | 1.0-0 |
| Built: | 2026-11-12 01:39:48 UTC |
| Source: | https://github.com/vdorie/dbarts |
Fits Bayesian additive regression trees (BART; Chipman, George, and McCulloch 2010), a Bayesian “sum-of-trees” model in which each tree is held to be a weak learner by its prior. The package offers two ways in, described below, and provides a BayesTree-compatible interface.
What distinguishes dbarts from other BART implementations is that its sampler is mutable: predictors, response, offset, and weights can be swapped between MCMC draws, so that BART can be a conditional model inside a larger Gibbs or Metropolis-Hastings sampler rather than only a standalone fit.
For an ordinary fit, use one of the fitting functions. Each runs the sampler to completion and returns posterior draws.
bart - the current interface, taking a formula or matrices and reaching the full feature set, including every response family. This is the one to reach for first.
bartBT - the BayesTree-compatible interface, kept at its historical defaults (200 trees, one chain, BayesTree's tree-move mixture, factors expanded to indicator columns, binary responses probit, rows with missing values dropped).
xbart - crossvalidates over k, power, base, and the tree count.
pdbart - partial dependence plots for one or two variables.
Fits support predict, fitted, residuals, extract, plot, and summary; see bartBT's ‘Generics’ section for what each returns and on which scale. survivalProbabilities turns a survival fit into survival-curve draws.
dbarts builds a dbartsSampler without running it. The sampler is a reference class whose methods - run, setResponse, setPredictor, setOffset, setWeights, and the rest - map onto the underlying C++ engine, so an outer sampler can alternate its own draws with BART's. dbartsData and dbartsControl build its data and control objects, dbartsPriors its priors, and samplePriorPredictive draws from the prior for calibration before any fitting. dbartsSpec resolves the same specification without constructing a sampler, for packages that embed dbarts and supply their own design matrix.
Reached through bart and dbarts unless noted.
Response families (family): "gaussian", "probit", "logistic", accelerated failure time ("aft"), discrete-time survival hazard ("hazard", "hazard.logistic"), multinomial ("multinomial"), ordered categorical ("ordinal"), negative-binomial counts ("nbinom"), and semicontinuous two-part ("hurdle.lognormal", bart only). "auto", the default, resolves the family from the response.
Outlier-robust Student-t errors (family = student(...)) and a heteroscedastic variance forest (variance).
Structural constraints: monotonicity (monotone), interaction limits (interactions), and block-additivity (blocks).
Leaf models: constant, linear, or Gaussian-process (leaf.prior; see dbartsPriors).
Variable selection by the DART prior (split.probs = dart()).
Predictors: missing values incorporated in place unconditionally, unordered factors split on level subsets (factors), and sparse or mixed dense/sparse input (Matrix::dgCMatrix, sparseFactor).
Warm starts from a previous fit (warm.start) or by XBART-style grow-from-root (n.grow.sweeps).
Every chain runs its own random number generator, so results never depend on the thread count and sampling does not advance R's stream. Calling set.seed beforehand suffices; passing seed instead makes a fit reproducible without touching R's stream at all. See bart's ‘Reproducibility’ section.
Two arrays of 4 bytes per observation per tree per chain dominate what the sampler itself holds, so its footprint is linear in the number of observations, the number of trees, and the number of chains, and everything else is a rounding error beside them. The predictor store costs 2 bytes per cell once, whatever the chain count, because every chain reads the same store. A test set costs its own store, 2 bytes per test cell, plus 16 bytes per test row per chain.
Worked examples, for the sampler alone (the engine and its predictor store, not the returned draws):
| observations | predictors | trees | chains | sampler |
| 10,000 | 10 | 75 | 1 | 7 MB |
| 100,000 | 20 | 200 | 1 | 170 MB |
| 100,000 | 20 | 200 | 4 | 660 MB |
| 1,000,000 | 50 | 200 | 1 | 1.8 GB |
A large- fit is usually limited not by the sampler but by the training predictions it returns. yhat.train is 8 bytes per observation per draw per chain, and two copies of it are live while the fit is packaged - the one the sampler wrote and the one the fit returns - so the 100,000-observation four-chain fit above at the default 500 draws peaks near 3.2 GB of returned array against 660 MB of sampler. The lever is keepTrainingFits = FALSE - an argument of bart and of dbartsControl, and keeptrainfits on bartBT - which drops the array and the fitted means taken from it; predict on a keepTrees fit recovers them for whichever rows are wanted. A per-draw callback (see bart) goes further alongside keepFits = FALSE by never allocating the array at all, taking the 100,000-observation four-chain fit above from about 3891 MB to about 698 MB, and a 1,000,000-observation one-chain fit at 50 predictors from about 10560 MB to about 2576 MB.
Two options cost more than their names suggest. keepTrees keeps every draw's trees, about 24 bytes per node per tree per draw per chain, which is 23 MB per chain at 200 trees and 500 draws and grows with the tree count and the draw count but not with . A designated-covariate leaf (leaf.prior = linear(...) or gp(...)) caches sufficient statistics keyed on leaf membership; measured, that cache runs about 13 to 14 bytes per observation per tree per chain, and at 100,000 observations, 200 trees and one chain it was 276 MB - larger than everything else the fit holds put together. It also replaces one of the two 4-byte arrays above with an 8-byte one.
Calling the R interface needs no special linkage. A package that drives the sampler from C should declare LinkingTo: dbarts and use the flat C API declared in the installed header ‘dbarts/dbarts.h’, whose entry points are reached through R_GetCCallable and versioned by the two-component handshake DBARTS_C_API_MAJOR/DBARTS_C_API_MINOR, with dbarts_apiHash() as an opt-in exact-ABI check, which moves on additive releases as well. That header creates no sampler and names no R type: the sampler is built in R - dbarts or dbartsSpec - and the handle the entry points take is the address in that object's external pointer, read with R_ExternalPtrAddr. See dbarts-embedding. The C++ interface of releases before 1.0-0, ‘dbarts/R_C_interface.hpp’, has been removed.
Vincent Dorie [email protected], with Hugh Chipman and Robert McCulloch. See citation("dbarts") for how to cite the package.
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.
bart to fit a model, dbarts to build a sampler, and the package vignettes: vignette("gibbs_sampler_mixture_model", package = "dbarts"), vignette("working_with_saved_trees", package = "dbarts") and vignette("dbarts-as-a-component", package = "dbarts").
BART is a Bayesian “sum-of-trees” model in which each tree is constrained by a prior to be a weak learner; see bartBT for the base gaussian/probit model definition. bart is dbarts' own formula-first fitting interface: besides the default gaussian/probit response it reaches further families through family - logistic, accelerated failure time (family = "aft"), discrete-time survival hazard (family = "hazard", "hazard.logistic"), K-category multinomial (family = "multinomial"), ordered categorical (family = "ordinal", a cumulative probit), negative-binomial counts (family = "nbinom"), and semicontinuous two-part responses (family = "hurdle.lognormal") - and, on its formula interface, an additional per-observation-modulated forest declared inline with a forest() term (see ‘Formula Terms’ below). None of these families is reachable from bartBT, which takes no family argument and always fits the gaussian or probit model.
bart( formula, data, test, subset, weights, offset, offset.test = offset, sigest = NULL, k = NULL, power = 2, base = 0.95, split.probs = NULL, n.trees = 75L, n.samples = 500L, n.burn = 500L, n.chains = 4L, n.threads = min(dbarts::guessNumCores(), n.chains), combineChains = TRUE, n.cuts = 100L, useQuantiles = FALSE, n.thin = 1L, keepTrainingFits = TRUE, printEvery = 100L, printCutoffs = 0L, verbose = TRUE, keepTrees = NULL, keepCall = TRUE, samplerOnly = FALSE, seed = NULL, monotone = NULL, interactions = NULL, blocks = NULL, variance = NULL, keepSampler = keepTrees, warm.start = NULL, n.grow.sweeps = 0L, factors = c("categorical", "indicators"), family = c("auto", "gaussian", "student", "probit", "logistic", "aft", "multinomial", "ordinal", "nbinom", "hazard", "hazard.probit", "hazard.logistic", "hurdle.lognormal"), weights.type = NULL, na.action = dbarts::na.keepPredictors, leaf.prior = NULL, storage = c("double", "single"), updateState = TRUE, keepFits = is.null(callback), callback = NULL, control = dbarts::dbartsControl(), ...) ## S3 method for class 'bartMultinomial' extract( object, type = c("ev", "ppd", "bart", "forest", "loglik", "sigma", "k", "leaf.prior.sd", "varcount", "trees"), sample = c("train", "test"), combineChains = TRUE, ...) ## S3 method for class 'bartMultinomial' fitted( object, type = c("ev", "class", "bart", "forest"), sample = c("train", "test"), ci.level = NULL, ...) ## S3 method for class 'bartMultinomial' predict( object, newdata, type = c("ev", "ppd", "bart", "forest", "class"), offset = NULL, weights = NULL, combineChains = TRUE, ci.level = NULL, na.action = dbarts::na.keepPredictors, n.threads, ...) ## S3 method for class 'bartMultinomial' print(x, ...) ## S3 method for class 'bartMultinomial' residuals(object, ...) ## S3 method for class 'bartMultinomial' family(object, ...) ## S3 method for class 'bartOrdinal' extract( object, type = c("ev", "ppd", "bart", "loglik", "thresholds", "sigma", "k", "leaf.prior.sd", "varcount"), sample = c("train", "test"), combineChains = TRUE, ...) ## S3 method for class 'bartOrdinal' fitted( object, type = c("ev", "class", "bart"), sample = c("train", "test"), ci.level = NULL, ...) ## S3 method for class 'bartOrdinal' predict( object, newdata, type = c("ev", "ppd", "bart", "class"), offset = NULL, weights = NULL, combineChains = TRUE, ci.level = NULL, na.action = dbarts::na.keepPredictors, n.threads, ...) ## S3 method for class 'bartOrdinal' print(x, ...) ## S3 method for class 'bartOrdinal' residuals(object, ...) ## S3 method for class 'bartOrdinal' family(object, ...) ## S3 method for class 'bartNegbin' extract( object, type = c("ev", "ppd", "bart", "loglik", "shape", "sigma", "k", "leaf.prior.sd", "varcount"), sample = c("train", "test"), combineChains = TRUE, ...) ## S3 method for class 'bartNegbin' fitted( object, type = c("ev", "ppd", "bart"), sample = c("train", "test"), ci.level = NULL, ...) ## S3 method for class 'bartNegbin' predict( object, newdata, type = c("ev", "ppd", "bart"), offset = NULL, weights = NULL, combineChains = TRUE, ci.level = NULL, na.action = dbarts::na.keepPredictors, n.threads, ...) ## S3 method for class 'bartNegbin' print(x, ...) ## S3 method for class 'bartNegbin' residuals(object, ...) ## S3 method for class 'bartNegbin' family(object, ...) ## S3 method for class 'bartHurdle' extract( object, type = c("ev", "ppd", "prob", "bart", "loglik", "sigma", "k", "leaf.prior.sd", "varcount"), sample = c("train", "test"), combineChains = TRUE, ...) ## S3 method for class 'bartHurdle' fitted( object, type = c("ev", "ppd", "prob", "bart"), sample = c("train", "test"), ci.level = NULL, ...) ## S3 method for class 'bartHurdle' predict( object, newdata, type = c("ev", "ppd", "prob", "bart"), offset = NULL, weights = NULL, combineChains = TRUE, ci.level = NULL, na.action = dbarts::na.keepPredictors, n.threads, ...) ## S3 method for class 'bartHurdle' print(x, ...) ## S3 method for class 'bartHurdle' residuals(object, type = "ev", ...) ## S3 method for class 'bartHurdle' family(object, ...) ## S3 method for class 'bartMultinomial' plot(x, plquants = c(0.05, 0.95), cols = NULL, ...) ## S3 method for class 'bartOrdinal' plot(x, plquants = c(0.05, 0.95), cols = NULL, ...) ## S3 method for class 'bartNegbin' plot(x, plquants = c(0.05, 0.95), cols = c("blue", "black"), ...) ## S3 method for class 'bartHurdle' plot(x, plquants = c(0.05, 0.95), cols = c("blue", "black"), ...) ## S3 method for class 'bartMultinomial' summary(object, ...) ## S3 method for class 'bartOrdinal' summary(object, vars = c("thresholds", "sigma", "k", "leaf.prior.sd"), ...) ## S3 method for class 'bartNegbin' summary(object, vars = c("shape", "sigma", "k", "leaf.prior.sd"), ...) ## S3 method for class 'bartHurdle' summary(object, vars = c("sigma", "k", "leaf.prior.sd", "resid.df"), ...) ## S3 method for class 'summary.bartHurdle' print(x, ...) ## S3 method for class 'bart' sigma(object, ...) ## S3 method for class 'bartMultinomial' sigma(object, ...) ## S3 method for class 'bartOrdinal' sigma(object, ...) ## S3 method for class 'bartNegbin' sigma(object, ...) ## S3 method for class 'bartHurdle' sigma(object, ...) ## S3 method for class 'bart' nobs(object, ...) ## S3 method for class 'bartMultinomial' nobs(object, ...) ## S3 method for class 'bartOrdinal' nobs(object, ...) ## S3 method for class 'bartNegbin' nobs(object, ...) ## S3 method for class 'bartHurdle' nobs(object, ...)bart( formula, data, test, subset, weights, offset, offset.test = offset, sigest = NULL, k = NULL, power = 2, base = 0.95, split.probs = NULL, n.trees = 75L, n.samples = 500L, n.burn = 500L, n.chains = 4L, n.threads = min(dbarts::guessNumCores(), n.chains), combineChains = TRUE, n.cuts = 100L, useQuantiles = FALSE, n.thin = 1L, keepTrainingFits = TRUE, printEvery = 100L, printCutoffs = 0L, verbose = TRUE, keepTrees = NULL, keepCall = TRUE, samplerOnly = FALSE, seed = NULL, monotone = NULL, interactions = NULL, blocks = NULL, variance = NULL, keepSampler = keepTrees, warm.start = NULL, n.grow.sweeps = 0L, factors = c("categorical", "indicators"), family = c("auto", "gaussian", "student", "probit", "logistic", "aft", "multinomial", "ordinal", "nbinom", "hazard", "hazard.probit", "hazard.logistic", "hurdle.lognormal"), weights.type = NULL, na.action = dbarts::na.keepPredictors, leaf.prior = NULL, storage = c("double", "single"), updateState = TRUE, keepFits = is.null(callback), callback = NULL, control = dbarts::dbartsControl(), ...) ## S3 method for class 'bartMultinomial' extract( object, type = c("ev", "ppd", "bart", "forest", "loglik", "sigma", "k", "leaf.prior.sd", "varcount", "trees"), sample = c("train", "test"), combineChains = TRUE, ...) ## S3 method for class 'bartMultinomial' fitted( object, type = c("ev", "class", "bart", "forest"), sample = c("train", "test"), ci.level = NULL, ...) ## S3 method for class 'bartMultinomial' predict( object, newdata, type = c("ev", "ppd", "bart", "forest", "class"), offset = NULL, weights = NULL, combineChains = TRUE, ci.level = NULL, na.action = dbarts::na.keepPredictors, n.threads, ...) ## S3 method for class 'bartMultinomial' print(x, ...) ## S3 method for class 'bartMultinomial' residuals(object, ...) ## S3 method for class 'bartMultinomial' family(object, ...) ## S3 method for class 'bartOrdinal' extract( object, type = c("ev", "ppd", "bart", "loglik", "thresholds", "sigma", "k", "leaf.prior.sd", "varcount"), sample = c("train", "test"), combineChains = TRUE, ...) ## S3 method for class 'bartOrdinal' fitted( object, type = c("ev", "class", "bart"), sample = c("train", "test"), ci.level = NULL, ...) ## S3 method for class 'bartOrdinal' predict( object, newdata, type = c("ev", "ppd", "bart", "class"), offset = NULL, weights = NULL, combineChains = TRUE, ci.level = NULL, na.action = dbarts::na.keepPredictors, n.threads, ...) ## S3 method for class 'bartOrdinal' print(x, ...) ## S3 method for class 'bartOrdinal' residuals(object, ...) ## S3 method for class 'bartOrdinal' family(object, ...) ## S3 method for class 'bartNegbin' extract( object, type = c("ev", "ppd", "bart", "loglik", "shape", "sigma", "k", "leaf.prior.sd", "varcount"), sample = c("train", "test"), combineChains = TRUE, ...) ## S3 method for class 'bartNegbin' fitted( object, type = c("ev", "ppd", "bart"), sample = c("train", "test"), ci.level = NULL, ...) ## S3 method for class 'bartNegbin' predict( object, newdata, type = c("ev", "ppd", "bart"), offset = NULL, weights = NULL, combineChains = TRUE, ci.level = NULL, na.action = dbarts::na.keepPredictors, n.threads, ...) ## S3 method for class 'bartNegbin' print(x, ...) ## S3 method for class 'bartNegbin' residuals(object, ...) ## S3 method for class 'bartNegbin' family(object, ...) ## S3 method for class 'bartHurdle' extract( object, type = c("ev", "ppd", "prob", "bart", "loglik", "sigma", "k", "leaf.prior.sd", "varcount"), sample = c("train", "test"), combineChains = TRUE, ...) ## S3 method for class 'bartHurdle' fitted( object, type = c("ev", "ppd", "prob", "bart"), sample = c("train", "test"), ci.level = NULL, ...) ## S3 method for class 'bartHurdle' predict( object, newdata, type = c("ev", "ppd", "prob", "bart"), offset = NULL, weights = NULL, combineChains = TRUE, ci.level = NULL, na.action = dbarts::na.keepPredictors, n.threads, ...) ## S3 method for class 'bartHurdle' print(x, ...) ## S3 method for class 'bartHurdle' residuals(object, type = "ev", ...) ## S3 method for class 'bartHurdle' family(object, ...) ## S3 method for class 'bartMultinomial' plot(x, plquants = c(0.05, 0.95), cols = NULL, ...) ## S3 method for class 'bartOrdinal' plot(x, plquants = c(0.05, 0.95), cols = NULL, ...) ## S3 method for class 'bartNegbin' plot(x, plquants = c(0.05, 0.95), cols = c("blue", "black"), ...) ## S3 method for class 'bartHurdle' plot(x, plquants = c(0.05, 0.95), cols = c("blue", "black"), ...) ## S3 method for class 'bartMultinomial' summary(object, ...) ## S3 method for class 'bartOrdinal' summary(object, vars = c("thresholds", "sigma", "k", "leaf.prior.sd"), ...) ## S3 method for class 'bartNegbin' summary(object, vars = c("shape", "sigma", "k", "leaf.prior.sd"), ...) ## S3 method for class 'bartHurdle' summary(object, vars = c("sigma", "k", "leaf.prior.sd", "resid.df"), ...) ## S3 method for class 'summary.bartHurdle' print(x, ...) ## S3 method for class 'bart' sigma(object, ...) ## S3 method for class 'bartMultinomial' sigma(object, ...) ## S3 method for class 'bartOrdinal' sigma(object, ...) ## S3 method for class 'bartNegbin' sigma(object, ...) ## S3 method for class 'bartHurdle' sigma(object, ...) ## S3 method for class 'bart' nobs(object, ...) ## S3 method for class 'bartMultinomial' nobs(object, ...) ## S3 method for class 'bartOrdinal' nobs(object, ...) ## S3 method for class 'bartNegbin' nobs(object, ...) ## S3 method for class 'bartHurdle' nobs(object, ...)
Data and formula.
formula |
An object of class |
data |
An optional data frame, list, or environment containing predictors, used together with a formula |
test |
An optional matrix or data frame with the same number of predictors as |
subset |
An optional vector of logicals or indices used to subset the data. Can be missing. A |
weights |
An optional vector of weights to be used in the fitting process. For a gaussian response, BART fits a model with observations A test sample's weights, the For |
offset |
An additive offset entering the family's mean or link, applied to training data; see For For For On a |
offset.test |
The equivalent of |
na.action |
A function that filters incomplete rows, as For |
factors |
How factor columns in a data frame enter the model, exactly as in |
Family and priors.
family |
The response family. Every setting only one family reads rides the family object rather than this signature, in
|
||||||||||||||||||||||||
weights.type |
How
Under |
||||||||||||||||||||||||
sigest |
For continuous response models, an estimate of the residual standard deviation (residual standard error), |
||||||||||||||||||||||||
k |
For numeric |
||||||||||||||||||||||||
power, base
|
Real numbers setting the tree prior's probability that a node at a given depth splits, |
||||||||||||||||||||||||
split.probs |
Prior probabilities that each predictor is chosen for a splitting rule: |
||||||||||||||||||||||||
leaf.prior |
The full |
||||||||||||||||||||||||
monotone |
Optional per-predictor monotonicity constraints, passed through to |
||||||||||||||||||||||||
interactions |
Optional interaction constraints, passed through to |
||||||||||||||||||||||||
blocks |
Optional block-additive constraint, passed through to |
||||||||||||||||||||||||
variance |
Heteroscedastic BART (Pratola et al. 2020): passed through to |
Sampling run.
n.trees |
The number of trees in the sum-of-trees formulation. In a model of several forests it is the count of the forest with no |
n.samples |
The number of posterior samples requested; |
n.burn |
Number of MCMC iterations to be treated as burn in. |
n.chains |
Integer specifying how many independent tree sets and fits should be calculated. Default 4; |
n.threads |
A positive integer giving a total thread budget, distinct from On |
combineChains |
Logical; if |
n.cuts |
The maximum number of possible values used in decision rules (see |
useQuantiles |
When |
n.thin |
Every |
seed |
Optional integer specifying the desired pRNG seed. |
warm.start |
A previous fit whose forests seed the initial state instead of drawing trees from the prior: either a |
n.grow.sweeps |
A non-negative integer; when positive, the initial forest is built by |
samplerOnly |
Builds the sampler from its arguments and returns it without running it. Useful to use the |
Output.
keepTrainingFits |
If |
printEvery |
As the MCMC runs, a message is printed every |
printCutoffs |
The number of cutoff rules printed to screen before the MCMC is run. Given a single integer, the same value is used for all variables. If 0, nothing is printed. |
verbose |
Logical; if |
keepTrees |
A fit that keeps its trees stores its sampler's state at the end of the fit, so a fit saved with |
keepCall |
Logical; if |
keepSampler |
Logical that can be used to save the underlying |
Engine.
storage |
Passed through to |
updateState |
Passed through to |
keepFits |
Passed through to |
callback |
|
control |
A |
... |
Present on the |
object |
An object of class |
newdata |
Test data for prediction. Obeys the same rules as |
type |
The quantity to return; see ‘Value’ below for what each family's generics accept and produce. As on a |
sample |
Either |
vars |
Character vector of fields to gather, as |
x |
An object of one of the four own-class families ( |
cols |
For |
plquants |
For |
ci.level |
For |
Every fit, of every class below, carries family, the family as specified once "auto" has resolved, and family.spec, the same family with its settings, which family(fit) returns (see bartBT's ‘Value’ section). Ask a fit what it is through these, not through which components are present: a run's options decide which draw channels it keeps.
Every fit answers sigma(fit) and nobs(fit), as an lm or glm fit does. sigma is the posterior mean of the residual sd, mean(extract(fit, type = "sigma")): on a hurdle fit the positive part's sd of , on an "aft" fit that of the log time, on a "student" fit the scale of its t errors, and 1 on a family with no residual scale (binary, hazard, multinomial, ordinal and "nbinom" fits), as sigma reads a binomial glm. A fit with a variance forest has a residual sd per row, not one, and sigma refuses it; extract(fit, type = "sigma") gives its draws. nobs counts the rows in the likelihood: those subset and na.action kept, less any of weight 0; a hazard fit's are its person-period rows.
Row names: every output indexed by observation carries the rows' names on its observation margin, on every class below. That covers the stored draws (yhat.train, yhat.test, their means, s.train, s.test, forestFits and the latent channels) and what fitted, residuals, extract, predict and survivalProbabilities return. Training rows are named after subset and na.action: a formula fit names them as its model frame does, "1" to "n" when the data has none, as lm does; the x interface takes rownames(x), a data frame's automatic names counting as "1" to "n", and leaves a matrix without row names unnamed. Test rows and newdata take their own row names the same way. A discrete-time hazard fit names its person-period rows by make.unique over the subject names, so a subject s1 at risk in three periods gives s1, s1.1 and s1.2, and survivalProbabilities names subjects. A fit also keeps the names as row.names.train and row.names.test, absent when the rows are unnamed.
Under the default and bartBT-compatible families ("gaussian", "probit", "logistic", "aft", "hazard" and its aliases), bart returns a list of class "bart", documented in full under bartBT's ‘Value’ section - the same yhat.train/sigma/varcount/... components (but no binaryOffset on a binary fit, which only bartBT returns), including forestFits, glue, bases, n.forests, and "forest.labels" and "forest.unit" attributes when the formula carries a forest() term (‘Formula Terms’ above), the second the unit the forests' sds are stated in, as the sd argument of forest takes it or the link's error sd: that term route is the only way bart itself reaches the per-forest channel, since it has no forests = formal of its own. A heteroscedastic fit (variance supplied) additionally carries s.train/s.test, posterior draws of the residual scale laid out as yhat.train/yhat.test; see the variance argument above. A discrete-time hazard fit (family = "hazard"/"hazard.logistic") additionally carries periods, the ordered period grid the person-period expansion used; survivalProbabilities dispatches its survival-curve branch on it. Under keepFits = FALSE, yhat.train/yhat.train.mean/yhat.test/yhat.test.mean, s.train/s.test, and forestFits/glue/bases, with the "forest.labels" and "forest.unit" attributes, are all ABSENT (not NULL within the list) rather than present-but-empty; plot/extract/fitted/residuals/predict then name keepFits in their error rather than failing on a bare NULL. The model descriptors - family, family.spec, n.forests, and on a family with a residual distribution resid.scale - are set by the model rather than by run options, so they survive keepFits = FALSE and the fit's own SHAPE stays readable even with every per-observation channel dropped.
The remaining families - "multinomial", "ordinal", "nbinom", and "hurdle.lognormal" - return their own list class instead, never "bart", each with its own generics, described below: precisely so a K-category or two-part fit cannot silently flow through a method that assumes the single-forest shape.
bart(family = "multinomial") returns a different list, of class "bartMultinomial". Components: call, family ("multinomial"), levels (the resolved category names, length K: levels(y.train) for a factor response, or colnames(y.train) - falling back to as.character(seq_len(K)) when unnamed - for a count-matrix response), levels.source ("labels", or "index" when levels were synthesized from a count matrix without column names), K, n.chains, n.trees, y (the original response: the factor y.train, or the validated n x K count matrix when a count response was supplied), offset (when trained with one; see bartBT), leaf.prior and fixed (as on a "bart" fit, the K forests sharing one leaf prior, so one list and one k), and yhat.train - the posterior draws of the K softmax probabilities, an array of dimension (n.chains , when n.chains > 1 and combineChains = FALSE) n.samples number of training observations K, with the resolved category levels as the trailing dimension's names; combineChains = TRUE (the default) folds the chain margin into the samples margin as usual. yhat.train already holds PROBABILITIES, not a latent score - there is no "bart"-scale component to convert, unlike the binary families. When test was supplied, yhat.test is the same K softmax probabilities on the held-out rows, dimensioned like yhat.train with the training-observation margin replaced by the test one. varcount is the per-sample per-category split-usage channel: each category forest's per-draw variable counts, dimensioned like yhat.train but with the number of training predictors in place of the number of observations, and colnames(x.train) (when present) named on that margin. fit is present whenever keepTrees is TRUE or keepSampler is set, independent of keepTrees: it is the dbartsSampler whose K-forest engine actually ran (not the temporary sampler it builds along the way), fully mutable and readable on the channels the softmax gives meaning to - $setResponse with the count matrix, $setCategoryOffset, $setPredictor, $setLeafPrior(normal(k = )), and the rest - and refused by name on the ones it does not ($setResponse given a vector, $setOffset, $setSigma, $setForestWeights); fit$storeState() followed by save/load restores a sampler predict.bartMultinomial can replay through. predict still requires keepTrees = TRUE - a kept fit alone carries no saved trees to replay - and errors otherwise.
Generics for a "bartMultinomial" fit: fitted(object) (type = "ev", the default) returns the posterior-mean n K probability matrix, columns named by the fit's captured levels; fitted(object, type = "class") returns the argmax of that mean matrix as a factor over the original levels - a classification convenience. extract(object, type = "ev", sample = "train") returns the full yhat.train draws, and sample = "test" returns yhat.test (an error if the fit carries no test channel); extract(object, type = "ppd") draws one category per posterior draw from its probability vector, returned as an integer code (1-based, indexing the fit's captured levels) in an array shaped like "ev" minus the K margin; on a fit whose response is a count matrix, its training rows instead draw a vector of category counts with that row's number of trials, rmultinom(1, n_i, p) per draw and row (all zeros at a row with no trial), in an array shaped like "ev", while its test rows, whose trial counts are unknown, draw a one-trial count vector, the unit vector of a category, in the same shape. A row of weight 0, training or test, has NA draws (see the weights item). extract/fitted/predict with type = "bart", and extract/fitted/predict with type = "forest", error naming the reason: the run records only the identified softmax probabilities, and a category's forest is a latent whose level is reproducibly structured yet not identified (in the same sense as BCF's ), so a raw replay would read as signal - the identified content is the log-ratio, which the logs of the reported probabilities carry. predict(object, newdata) requires object fit with keepTrees = TRUE (error otherwise); it codes newdata to the training columns exactly as predict.bart does and returns a levels-named (n.chains ) n.samples number of new observations K probability array, the yhat.test/yhat.train convention; type = "ppd" draws one category per posterior draw the same way extract(object, type = "ppd") does on a factor response, and on a count-matrix fit a one-trial count vector, since the trial count of a new row is unknown; with weights, each draw is instead the count per category over that many new trials, in an array shaped like "ev", at newdata or, without it, at the training rows in place of their trials, a weight of 0 drawing K zero counts (see the weights item); type = "bart" and type = "forest" are named only to be refused, for the non-identification reason above; type = "class" returns the same argmax factor fitted(object, type = "class") does, over the probability draws predict itself replays; paired with ci.level it is refused by name instead - a class prediction is a label rather than a quantity with a credible band. offset supplies the per-category shift at the new rows, required on a fit trained with an offset and reproducing yhat.train when the training offset is passed back at the training rows. residuals(object) returns an n K matrix, the observed proportion (an indicator for a factor response, y / rowSums(y) for a count-matrix one, 0 at a row with no trial as glm takes a zero-weight row) minus the fitted probability in fitted(object), per category. extract's combineChains (default TRUE) reshapes "ev"/"ppd"/"loglik" to a combined or per-chain layout, exactly as extract.bart's does; refused by name on fitted and residuals, which always summarize the combined draws. fitted/predict's ci.level returns an (observation K 3) array of est/ci.lower/ci.upper instead of a 3-column matrix, since a category margin survives alongside the observation one; refused by name on residuals (as bartBT's own ci.level item). extract(object, type = "loglik") is the multinomial log-density of the observed row (its coefficient included, so it reduces to for a one-trial row), extract-only, sample = "test" refused by name, shaped like "ev" minus the K margin - loo/WAIC on it is leave-one-row-out, since the likelihood unit is the whole count row. forest/contribution on extract/predict (outside extract(object, type = "trees"), described below), sample on fitted, type on residuals, and vars on summary are all refused by name rather than silently ignored: none is meaningful on this K-widened, non-identified-latent shape. extract(object, type = "trees") forwards to the K-forest sampler's own dbartsSampler getTrees, exactly as it does for a "bart" fit (see ‘Extracting Trees’ in bartBT): unlike "bart"/"forest" above, a category's TREE STRUCTURE is recorded and identified (only its level is not), so forest selects one of the K category forests instead of being refused. plot(object) adds a second panel to the per-category trace: the posterior median and interval of the predicted probability of each observation's OWN observed category against that median (a count response with multi-trial rows instead plots the observed proportion against the interval of the drawn , one point per row-category cell). plotTree and survivalProbabilities are refused by name (a multinomial fit's trees live on its sampler; it has no hazard channel). extract(object, type = "varcount") returns the per-category split-usage channel described above. summary(object) pools the per-category mean predicted probability - this family's only scalar posterior parameter - into posterior mean/sd, split-Rhat and bulk/tail ESS, named prob[<level>], the multinomial analog of summary.bart's /k summary.
bart(family = "ordinal") likewise returns its own list, of class "bartOrdinal". Components: call, family ("ordinal"), levels (the ordered category names, length K), K, n.chains, n.trees, y (the observed categories as an ordered factor over levels), yhat.train (and yhat.test when test was supplied) - the posterior draws of the K category probabilities, shaped and levels-named exactly as the multinomial arrays above - latent.train (and latent.test) - the corresponding draws of the latent on the unit-variance probit scale, shaped like a binary family's yhat.train - thresholds - the posterior draws of the K - 1 finite thresholds , dimensioned draws (K - 1), the ordinal analog of gaussian's sigma, from which probabilities at any latent value can be reconstructed - k when the leaf scale is drawn, offset (when trained with one; see bartBT), leaf.prior and fixed as on a "bart" fit (see bartBT), and varcount. thresholds.raw (the per-draw thresholds in the internal layout predict consumes) is present only under keepTrees. fit is present whenever keepTrees is TRUE or keepSampler is set, independent of keepTrees: it is the dbartsSampler whose engine actually ran, fully mutable and readable like any sampler dbarts returns, and fit$storeState() followed by save/load restores a sampler predict.bartOrdinal can replay through. summary(object) reports the sampled thresholds alongside whatever mean-function scale vars finds present, naming the pinned first threshold and any parameter held fixed on a line under the table, pooled into posterior mean/sd, split-Rhat and bulk/tail ESS, the ordinal analog of summary.bart's /k/ summary.
Generics for a "bartOrdinal" fit: fitted(object) returns the posterior-mean n K probability matrix (columns named by levels); fitted(object, type = "class") the argmax category of that mean as an ordered factor; fitted(object, type = "bart") the posterior-mean latent. extract(object, type = "ev") returns the probability draws, type = "bart" (alias "link") the latent draws, and type = "ppd" draws one category per posterior draw (1-based codes indexing levels). predict(object, newdata) requires keepTrees = TRUE and returns the probability draws at newdata (type = "bart" the replayed latent; type = "ppd" category draws, or with weights the count per category over that many new trials, as for bartMultinomial; type = "class" the argmax ordered factor fitted(object, type = "class") returns, over the replayed draws; paired with ci.level it is refused by name instead, for the same reason bartMultinomial refuses it); when newdata matches the fit-time test it reproduces yhat.test. residuals(object) returns the n K matrix of observed-indicator minus fitted probability. extract's combineChains (default TRUE) and fitted/predict's ci.level work as for bartMultinomial above, including the (observation K 3) interval shape for a K-margined type, the refusal of both on residuals, and the refusal of combineChains on fitted/residuals. extract(object, type = "loglik") is - exactly the stored category probability at the observed level, since yhat.train already holds the cumulative-probit difference - extract-only, sample = "test" refused by name, shaped like type = "ppd". forest/contribution on extract/predict and sample on fitted are refused by name (this family has a single forest and fitted is always the training rows). plot(object) traces the free thresholds ( is pinned and carries no information; at K = 2 there is none, and the plot degrades to one full-device panel) alongside the per-observation latent interval, observations ordered by median , colored by observed level, with dashed reference lines at the posterior-median thresholds. plotTree and survivalProbabilities are refused by name. extract(object, type = "thresholds") returns the threshold draws, threshold[1] pinned at 0 through threshold[K - 1], and extract(object, type = "varcount") the per-predictor split-usage channel; summary's own default vars is c("thresholds", "sigma", "k", "leaf.prior.sd"), of which a fit keeps the leaf-scale one it named.
bart(family = "nbinom") likewise returns its own list, of class "bartNegbin". Components: call, family ("nbinom"), n.chains, n.trees, y (the observed counts), yhat.train (and yhat.test when test was supplied) - the posterior draws of the mean counts , shaped like a binary family's yhat.train - latent.train (and latent.test) - the corresponding draws of the log mean - shape - the per-draw shape , the count analog of gaussian's sigma, absent when the shape is held, whose value is in fixed - k when the leaf scale is drawn, as on a "bart" fit, offset (when trained with one; see bartBT), leaf.prior and fixed (its shape, when held fixed, among them), and varcount. shape.raw (the per-draw in the internal layout predict consumes) is present only under keepTrees. fit is present whenever keepTrees is TRUE or keepSampler is set, independent of keepTrees: it is the dbartsSampler whose engine actually ran, fully mutable and readable - $getShape() on it answers with the fit's own - and fit$storeState() followed by save/load restores a sampler predict.bartNegbin can replay through. summary(object) reports the shape draws, when the shape was sampled, alongside whatever mean-function scale vars finds present (a shape or k held fixed is named on a line under the table), pooled into posterior mean/sd, split-Rhat and bulk/tail ESS, the count analog of summary.bart's /k/ summary.
Generics for a "bartNegbin" fit: fitted(object) returns the posterior-mean count per observation; fitted(object, type = "bart") the posterior-mean log mean; fitted(object, type = "ppd") a Monte Carlo mean over extract(object, type = "ppd", sample = "train") draws. extract(object, type = "ev") returns the mean-count draws, type = "bart" the log-mean draws, and type = "ppd" draws one count per posterior draw from ; sample = "test" selects the test channel. predict(object, newdata) requires keepTrees = TRUE and returns the mean-count draws at newdata (type = "bart" the replayed log mean; type = "ppd" count draws, or with weights the sum of that many new counts, a weight of 0 drawing 0), with an optional log-exposure offset; when newdata matches the fit-time test and no offset is given it reproduces yhat.test. residuals(object) returns the observed count minus the posterior-mean count per observation. extract's combineChains and fitted/predict's ci.level (a plain 3-column matrix here - this family has no K margin) work as for bartBT, including combineChains's refusal on fitted/residuals and ci.level's on residuals. extract(object, type = "loglik") is , extract-only, sample = "test" refused by name. forest/contribution on extract/predict and sample on fitted are refused by name. plot(object) traces the integer-gridded shape (a step plot; there is no burn-in channel to bridge from, since bart drives one n.burn/n.samples sweep for this family; no trace is drawn for a shape held fixed, which print names instead) alongside bartBT's own gaussian observed-vs-fitted panel, applied to the counts. The shape trace shows the kept draws only; the burn-in draws of the shape are not stored. plotTree and survivalProbabilities are refused by name. extract(object, type = "shape") returns the per-draw shape , type = "k" and "leaf.prior.sd" the leaf scale as on a "bart" fit, and extract(object, type = "varcount") the per-predictor split-usage channel; summary's own default vars is c("shape", "sigma", "k", "leaf.prior.sd"), of which a fit keeps the leaf-scale one it named.
bart(family = "hurdle.lognormal") returns its own list, of class "bartHurdle", holding both component fits ($zero, a "bart" probit fit of the zero-part indicator; $positive, a "bart" gaussian fit of on the positive subset) plus call and family ("hurdle.lognormal"). extract/fitted/predict/residuals/print methods for "bartHurdle" compose the two components: type = "ev" (the default) is the natural-scale posterior mean or draws described under the family argument above, type = "prob" the zero part's own probability of a positive response, type = "link"/"log" the positive part's log-scale linear predictor, and type = "ppd" the bimodal predictive draw. ci.level on fitted/predict works as for bartBT, including its refusal on residuals; combineChains is likewise refused by name on fitted/residuals, and fitted takes sample as the third argument, after type and before ci.level, as on every class with a test channel; sample = "test" reads the rows of the test set. residuals(object) returns the observed response minus fitted(object) on the natural scale. extract(object, type = "loglik") is the density of at its own natural scale (a Jacobian against the components' log-scale channels, so it is comparable to any other model OF y, and differs from a log-y computation by the constant ): where , else , with NO truncation (the lognormal positive part's support is already , unlike a count hurdle's positive part, which would have to be truncated at zero - the two rules must not be conflated); it is NOT the sum of the two components' own "loglik" channels, extract-only, sample = "test" refused by name. here is , the complement of the zero probability other implementations report (brms's hu), so the zero branch is rather than ; a formula ported from one of those must be inverted. forest/contribution on extract/predict are refused by name (each component is a single forest). plot(object) draws four panels, three when the positive component held sigma fixed: the positive component's sigma trace (left out in that case); the zero part's probability ; the positive part on the scale it fit ( over the rows); and the composed natural-scale mean over all n rows, the only panel showing the model this family exists for. plotTree and survivalProbabilities are refused by name, naming object$zero$fit/object$positive$fit as the route to the trees. extract(object, type = "sigma") returns $positive's sigma draws, the only sigma the composition carries; extract(object, type = "k") and type = "varcount" each return a list, named zero/positive, of that component's own draws - each list holds both components, a component's draws where its k is modeled and one number where it is fixed; type = "leaf.prior.sd" is the same list of each component's own spread (see bart's k item). summary(object) reports both components - $zero's and $positive's own summary.bart tables, under their own headers - rather than pooling them into one, since the two component fits share no parameters.
bart, bartBT, xbart and rbart_vi refuse a fit in which every predictor holds one value on the rows kept and no forest has a basis, naming the columns: a tree splits a predictor between its values, so the fit would be an intercept-only model under a normal prior. Add a predictor that varies, or drop the term. dbarts takes such a sampler, for code that gives a column its values later with $setPredictor, and so does bart(samplerOnly = TRUE). A fit with a basis forest is not refused.
A model of several forests is written in bart's formula as a sum of forest() terms, each one function of the predictors named inside it, without a separate dbarts forests = list (the two routes are mutually exclusive: a formula with a forest() term given together with forests = is refused by name):
y ~ forest(x1 + x2) + forest(x1 + x2, basis = z) # numeric z: one coefficient y ~ forest(x1 + x2) + forest(x1, basis = factor(z)) # factor z: one coefficient per level y ~ forest(x1 + x2) + forest(x1, basis = a) + forest(x1, basis = b) # two columns: a forest each
A forest's multiplier is its basis argument. Every argument of a term but the first is the same argument of a forest in dbarts's forests = list and is checked the same way; the first, the forest's predictors, is read against data in a formula and against the fit's predictors in a list (see forest's vars item). A forest() is not crossed with another term: z:forest(x1 + x2) and z * forest(x1 + x2) are refused, the message giving the term to write, forest(x1 + x2, basis = z).
The forest with no basis is the forest with no multiplier, and takes bart's own leaf prior and k as a single forest does, whatever stands beside it: held at 1, it is the forest bart would fit alone, unless it states sd or amplitude = normal() or student(). It may be left as plain terms, y ~ x1 + x2 + forest(x1 + x2, basis = z), which is the same model as the first line above, draw for draw; and written alone, y ~ forest(x1 + x2) is the single-forest fit y ~ x1 + x2, in every family that takes a formula. Plain predictor terms beside a forest() with no basis are refused, being two readings, one forest or two; write each as a forest(). It is the model's first forest wherever it is written, and bart's own n.trees, power, base, interactions and blocks are its: n.trees, power, base, interactions or blocks stated both on that term and as bart's argument is refused as one thing given twice, a default's own value included. Several forest() terms with no basis, y ~ forest(x1) + forest(x2) + forest(x3), are the first forests, in the order written, and share one prior total, bart's own leaf prior, each an equal part (see forest's Details): the model is bart's one forest with its trees in blocks. They split n.trees as blocks() does, 38 and 37 of 75, a term stating n.trees keeping its own outside the split; bart's n.trees, power and base reach each term that states none and are refused only where every one states its own, and its interactions and blocks are refused, stated on a term instead. The other forests keep the order they are written in, and each has 50 trees under base = 0.25, power = 3 unless it states its own, whichever is written first. In a formula whose forests all have a basis those arguments of bart have no forest to belong to: each one that is stated is refused by name, its default's own value included, as are leaf.prior, k and a control that names n.trees. A leaf.prior or k written as NULL is named, and refused as any other is. State a count and a tree prior on a forest, as forest(x1, basis = z, n.trees = 100, power = 3).
A forest's first argument is the predictors it splits on, written as the right-hand side of a model formula of its own: names joined by +, calls such as log(x1) and factor(g), . for every column of data but the response, and - to remove a term. The fit's predictors are the terms of all of its forests, each once and those of the forest with no basis first, and each forest splits on the columns of its own terms: in y ~ x1 + x2 + forest(x3, basis = z) the fit has the predictors x1, x2 and x3, the first forest splits on x1 and x2 and the second on x3. A forest with no first argument, forest(basis = z), splits on every predictor of the fit. A term that gives several columns - a factor under factors = "indicators", poly(x1, 2) - is all of them. Only the first argument may be given without its name; every other argument is given by name. A forest's basis is read as code, like its predictors (below), and the rest are evaluated where the formula was written, exactly as they are for dbarts's own forests =. Predictors may also be named, as forest(c("x1", "x2")), each name of a column of data being the term the name written out is. An offset() and an intercept term (1, 0 or - 1) are the fit's and are written beside the forests, wherever among them, not inside one. A removal written beside the forests takes its term from the forest with no basis and from no forest that names predictors of its own: the forest with no basis has the terms of the formula with its forest() replaced by what is inside it and every forest with a basis left out, so y ~ forest(.) - x3 + forest(x3, basis = z) and y ~ . - x3 + forest(x3, basis = z) are one model; a removal that leaves that forest no predictor is refused, and one of a term it does not have is passed by, as R passes it by in a plain formula (see forest's vars item).
A forest's basis is what the forest is multiplied by, written as the right-hand side of a model formula without the tilde and meaning what it means in lm, and is one numeric column or two levels: arithmetic is written inside I(), so I(a + b) is one column, the sum; factor(z), a character column and a logical column of two levels give one column for each level; scale(w) and poly(w, 1) are terms as in lm. Several columns, a + b or poly(w, 2), and three or more levels are refused, with the form to write: a forest for each column, or for each level but the first. Its names are found in data and then where the formula was written. It has a value for every row of data and is cut by subset and the na.action with the predictors, scale() taking its center from every row as in lm. The same basis given through dbarts's forests = is the same columns on the same rows. forest's basis item is the full account: what is refused, how the columns are named, and where a name is found in each of the two ways of writing a forest.
A handful of shapes are refused outright rather than silently misinterpreted, each error naming the offending expression: a forest() crossed with another term by : or *; a forest() anywhere other than a top-level additive term (inside I(), a removal, or the formula's left-hand side); a second unnamed argument, a tilde, a position, an offset() or an intercept term in a forest's first argument; in a basis, * between terms, a term multiplied or divided by a number, cbind() and a factor beside other terms, each with what to write in its place; a forest with a basis and no forest beside it; a formula that names no predictors; test given together with a model of several forests (an amplitude-coupled fit has no per-observation test replay); and a model of several forests in a family the multiplier model does not support ("aft", "ordinal", "nbinom", "multinomial", and "hurdle.lognormal" - gaussian, probit, logistic and the hazard families are the only families a forest with a basis can join, a hazard fit's basis having one value per subject). xbart, bartBT, rbart_vi, pdbart, pd2bart and dbartsData take no forest() term and say so. See ‘Value’ below, and extract's type = "forest", for reading the resulting per-forest fits back out.
predict builds a basis again at the new rows as predict does for lm: a call to scale(), poly(), ns() or bs() is centered, scaled or spanned by what it computed on the fitted rows, which are every row of data whatever subset keeps. Arithmetic inside I(), such as I(w - mean(w)), is evaluated on the rows given to predict, as lm evaluates it, and is not refused; see SafePrediction. So forest(x1 + x2, basis = scale(w)) standardizes a multiplier by the fitted rows' mean and sd. A factor level the fit did not have is refused at predict.
Every chain runs its own pseudo-random generator. A seeded fit never draws
from R's stream, though it may still create .Random.seed in
a session that has none yet.
set.seed versus seed. Leave seed at its
default (NULL) and call set.seed beforehand:
each chain's generator is then seeded from R's stream when the sampler is
created, one uniform draw per chain in chain order, and running the
sampler afterward never advances the stream further. Passing seed
instead drives the chain seeds from a separate, dedicated generator and
leaves R's stream untouched altogether. A single number named in the call
always wins over a seed already sitting in control; NULL
means not given here and defers to control's own seed instead, and
an explicit NA reads as NULL for one release, with a
once-per-session warning; neither discards a control seed. A family = "hurdle.lognormal" fit derives its two
component seeds from the one seed in force (the call's, or
control's); without one, the two
components draw their own chain seeds from R's stream in turn. Do not rely
on bart(seed = S) and set.seed(S); bart() giving the same
draws. They currently agree under R's default generator, but this is not
guaranteed; only seed gives the same draws under any
RNGkind.
Warning classes. Only the warnings a caller has a reason to catch or mute apart from the rest carry a class, and every such class inherits dbartsWarning: deprecations (dbartsDeprecatedWarning, which also inherits base R's deprecatedWarning; see dbarts-deprecated), the slow-count warning of a monotone fit (dbartsSlowCountWarning; see monotone), warnings that a supplied input was replaced by another (dbartsFallbackWarning; dbartsGPFallbackWarning for Gaussian-process leaves, see dbartsPriors), the warning that the rows in the likelihood leave nothing to read the response's scale from, so every row is used (dbartsScaleFallbackWarning; see the weights item), and the warning that a hazard fit's projected memory exceeds the machine's (dbartsMemoryWarning; see dbartsFamilies). Every other warning is an ordinary one, matched by its text.
Chains and n.threads. Results never depend on the thread
count: a fit, its predict, and samplePriorPredictive
all give the same draws whatever n.threads is asked for. A given
chain's draws also do not depend on how many other chains ran alongside
it - chain 1 of a 1-chain seeded run reproduces chain 1 of a 4-chain run
at the same seed, and likewise for any other chain index. Adding a test
set, keepTrees, and verbose do not change the draws either;
storage = "single", dbartsControl's treeShift,
and any change to the model or the data do.
Simulated outcomes. A type = "ppd" draw on predict,
extract, or fitted, and samplePriorPredictive's
own type = "ppd", adds observation noise drawn from R's stream
rather than from the fit's chain generators - even on a fit made with
seed. Call set.seed right before such a call to reproduce
it; seed does not cover this noise.
samplePriorPredictive(type = "ev") only touches R's stream when its
control is unseeded (building the private sampler it draws from); with a
seeded control it rebuilds the same sampler every time and so returns the
same draws on every call - vary the seed, or leave the control unseeded,
for different ones.
Continuing, copying, and restoring a sampler. These apply to an
embedded dbarts sampler kept with keepSampler or
samplerOnly.
Calling run() more than once continues its chains' streams
exactly: run(50, 20) followed by run(0, 20) matches
run(50, 40) bitwise.
storeState() (what save needs) and
setState() (what restores it, including after
load) continue those same streams too: the draws
typically agree to the last few digits, not bitwise, since restoring
rebuilds the fitted values by re-summing the trees.
copy(), deep or shallow, installs the original's current
chain, or, where its engine is gone, as after a reload, the state
storeState() last captured, so the copy continues the same
streams as the original rather than starting an independent chain -
again typically to the last few digits, not bitwise; create a new
sampler with a different seed for an independent one. A copy of
a sampler whose engine is gone and that has no stored state is
refused, as its other calls are.
An unseeded sampler draws fresh chain seeds from R's stream every
time its underlying engine is (re-)created - at copy(), and at
the first use after a reload, including a first setState() call
- exactly as building a new unseeded sampler would. A seeded sampler
never touches R's stream this way.
A bart fit made with keepTrees = TRUE does not
store its sampler's state automatically: call
fit$fit$storeState() before saving so a reload can
predict and keep running.
xbart. An xbart call derives every seed it
uses - one split seed per replication, one seed per sampler its units
create (one per (replication, fold) unit at each distinct tree count) -
with sample.int after set.seed(seed), in one pass, in
its own process, restoring R's stream afterward; without a seed,
set.seed beforehand reproduces the same run. That derivation draws
under the CALLER's own RNGkind, so a given seed draws
different values, and so gives different results, under a different kind -
what stays fixed for a given seed and RNGkind is
n.threads. Each unit's sampler takes its seed through
control's seed slot exactly as bart's own seed does,
driving a dedicated generator that never reads R's stream, so no worker
ever reads its own RNGkind() to fit a unit and results are identical
at any n.threads. A supplied loss function that draws random numbers
draws on the worker running it, from that process's own default generator;
at n.threads greater than 1 this makes the run not reproducible,
whatever seed xbart itself is given.
What moves .Random.seed. Unseeded, creating a
sampler (n.chains uniforms per sampler; a
family = "hurdle.lognormal" fit creates two), xbart, and
copy() or the first use after a reload of an unseeded sampler,
advance R's stream; the simulated-outcome draws above and
dbartsDrawLatents always do. Everything
else a sampler does after creation draws only from its chains' own
generators and leaves R's stream alone.
Across machines and versions. A given seed reproduces the same
draws bitwise only on one machine, with one build of the package, on
whatever processor features it uses. It is not promised across different
machines, operating systems, or compilers: the math library and the
compiler's floating-point code can differ in the last bit. Expect the same
posterior elsewhere, not the same numbers. It is likewise not promised
across dbarts versions - a version that changes the sampler moves
the draws - nor against the 0.9-x series, whose engine and RNG were both
different.
Hugh Chipman: [email protected], Robert McCulloch: [email protected], Vincent Dorie: [email protected].
Chipman, H., George, E., and McCulloch, R. (2010) BART: Bayesian additive regression trees. The Annals of Applied Statistics, 4(1), 266–298. doi:10.1214/09-AOAS285.
He, J., Yalov, S., and Hahn, P.R. (2019) XBART: accelerated Bayesian additive regression trees. Proceedings of the 22nd International Conference on Artificial Intelligence and Statistics (AISTATS), PMLR 89, 1130–1138.
Linero, A.R. (2018) Bayesian regression trees for high-dimensional prediction and variable selection. Journal of the American Statistical Association, 113(522), 626–636.
Pratola, M.T., Chipman, H.A., George, E.I., and McCulloch, R.E. (2020) Heteroscedastic BART via multiplicative regression trees. Journal of Computational and Graphical Statistics, 29(2), 405–417.
bartBT for the BayesTree-compatible interface and the shared "bart"-class Value/Details (Decision Rules, leaf k, Generics, Saving, Extracting Trees); this page's own ‘Reproducibility’ section above covers bartBT too.
dbarts for the mutable sampler bart builds on, forest for the constructor a forest() formula term calls, and xbart for the other formula-first entry point.
## binary response with a logistic link set.seed(0) n <- 60L x.bin <- matrix(runif(n * 2), n, 2) f.bin <- 3 * x.bin[,1] - 1.5 y.bin <- rbinom(n, 1L, plogis(f.bin)) fit.logit <- bart(y.bin ~ x.bin, family = "logistic", n.samples = 20L, n.burn = 20L, n.chains = 1L, n.trees = 20L, n.threads = 1L) ## a shallower tree prior, and DART variable selection fit.shallow <- bart(y.bin ~ x.bin, power = 3, base = 0.5, n.samples = 20L, n.burn = 20L, n.chains = 1L, n.trees = 20L, n.threads = 1L) fit.dart <- bart(y.bin ~ x.bin, split.probs = dart(), n.samples = 20L, n.burn = 20L, n.chains = 1L, n.trees = 20L, n.threads = 1L) ## forest() formula terms: a prognostic forest, and a second forest whose ## amplitude is modulated by a treatment of two levels, factor(z) - the ## Bayesian causal forest shape, written in the formula rather than through ## dbarts()'s forests = set.seed(1) n <- 60L x1 <- runif(n); x2 <- runif(n) z <- rbinom(n, 1L, 0.5) y <- x1 + z * (1 + x2) + rnorm(n, 0, 0.2) fit.bcf <- bart(y ~ forest(x1 + x2) + forest(x1 + x2, basis = factor(z)), n.samples = 20L, n.burn = 20L, n.chains = 1L, n.trees = 10L, n.threads = 1L) fit.bcf$n.forests modulatingFit <- dbarts::extract(fit.bcf, type = "forest", forest = 2L)## binary response with a logistic link set.seed(0) n <- 60L x.bin <- matrix(runif(n * 2), n, 2) f.bin <- 3 * x.bin[,1] - 1.5 y.bin <- rbinom(n, 1L, plogis(f.bin)) fit.logit <- bart(y.bin ~ x.bin, family = "logistic", n.samples = 20L, n.burn = 20L, n.chains = 1L, n.trees = 20L, n.threads = 1L) ## a shallower tree prior, and DART variable selection fit.shallow <- bart(y.bin ~ x.bin, power = 3, base = 0.5, n.samples = 20L, n.burn = 20L, n.chains = 1L, n.trees = 20L, n.threads = 1L) fit.dart <- bart(y.bin ~ x.bin, split.probs = dart(), n.samples = 20L, n.burn = 20L, n.chains = 1L, n.trees = 20L, n.threads = 1L) ## forest() formula terms: a prognostic forest, and a second forest whose ## amplitude is modulated by a treatment of two levels, factor(z) - the ## Bayesian causal forest shape, written in the formula rather than through ## dbarts()'s forests = set.seed(1) n <- 60L x1 <- runif(n); x2 <- runif(n) z <- rbinom(n, 1L, 0.5) y <- x1 + z * (1 + x2) + rnorm(n, 0, 0.2) fit.bcf <- bart(y ~ forest(x1 + x2) + forest(x1 + x2, basis = factor(z)), n.samples = 20L, n.burn = 20L, n.chains = 1L, n.trees = 10L, n.threads = 1L) fit.bcf$n.forests modulatingFit <- dbarts::extract(fit.bcf, type = "forest", forest = 2L)
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 , where .
For binary response , , where 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.
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, ...)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, ...)
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 |
y.train |
Dependent variable for training (in sample) data. If |
x.test |
Explanatory variables for test (out of sample) data. Should have same column structure as |
sigest |
For continuous response models, an estimate of the residual standard deviation (residual standard error), |
sigdf |
Degrees of freedom for error variance prior. Not applicable when |
sigquant |
The quantile of the error variance prior that the rough estimate ( |
k |
For numeric |
power |
Power parameter for tree prior. Default 2, Chipman, George, and McCulloch's empirical recommendation (see References) for the split-probability decay |
base |
Base parameter for tree prior. Default 0.95, from the same source as |
splitprobs |
Prior and transition probabilities of variables used to generate splits. Can be missing/empty/ |
binaryOffset |
Used for binary |
weights |
An optional vector of weights to be used in the fitting process. For a gaussian response, BART fits a model with observations |
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 |
ndpost |
The number of posterior draws after burn in, |
nskip |
Number of MCMC iterations to be treated as burn in. |
printevery |
As the MCMC runs, a message is printed every |
keepevery |
Every |
keeptrainfits |
If |
usequants |
When |
numcut |
The maximum number of possible values used in decision rules (see |
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 |
nchain |
Integer specifying how many independent tree sets and fits should be calculated. Default 1 for |
nthread, n.threads
|
A positive integer giving a total thread budget, distinct from On |
combinechains, combineChains
|
Logical; if |
keeptrees |
Logical; must be |
keepcall |
Logical; if |
seed |
Optional integer specifying the desired pRNG seed. |
proposalprobs |
Named numeric vector or |
keepsampler |
Logical that can be used to save the underlying |
object |
An object of class |
newdata |
Test data for prediction. Obeys all the same rules as |
offset |
For |
sampleronly |
Builds the sampler from its arguments and returns it without running it. Useful to use the |
x |
Object of class |
plquants |
In the plots, beliefs about |
cols |
Vector of two colors. First color is used to plot the median of |
type |
The quantity to be returned by generic functions. Options are |
sample |
Either |
forest |
For |
bases |
For |
contribution |
For |
na.action |
For |
ci.level |
For |
... |
Additional arguments passed on to |
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 in the numeric case and just in the binary 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 (and in the numeric case) where * denotes a particular draw. The is either a row from the training data (x.train) or the test data (x.test).
Decision rules for any tree are of the form vs. for each ‘’ corresponding to a column of x.train. usequants determines the means by which the set of possible is determined. If usequants is TRUE, then the 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 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 half-way values and = numcut, cutoff , counting from one, is the half-way value at position , 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.
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 priors are supported, where is a degrees of freedom and 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 is 1 and is , 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.
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 minus fitted(object, type = type, sample = "train"); the default type = "ev" gives ordinary response-scale residuals, so for a binary fit this is . 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).
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().
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.
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.
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 case, the list has components:
call |
The matched call, or |
yhat.train |
A array/matrix of posterior samples. The |
yhat.test |
Same as |
yhat.train.mean |
Vector of means of |
yhat.test.mean |
Vector of means of |
sigma |
Matrix of posterior samples of |
first.sigma |
Burn-in draws of |
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 |
varprobs |
Present only under a DART prior: the sampled split-variable probabilities, in the same layout as |
forestFits, glue, bases
|
Present only for an amplitude-coupled multi-forest fit: built through |
basis.columns |
Present only for an amplitude-coupled multi-forest fit made with |
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 |
sigest, sigest.fallback
|
The rough error standard deviation ( |
resid.scale, resid.df
|
|
y |
The input dependent vector of values for the dependent variable. This is used in |
fit |
Optional sampler object which stores the values of the tree splits. Required for using |
n.chains |
Information that can be lost if |
k |
Optional matrix of posterior samples of |
first.k |
Burn-in draws of |
leaf.prior |
The leaf prior the fit ran under, on every fit: the sampler's own reading as the run ended ( |
fixed |
The scalars the sampler held fixed, a named list on every fit, empty when there are none: among |
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). |
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 |
family |
The response family as specified, once |
family.spec |
The same family as a family object carrying its settings (a Student-t |
In the binary 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 instead. In addition the list has a binaryOffset component giving the value used.
Note that in the binary , case yhat.train and yhat.test are . For draws of the probability , 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 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 on the horizontal axis and posterior intervals for the corresponding on the vertical axis. For binary response fits, only this second kind of plot is drawn, with the posterior median of 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.
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.
Hugh Chipman: [email protected], Robert McCulloch: [email protected], Vincent Dorie: [email protected].
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.
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.
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.
## simulate data (example from Friedman MARS paper) ## y = f(x) + epsilon , epsilon ~ N(0, sigma) ## x consists of 10 variables, only first 5 matter f <- function(x) { 10 * sin(pi * x[,1] * x[,2]) + 20 * (x[,3] - 0.5)^2 + 10 * x[,4] + 5 * x[,5] } set.seed(99) sigma <- 1.0 n <- 100 x <- matrix(runif(n * 10), n, 10) Ey <- f(x) y <- rnorm(n, Ey, sigma) ## run BART set.seed(99) bartFit <- bartBT(x, y) plot(bartFit) ## compare BART fit to linear matter and truth = Ey lmFit <- lm(y ~ ., data.frame(x, y)) fitmat <- cbind(y, Ey, lmFit$fitted, bartFit$yhat.train.mean) colnames(fitmat) <- c('y', 'Ey', 'lm', 'bart') print(cor(fitmat)) ## fit with missing predictor values: every split rule learns a ## direction for NAs (MIA, always on; no argument selects it) set.seed(1) n <- 60L x.na <- matrix(runif(n * 2), n, 2) x.na[1:5, 1] <- NA y.na <- x.na[,2] + rnorm(n, 0, 0.3) y.na[is.na(x.na[,1])] <- y.na[is.na(x.na[,1])] + 2 fit.na <- dbarts(y.na ~ x.na, control = dbartsControl( n.samples = 20L, n.burn = 20L, n.chains = 1L, n.threads = 1L), n.trees = 20L) samples.na <- fit.na$run() ## recipe: between-draws row subsetting on a latent family (e.g. principal ## stratification or mediation, where an outer Gibbs step redraws which rows ## belong to a stratum every iteration). $setActiveRows changes which rows ## are "in" the model from one run() to the next, without rebuilding the ## sampler and without losing any row's fitted value; see the "active" entry ## of \link{dbartsSampler-class} for the full semantics. Unlike zero case ## weights (gaussian, probit, ordinal and nbinom only), this also reaches ## logistic and aft samplers - and an emptied stratum is a legal all-zeros mask ## rather than a case the caller must special-case and skip. set.seed(3) n <- 120L x.strat <- matrix(runif(n * 2), n, 2) y.strat <- rbinom(n, 1L, plogis(2 * x.strat[,1] - 1)) sampler.strat <- dbarts(x.strat, y.strat, family = "probit", control = dbartsControl(n.chains = 1L, n.threads = 1L, updateState = FALSE), n.trees = 20L) stratum <- rbinom(n, 1L, 0.6) # this iteration's stratum membership sampler.strat$setActiveRows(stratum) draws.strat <- sampler.strat$run(20L, 20L) ## the next outer iteration redraws the stratum; even a stratum that empties ## out is accepted and runs, rather than needing to be skipped stratum <- rep(0, n) sampler.strat$setActiveRows(stratum) draws.empty <- sampler.strat$run(0L, 5L)## simulate data (example from Friedman MARS paper) ## y = f(x) + epsilon , epsilon ~ N(0, sigma) ## x consists of 10 variables, only first 5 matter f <- function(x) { 10 * sin(pi * x[,1] * x[,2]) + 20 * (x[,3] - 0.5)^2 + 10 * x[,4] + 5 * x[,5] } set.seed(99) sigma <- 1.0 n <- 100 x <- matrix(runif(n * 10), n, 10) Ey <- f(x) y <- rnorm(n, Ey, sigma) ## run BART set.seed(99) bartFit <- bartBT(x, y) plot(bartFit) ## compare BART fit to linear matter and truth = Ey lmFit <- lm(y ~ ., data.frame(x, y)) fitmat <- cbind(y, Ey, lmFit$fitted, bartFit$yhat.train.mean) colnames(fitmat) <- c('y', 'Ey', 'lm', 'bart') print(cor(fitmat)) ## fit with missing predictor values: every split rule learns a ## direction for NAs (MIA, always on; no argument selects it) set.seed(1) n <- 60L x.na <- matrix(runif(n * 2), n, 2) x.na[1:5, 1] <- NA y.na <- x.na[,2] + rnorm(n, 0, 0.3) y.na[is.na(x.na[,1])] <- y.na[is.na(x.na[,1])] + 2 fit.na <- dbarts(y.na ~ x.na, control = dbartsControl( n.samples = 20L, n.burn = 20L, n.chains = 1L, n.threads = 1L), n.trees = 20L) samples.na <- fit.na$run() ## recipe: between-draws row subsetting on a latent family (e.g. principal ## stratification or mediation, where an outer Gibbs step redraws which rows ## belong to a stratum every iteration). $setActiveRows changes which rows ## are "in" the model from one run() to the next, without rebuilding the ## sampler and without losing any row's fitted value; see the "active" entry ## of \link{dbartsSampler-class} for the full semantics. Unlike zero case ## weights (gaussian, probit, ordinal and nbinom only), this also reaches ## logistic and aft samplers - and an emptied stratum is a legal all-zeros mask ## rather than a case the caller must special-case and skip. set.seed(3) n <- 120L x.strat <- matrix(runif(n * 2), n, 2) y.strat <- rbinom(n, 1L, plogis(2 * x.strat[,1] - 1)) sampler.strat <- dbarts(x.strat, y.strat, family = "probit", control = dbartsControl(n.chains = 1L, n.threads = 1L, updateState = FALSE), n.trees = 20L) stratum <- rbinom(n, 1L, 0.6) # this iteration's stratum membership sampler.strat$setActiveRows(stratum) draws.strat <- sampler.strat$run(20L, 20L) ## the next outer iteration redraws the stratum; even a stratum that empties ## out is accepted and runs, rather than needing to be skipped stratum <- rep(0, n) sampler.strat$setActiveRows(stratum) draws.empty <- sampler.strat$run(0L, 5L)
Build a block-additive constraint confining each whole tree in a BART fit to
one declared group of predictors, so the ensemble is exactly a sum of
per-group functions (a functional-ANOVA / grouped-GAMI
decomposition). Pass the result as the blocks argument of
dbarts or bart. The constraint is applied per
forest, so in a multi-forest model each forest can carry its own partition.
A multinomial fit applies it to each of its category forests, so
trees.per.group sums to the trees in one category forest.
The constructor is not exported: it resolves by bare name inside the
arguments that take it, and elsewhere is written
dbartsForests$blocks(...); see dbartsForests.
blocks(groups, trees.per.group = NULL)blocks(groups, trees.per.group = NULL)
groups |
A list partitioning the forest's predictors into disjoint blocks. Each entry is a character vector of model-matrix column names (a bare factor term name expands to its indicator columns) or a numeric vector of column indices. The partition must be total and disjoint: every predictor is named in exactly one group. A single vector (rather than a list) is taken as one group. |
trees.per.group |
Optional integer vector, one entry per group, giving how many of the
|
Each tree is assigned to exactly one group and split-restricted to that
group's predictors, so no path in the tree - and hence no term in the
ensemble - mixes predictors from different groups. The assignment is
deterministic and contiguous (the first trees.per.group[1] trees to
group 1, the next trees.per.group[2] to group 2, and so on) and
consumes no random numbers, so a fit is exactly reproducible.
Each of the groups takes an equal part, , of the forest's
prior variance, whatever its tree count: a group of trees gives
each of its leaves the variance , the forest's
prior standard deviation, so the forest as a whole keeps the prior a forest
without groups has. trees.per.group says how complex each group's
function may be, not how much of the response it explains. With equal
counts every tree has the leaf prior of the same forest without groups.
Several forests with no basis written as their own terms,
y ~ forest(x1) + forest(x2), are the same model as the one forest
y ~ forest(x1 + x2, blocks = blocks(list("x1", "x2"))) at the same
tree counts (see forest's Details).
Unlike interactions(groups = ), which is a per-path
allow-list that leaves un-named predictors unconstrained, blocks
lowers to a static per-tree column mask: a predictor named in no block would
be masked out of every tree and never enter the fit. The partition is
therefore required to be total, and every value is validated against the
model matrix at fit time - an unpartitioned predictor, a predictor named in
more than one group, an unrecognized name, or a trees.per.group of the
wrong length, with a non-positive entry, or not summing to n.trees is
an error. For a forest that is already restricted to a subset of the columns,
the partition is over that forest's available columns.
blocks and interactions act on independent seams (which
columns a tree may use versus which may co-occur on a path) and may be
combined on one forest. Block-additivity is also orthogonal to monotone
constraints (see dbarts's monotone).
A dbartsBlocks specification object, resolved when a sampler is built.
dbartsForests,
interactions, dbarts, bart
set.seed(0) n <- 100L x <- matrix(runif(n * 3), n, 3, dimnames = list(NULL, c("x1", "x2", "x3"))) y <- 2 * x[, 1] + ifelse(x[, 2] > 0.5, 1, -1) + rnorm(n, 0, 0.2) df <- data.frame(y, x) ## block-additive fit: f(x) = f1(x1) + f2(x2, x3), no tree mixing the blocks fit <- bart(y ~ x1 + x2 + x3, df, blocks = blocks(groups = list("x1", c("x2", "x3"))), n.trees = 20L, n.samples = 20L, n.burn = 20L, n.chains = 1L, verbose = FALSE) ## split the 20 trees explicitly: 5 to the first block, 15 to the second fit.split <- bart(y ~ x1 + x2 + x3, df, blocks = blocks(groups = list("x1", c("x2", "x3")), trees.per.group = c(5L, 15L)), n.trees = 20L, n.samples = 20L, n.burn = 20L, n.chains = 1L, verbose = FALSE)set.seed(0) n <- 100L x <- matrix(runif(n * 3), n, 3, dimnames = list(NULL, c("x1", "x2", "x3"))) y <- 2 * x[, 1] + ifelse(x[, 2] > 0.5, 1, -1) + rnorm(n, 0, 0.2) df <- data.frame(y, x) ## block-additive fit: f(x) = f1(x1) + f2(x2, x3), no tree mixing the blocks fit <- bart(y ~ x1 + x2 + x3, df, blocks = blocks(groups = list("x1", c("x2", "x3"))), n.trees = 20L, n.samples = 20L, n.burn = 20L, n.chains = 1L, verbose = FALSE) ## split the 20 trees explicitly: 5 to the first block, 15 to the second fit.split <- bart(y ~ x1 + x2 + x3, df, blocks = blocks(groups = list("x1", c("x2", "x3")), trees.per.group = c(5L, 15L)), n.trees = 20L, n.samples = 20L, n.burn = 20L, n.chains = 1L, verbose = FALSE)
Creates a sampler object for a given problem which fits a Bayesian Additive Regression Trees model. Internally stores state in such a way as to be mutable.
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, ...)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, ...)
formula |
An object of class |
||||||||||||||||||||
data |
An optional data frame, list, or environment containing predictors to be used with the model. For backwards compatibility, can also be the |
||||||||||||||||||||
test |
An optional matrix or data frame with the same number of predictors as |
||||||||||||||||||||
subset |
An optional vector specifying a subset of observations to be used in the fitting process. Each argument that holds rows, the first argument, |
||||||||||||||||||||
weights |
An optional vector of weights to be used in the fitting process. For a gaussian response, BART fits a model with observations |
||||||||||||||||||||
offset |
An optional vector specifying an offset from 0 for the relationship between the underlying function, |
||||||||||||||||||||
offset.test |
The equivalent of |
||||||||||||||||||||
verbose |
A logical determining if additional output is printed to the console, including the one-line message |
||||||||||||||||||||
n.samples |
A non-negative integer ( |
||||||||||||||||||||
power, base
|
Real numbers setting the tree prior's probability that a node at a given depth splits, |
||||||||||||||||||||
split.probs |
Prior probabilities that each predictor is chosen for a splitting rule: |
||||||||||||||||||||
leaf.prior |
An expression of the form |
||||||||||||||||||||
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 |
||||||||||||||||||||
interactions |
Optional interaction constraints, built with |
||||||||||||||||||||
blocks |
Optional block-additive constraint, built with |
||||||||||||||||||||
variance |
Optional heteroscedastic variance forest (HBART; Pratola, Chipman, George, and McCulloch 2020). When supplied, a second ensemble models the residual variance surface |
||||||||||||||||||||
forests |
Optional list of |
||||||||||||||||||||
n.trees |
The number of trees of the forest with no |
||||||||||||||||||||
n.cuts, useQuantiles
|
The maximum number of cut points per predictor and whether to place them at the predictors' quantiles. |
||||||||||||||||||||
control |
An object inheriting from |
||||||||||||||||||||
sigest |
A positive numeric estimate of the residual standard deviation supplied at creation, or one of |
||||||||||||||||||||
na.action |
A function that filters incomplete rows, as |
||||||||||||||||||||
... |
Not used for new code: the channel that lets a retired argument spelling ( |
||||||||||||||||||||
sigma |
The 0.9-x spelling of |
||||||||||||||||||||
node.prior |
The 0.9-x spelling of |
||||||||||||||||||||
tree.prior |
The 0.9-x spelling of the tree prior, accepted for one release with a once-per-session warning (class |
||||||||||||||||||||
callback |
|
||||||||||||||||||||
seed |
Optional integer seed for the random number generator, a convenience mirror of |
||||||||||||||||||||
factors |
How factor columns in a data frame enter the model. The default |
||||||||||||||||||||
family |
The response model.
|
||||||||||||||||||||
weights.type |
How
Under |
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 input is stored columnar: no 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).
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.
Continuous responses are range-scaled internally: y (net of offset) is mapped to 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).
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 at every for the constant leaf only; under the other leaf models the prior of 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 equal to sd times for the internally standardized leaf covariates (a missing value maps to , and a constant column contributes 0); the prior mean is exact. Under a gp leaf prior it is an UPPER bound over , attained at rows reproducing a leaf member and on leaves past max.leaf.size (which draw as constant leaves); elsewhere the prior variance is and decays to 0 as 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 : 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).
A reference object of dbartsSampler.
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.
dbartsData, extract.dbartsSampler, sparseFactor
set.seed(8) n <- 100L x <- matrix(runif(n * 3L), n, 3L) y <- 2 * x[, 1L] - x[, 2L] + rnorm(n, 0, 0.2) control <- dbartsControl(n.chains = 1L, n.threads = 1L, n.burn = 0L, n.samples = 1L, updateState = FALSE) ## The sampler is created once and then run repeatedly, so that BART can act ## as a conditional model inside a larger Gibbs/Metropolis-Hastings sampler. sampler <- dbarts(y ~ x, control = control, n.trees = 25L) samples <- sampler$run(numBurnIn = 50L, numSamples = 1L) str(samples$train) ## an outer step revises the response; the sampler picks it up on the next ## run() without being rebuilt. The prior scale set at creation stays locked ## unless updateScale = TRUE is passed (burn-in only). sampler$setResponse(y + rnorm(n, 0, 0.05)) samples <- sampler$run() ## priors are given as expressions in dbarts's own vocabulary sampler <- dbarts(y ~ x, control = control, power = 1.5, leaf.prior = normal(k = chi(1.5, 2)), family = gaussian(sigma = chisq(df = 5)), n.trees = 25L) ## an additive fit that is monotone increasing in the first predictor sampler <- dbarts(y ~ x, control = control, interactions = interactions(max.order = 1L), monotone = c(1, 0, 0), n.trees = 25L) samples <- sampler$run(numBurnIn = 20L, numSamples = 5L) ## a non-gaussian family: counts by negative binomial, offset a log-exposure counts <- rnbinom(n, size = 4, mu = exp(0.5 * x[, 1L]) * 4) sampler <- dbarts(x, counts, family = "nbinom", control = control, n.trees = 25L) samples <- sampler$run(numBurnIn = 20L, numSamples = 5L)set.seed(8) n <- 100L x <- matrix(runif(n * 3L), n, 3L) y <- 2 * x[, 1L] - x[, 2L] + rnorm(n, 0, 0.2) control <- dbartsControl(n.chains = 1L, n.threads = 1L, n.burn = 0L, n.samples = 1L, updateState = FALSE) ## The sampler is created once and then run repeatedly, so that BART can act ## as a conditional model inside a larger Gibbs/Metropolis-Hastings sampler. sampler <- dbarts(y ~ x, control = control, n.trees = 25L) samples <- sampler$run(numBurnIn = 50L, numSamples = 1L) str(samples$train) ## an outer step revises the response; the sampler picks it up on the next ## run() without being rebuilt. The prior scale set at creation stays locked ## unless updateScale = TRUE is passed (burn-in only). sampler$setResponse(y + rnorm(n, 0, 0.05)) samples <- sampler$run() ## priors are given as expressions in dbarts's own vocabulary sampler <- dbarts(y ~ x, control = control, power = 1.5, leaf.prior = normal(k = chi(1.5, 2)), family = gaussian(sigma = chisq(df = 5)), n.trees = 25L) ## an additive fit that is monotone increasing in the first predictor sampler <- dbarts(y ~ x, control = control, interactions = interactions(max.order = 1L), monotone = c(1, 0, 0), n.trees = 25L) samples <- sampler$run(numBurnIn = 20L, numSamples = 5L) ## a non-gaussian family: counts by negative binomial, offset a log-exposure counts <- rnbinom(n, size = 4, mu = exp(0.5 * x[, 1L]) * 4) sampler <- dbarts(x, counts, family = "nbinom", control = control, n.trees = 25L) samples <- sampler$run(numBurnIn = 20L, numSamples = 5L)
Reference for using BART as a conditional model inside a Gibbs or Metropolis-Hastings scheme the
caller writes: which channel an outer block writes, which fit it reads back, whose prior is in
force after a swap, and how a composition is checked. The runnable set is
vignette("dbarts-as-a-component", package = "dbarts"), six named recipes with their
output; this page is the rule each of them applies.
A dbartsSampler is created once by dbarts and then run one
sweep at a time with run(0L, 1L), its inputs replaced between sweeps. The fitting
functions bartBT and bart own their own loop
and are not the surface for this; they return fit objects, and the R modeling accessors
(fitted, predict, extract) apply to those.
Each method replaces one input in place, on every chain, taking effect at the next sweep. All
of them are documented in dbartsSampler.
| method | what the outer block owns | typical use |
$setResponse(y) |
the regression target | a partial residual, a working response, an imputed outcome |
$setOffset(o) |
an additive term BART does not fit | another block's linear predictor, a fixed exposure |
$setWeights(w) |
per-observation precision, or under weights.type = "frequency" a count of identical observations |
a Polya-Gamma precision, a variance mixture; under frequency, fractional counts such as expected memberships |
$setSigma(s) |
the residual standard deviation | a scale drawn elsewhere; use with family = gaussian(sigma = fixed()) so the next run() does not redraw it |
$setPredictor(x, column) |
one predictor column | a latent covariate, an imputed predictor |
$setActiveRows(a) |
which rows enter the likelihood | a subset indicator drawn by another block |
$setLeafPrior(normal(sd = )) |
the leaf prior's spread | stating the prior a cold-start vector did not |
A predictor moved per observation rather than wholesale takes
$setPredictor(x, column, forceUpdate = "partial"), or
updatePredictorPerObservationJointly when several samplers share the column.
Both return a per-observation install mask, FALSE where the new value would empty a leaf
and was rolled back; under a monotone constraint the joint form also declines a
value that would leave a tree's leaf values out of order. That mask is part of a Metropolis accept decision, not a
diagnostic: a declined observation holds its old value, so the likelihood read after the call
is its old likelihood, and treating the resulting ratio as an acceptance leaves the outer sampler's copy
of the latent disagreeing with what the samplers hold.
Not every channel is open on every model. A refusal is part of the model rather than a
limitation - setSigma on a family that fixes the residual scale by definition, a
response swap that would re-anchor a calibration stated at creation - and each names its
reason.
A sampler whose family augments its likelihood (the probit and ordinal
latents, the Polya-Gamma precisions of logistic, binomial and nbinom,
the Student-t scales, an aft sampler's imputed times) draws those values at the start of
each sweep, against the fit the previous sweep left and the inputs in force, and then draws
its trees against them. A sweep therefore runs in this order: the augmentation variables, then
the trees, then sigma and the other parameters. No setter draws them: $setResponse,
$setOffset, $setPredictor, $setSigma, $setWeights,
$setActiveRows, $setForestBasis, $setData, $setModel and
$setState store what they are given, and the next sweep draws the latents against the
change.
Two kinds of outer step are both exact under this order. One conditions on the latent: it
runs the sampler, reads $getLatents(), and draws its own quantity given those values.
The other integrates the latent out, scoring a proposal with the probit likelihood
pnorm(f) of the response, say, and then installing what it accepted; the next sweep
draws the latents under the accepted values, so the trees never fit a latent drawn before the
change. The order is also what makes a setter call and a restore undo each other exactly:
$setWeights with the old weights and $setState with the stored state, in either
order, leave the sampler continuing bit for bit as one that installed the stored state under the old weights would.
Six methods report a fitted quantity and no two report the same one; the table in
‘Reading the fit’, dbartsSampler, is authoritative.
The rule an outer block needs: it conditions on , so it reads
$getFitsWithoutOffset() and adds back whatever offset it installed.
run()$train reports the same location with the offset folded in. The location latent
of "probit", "ordinal" and "aft" that $getLatents() reports is on
that same offset-inclusive scale, , so
the difference z - train is the residual , which carries none of the offset's
signal. A block that owns the offset regresses z - $getFitsWithoutOffset(); used the
other way, the offset reaches it as a coefficient shrunk toward zero rather than as an error.
The latent of "logistic", "nbinom" and a Student-t residual distribution is a
precision, a location at no scale, with no offset in it; dbartsWorkingResponse
gives the offset-free working response for any of them.
$getLatents() returns the values the last sweep's trees were drawn from, so after a run
it and $getFitsWithoutOffset() are a joint draw, the latent being the value the fit was
drawn from. Between a setter and the next run it returns the values from before the setter
($setData starts them as creation does, an ordinal or negative-binomial sampler from the kept cutpoints or shape, and an aft $setResponse
leaves a censored row at its new bound), not values drawn against the change; the next sweep
draws them afresh.
The leaf prior is calibrated once, at creation, from the response the sampler was built on. A
per-sweep setResponse deliberately does not re-anchor it (updateScale =
FALSE, the default), so that the sweeps are comparable - which also means a sampler built on a
cold-start vector keeps that vector's range as its prior scale for the whole run, and its midrange
as the prior's center (read back as $getLeafPrior()$prior.mean, which no setter writes
except through the offset). State the
prior instead of inheriting it: leaf.prior = normal(sd = ) at creation (see
dbartsPriors), or $setLeafPrior(normal(sd = )) afterward, with
$getLeafPrior() reporting what is actually in force. A caller whose rows enter and leave the
likelihood asks for the scale to be taken again from the rows then in with updateScale = TRUE
on $setWeights or $setActiveRows, in burn-in only, and a linear or
gp leaf's covariate center and scale with updateStandardization = TRUE on the same
call; FALSE after burn-in holds both, so every kept draw comes from one prior (see
updateStandardization). A named sd is absolute: a
channel that does re-anchor the transform leaves it where it was.
A decomposition across samplers needs the same care in the other direction. Each
carries a prior sized for the whole of , so their sum has
times the prior standard deviation one sampler would have; dividing each
prior.sd by restates them as shares of one budget.
The value in force during a sweep is the one installed before it. Create the sampler with the
outer block's initial value already in place, and write the channel before run, never
after: a sweep run against a stale offset, weight or response has drawn from the wrong
conditional and nothing later reports it. The mutators store the state after
each write when control@updateState is TRUE, the default, so a sampler driven a
sweep at a time is built with dbartsControl(updateState = FALSE), as the vignette's
recipes are; a per-sweep write then costs nothing beyond the write itself.
The per-observation augmentation a non-gaussian sampler runs internally is callable directly:
dbartsDrawLatents draws the latent at a supplied fit and
dbartsWorkingResponse turns it into the quantity the outer sampler
regresses on. An outer sampler that needs the latent for its own blocks runs the step itself over a
gaussian sampler with family = gaussian(sigma = fixed(1)), rather than reimplementing the family.
Their fit argument is offset-free, as $getFitsWithoutOffset() reports it.
A package that runs its outer block in C or C++ declares LinkingTo: dbarts and
includes ‘dbarts/dbarts.h’, the flat C API. It builds the sampler in R from its own
R code and then reads the handle out of that object's external pointer with
R_ExternalPtrAddr ($getPointer() is what hands the pointer down). dbarts
takes a formula or a matrix, not a model object, so a consumer starting from its own
already-built (control, model, data) triple (dbartsSpec resolves one
without constructing a sampler) builds the sampler instead with
methods::new("dbartsSampler", control, model, data), then calls $getPointer()
on the result. There is no creation entry point and
no R type in the header; the handle is the whole boundary.
The handle is valid until the R object is garbage collected or replaces its pointer, which it
does whenever it re-creates its engine from a stored state - after a load, or
after $setState. Re-read the handle after any such restore, and keep the R object
reachable for as long as the C side holds one.
What the header reaches is the per-sweep loop: dbarts_sampler_run into caller-owned
buffers, the conditioning channels setResponse, setOffset and
setSigma, getLatents, predict, tree storage and printing, and the
queries the outer sampler sizes its results struct from, among them
dbarts_sampler_numFittedValuesPerObservation and
dbarts_sampler_numVariableCountForests, the widths of a multinomial or multi-forest
sampler's fits and split counts; a flat run polls for R's interrupt as $run does and, once the workers have joined, raises it
as R's interrupt condition (not an error: try() lets it through), leaving the sampler usable, with any
saved results of that call to be discarded and a pass over the trees possibly partly applied; it also
warns of a slow monotone leaf-order count once per sampler. Everything else in the table above - the
predictor and weight channels, the active-row mask, the state round trip, tree extraction, the
multi-forest surface - is an R method on the same object, and the two views drive one engine.
The setters COPY what they are handed into buffers the sampler owns at creation, so the
caller's array is free the moment the call returns and conditioning on new values means
calling the setter again rather than writing through the array.
Recovering a known truth on one simulated data set is weak evidence.
dbartsValidateComposition runs simulation-based calibration over the composed
one-sweep step and reports, per scalar functional, whether the kernel targets the posterior the
stated prior and likelihood imply. It catches the defect class in which a posterior mean is
reported where a draw belongs.
dbartsSampler for every method named here,
dbarts for creating one, dbartsAugmentation for the augmentation
helpers, dbartsValidateComposition for the calibration check,
updatePredictorPerObservationJointly for the shared-predictor sweep, and
samplePriorPredictive for inspecting a prior before fitting.
The per-observation data augmentation a non-gaussian dbartsSampler runs
inside each sweep, callable from R against R's own random number stream.
dbartsDrawLatents draws the augmentation variable at a supplied fit - the quantity
getLatents reports for that family - and
dbartsWorkingResponse turns a drawn latent into the response the outer sampler regresses on. Neither
touches a sampler: an outer sampler writing its own Gibbs step around BART, or around anything else, need
not reimplement the family's augmentation.
dbartsDrawLatents(family, fit, y, weights = NULL, offset = NULL, sigma = NULL, shape = NULL, thresholds = NULL, df = NULL) dbartsWorkingResponse(family, latent, y, weights = NULL, offset = NULL, shape = NULL)dbartsDrawLatents(family, fit, y, weights = NULL, offset = NULL, sigma = NULL, shape = NULL, thresholds = NULL, df = NULL) dbartsWorkingResponse(family, latent, y, weights = NULL, offset = NULL, shape = NULL)
family |
One of |
fit |
A numeric vector of each observation's location without the offset -
|
latent |
A numeric vector of length |
y |
The response, of length |
weights |
|
offset |
A numeric vector of length |
sigma |
|
shape |
|
thresholds |
|
df |
|
The offset convention. fit is the location without the offset, the engine's
own convention at every augmentation site, and the linear predictor is formed internally as
fit + offset. The two arguments are therefore not interchangeable, and the pair of
functions is what tells them apart: dbartsDrawLatents(fit = f, offset = o) and
dbartsDrawLatents(fit = f + o, offset = NULL) draw from the same distribution and agree, while
dbartsWorkingResponse differs between the two, the working response being stated in
units the offset has been taken out of. Pass the offset as offset to both.
Why two functions. For "probit", "ordinal" and "aft" the latent is a
LOCATION and the working response is that location less the offset. For "logistic" and
"nbinom" it is a PRECISION - the Polya-Gamma - and what the outer sampler
regresses on is and
respectively, under per-row
precision weights . For "student" the latent is the scale-mixing
, which weights the row rather than entering the response, so the working
response is the gaussian one. An outer sampler that regresses on the latent itself is fitting a different
model, which is the composition defect these functions exist to prevent.
Random numbers. The draws come from R's own stream, through a generator created and
destroyed within the call: set.seed reproduces them, they advance the stream, and
they compose with any other R draw. They never touch a sampler's chain generator, which is seeded
separately and never advances R's stream. That stream is not thread safe, so these
functions must not be called from a worker thread; call them on the main thread and hand the
result to the workers.
A numeric vector of length . dbartsDrawLatents carries a "quantity"
attribute of "location" ("probit", "ordinal", "aft") or
"precision" ("logistic", "nbinom", "student"), matching what
getLatents reports for that family.
dbartsSampler, whose getLatents,
getFitsWithoutOffset and getShape methods report the same quantities from
inside a running sampler.
set.seed(99) f <- rnorm(50L) o <- rep(0.25, 50L) y <- rbinom(50L, 1L, pnorm(f + o)) # one Albert-Chib step: the truncated-normal latent at the current fit, then # the response the outer sampler regresses on z <- dbartsDrawLatents("probit", fit = f, y = y, offset = o) attr(z, "quantity") head(dbartsWorkingResponse("probit", latent = z, y = y, offset = o)) # logistic draws a PRECISION, so its working response is a quotient, not the # latent shifted w <- dbartsDrawLatents("logistic", fit = f, y = y, offset = o) head(dbartsWorkingResponse("logistic", latent = w, y = y, offset = o))set.seed(99) f <- rnorm(50L) o <- rep(0.25, 50L) y <- rbinom(50L, 1L, pnorm(f + o)) # one Albert-Chib step: the truncated-normal latent at the current fit, then # the response the outer sampler regresses on z <- dbartsDrawLatents("probit", fit = f, y = y, offset = o) attr(z, "quantity") head(dbartsWorkingResponse("probit", latent = z, y = y, offset = o)) # logistic draws a PRECISION, so its working response is a quotient, not the # latent shifted w <- dbartsDrawLatents("logistic", fit = f, y = y, offset = o) head(dbartsWorkingResponse("logistic", latent = w, y = y, offset = o))
Convenience function to create a control object for use with a dbarts sampler.
Every integer-valued argument here (n.samples, n.cuts, n.burn, n.trees, n.chains, n.threads, n.thin, printEvery, printCutoffs, categoricalExhaustiveCap, testFitParallelCutoff, predictParallelCutoff, n.perturb.cuts, seed) refuses a fractional double, naming the argument, rather than silently truncating it - the same whole-number rule every other count formal in the package follows, since it too is coerced through this construction.
dbartsControl( verbose = FALSE, keepTrainingFits = TRUE, keepFits = TRUE, useQuantiles = NULL, treeShift = c("auto", "always", "never"), keepTrees = FALSE, storage = c("double", "single"), n.samples = NULL, n.cuts = NULL, n.burn = 200L, n.trees = NULL, n.chains = 4L, n.threads = min(dbarts::guessNumCores(), n.chains), n.thin = 1L, printEvery = 100L, printCutoffs = 0L, categoricalExhaustiveCap = 10L, testFitParallelCutoff = 65536L, predictParallelCutoff = 50000L, sparseDensityThreshold = 0.2, proposal.probs = c( birth_death = 0.6, swap = 0, change = 0.4, perturb = 0, rule_gibbs = 0, birth = 0.5), n.perturb.cuts = 1L, seed = NULL, updateState = TRUE, ...)dbartsControl( verbose = FALSE, keepTrainingFits = TRUE, keepFits = TRUE, useQuantiles = NULL, treeShift = c("auto", "always", "never"), keepTrees = FALSE, storage = c("double", "single"), n.samples = NULL, n.cuts = NULL, n.burn = 200L, n.trees = NULL, n.chains = 4L, n.threads = min(dbarts::guessNumCores(), n.chains), n.thin = 1L, printEvery = 100L, printCutoffs = 0L, categoricalExhaustiveCap = 10L, testFitParallelCutoff = 65536L, predictParallelCutoff = 50000L, sparseDensityThreshold = 0.2, proposal.probs = c( birth_death = 0.6, swap = 0, change = 0.4, perturb = 0, rule_gibbs = 0, birth = 0.5), n.perturb.cuts = 1L, seed = NULL, updateState = TRUE, ...)
... |
Not used for new code: the channel that lets a retired argument spelling reach a message naming its successor, instead of R's own “unused argument” error. Any other name is refused. Removed in dbarts 1.1-0. |
verbose |
Logical controlling sampler output to console. |
keepTrainingFits |
Logical controlling whether or not training fits are returned when the sampler runs. These are always computed as part of the fitting procedure, so disabling will not substantially impact running time. |
keepFits |
Logical controlling whether every per-observation channel - training fits, test fits, the heteroscedastic variance surface, and per-forest fits - is returned when the sampler runs; |
useQuantiles |
Deprecated: the rule belongs to the data, stated as |
treeShift |
A string, one of |
keepTrees |
A sampler saved to disk and reloaded needs its state stored first, with |
storage |
A character string selecting the precision of the internal running residual. The default |
n.samples |
A non-negative integer giving the default number of samples to return each time the sampler is run; |
n.cuts |
Deprecated: the cut count belongs to the data, stated as |
n.burn |
A non-negative integer determining how many samples, if any, are thrown away at the beginning of a run of the sampler. |
n.trees |
Deprecated: the number of trees belongs to the model, stated as |
n.chains |
A positive integer detailing the number of independent chains for the sampler to use. |
n.threads |
A positive integer giving a total thread budget, distinct from |
n.thin |
A positive integer determining how many iterations the MCMC chain should jump on the decision trees alone before recording a sample. Serves to “thin” the samples against serial correlation. |
printEvery |
If |
printCutoffs |
A non-negative integer specifying how many of the decision rules for a variable are printed in verbose mode. |
categoricalExhaustiveCap |
A positive integer of at least 2 and at most 30 giving the number of categories PRESENT at a node up to which the grow-from-root scan ( |
testFitParallelCutoff |
A positive integer giving the number of test rows at or above which a chain fits its test matrix across its share of the thread budget instead of on its own thread. Time only: the two paths compute in the same order and return bit-for-bit the same fits. The default sits past the measured crossover on the machine it was measured on - four threads win 1.54 times at 65536 rows and 2.97 times at 262144, while the serial path already costs 16.5 msec per iteration at 32768 - so a caller with large test sets and threads to spare may lower it. Requires |
predictParallelCutoff |
A positive integer giving the number of tree traversals (rows times trees times draws) at or above which |
sparseDensityThreshold |
A number in |
proposal.probs |
Named numeric vector or |
n.perturb.cuts |
The most cut positions a perturb proposal moves a split either way: a displacement is drawn uniformly from the cuts within that many positions of the current one, clipped to those the node's ancestors and descendants allow. A whole number from 1 to the cut cap of 65533, or |
seed |
Random number generator seed. |
updateState |
Logical setting the default behavior for many sampler methods with regards to the immediate updating of the cached state of the object. A current, cached state is what saving/loading the sampler needs, and it is also the state a |
An object of class dbartsControl. Besides the settings it was given, its n.trees, useQuantiles and binary slots read what the sampler that holds it runs, the model's count, the data's rule and whether the family is binary; they are copies the sampler writes, kept so that code that reads them goes on working, and the family alone decides binary. A control taken from a fit carries its run settings and nothing else into the next fit, through any function that takes a control.
Nine fixed values decide what the engine will represent and where it switches strategy. Each was measured on one machine (arm64 macOS, 10 cores); the five that a workload can profitably move are settings here, and the rest are limits of the representation or of a proposal family, with nothing found that moving would buy. A recommended range is given where a measurement supports one.
| Limit | Where | Default | Recommended | Settable |
| Cuts per predictor | quantized predictor code | 65533 | up to the cap | no; n.cuts above it is refused |
| Categorical levels | quantized predictor code | 65535 | any real factor | no; a wider factor is refused by name |
| Ordered-factor levels | quantized predictor code | 65534 | any real factor | no; one code goes to the cut grid |
| Exact categorical enumeration | grow-from-root scan | 10 present levels | 8 to 14 | yes, categoricalExhaustiveCap |
| Perturb window | the perturb proposal | 1 grid position | 1 | yes, n.perturb.cuts, up to the cut cap or Inf; acceptance falls with width |
| Test-fit parallel cutoff | test-set fitting | 65536 rows | 8192 to 65536 | yes, testFitParallelCutoff |
| Predict parallel cutoff | predict |
50000 traversals | 3e4 to 1e5 | yes, predictParallelCutoff |
| Sparse density threshold | dgCMatrix storage |
0.2 | 0.05 to 0.5 | yes, sparseDensityThreshold |
| Gaussian-process leaf size | gp leaves |
256 observations | 256 to 512 | yes, gp(max.leaf.size = )
|
Of the settings in this table, the categorical enumeration cap and the Gaussian-process leaf size change what is sampled. The perturb window changes how a proposal moves, so it changes the draws, but not the posterior they target. The two parallel cutoffs buy time and return bit-for-bit the same draws either side of themselves. The density threshold buys memory and draws the same splits either side, but is not bitwise, as its entry above says.
## a small, single-chain, reproducible control for embedding a sampler in a ## larger Gibbs loop: one sample per run(), no burn-in, state cached on demand control <- dbartsControl(n.chains = 1L, n.threads = 1L, n.burn = 0L, n.samples = 1L, seed = 7L, updateState = FALSE) control n <- 50L x <- matrix(runif(n * 2L), n, 2L) y <- x[, 1L] - x[, 2L] + rnorm(n, 0, 0.2) sampler <- dbarts(y ~ x, control = control, n.trees = 25L) samples <- sampler$run() str(samples$train)## a small, single-chain, reproducible control for embedding a sampler in a ## larger Gibbs loop: one sample per run(), no burn-in, state cached on demand control <- dbartsControl(n.chains = 1L, n.threads = 1L, n.burn = 0L, n.samples = 1L, seed = 7L, updateState = FALSE) control n <- 50L x <- matrix(runif(n * 2L), n, 2L) y <- x[, 1L] - x[, 2L] + rnorm(n, 0, 0.2) sampler <- dbarts(y ~ x, control = control, n.trees = 25L) samples <- sampler$run() str(samples$train)
Convenience function to create a data object for use with a dbarts sampler.
dbartsData( formula, data, test, subset, weights, offset, offset.test = offset, factors = c("categorical", "indicators"), na.action = dbarts::na.keepPredictors, counts = NULL, n.cuts = NULL, useQuantiles = NULL, keep.data = TRUE)dbartsData( formula, data, test, subset, weights, offset, offset.test = offset, factors = c("categorical", "indicators"), na.action = dbarts::na.keepPredictors, counts = NULL, n.cuts = NULL, useQuantiles = NULL, keep.data = TRUE)
formula, data, test, subset, weights, offset, offset.test, factors, na.action
|
As in |
n.cuts, useQuantiles
|
The maximum number of cut points per predictor, one number for every column, one per column, or by column or term name with |
keep.data |
Whether an object built from a formula and a data frame or list keeps the frame. |
counts |
Optional |
Built from a formula and a data frame or list, with keep.data = TRUE, the object keeps data whole (in its frame slot), rows, the positions in it of the rows kept after subset and the na.action, read from the model frame as lm reads them, so an na.action that records nothing of what it drops keeps the rows it returns (NULL when every row is kept in order; a repeated row, and a NA in subset that the na.action keeps, appear as they are), rows.total, the number of rows handed over, which rows are positions within (NULL where rows is), frame.columns, the names of its columns, frame.source, "frame" ("environment" beside the names of an environment the data were read from, and NULL where no data were given), and what reads the formula, weights and offset against the frame again. A caller's variable the formula, weights or offset names is kept as its value at the build, a function of no package among them, with the names it reads, so that a later change to the workspace, a function redefined or removed included, leaves the object unchanged; a function local to a caller's function is kept without the rest of that function's variables, and a package's function by name. A later change to data leaves the object unchanged. The slots x, y, and where they were given weights and offset hold a stand-in that stops, naming model.frame(object), under dim, length, [, as.matrix, as.numeric, arithmetic, sum, mean, c, rep, unique, cbind, rbind and sd; is.na, anyNA and is.finite stop too, rather than answer for values the slot does not hold; var and paste read it in R's own code, which gives no way to stop them, and answer NA with a warning or the slot's name; attr() of one gives NULL, and a weights or offset that was not given is NULL. Read the data with model.frame(object) and nobs(object), which counts the rows in the likelihood (those with a positive weight), as it does for a fit. Every refusal and warning of the build is given at the build.
A sampler, and dbartsSpec's data, are made from the block-holding object that keep.data = FALSE gives, which the fitting functions make from a frame-keeping one by evaluating the formula against the frame again, on the kept rows, with the caller's variables as they were at the build; the sampler's data hold no frame. A frame-keeping object loaded in another session does this at its first fit, so the packages its formula calls must be installed there. A build whose formula, weights or offset draw from R's random-number generator, as rnorm(n) ~ x and y ~ jitter(x) do, keeps no frame and holds the values drawn, as keep.data = FALSE does, so that every fit from the object fits the same values; drawing data or subset does not count, as the frame and the rows are kept. A term drawing from a generator outside R's, which leaves R's stream where it was, is not seen: the object keeps its frame and draws again at each fit.
Data frame columns - through the formula interface or a frame passed as x.train - map to predictors as follows:
numeric and logical columns enter as ordinal predictors, as do classed numbers such as Date, POSIXct and difftime, by their numeric value (a POSIXlt column is refused; convert it with as.POSIXct);
unordered factors each become a single categorical predictor under the default factors = "categorical", with splits sending a subset of levels down each branch; factors = "indicators" instead expands each factor into binary indicator columns, as previous versions always did - a factor past 100 levels builds this expansion as a sparse (dgCMatrix-backed) block automatically, with no user-facing argument: the tree structure grown is the same as the dense expansion's, though leaf-mean draws can differ from it in the last bit;
ordered factors enter as their own predictor kind, coded numerically by level order and split at a threshold on those codes; the split grid is the midpoints between consecutive declared levels, one candidate per level boundary, so n.cuts does not apply to such a column and adjacent levels are always separable;
matrix columns (e.g. from poly) splice in as ordinal predictors, one per column;
Matrix::sparseVector and dgCMatrix columns (assigned into the frame; they do not survive data.frame(...) or I()) enter as sparse ordinal predictors. Both interfaces accept them for training: a bare S4 column does not survive model.frame, so the formula path lifts any such column out of data before model.frame runs and re-attaches it, row-subset under subset and na.action alike, to the assembled predictor matrix afterward - named in formula like any other column, including through ., with no marker. A sparse name wrapped in poly(), ns(), log(), offset(), or a ':'/'*' interaction is refused by name, as an interaction among dense terms already is. test/x.test accepts them under either interface, since a test set is never run through model.frame;
sparseFactor columns enter as a single sparse categorical predictor, coded and binned identically to a dense factor of the same values. Both interfaces accept them, the same pull-out/re-attach the other sparse column kinds get on the formula path.
On the formula path, a sparse column re-attaches after every dense term regardless of where it was named, each in the order its name appears in formula (after . expansion) rather than its position in data; test is matched to x.train by name (or by position when neither carries names), so the two stay aligned regardless of this reordering.
Factor level tables are retained so that test data are coded identically, and a factor predictor's level count - ordered or unordered - is the declared level table rather than the levels the training rows happen to take. A level declared but unobserved in training therefore keeps its own bin, and test or replacement data carrying it are accepted at every entrance (creation, setTestPredictor, predict, setPredictor, setData, which reads a factor of the new data by label against the sampler's table whatever levels it declares); conversely a value that is not an existing integer level code is refused at those same entrances, naming the kind, for ordered and unordered factors alike. An unordered factor is limited to 65535 levels and an ordered one to 65534 - one lower, since an ordered factor spends a code on the upper bin of its cut grid - and a wider one is an error naming the column. This holds equally for dense factors, sparseFactor columns, and dense factors inside a mixed dense/sparse frame. Drop unused levels before fitting (droplevels) if you would rather they not be modeled. test accepts the same column types as x.train, including sparseFactor and sparse ordinal columns. A sparseFactor or sparse ordinal test column recodes over the training level table and stays resident - through creation and setTestPredictor - rather than densifying at ingestion, the same storage tier rule as training. predict and getTrees(newdata = ) code a test set the same way and then route its rows through the trees off that storage, materializing no dense matrix of their own.
Data frame input is stored columnar: no double matrix is retained. Code that previously reached into the data object's x slot expecting a plain matrix should call extract(sampler, "predictors") - or as.matrix on the slot - to obtain the numeric predictor matrix, factor columns as their integer codes.
An object of class dbartsData. Its frame, rows, frame.columns and frame.source slots are described under ‘Data kept’. Its rowNames slot records the names of the kept training and test rows, as list(train, test), or NULL when neither is named; a fit carries them on its outputs as the row names paragraph of bart's ‘Value’ section describes. Its bases, basis.levels, basis.written and basis.scale slots are NULL as created: a forest's basis is stated on the forest (see forest), and these slots are written on the data object a sampler of several forests holds. There bases holds each forest's block as the sampler uses it, a factor's level indicators among them; basis.levels records, for each forest of levels, the levels in the order of the block's columns, and NULL for a forest of numbers or with no basis; and basis.written the text each basis written as code was written as, NA for a basis handed over as a value and for a forest with none, by which a forest beside these data keeps the held basis (forest(basis = factor(z)) for one written factor(z)). on the data object a sampler holds it records, for each forest of numbers that states no sd, the standard deviation of its column over the rows in the likelihood when the sampler was first created, which that forest's default sd was taken from (see sd in forest), and a sampler created from such an object is handed it, so a copy, a reload and a sampler made again from its own control, model and data have the creation's prior whatever column is then in force. A forest that names a held basis by its text keeps the entry, wherever it stands in the list, and one given a new value takes the scale of that value; clearing an entry by hand has the next creation take the scale of the column in force. Its missing.seen slot is NULL as created; on the data object a sampler holds it records, once a predictor has been changed, the columns that sampler can hold missing values in, as a logical per predictor column (see ‘Missing values in predictors’ in dbartsSampler), and a sampler created from such an object takes them. Its status slot is NULL as created; on the data object an aft sampler holds it records the censoring status in force, 1 for an event and 0 for a censored row, which setResponse(status = ) rewrites and a copy or a reload is created from. Its useQuantiles slot is NA as created; on the data object a sampler holds it records whether the cut points are placed at the predictors' quantiles (see useQuantiles in dbartsControl), the value the sampler's control then carries.
Four more slots record what a sampler derives from its data; where basis.scale keeps the value of the sampler's first creation, they follow what the sampler holds while the data move. Each is NULL as created: cutPoints, a list with one entry per predictor column, NULL for an unordered factor and otherwise the column's cut points, strictly increasing, with their weights, where they are not equally likely, as the entry's "mass" attribute (an increasing sequence whose successive differences are the weights, as a state's cutMass holds them); response.range, the c(min, max) of the response the leaf prior's scale is taken from, NULL under a family that reads none (probit, logistic, ordinal and multinomial), and under nbinom c(center, center + 1) of the count fit's center, where a pair of another width, as a range recorded under another family is, is read by its first number, the sampler recording it as c(center, center + 1), and an equal pair is refused; forest.calibration, c(anchor = , unit = ) of a model of several forests (see forest), NULL elsewhere; and standardization, for a forest of linear or gp leaves a list with one entry per forest holding list(center = , scale = ), each named by the leaf covariates where each one's column name is present, non-empty and the name of no other column, and otherwise with columns, their column positions, beside them, a scale of NA for a covariate without spread, and beside them, for gp leaves whose model gives no lengthscale, the lengthscale derived with them; NULL as a whole, and not an entry per forest, where no forest's leaves take a covariate. The data object a sampler holds, sampler$data, records them from creation on, and the sampler rewrites them after every call that changes one. A sampler created from a data object by new("dbartsSampler", control, model, data), and the copy and reload of a sampler, which are created from its own, uses each value the object records and derives the others. A new fit, by dbarts, bart or dbartsSpec, takes the cut points and the leaf standardization the object records and derives the response-based values from its response: response.range, forest.calibration and sigma's starting estimate (unless sigest states one), so dbarts(sampler$data) after sampler$setResponse() calibrates to the new response, as a fresh fit does, and sampler$copy() is the way to the same model again. A data object made afresh from the same rows derives its own. No door states a response range: the records are read only from a sampler's own data. A sampler's setData does the same, except that it keeps its own response range where the object records none, unless its updateCutPoints, updateScale or updateStandardization says to derive a value or to keep the sampler's (see dbartsSampler-class), so sampler$setData(sampler$data), the object handed back whole, keeps them. xbart takes cutPoints for every fold and derives the others in each fold, from the fold's training rows, whatever the object records. A record that fits no data - another number of columns, cut points for an unordered factor, on an ordered factor other than those of its levels, repeated or not finite, a range that is not two finite numbers, a standardization whose centers are not finite, whose scales are neither positive nor NA, whose lengthscales are not positive, whose names are missing, empty or repeated, or whose columns are not one position per center - is refused, naming the slot; setting it to NULL derives the value instead. Cut points out of order are sorted. Which covariates the leaves take is the model's, so a standardization is matched to them by its keys, names to leaf columns whose names could key one, the others deriving, columns where a leaf column's name could not, and one with neither by position where the counts agree: an entry for a covariate the leaves do not take is not read, a covariate without one is derived, and a lengthscale the model supplies is used in place of the record's.
dbarts, model.frame.dbartsData, extract.dbartsSampler, sparseFactor
set.seed(3) n <- 60L df <- data.frame( x = runif(n), g = factor(sample(c("a", "b", "c"), n, replace = TRUE)) ) df$y <- df$x + 0.5 * (df$g == "b") + rnorm(n, 0, 0.1) ## the formula interface; 'g' enters as one categorical predictor data <- dbartsData(y ~ x + g, df) data ## the same data through the backwards-compatible x/y interface, with a ## test set that is coded against the training level table train <- df[1:40, ] test <- df[41:60, c("x", "g")] data <- dbartsData(train[, c("x", "g")], train$y, test) ## build a sampler on it, rather than letting dbarts() ingest again sampler <- dbarts(data, control = dbartsControl( n.chains = 1L, n.threads = 1L, n.samples = 10L, n.burn = 10L, updateState = FALSE), n.trees = 25L) samples <- sampler$run() str(samples$test)set.seed(3) n <- 60L df <- data.frame( x = runif(n), g = factor(sample(c("a", "b", "c"), n, replace = TRUE)) ) df$y <- df$x + 0.5 * (df$g == "b") + rnorm(n, 0, 0.1) ## the formula interface; 'g' enters as one categorical predictor data <- dbartsData(y ~ x + g, df) data ## the same data through the backwards-compatible x/y interface, with a ## test set that is coded against the training level table train <- df[1:40, ] test <- df[41:60, c("x", "g")] data <- dbartsData(train[, c("x", "g")], train$y, test) ## build a sampler on it, rather than letting dbarts() ingest again sampler <- dbarts(data, control = dbartsControl( n.chains = 1L, n.threads = 1L, n.samples = 10L, n.burn = 10L, updateState = FALSE), n.trees = 25L) samples <- sampler$run() str(samples$test)
A list of constructor functions building the response families that the
family argument of bart, dbarts,
dbartsSpec and xbart accepts. Bundling them
keeps generic names like gaussian and probit out of the
search path, where another package - stats::gaussian first among
them - could mask them or be masked depending on attach order.
family takes either a token string (family = "gaussian"),
meaning that family at its defaults, or one of these calls
(family = student(df = 4)), meaning that family with settings.
Inside the family argument the constructors resolve by bare name
whatever the caller has attached, exactly as the prior vocabulary does
inside split.probs, including when a wrapper forwards the argument
through its own ...; elsewhere reach them through this list. That
vocabulary shadows the caller's own frame for these ten names only, so a
variable named gaussian holding student(3) resolves there
to the gaussian family, not to its own value; name such a variable
something else, or write dbartsFamilies$student(3). A wrapper's
named formal that instead forces a bare constructor call before passing it
on reaches R's own could-not-find-function error, extended with the same
hint naming dbartsFamilies$student(...) and its siblings.
Base R's family objects are accepted as glm takes them.
stats::gaussian(), or stats::gaussian(link = "identity"), is
the gaussian family (dbarts's own gaussian() below takes no
link, since the identity link is the only one it fits, and refuses
one by name),
binomial(link = "probit") is probit, and
binomial(link = "logit") is logistic; the word
"binomial" and the bare function binomial mean
binomial(), the logit link, so a 0/1 response fit with
family = binomial is logistic where "auto" is probit. Any
other link of those two, and every other stats, quasi or foreign
family (poisson, Gamma, quasibinomial,
MASS::negative.binomial, ...), is refused by name.
Every setting that only one family reads rides its family object rather
than a formal of the fitting function. That includes the residual
scale's own prior, sigma, on the four families that draw a
residual scale: it takes a dbartsPriors residual prior,
chisq(df, quant) or fixed(value), resolved in the prior
vocabulary inside the family call. The retired spellings
resid.prior, sigdf and sigquant are accepted for
one release with a once-per-session warning and are removed in dbarts
1.1-0; resid.prior is retired that way on dbarts
and xbart as well (dbartsSpec refuses it), so the family
object is the one home of the residual prior. A call that writes the prior
both ways is refused where the two disagree, naming both spellings, and
accepted in silence where they say the same thing.
## S4 method for signature 'dbartsFamily' show(object)## S4 method for signature 'dbartsFamily' show(object)
object |
A family object, as one of the constructors below returns. Printing one names the call that would build it. A family object carrying a setting its constructor does not take is refused by name. |
A list of functions:
gaussian(sigma = NULL)A continuous response with normal errors; the default for a numeric
response under family = "auto". sigma is the prior on
the residual scale: NULL is the shipped
chisq(3, 0.9), chisq(df, quant) names another
scaled-inverse-chi-squared, and fixed(value) pins the
residual variance and suppresses the sampler's own draw, which is
what an outer sampler owning wants. The former
resid.prior, sigdf and sigquant arguments.
sigest, the estimate the chisq quantile is calibrated
against, is not a family setting and stays a fitting-function
argument; it stands beside chisq, and is refused beside
fixed, which has no scale to calibrate.
student(df = NULL, sigma = NULL)A continuous response with outlier-robust Student-t errors, drawn by
the Gaussian scale-mixture augmentation. df = NULL estimates
the degrees of freedom on a capped grid; a positive number fixes
them. sigma is the scale-mixture's own residual prior, as for
gaussian.
probit(), logistic()
Binary latent-variable models for a 0/1 response.
multinomial(), ordinal()
Unordered K-category softmax and ordered cumulative-probit models.
nbinom(shape = NULL)Negative-binomial counts on a log link: the forest models the log of
the mean count, and the variance is
for shape . A larger shape is closer to Poisson; is
size in rnbinom and theta in MASS and mgcv.
NULL estimates the shape
on a capped positive-integer grid; a positive integer fixes
it. Each sweep's latent draw costs time in proportion to
, so a large fixed is slow: at
, a thousand sweeps over a thousand
observations take about half an hour. By in the hundreds
the model is already close to a Poisson one. A fixed shape above
is refused, as a count above it is.
aft(sigma = NULL)Accelerated failure time (log-normal) survival. The log-time
residual scale is drawn as a gaussian one is, so sigma is its
prior, as for gaussian.
hazard(breaks = NULL, link = c("probit", "logistic"))Discrete-time survival hazard by person-period expansion.
breaks sets the period grid: NULL uses the sorted
distinct observed times of the subjects in the likelihood (those of
positive weight), a single positive integer bins at that many
quantiles of those times, and a numeric boundary vector gives explicit right-closed
intervals. link selects the binary link the
expanded rows are fit under, and is what the tokens
"hazard.probit" and "hazard.logistic" name.
A hazard fit keeps its trees by default (keepTrees = NULL in
bart), because its survival curves replay them; the
trees take about 20 to 27 MB at the defaults, whatever the row count.
keepTrees = FALSE drops them, and then
survivalProbabilities refuses.
A subject is at risk for one row a period, so on the default grid with
distinct times the rows grow as the square of the subjects (1,000
subjects give about 500,000 rows) and on a grid of periods as
times the subjects. Memory, not time, is what a row costs: at
bart's defaults (four chains of 500 kept draws, 75
trees) about 35 KB a row at its peak, about 32 KB of which are the kept
draws of the training fits (8 bytes a draw a chain in the fit returned,
and about 16 while they are copied out), so a million rows take about
35 GB. keepTrainingFits = FALSE leaves about 3 KB a row: about
300 bytes the chains share and about 620 a chain, 8 bytes a tree. A
predictor column beyond three adds about 34 bytes a row, and a held-out
subject passed as test is expanded to every period. No row count is refused: when the peak
projected from these figures exceeds the machine's physical memory, the
fit warns once per session, before any row is built, with a warning of
class dbartsMemoryWarning that names the rows, the two figures
and the ways out (a coarser hazard(breaks = ),
keepTrainingFits = FALSE or fewer chains), and then runs; a
sampler's $setData warns the same way. The memory read is the
smaller of the machine's installed memory and, on Linux, the limit a
container or a job scheduler sets on the process (its cgroup's
memory.max, or memory.limit_in_bytes in version 1), and
the warning says “this process may use” that limit where it is
the smaller. Where neither can be read there is no warning.
hurdle.lognormal(sigma = NULL)A semicontinuous two-part response: a zero-part probit glued to a
lognormal positive part. Composed from two samplers, so only
bart fits it. sigma is the positive part's
residual prior; the zero-part probit has a fixed unit latent scale
and takes none.
Which entry points accept which family:
| family | bart | dbarts | dbartsSpec | xbart |
gaussian |
yes | yes | yes | yes |
student |
yes | yes | yes | no |
probit |
yes | yes | yes | yes |
logistic |
yes | yes | yes | yes |
aft |
yes | yes | yes | no |
multinomial |
yes | yes | yes | no |
ordinal |
yes | yes | yes | no |
nbinom |
yes | yes | yes | no |
hazard |
yes | yes | no | no |
hurdle.lognormal |
yes | no | no | no |
A family the entry point does not fit is refused by name. See
dbarts's family argument for what each family
models and what it supports.
f <- dbartsFamilies$student(df = 4) f ## the residual prior rides the family too dbartsFamilies$gaussian(sigma = dbartsPriors$chisq(df = 5, quant = 0.75)) set.seed(99) n <- 100L x <- matrix(rnorm(n * 2L), n, 2L) y <- x[, 1L] + rt(n, 4) fit <- bart( x, y, family = student(df = 4), n.samples = 50L, n.burn = 50L, n.chains = 1L, verbose = FALSE )f <- dbartsFamilies$student(df = 4) f ## the residual prior rides the family too dbartsFamilies$gaussian(sigma = dbartsPriors$chisq(df = 5, quant = 0.75)) set.seed(99) n <- 100L x <- matrix(rnorm(n * 2L), n, 2L) y <- x[, 1L] + rt(n, 4) fit <- bart( x, y, family = student(df = 4), n.samples = 50L, n.burn = 50L, n.chains = 1L, verbose = FALSE )
A list of the constructor functions building the forest specifications that
the monotone, interactions, blocks, variance and
forests arguments of dbarts, dbartsSpec and
bart accept. The constructors are not exported, so that names
like forest and blocks stay out of the search path, where
another package could mask them or be masked depending on attach order.
Inside those arguments, and inside a formula's forest() term, the
constructors resolve by bare name: a call is always the constructor, and a
bare name the caller has assigned a value to is that value. Anywhere else -
a specification built ahead of the call, or an argument a wrapper forces
before passing it on - write dbartsForests$interactions(...).
forest()'s first argument, the predictors a forest splits on, is
read as terms when it names a predictor of the fit and otherwise takes the
value it has where and when the constructor is called. Its basis is
read the same way: a name of a column of the fit's data is that column, and
anything else is what it was where and when the constructor is called; see
forest.
A list of functions:
interactionsInteraction constraints; see interactions.
blocksBlock-additive constraints; see blocks.
monotoneMonotone constraints and their prior; see monotone.
forestOne forest of a model, in a forests list or as a term of a
formula; see forest.
varianceForestThe heteroscedastic variance forest; see varianceForest.
dbarts, bart, dbartsPriors,
dbartsFamilies
## built ahead of the call, then passed as a value constraint <- dbartsForests$interactions(max.order = 1) set.seed(0) n <- 100L x <- matrix(runif(n * 3), n, 3, dimnames = list(NULL, c("x1", "x2", "x3"))) y <- 2 * x[, 1] + ifelse(x[, 2] > 0.5, 1, -1) + rnorm(n, 0, 0.2) fit <- bart(x, y, interactions = constraint, n.trees = 25L, n.samples = 20L, n.burn = 20L, n.chains = 1L, verbose = FALSE) ## the same constraint, written by bare name inside the argument fit.bare <- bart(x, y, interactions = interactions(max.order = 1), n.trees = 25L, n.samples = 20L, n.burn = 20L, n.chains = 1L, verbose = FALSE)## built ahead of the call, then passed as a value constraint <- dbartsForests$interactions(max.order = 1) set.seed(0) n <- 100L x <- matrix(runif(n * 3), n, 3, dimnames = list(NULL, c("x1", "x2", "x3"))) y <- 2 * x[, 1] + ifelse(x[, 2] > 0.5, 1, -1) + rnorm(n, 0, 0.2) fit <- bart(x, y, interactions = constraint, n.trees = 25L, n.samples = 20L, n.burn = 20L, n.chains = 1L, verbose = FALSE) ## the same constraint, written by bare name inside the argument fit.bare <- bart(x, y, interactions = interactions(max.order = 1), n.trees = 25L, n.samples = 20L, n.burn = 20L, n.chains = 1L, verbose = FALSE)
The container a data frame's predictor columns assemble into whenever any
column is sparse-backed (a sparseFactor column, or a
Matrix::sparseVector/dgCMatrix column assigned into the
frame): dense columns stay a per-column list and sparse columns stay one
shared dgCMatrix, rather than materializing one dense matrix. makeModelMatrixFromDataFrame returns
one whenever x carries a sparse column; dbartsData's
x/y interface (and so dbarts's and bart's)
returns one under the same condition and stores it in the resulting
dbartsData object's x/x.test slot. A fit or sampler
made from a formula or a data frame holds one as its data@x
whether or not a column is sparse. The formula
interface accepts a sparse column too, named like any other (including
through .): a bare S4 column cannot survive
model.frame, so it is lifted out of data first and
re-attached, row-subset under subset and na.action, to the
assembled predictor matrix afterward.
## S3 method for class 'dbartsMixedMatrix' dim(x) ## S3 method for class 'dbartsMixedMatrix' dimnames(x) ## S3 method for class 'dbartsMixedMatrix' x[i, j, drop = TRUE] ## S3 method for class 'dbartsMixedMatrix' as.matrix(x, ...) ## S3 method for class 'dbartsMixedMatrix' as.data.frame(x, row.names = NULL, optional = FALSE, ...)## S3 method for class 'dbartsMixedMatrix' dim(x) ## S3 method for class 'dbartsMixedMatrix' dimnames(x) ## S3 method for class 'dbartsMixedMatrix' x[i, j, drop = TRUE] ## S3 method for class 'dbartsMixedMatrix' as.matrix(x, ...) ## S3 method for class 'dbartsMixedMatrix' as.data.frame(x, row.names = NULL, optional = FALSE, ...)
x |
An object of class |
i, j
|
Row and column indices, as for a matrix. Supplying |
drop |
Logical; as for a matrix, only consulted when |
row.names |
|
optional |
Unused. |
... |
Unused. |
dim and dimnames - and so the base nrow, ncol,
and colnames, which are defined in terms of them and need no
method of their own - read like a matrix's; row names are always
NULL. x[, j] (or x[, "name"]) returns the
indexed/named column(s) as an ordinary numeric vector or matrix.
x[i, ] keeps the container, row-subset. x[i] with j
omitted also row-subsets, unlike a plain matrix's single-index linear
indexing. as.matrix materializes the whole object to a dense
numeric matrix (a factor column's codes,
zero-based) and is the escape hatch for any operation the container
itself does not support.
as.data.frame gives the predictors as the model sees them, one
column per column of the container, named by colnames(x): numeric
columns as numeric, and a factor column as a factor over its declared
levels, which keeps a level no row takes. For a fit made from a formula of
plain variables, predict and setTestPredictor take that data
frame as new data. A formula that transforms or expands a variable
(I(z^2), factor(i), a matrix term, poly(z, 2)) names
columns that are not the variables it reads, so new data for it is a data
frame of those variables, not this one.
What is not supported: matrix-style subassignment (x[i, j]
<- value errors). is.matrix(x) is FALSE, and a base function
that does not dispatch on the class, such as cbind, does not see a
matrix. Code that needs a matrix should call as.matrix(x) first.
dim returns an integer vector of length two. dimnames
returns a length-two list, the first element always NULL. [
with j supplied returns a numeric vector or matrix, matching
drop; with j missing it returns another
dbartsMixedMatrix. as.matrix returns a plain numeric
matrix, and as.data.frame a data frame.
makeModelMatrixFromDataFrame, dbartsData,
sparseFactor
if (requireNamespace("Matrix", quietly = TRUE)) { df <- data.frame(a = 1:5) df$b <- Matrix::sparseVector(c(1, 2), c(1, 3), length = 5) mm <- makeModelMatrixFromDataFrame(df) class(mm) dim(mm) colnames(mm) mm[, "a"] as.matrix(mm) }if (requireNamespace("Matrix", quietly = TRUE)) { df <- data.frame(a = 1:5) df$b <- Matrix::sparseVector(c(1, 2), c(1, 3), length = 5) mm <- makeModelMatrixFromDataFrame(df) class(mm) dim(mm) colnames(mm) mm[, "a"] as.matrix(mm) }
A list of constructor functions building the prior specifications that the
split.probs (dart()) and leaf.prior arguments of
dbarts and the fitting functions accept. Bundling them keeps generic names like
normal out of the search path, where another package could mask them
or be masked depending on attach order.
The residual priors chisq and fixed are what a family
object's sigma setting takes - family = gaussian(sigma =
chisq(3, 0.9)) - which is the one place every entry point reaches the
residual prior; this vocabulary resolves by bare name inside that argument
too.
A list of functions:
cgm(power = 2, base = 0.95, split.probs = NULL)The value of the retired tree.prior argument of dbarts
and dbartsSpec, which is accepted with a warning until
dbarts 1.1-0, when cgm is removed. Write the tree prior as
power, base and split.probs instead. A
NULL power or base is the default. split.probs
weights the choice of split variable: NULL is uniform, a named
vector assigns by column or term name (with an optional
".default" element), an unnamed vector assigns by position.
Entries must be non-negative and finite, with at least one positive.
Named or positional probabilities are matched to the data when a
sampler is built. A column of probability zero is never split on, just
as one a forest's vars leaves out is never split on, on every
path: where the columns of positive probability are used up along a path, the node
cannot split. A sampler's $setModel refuses a zero on a column
its trees split on.
dart(a = 0.5, b = 1, rho = NULL,
alpha = 1, update.alpha = TRUE, update.delay = NULL)DART (Linero 2018), given as split.probs = dart(): a Dirichlet
prior over the split-variable probabilities inducing variable
selection. The tree's depth is the fitting function's power and
base, as without DART.
alpha is the concentration, optionally sampled
(update.alpha) on a grid with a Beta(a, b) prior
on alpha / (alpha + rho); rho defaults to the number of
predictors. NA is a missing value, not a spelling of the default,
and is refused for rho and update.delay alike. Updates hold
until update.delay iterations have
passed (default: half the control's burn-in), so the forest is
likelihood-informed when counts first enter the Dirichlet.
normal(k = NULL, sd = NULL)Normal prior on the leaf values, named one of two ways, never both. Either names the spread of the whole forest - the sum of trees - not of one tree.
k is relative to the scale the data fixes: a positive scalar,
a hyperprior on k built with chi, or NULL for
the default, 2 for continuous responses and chi(1.5, 2) for
binary ones and counts (nbinom). The continuous default follows Chipman, George, and
McCulloch's argument that with leaf standard deviation
sigma_mu = 0.5 / (k * sqrt(m)) for m trees, k
prior standard deviations of span the whole response
range regardless of m; see dbarts's Details for
the response-scaling caveat this relies on. A string such as
"chi(1.5)" is kept for 0.9-x. k = Inf is accepted and
holds every tree at zero, so the fit is the offset, plus on a
continuous response the center of the range y - offset spans.
sd is the standard deviation of the normal prior on the leaf
model's own parameter, for the forest total, on the scale the
family's forest fits: a positive number, or a hyperprior on the sd
itself built with invchi. It takes no string form. The scale
and the k.scale k is relative to, per family:
| family | sd is stated in |
k.scale at k = 1 |
| gaussian, student | response units | half the training response range |
| aft | log survival time | half the observed log-time range |
| probit, ordinal | probit latent | 3 |
| logistic | log-odds latent | |
| nbinom | log mean | 3 |
| hazard | its link's latent | 3 or
|
so a fixed k is the sd k.scale / k. For the
constant leaf sd is exactly the prior standard deviation of
at every ; for the other leaf models it is the sd of
their parameter, and the prior spread of it implies is a
consequence stated under each. Under a monotone constraint
(see dbarts) sd is the prior sd of a leaf value
that no ordered neighbor bounds; a leaf a neighbor bounds is drawn
from a normal times
as wide, truncated to the ordering, which matches its marginal prior
variance to sd^2, and sd is a lower bound on the prior
sd of in the interior. A named sd is absolute, and
is another way of writing k: the sampler runs sd = s as
k = k.scale / s against the table's k.scale, and
sd = invchi(df, s) as k = chi(df, k.scale / s) started
at k.scale / s, and restates either whenever the response
transform is re-anchored (see dbartsSampler-class), so
the sd, or the prior on it, keeps its meaning where a k moves
with the data. A drawn sd's current value lags at a re-anchor until
its next draw, as a drawn k does. The k.scale a sampler
or a fit reports is the table's, however the prior was written. It is
refused on multinomial and multi-forest
models (whose spreads come from their calibration maps, the latter
stated through forest(sd = ), a different quantity),
and on a hurdle fit, whose two parts are on different scales.
NULL leaves either unnamed; NA is a missing value and is
refused, here and in linear and gp. A bare normal()
given as a forest's amplitude is something else, a normal prior on
that forest's drawn coefficient whose median size is 1 (on a factor, the
difference between two levels' coefficients); see forest.
linear(columns, k = NULL, sd = NULL)Each leaf fits an intercept plus a linear term in the designated
continuous predictor columns instead of a constant, so the forest
models smoothly-varying coefficients. columns names model
matrix columns (character) or indexes them (numeric) and is matched
to the data when a sampler is built; unordered factor columns cannot
be designated. The covariates are standardized internally and every
coefficient shares the normal(k) prior. Reported leaf values
keep the intercept; getTrees adds one beta.<column>
column per covariate. xbart accepts the same
specification through its own leaf.prior argument.
k and sd name the spread as they do for
normal, sd per standardized covariate: every
coefficient, the intercept included, has prior sd sd for the
forest total, so the prior sd of is
sd * sqrt(1 + ||z||^2) at standardized covariates , and
sd is its lower bound, attained at the covariate means.
gp(columns, k = NULL, lengthscale = NULL,
max.leaf.size = 256L, sd = NULL)Each leaf fits a smooth Gaussian-process function of the designated
continuous predictor columns, drawn under a squared-exponential
kernel whose prior scale ties to k exactly as the other leaf
priors; columns resolves as for linear, and k
may be fixed or given the chi hyperprior, sampled from the
drawn functions' standardized magnitudes.
lengthscale fixes the kernel lengthscales on the
standardized covariate scale, one value per column or one recycled
scalar; NULL uses the median pairwise-distance heuristic per
column. Leaves holding more than max.leaf.size observations
fall back to constant fits, confining the cubic kernel cost.
Fewer trees are needed than for constant leaves: 10 to 25 is a
reasonable range, since each leaf already fits a smooth function, while
past about 50 the per-tree shrinkage leaves each function too small to
improve on constant fits and the cost, linear in the number of trees and
cubic in the leaf size, keeps rising. The two settings interact: a tree
typically holds only two or three leaves, so a leaf carries a sizable
fraction of the sample and max.leaf.size must be comparable to
that fraction for the kernel to be used at all; lowering n.trees
grows deeper trees and is the effective way to bring leaves under the
cap, whereas lowering max.leaf.size only sends more leaves to the
constant fallback.
Because that fallback is silent - the fit stays coherent, it is simply
not a Gaussian process over the leaves that took it - every leaf
evaluation is counted. The counts ride the fit as gp.fallback
(a named pair, evaluations and fallbacks), and a run in
which more than a quarter of evaluations fell back warns once (class dbartsGPFallbackWarning), giving
the share: at the default cap on a design of any size that is the
normal outcome, not an error, and the warning is the notice that the
cap rather than the kernel is doing the modeling. The remedies are the
two the paragraph above names, in the order it names them.
Function-valued fits ride prediction only: getTrees reports
NA leaf values, and keepTrees storage grows with the
leaf sizes. xbart accepts the same specification
through its own leaf.prior argument. k and sd
name the spread as they do for normal, sd as the
amplitude of the forest total's Gaussian process: the prior sd of
is sd at a leaf's own rows and decays away from
them, so sd is its upper bound.
predict at a training row re-krigs the jitter-free
posterior mean from the cached kernel and drawn training values,
while the fit recorded during sampling includes a small
conditioning nugget on the kernel diagonal; the two differ by
roughly 2e-3 to 3e-3 at training locations (never during MCMC,
which reads the recorded fit directly - only predict and
test-data prediction re-krig).
chi(df = 1.5, scale = 2)Chi hyperprior over k, sampled along with the rest of the
model: k is given a chi distribution with df degrees
of freedom and scale scale. The default, chi(1.5, 2),
centers the sampled k near the field-standard fixed value of
2 (prior median 1.9) while letting it adapt to the data. It is the
same prior as sd = invchi(df, k.scale / scale). scale =
Inf remains accepted, but the posterior it gives k is
improper: with little signal, few trees or many degrees of freedom,
k can drift to infinity, where every leaf is zero and the
trees add nothing to the fit. The first argument was
degreesOfFreedom in 0.9-x; that name is accepted, with a
warning, until dbarts 1.1-0.
invchi(df = 1.5, scale)Scaled inverse chi hyperprior over a leaf prior's sd, on the
sd's own scale: ,
equivalently is scaled inverse chi-square with
df degrees of freedom. scale has no default, since a
spread on the family's scale has no data-free one; scale = 0
is the improper limit. It is the
same prior as k = chi(df, k.scale / scale), and
chi(df, Inf) is invchi(df, 0); the binary defaults are
invchi(1.5, 1.5) on probit and
invchi(1.5, pi * sqrt(3) / 2) on logistic. In Stan's terms it
is scaled_inv_chi_square(df, scale / sqrt(df)) on the
variance, and an inverse gamma with shape df / 2 and scale
scale^2 / 2. No other distribution on the sd is offered: this is the
one conjugate to the normal leaves, which the sampler draws exactly;
a half-t or half-Cauchy would need a non-conjugate update. Refused
under a monotone constraint, as a chi on k is.
chisq(df = 3, quant = 0.9)Chi-squared prior on the residual variance. Its scale is set from
sigest, the residual-scale estimate supplied (or derived) at
creation: quant is the prior probability that the residual
standard deviation is below that estimate, so sigest = 1 gives
the prior under which is below 1 with probability
quant. df is a single positive finite number and
quant a single number between 0 and 1: an infinite df,
the limit that holds at a point, is refused, and
fixed() states a held value.
fixed(value = 1)Fixed residual variance, in squared response units. It is the residual
scale rather than a distribution over one, so it ignores sigest - which
is refused beside it unless it equals the square root of value,
when it is accepted with a message and is an error from dbarts 1.1-0 - and
suppresses the sampler's own draw. value
is a single positive finite number.
student(df = 1)A Student-t prior with df degrees of freedom, finite and at least
1, on a forest's drawn coefficient, given as a forest's
amplitude; see forest. A bare student() means
df = 1 here, the half-Cauchy, while the response family of the
same name, dbartsFamilies$student, estimates its df when
none is given; each is read by where it is written.
Inside the prior arguments of the fitting functions - and inside a family's
sigma - the same constructors are available by bare name, so dbarts(..., leaf.prior =
normal(chi(1.5))) works regardless of what packages are attached: those
arguments are evaluated with this vocabulary layered over the calling
environment (for an argument a wrapper forwards through its ...,
the one it was written in), along with num.vars, the number of predictor columns.
A prior object built ahead of time with dbartsPriors$... can be
passed to the same arguments. A wrapper's named formal that forces a bare
constructor call before passing it on reaches R's own could-not-find-function
error instead, extended with a hint naming dbartsPriors$normal(...) and
its siblings.
Chipman, H., George, E., and McCulloch, R. (2010) BART: Bayesian additive regression trees. The Annals of Applied Statistics, 4(1), 266–298. doi:10.1214/09-AOAS285.
Linero, A.R. (2018) Bayesian regression trees for high-dimensional prediction and variable selection. Journal of the American Statistical Association, 113(522), 626–636.
Gramacy, R.B. and Lee, H.K.H. (2008) Bayesian Treed Gaussian Process Models With an Application to Computer Modeling. Journal of the American Statistical Association, 103(483), 1119–1130.
prior <- dbartsPriors$normal(dbartsPriors$chi(1.5)) x <- matrix(runif(200), ncol = 2) y <- x[, 1] + rnorm(100, 0, 0.5) sampler <- dbarts(y ~ x, leaf.prior = prior, power = 1.5) ## DART: a Dirichlet prior over split-variable probabilities, useful ## when only a handful of predictors out of many are relevant set.seed(0) n <- 60L x.dart <- matrix(runif(n * 8), n) y.dart <- 4 * x.dart[, 1] + rnorm(n, 0, 0.2) fit.dart <- dbarts(y.dart ~ x.dart, split.probs = dart(), control = dbartsControl(n.chains = 1L, n.threads = 1L), n.trees = 10L) samples.dart <- fit.dart$run(20L, 20L) ## linear leaves: each leaf fits an intercept plus a slope in x1, ## useful for a function that is smooth and roughly linear in a subset ## of the predictors set.seed(1) x1 <- runif(n) x2 <- runif(n) y.lin <- 3 * x1 + rnorm(n, 0, 0.2) df.lin <- data.frame(x1, x2, y.lin) fit.lin <- dbarts(y.lin ~ x1 + x2, df.lin, leaf.prior = linear("x1"), control = dbartsControl(n.chains = 1L, n.threads = 1L), n.trees = 10L) samples.lin <- fit.lin$run(20L, 20L) ## gp leaves: each leaf fits a smooth Gaussian-process function of x1, ## useful for a smoothly-varying, nonlinear function set.seed(2) y.gp <- sin(2 * pi * x1) + rnorm(n, 0, 0.2) df.gp <- data.frame(x1, x2, y.gp) fit.gp <- dbarts(y.gp ~ x1 + x2, df.gp, leaf.prior = gp("x1", max.leaf.size = 52L), control = dbartsControl(n.chains = 1L, n.threads = 1L), n.trees = 10L) samples.gp <- fit.gp$run(20L, 20L) ## the cap of 52 observations per leaf sends some leaves to the constant ## fallback (about a tenth of the evaluations here), counted in gp.fallback; ## a warning comes only when more than a quarter fall back print(unlist(attr(samples.gp, "gp.fallback")))prior <- dbartsPriors$normal(dbartsPriors$chi(1.5)) x <- matrix(runif(200), ncol = 2) y <- x[, 1] + rnorm(100, 0, 0.5) sampler <- dbarts(y ~ x, leaf.prior = prior, power = 1.5) ## DART: a Dirichlet prior over split-variable probabilities, useful ## when only a handful of predictors out of many are relevant set.seed(0) n <- 60L x.dart <- matrix(runif(n * 8), n) y.dart <- 4 * x.dart[, 1] + rnorm(n, 0, 0.2) fit.dart <- dbarts(y.dart ~ x.dart, split.probs = dart(), control = dbartsControl(n.chains = 1L, n.threads = 1L), n.trees = 10L) samples.dart <- fit.dart$run(20L, 20L) ## linear leaves: each leaf fits an intercept plus a slope in x1, ## useful for a function that is smooth and roughly linear in a subset ## of the predictors set.seed(1) x1 <- runif(n) x2 <- runif(n) y.lin <- 3 * x1 + rnorm(n, 0, 0.2) df.lin <- data.frame(x1, x2, y.lin) fit.lin <- dbarts(y.lin ~ x1 + x2, df.lin, leaf.prior = linear("x1"), control = dbartsControl(n.chains = 1L, n.threads = 1L), n.trees = 10L) samples.lin <- fit.lin$run(20L, 20L) ## gp leaves: each leaf fits a smooth Gaussian-process function of x1, ## useful for a smoothly-varying, nonlinear function set.seed(2) y.gp <- sin(2 * pi * x1) + rnorm(n, 0, 0.2) df.gp <- data.frame(x1, x2, y.gp) fit.gp <- dbarts(y.gp ~ x1 + x2, df.gp, leaf.prior = gp("x1", max.leaf.size = 52L), control = dbartsControl(n.chains = 1L, n.threads = 1L), n.trees = 10L) samples.gp <- fit.gp$run(20L, 20L) ## the cap of 52 observations per leaf sends some leaves to the constant ## fallback (about a tenth of the evaluations here), counted in gp.fallback; ## a warning comes only when more than a quarter fall back print(unlist(attr(samples.gp, "gp.fallback")))
A reference class object that contains a Bayesian Additive Regression Trees sampler in such a way that it can be modified, stopped, and started all while maintaining its own state.
## S4 method for signature 'dbartsSampler' run( numBurnIn = NULL, numSamples = NULL, updateState = NULL, ..., callback = NULL ) ## S4 method for signature 'dbartsSampler' sampleTreesFromPrior(updateState = NULL) ## S4 method for signature 'dbartsSampler' sampleLeafParametersFromPrior(updateState = NULL) ## S4 method for signature 'dbartsSampler' sampleVarianceForestFromPrior(updateState = NULL) ## S4 method for signature 'dbartsSampler' growFromRoot(n.sweeps = 2L, updateState = NULL) ## S4 method for signature 'dbartsSampler' copy(shallow = FALSE) ## S4 method for signature 'dbartsSampler' show() ## S4 method for signature 'dbartsSampler' predict(x.test, offset.test, n.threads = [email protected]) ## S4 method for signature 'dbartsSampler' predictForests( x.test, offset.test, n.threads = [email protected] ) ## S4 method for signature 'dbartsSampler' setControl(newControl) ## S4 method for signature 'dbartsSampler' setModel(newModel) ## S4 method for signature 'dbartsSampler' setData( newData, updateState = NULL, updateCutPoints = NULL, updateScale = NULL, updateStandardization = NULL ) ## S4 method for signature 'dbartsSampler' setResponse( y, updateScale = FALSE, updateState = NULL, status = NULL ) ## S4 method for signature 'dbartsSampler' setOffset(offset, updateScale = FALSE, updateState = NULL) ## S4 method for signature 'dbartsSampler' setWeights( weights, updateState = NULL, updateScale = FALSE, updateStandardization = FALSE ) ## S4 method for signature 'dbartsSampler' setCategoryOffset(offset, updateState = NULL) ## S4 method for signature 'dbartsSampler' setCategoryTestOffset(offset.test) ## S4 method for signature 'dbartsSampler' setActiveRows( active, updateState = NULL, updateScale = FALSE, updateStandardization = FALSE ) ## S4 method for signature 'dbartsSampler' setForestWeights(forest, weights, updateState = NULL) ## S4 method for signature 'dbartsSampler' setForestBasis(forest, basis, updateState = NULL, updateBasisScale = FALSE) ## S4 method for signature 'dbartsSampler' setSigma(sigma, updateState = NULL) ## S4 method for signature 'dbartsSampler' setPredictor( x, column, forceUpdate, updateCutPoints = "none", updateState = NULL, updateStandardization = FALSE ) ## S4 method for signature 'dbartsSampler' setCutPoints(cuts, column, updateState = NULL, splits = "position") ## S4 method for signature 'dbartsSampler' setTestPredictor(x.test, column) ## S4 method for signature 'dbartsSampler' setTestPredictorAndOffset(x.test, offset.test) ## S4 method for signature 'dbartsSampler' setTestOffset(offset.test) ## S4 method for signature 'dbartsSampler' printTrees(treeNums, chainNums, sampleNums) ## S4 method for signature 'dbartsSampler' getTrees( treeNums, chainNums, sampleNums, current = FALSE, newdata = NULL, forest = NULL ) ## S4 method for signature 'dbartsSampler' getSigmas(result) ## S4 method for signature 'dbartsSampler' getShape() ## S4 method for signature 'dbartsSampler' getLatents(result) ## S4 method for signature 'dbartsSampler' getSumsOfSquaredResiduals(result) ## S4 method for signature 'dbartsSampler' getFitsWithoutOffset() ## S4 method for signature 'dbartsSampler' getVariance(test = FALSE) ## S4 method for signature 'dbartsSampler' getForestFits(forest = NULL) ## S4 method for signature 'dbartsSampler' getForestAmplitudes(forest = NULL) ## S4 method for signature 'dbartsSampler' getForestVariableCounts(forest = NULL) ## S4 method for signature 'dbartsSampler' getLeafPrior(forest = NULL) ## S4 method for signature 'dbartsSampler' getK(forest = NULL) ## S4 method for signature 'dbartsSampler' setLeafPrior(leaf.prior, updateState = NULL) ## S4 method for signature 'dbartsSampler' getForest(forest = NULL) ## S4 method for signature 'dbartsSampler' setForest(forest = NULL, sd = NULL, power = NULL, base = NULL, amplitude = NULL, proposal.probs = NULL, n.perturb.cuts = NULL, treeShift = NULL, updateState = NULL, n.trees = NULL, vars = NULL, interactions = NULL, blocks = NULL, basis = NULL, ...) ## S4 method for signature 'dbartsSampler' setTreePrior(power = NULL, base = NULL, split.probs = NULL) ## S4 method for signature 'dbartsSampler' getVarianceForest() ## S4 method for signature 'dbartsSampler' setVarianceForest(power = NULL, base = NULL, proposal.probs = NULL, n.perturb.cuts = NULL, updateState = NULL, n.trees = NULL, vars = NULL, ...) ## S4 method for signature 'dbartsSampler' installTrees(donor, samples = NULL, forceUpdate = FALSE) ## S4 method for signature 'dbartsSampler' sampleNodeParametersFromPrior(updateState = NULL) ## S4 method for signature 'dbartsSampler' startThreads(n.threads = [email protected]) ## S4 method for signature 'dbartsSampler' stopThreads() ## S4 method for signature 'dbartsSampler' storeState(ptr = getPointer()) ## S4 method for signature 'dbartsSampler' setState(newState, forceUpdate = FALSE) ## S4 method for signature 'dbartsSampler' plotTree( treeNum, chainNum, sampleNum, forest = NULL, treePlotPars = c( nodeHeight = 12, nodeWidth = 40, nodeGap = 8), ... )## S4 method for signature 'dbartsSampler' run( numBurnIn = NULL, numSamples = NULL, updateState = NULL, ..., callback = NULL ) ## S4 method for signature 'dbartsSampler' sampleTreesFromPrior(updateState = NULL) ## S4 method for signature 'dbartsSampler' sampleLeafParametersFromPrior(updateState = NULL) ## S4 method for signature 'dbartsSampler' sampleVarianceForestFromPrior(updateState = NULL) ## S4 method for signature 'dbartsSampler' growFromRoot(n.sweeps = 2L, updateState = NULL) ## S4 method for signature 'dbartsSampler' copy(shallow = FALSE) ## S4 method for signature 'dbartsSampler' show() ## S4 method for signature 'dbartsSampler' predict(x.test, offset.test, n.threads = control@n.threads) ## S4 method for signature 'dbartsSampler' predictForests( x.test, offset.test, n.threads = control@n.threads ) ## S4 method for signature 'dbartsSampler' setControl(newControl) ## S4 method for signature 'dbartsSampler' setModel(newModel) ## S4 method for signature 'dbartsSampler' setData( newData, updateState = NULL, updateCutPoints = NULL, updateScale = NULL, updateStandardization = NULL ) ## S4 method for signature 'dbartsSampler' setResponse( y, updateScale = FALSE, updateState = NULL, status = NULL ) ## S4 method for signature 'dbartsSampler' setOffset(offset, updateScale = FALSE, updateState = NULL) ## S4 method for signature 'dbartsSampler' setWeights( weights, updateState = NULL, updateScale = FALSE, updateStandardization = FALSE ) ## S4 method for signature 'dbartsSampler' setCategoryOffset(offset, updateState = NULL) ## S4 method for signature 'dbartsSampler' setCategoryTestOffset(offset.test) ## S4 method for signature 'dbartsSampler' setActiveRows( active, updateState = NULL, updateScale = FALSE, updateStandardization = FALSE ) ## S4 method for signature 'dbartsSampler' setForestWeights(forest, weights, updateState = NULL) ## S4 method for signature 'dbartsSampler' setForestBasis(forest, basis, updateState = NULL, updateBasisScale = FALSE) ## S4 method for signature 'dbartsSampler' setSigma(sigma, updateState = NULL) ## S4 method for signature 'dbartsSampler' setPredictor( x, column, forceUpdate, updateCutPoints = "none", updateState = NULL, updateStandardization = FALSE ) ## S4 method for signature 'dbartsSampler' setCutPoints(cuts, column, updateState = NULL, splits = "position") ## S4 method for signature 'dbartsSampler' setTestPredictor(x.test, column) ## S4 method for signature 'dbartsSampler' setTestPredictorAndOffset(x.test, offset.test) ## S4 method for signature 'dbartsSampler' setTestOffset(offset.test) ## S4 method for signature 'dbartsSampler' printTrees(treeNums, chainNums, sampleNums) ## S4 method for signature 'dbartsSampler' getTrees( treeNums, chainNums, sampleNums, current = FALSE, newdata = NULL, forest = NULL ) ## S4 method for signature 'dbartsSampler' getSigmas(result) ## S4 method for signature 'dbartsSampler' getShape() ## S4 method for signature 'dbartsSampler' getLatents(result) ## S4 method for signature 'dbartsSampler' getSumsOfSquaredResiduals(result) ## S4 method for signature 'dbartsSampler' getFitsWithoutOffset() ## S4 method for signature 'dbartsSampler' getVariance(test = FALSE) ## S4 method for signature 'dbartsSampler' getForestFits(forest = NULL) ## S4 method for signature 'dbartsSampler' getForestAmplitudes(forest = NULL) ## S4 method for signature 'dbartsSampler' getForestVariableCounts(forest = NULL) ## S4 method for signature 'dbartsSampler' getLeafPrior(forest = NULL) ## S4 method for signature 'dbartsSampler' getK(forest = NULL) ## S4 method for signature 'dbartsSampler' setLeafPrior(leaf.prior, updateState = NULL) ## S4 method for signature 'dbartsSampler' getForest(forest = NULL) ## S4 method for signature 'dbartsSampler' setForest(forest = NULL, sd = NULL, power = NULL, base = NULL, amplitude = NULL, proposal.probs = NULL, n.perturb.cuts = NULL, treeShift = NULL, updateState = NULL, n.trees = NULL, vars = NULL, interactions = NULL, blocks = NULL, basis = NULL, ...) ## S4 method for signature 'dbartsSampler' setTreePrior(power = NULL, base = NULL, split.probs = NULL) ## S4 method for signature 'dbartsSampler' getVarianceForest() ## S4 method for signature 'dbartsSampler' setVarianceForest(power = NULL, base = NULL, proposal.probs = NULL, n.perturb.cuts = NULL, updateState = NULL, n.trees = NULL, vars = NULL, ...) ## S4 method for signature 'dbartsSampler' installTrees(donor, samples = NULL, forceUpdate = FALSE) ## S4 method for signature 'dbartsSampler' sampleNodeParametersFromPrior(updateState = NULL) ## S4 method for signature 'dbartsSampler' startThreads(n.threads = control@n.threads) ## S4 method for signature 'dbartsSampler' stopThreads() ## S4 method for signature 'dbartsSampler' storeState(ptr = getPointer()) ## S4 method for signature 'dbartsSampler' setState(newState, forceUpdate = FALSE) ## S4 method for signature 'dbartsSampler' plotTree( treeNum, chainNum, sampleNum, forest = NULL, treePlotPars = c( nodeHeight = 12, nodeWidth = 40, nodeGap = 8), ... )
numBurnIn |
A non-negative integer determining how many iterations the sampler should skip before storing results. If |
numSamples |
A positive integer determining how many posterior samples should be returned. If |
callback |
|
updateState |
A logical determining if the local cache of the sampler's state should be updated after the call completes. One convention applies to every method that takes this argument - |
shallow |
A logical determining if the copy should retain the underlying data of the sampler ( |
newControl |
An object inheriting from |
newModel |
An object inheriting from |
newData |
An object inheriting from |
y |
A numeric response vector, or on a count sampler the matrix below, of length equal to that with which the sampler was created, and lying in the response family's support: 0/1 for |
status |
For |
x |
For |
x.test |
A new matrix, data frame, or sparse-bearing test set (the column types accepted by |
offset |
A numeric vector of length equal to that with which the sampler was created, or For |
updateScale |
Logical indicating whether BART's internal scale should re-anchor to the new offset ( |
offset.test |
A numeric vector of length equal to that of the test matrix, or For |
n.threads |
For These are native threads, so
|
sigma |
A single positive residual standard deviation, on the original response scale; it is assigned to every chain. |
weights |
A numeric vector of case weights, of length equal to that with which the sampler was created. What a weight MEANS is family-specific: for a gaussian-family sampler it is a precision, non-negative, or under For |
active |
A numeric vector of per-observation 0/1 membership indicators - "row An inactive row ( An inactive row's own latent draw is SKIPPED - no random numbers are consumed for it - for every family except Student-t, whose per-row An inactive row's pointwise log-likelihood - the value the flat C API's Three quantities do NOT follow the mask, by design, so a caller wanting them recomputed on the active subset must re-create the sampler instead: the split-candidate cut grid stays the FULL-data grid, holding the tree prior fixed while the row set moves; the response transform and residual prior scale stay creation's calibration (a masked gaussian - and so The mask does not ride a sampler's saved |
basis |
The data the named forest's amplitudes multiply, with as many rows as the sampler was created with and one amplitude per column. It is a value, or a one-sided formula, which is read as the |
updateBasisScale |
For |
forest |
A single positive integer indexing the forests from |
leaf.prior |
For |
sd, power, base, amplitude, proposal.probs, n.perturb.cuts, treeShift
|
For |
split.probs |
For |
cuts |
For |
column |
An integer or character string vector specifying which column/columns of
the predictor matrix is to be replaced or for which cuts should be used.
When updating predictors, it can be missing and the entire matrix will be
substituted; a sparse or mixed dense/sparse design accepts that too, and
keeps its storage (the replacement is spliced into the container rather
than replacing it with a plain matrix). Such a design may equally be
mutated one column at a time by naming |
forceUpdate |
For For For |
updateCutPoints |
For |
updateStandardization |
For For A loop whose rows in the likelihood change, such as a mixture component
or an imputation step, can let the response's scale and the leaf
covariates' center and scale follow the rows in during burn-in and then
hold them, so every kept draw comes from one prior: pass
sampler <- dbarts(y ~ x1 + x2, data, weights = w,
leaf.prior = linear("x1"),
control = dbartsControl(n.chains = 1L, keepTrees = TRUE))
for (i in seq_len(n.burn + n.keep)) {
w <- drawMembership(sampler) # the outer sampler's step
burning <- i <= n.burn
sampler$setWeights(w, updateScale = burning,
updateStandardization = burning)
draw <- if (burning) sampler$run(1L, 0L) else sampler$run(0L, 1L)
}
Creation and a |
splits |
For |
treeNums |
An integer vector listing the indices of the trees to print or return. |
chainNums |
An integer vector listing the chains to return from |
sampleNums |
An integer vector listing the saved samples to return from |
current |
For |
newdata |
For |
result |
For |
test |
For |
treeNum |
An integer listing the indices of the tree to plot. |
chainNum |
For |
sampleNum |
For |
treePlotPars |
A named numeric vector containing the quantities |
donor |
For |
samples |
For |
n.sweeps |
For |
ptr |
For |
newState |
For |
n.trees, vars, interactions, blocks
|
For |
... |
For |
A dbartsSampler is a mutable object which contains information pertaining to fitting a Bayesian additive regression tree model. The sampler is first created and then, in a separate instruction, run or modified. In this way, MCMC samplers can be constructed with BART components filling arbitrary roles.
Besides dbarts, a sampler is created by new("dbartsSampler", control, model, data, active = NULL) from the list dbartsSpec returns. The list's data object carries the fit's weights, a "probit", "ordinal" or "nbinom" fit's 0/1 weights among them, so a sampler created from it is the sampler dbarts builds (dbartsSpec, data, gives the by-hand route). active is a 0/1 mask installed once the sampler is built, as setActiveRows(active) installs it, composing with the weights; a sampler created with it reads over the rows in, those the weights and the mask both keep, the center of an "nbinom" count, a linear or gp leaf's covariate center and scale, and under "probit" and "logistic" the default sd of a forest on a numeric column that states none.
A sampler made this way takes its tree count from the model and its quantile rule and cut count from the data object, where they state them. A control that is fresh, or copied from a fit, says nothing of them, and a copied count or rule that differs draws a warning saying it is not used. A count or rule written on the control is used where the model or the data object states none and is refused, by name, where it states another, or, for a count, where every forest has a basis. Whether the family is binary is the model's family alone.
Six methods report a fitted quantity and no two report the same one. They differ along three axes - the SCALE the values live on, whether the installed OFFSET is in them, and whether they answer from the CURRENT state or from stored draws:
| method | scale | offset | current or stored |
run()$train |
response (latent under a binary family) | included | one slab per recorded draw |
$getFitsWithoutOffset() |
response (latent under a binary family) | excluded | current |
$getForestFits(f) |
internal, and one forest only | excluded | current |
$predict(x) |
response (latent under a binary family) | whatever you pass it | the saved samples under keepTrees, else the current trees |
$predictForests(x) |
internal, one channel per forest | excluded, and refused if passed | the saved samples under keepTrees, else the current trees |
$getLatents() |
the family's own augmentation variable, which is a location for some families and a precision for others | not a fit; see ‘Value’ | current |
A multinomial (softmax) sampler reads and writes a strict subset of this surface, by the model rather than by omission. Its response channels are $setResponse, which takes the count matrix, $setCategoryOffset and $setCategoryTestOffset; the predictor family ($setPredictor in all four shapes, $setCutPoints, $setTestPredictor) and the global $setActiveRows, with or without updateScale = TRUE, are open, and $predict answers with the category probabilities and takes the matching per-category offset. Everything else on the mutation surface is refused, each by a message naming the capability and, where one exists, the channel that serves the caller instead: $setResponse given a vector of numbers and $setOffset (a flat vector cannot express the matrix, and a flat shift is the softmax's null direction), $setWeights (an integer case weight is already row-wise replication in the count response, and a non-integer one has no exact augmentation sampler), $setSigma (no residual scale), $setData and $setModel (the K category forests fix their data and their calibration at creation), a named sd or a k hyperprior on $setLeafPrior, which takes normal(k = ) with a fixed k (the softmax map owns every category forest's leaf scale), $setForestWeights and $setForestBasis (its forests are its categories, which carry no amplitudes), and $getFitsWithoutOffset (its reported channels are probabilities, not one additive location). Per-forest masking is refused permanently rather than pending: a category's margin is a log-sum-exp over the other , so a mask on one forest alone has no conditional to be a mask of.
The composition rule follows from the table: an outer block conditions on , so it reads $getFitsWithoutOffset() and adds back whatever offset it installed, rather than differencing $getLatents() against run()$train: a probit, ordinal or aft latent is on the offset-inclusive scale, , as run()$train is, so the difference is the residual with none of the offset's signal. A block that owns the offset regresses z - $getFitsWithoutOffset(); a precision latent carries no location and no offset, and dbartsWorkingResponse gives the offset-free working response.
Where the boundary runs. These are the methods of the mutable sampler, and their audience is a model writer composing BART into a larger scheme: they return engine primitives on the engine's own terms. The R modeling conventions - fitted, predict, extract - apply to FIT objects instead, the results of bartBT and bart. Those accessors read the stored yhat.train/yhat.test channels the engine already wrote the offset into, and no type arm removes it: type = "bart" returns those draws as they stand, "ev" maps them through the response transform, "ppd" samples from them, and "loglik" evaluates against them - all offset-inclusive. (extract on a dbartsSampler itself takes type = "predictors" only and returns the design matrix; it is not a fitted-value accessor.) So an offset-free fit is available from the sampler surface and nowhere on the fit-object surface, which is the division rather than an omission.
save-ing and loading a dbarts sampler for future use requires that R's serialization mechanism be able to access the state of the sampler which, for memory purposes, is only made available to R on request. To make it available, call storeState() on the sampler before saving, e.g. for the object sampler, execute sampler$storeState() (a fit of bart that keeps its trees has done so at the end of its fit); this captures the sampler's current state into the serializable state field regardless of the updateState setting.
The state object is opaque and engine-specific, and carries a format version and the package version that wrote it. A state loads only within the format version of the dbarts that wrote it; loading it with an incompatible version refuses cleanly, naming both versions, rather than risk a silent misread. There is no cross-version migration: re-fit the model, or restore the state with the dbarts release that wrote it. A sampler saved by dbarts 0.9-x refuses every method, naming that version and saying to refit it with this one; its data, control and model fields still read.
To restore a saved state into a sampler, call setState(newState) and check what it returns, as in if (!sampler$setState(state)) stop("the state no longer fits"). setState validates that newState inherits from bartcoreState and re-creates the underlying engine if needed: a sampler whose engine is gone, as after a load, is first rebuilt on the cut points, weights, response range and leaf standardization its data object records and from its own saved state, as any other call rebuilds it, so that setState gives what it gives a sampler that was never saved; one with no saved state, or one whose saved state is refused, is created anew on the same record, and newState goes onto its cut points as onto a live sampler's. Then, where every tree of the state fits the sampler as it stands, it installs the state, caches it on the state field and returns TRUE; where one does not, it installs nothing, leaves the sampler, its engine and its state field exactly as they were, and returns FALSE. TRUE does not mean bit for bit. It means the trees and leaf values are the stored ones, and the quantities the sampler draws are the stored ones where the state holds them. Of the kept draws (keepTrees) the newest that fit the sampler's own store are taken, whatever number the state holds. The latent variables it carries go in as stored and none is drawn, the next sweep drawing them against the weights and censoring status then in force, and the chain continues the state's own generator streams from where they left off, typically to the last few digits, not bitwise (see the Reproducibility section of bart).
A tree does not fit, and setState returns FALSE, when it would have to be changed before the sampler could hold it. The trees are judged against the predictors and the cut points the sampler holds at the call and against its own constraints: a split whose threshold is not one of the sampler's cut points for its column; a leaf that no row of those predictors reaches; a split the state holds outside the range the splits above it leave; a rule that records a side for missing values on a column that has never held one in this sampler (see ‘Missing values in predictors’); a split on a column the tree's forest may not use - a forest's vars, a blocks group, a moderator forest's columns or a variance = ~ x1 + x2 variance forest's; a split that breaks the forest's interactions limit; under a monotone constraint, leaf values that are out of order as stored; and, under DART, split weights of 0 on a column the sampler may split on, as a state taken from a sampler whose forest left that column out holds (negative, missing and all-zero weights are errors, forced or not). setState(newState, forceUpdate = TRUE) installs such a state all the same, as a forced setPredictor leaves the trees it meets, and returns NULL invisibly: a split whose threshold is not a cut point moves to the nearest cut point inside the range the splits above it leave, to the upper one of two equally near, and one with no cut point left there becomes a single leaf, along with everything beneath it, at the mean of the leaves it replaces, weighted by the rows each held under the stored thresholds; a split with a side no row reaches becomes a single leaf, along with everything beneath it, at the mean of the leaves it replaces, weighted by their rows; so does a split outside its range; a tree is cut back in the same way at the first split from its root that the forest's columns or its interaction limit do not allow, the splits above it kept; a rule stops recording a side its column cannot use; and a monotone tree whose values are out of order is merged where its order breaks, each merged part one leaf at the mean of the leaves it replaces weighted by their rows. DART's split weights in such a state start fresh, equal over the columns the forest may split on, as installTrees starts them, with a drawn concentration restarted at its initial value and the delay counter restarted, the next sweep drawing the weights from the trees installed. After a forced setState the state field holds the chain the sampler holds after the install, repairs and drawn sides for missing values included, not the state as it was given: installing the field again without forceUpdate returns TRUE, and a copy or a reload starts from the repaired chain. A forced install that repaired nothing stores a state identical to the one given only where the sampler's store of kept draws (keepTrees) holds the same number as the state's; otherwise the newest that fit are kept and the stored state differs in them. An unforced install that went onto the sampler's own cut points and weights keeps the state as given; one that went onto other cut points or weights than it records is not kept, and the field holds what the sampler holds after the install. Likewise after an unforced install that drew a side for missing values (see ‘Missing values in predictors’) the field holds the state as given, without the sides, and installing it again, as a copy or a reload does, draws the same ones. storeState() stores what the sampler now holds. Forcing checks nothing first, so a loop that restores its own state onto rows it has already put back, where nothing can need repair, can pass forceUpdate = TRUE and skip the check, which costs about as much as one iteration of the sampler. To undo a predictor change exactly, put the old predictor back first, with setPredictor(..., forceUpdate = TRUE), and then call setState. An unforced setPredictor can be refused, returning FALSE and leaving the changed predictor in place; setState then judges the state against the changed predictor, as it does when called before the predictor is put back.
Some states are refused, with an error, whether forced or not, and the sampler is left exactly as it was: one that is not a bartcoreState or is of an older encoding, one with another number of chains, forests or trees or another leaf model, one whose recorded levels are not the sampler's (below), and one with a malformed block or tree. A state in which a numeric column's cut points repeat a value is refused, naming the column and the value: no sampler of this version writes one, and with every point held once a stored split's value names one position. A Student-t, logistic or negative-binomial sampler also refuses a state whose latent variables are not all positive and finite. So is one holding a value no chain could run from, which no sampler writes: a sigma that is not positive and finite; a k that is negative, or is 0 or infinite under a prior whose scale could not draw that value (a draw reaches 0 only under a scale below about 3e-145 and infinity only under an infinite scale or one above about 1e146); a response transform that is not finite; a random-number generator state out of range or all zero; DART split weights that are negative, missing, not finite or all zero, or a DART concentration that is not positive and finite; and ordinal cutpoints whose first is not 0 or that do not increase. Beyond that a state is not checked against the response family of the sampler that stored it: one whose contents fit this sampler is installed, and what the sampler then holds of another family's state is not promised. To start a sampler from a fit of another family, use installTrees, which takes the donor's trees and, where this sampler draws them, its sigma, k and DART state, and none of its latent variables. A state's k is installed as recorded, whatever leaf prior this sampler holds; the leaf sd is then k.scale / k against this sampler's k.scale.
Assigning the field directly (sampler$state <- newState) does not restore the sampler - it only overwrites the R-side cache, leaving the engine untouched, so the next run continues from the engine's own state rather than the assigned one. A reload, and a copy of a sampler whose engine is gone, install the field as setState does with forceUpdate = TRUE, having no other state to fall back on: a tree that no longer fits is repaired, and nothing is reported. Such an object whose field holds a state that is refused cannot be copied, and after a reload raises that refusal at each use until a state of its own is assigned; one whose field holds no state is refused the same ways. A copy of a sampler whose engine exists takes its current chain and not the field. Always route a restore through setState.
A state carries no data, a forest's basis among them, but it records the level names of each forest a factor multiplies, as the sampler's data object holds them (the attribute basisLevels, a list with one entry per forest, NULL for a forest of no factor; absent where no forest multiplies a factor). setState, a copy and a reload put each of the state's coefficients on the recipient's level of the same name, so a state installed in a sampler whose factor has the same levels in another order, as after relevel, gives each level its own coefficient; the recipient's levels and block are its own before and after. A state whose names differ from the recipient's, forest by forest - another name, another number of levels, or a factor where the recipient's forest multiplies numbers or nothing - is refused with an error, whatever forceUpdate says, and the sampler is left as it was. A state that records no levels goes in by position.
A state never changes the sampler's model. The leaf prior, its k where fixed, a fixed sigma, Student-t df, negative-binomial shape or DART concentration, a fixed amplitude prior or amplitude, and a supplied Gaussian-process lengthscale are the sampler's own, before and after; a value the sampler draws is installed where the state holds one and kept where it does not, so a state written before these blocks were dropped still installs. The response transform a k-named prior is anchored to, and which every leaf value is stored relative to, is not in the state either: it is derived from the data when the sampler is created and when setResponse or setOffset at updateScale = TRUE, setWeights or setActiveRows at updateScale = TRUE, or a setData that derives it, re-anchors it, and recorded as the response.range of the sampler's data object (see dbartsData), so a copy or a reload is re-created in it. A state goes in as stored: its trees, leaf values, linear slopes, k, sigma and kept draws are numbers on the sampler's internal scale, and an install - setState, copy, a reload - reads them against this sampler's response mapping and leaf standardization and never converts them. A state stored under the mapping in force, as a sampler's own, a copy's or a reload's is unless a re-anchor came between, puts the chain back where it was stored, value for value. A state stored before a re-anchor, or by a sampler on another response, is legal and has no special meaning: the same internal numbers read on this sampler's scale are a position the chain could hold, and the next draws move the parameters where the data say. A response that was only rescaled is then no change at all on the internal scale, the fit, the leaf prior's spread and sigma all rescaling with it; one whose center moved as well is fitted wrongly until the draws catch up. A kept draw restored across mappings predicts on the new scale, where a re-anchor converts the kept draws so that they predict what they did. No leaf model refuses such a state; one whose saved Gaussian-process draws were made under another leaf standardization or other lengthscales than this sampler holds is refused, a saved Gaussian-process draw replaying only under its own. The state records the mapping it was read under, which no install reads. Because a re-anchor is not in the state, restoring a state stored before one does not undo it; to roll a re-anchoring setResponse(y2, updateScale = TRUE) back, re-anchor to the old response with setResponse(y, updateScale = TRUE) and then setState the saved state, so that the response is restored with the state. The cut points and their weights are the sampler's, and setState writes neither: a state records the ones its thresholds were stored on (its cutPoints and cutMass attributes) and goes onto the sampler's. Where every threshold of the state is one of the sampler's cut points, as on a grid that only gained points, the trees are the stored ones and setState returns TRUE if they fit; where one is not, the state is declined or, forced, has that split moved (above). Other weights on equal cut points change no tree: the state goes in, TRUE, and the chain runs on under the sampler's weights, which is not the chain the state was stored from. So restoring a state does not undo a change of cut points made by setCutPoints or by setPredictor(updateCutPoints = ); 0.9-x's setState did. To restore the cut points too, hold the state in a variable, since setCutPoints replaces the state field under updateState, and set them first, the whole set in one call: sampler$setCutPoints(attr(st, "cutPoints")) and then sampler$setState(st). A column whose cut points had been changed and for which attr(st, "cutMass") holds an entry then has its points back and not its weights: setState still returns TRUE, and the chain runs with that column's cut points equally likely. setPredictor(x[, j], j, updateCutPoints = "value") gives back both while the column holds the values its cut points were derived from. A copy and a reload, which create a new engine, take the cut points, weights and leaf standardization the sampler's data object records, which are the ones in force (see dbartsData), and none from a state. A reload of a sampler saved after a change of cut points with no storeState() since has the stored state's splits moved onto the recorded cut points by value, as a forced setState moves them, and its state field then holds what its engine holds; call storeState() before saving after a change of cut points to have it reload as it stands. A copy of a sampler whose engine exists takes its current chain, which is on those cut points already. On a column the sampler holds as an ordered factor, whose cut points its number of levels fixes, a state recording other cut points is refused, by setState, a copy and a reload alike. On a sampler made from a data frame, setData reads the new data's factors by label and records the sampler's own levels, so a copy and a reload hold the levels the sampler was created with and take the state it stored. A linear or Gaussian-process leaf's covariate standardization, each covariate's center and scale and a Gaussian-process leaf's heuristic lengthscale, is data too: derived when the sampler is created, by a setData that derives it and by setPredictor, setWeights or setActiveRows with updateStandardization = TRUE, and recorded as the standardization of the sampler's data object, which a copy and a reload take. A state records the standardization it was stored under, which no install reads: the sampler keeps its own, so kept linear draws restored across a change of standardization predict under the sampler's until the draws replace them, as kept draws restored across a change of response mapping predict on the new scale. A leaf covariate that held a single value when its standardization was derived has no scale: the state and the record hold NA for it, and the covariate is divided by 1.
A state brings back none of these values, so a sampler that changed one and is to go back to a stored state has it put back first. The data object held in a variable before the change, d <- sampler$data, is the general answer: it records every one, the weights of the cut points included, so setData(d) puts back the observations and every derived value with them.
| value | changed by | put back by |
| cut points | setCutPoints; setPredictor(updateCutPoints = ); a setData that derives them |
setCutPoints(d@cutPoints), the whole set; or setData(d) |
| their weights | the same | setPredictor(x[, j], j, updateCutPoints = "value") while column j holds the values they came from; or setData(d) |
| leaf center, scale, lengthscale | updateStandardization = TRUE on setPredictor, setWeights or setActiveRows; a setData that derives them |
setPredictor of the old values with updateStandardization = TRUE, under the weights and mask they were read over; or setData(d) |
| response range | updateScale = TRUE on setResponse, setOffset, setWeights or setActiveRows; a setData that derives it |
the same setter on the old response, offset, weights or mask with updateScale = TRUE; or setData(d) |
| forest anchor and unit | nothing | - |
Then setState(st) of a state st stored before the change installs it and returns TRUE, and the chain is the one stored.
The case weights and an aft sampler's censoring status are not in the state, and the state records nothing of either: the latents it carries are the values its trees were drawn from, setState installs them and draws none, and the next sweep draws them against the weights and censoring status then in force. A weight change is undone by setWeights with the old weights and setState with the stored state, in either order, the sampler then continuing bit for bit as one that installed the stored state under the old weights would, and setState returns TRUE in both. A sampler saved after its weights changed without a store is re-created from the last stored state under the weights it then holds; it is a continuation of the stored chain and not of the live sampler, carrying no sweep made since the store. Call storeState() after the change to have it reload as it stands; a copy of a sampler whose engine exists takes its current chain.
A predictor column can hold missing values from the first time the sampler is given one in it - at creation, or later by setPredictor, setData or updatePredictorPerObservationJointly - and from then on for the life of the sampler, whatever values the column holds afterwards. Each split rule on such a column sends missing values down one side, and the sampler draws that side as part of the model. When a column first becomes able to hold missing values, every rule already on it, in the current trees and in every saved draw (keepTrees), has its side drawn at random, left or right with probability one half each, from each chain's own generator; a change that is refused undoes these draws with the rest of it. A rule on an unordered factor column has its side drawn only where a missing value can reach it: beneath a rule on the same column that sends missing values down the other side none can arrive, and the rule holds no drawn side, exactly as on a sampler whose column held missing values at creation. A saved draw was made when no value in the column was missing, so nothing it was drawn from bears on that side, and one half is that draw's posterior for it. predict then routes a missing value in the column through every saved draw, those made before its first missing value and those made after. A column that has never held a missing value has no side to route by, and predict refuses a missing value in it. copy and a reload keep which columns can hold missing values.
A stored state records which columns could hold a missing value when it was stored. When setState, a copy or a reload installs it into a sampler where a further column can - a state stored before that column's first missing value, or by a sampler whose column never held one - every rule on that column, in the state's current trees and in its saved draws, has its side drawn in the same way before the state is judged, from the generators the state carries; a state stored just before a single setPredictor call gave the column its first missing value, and installed just after it, draws the sides that call drew. setState returns TRUE for such an install unless a drawn side leaves a leaf with no row or a monotone tree out of order, where it returns FALSE as for any state that does not fit (see ‘Saving’). A state stored before this record was kept draws nothing, and its rules on such a column send missing values left. A warm start (installTrees, or warm.start of bart) from a fit whose data could not hold a missing value in a column draws, from each receiving chain's own generator, the side of every rule on that column in the trees it installs.
Each accepted predictor mutation does two things: the engine updates its internal representation, and the R layer collects the accepted values into the sampler's data object so that replay, saving, and re-quantization see current data. The collection is by reference for data-frame-built samplers (only the affected column changes hands) but requires copying the full predictor matrix when the sampler was built from a matrix, so tight loops that mutate predictors every iteration are better served by data-frame input. The remaining per-call overhead is a few tens of microseconds of R method dispatch and bookkeeping - the price of R-level consistency. Predictor mutation has no counterpart in the flat C interface (dbarts.h), which reaches the per-sweep conditioning channels and leaves every whole-data channel to these methods, so a client that mutates predictors every iteration is served by data-frame input rather than by dropping below R.
getPointer() returns the sampler's underlying engine pointer, checking it for validity first. If the engine the cached pointer refers to is no longer live (typically after a load), it transparently re-creates one from control, model, data and the stored state, reinstalls every recorded forest weight and any recorded active-row mask (see reapplyForestWeights below, since neither rides the saved state) so the replacement matches a freshly built engine, and only then replaces the cached pointer; a re-creation that fails leaves the sampler exactly as it was. reapplyForestWeights(ptr) re-installs every per-forest weight mirrored on the sampler onto a freshly (re-)created ptr, and reapplyActiveRows(ptr) the mirrored active-row mask; they are called only from getPointer, setState and copy, never directly.
getPointer() is the only R-level primitive for exchanging engine pointers with code that drives the engine directly through dbarts.h: it is where a compiled consumer obtains the handle that header's entry points take, since that header declares no creation entry of its own. There is no other R-level path to that boundary: the low-level .Call wrappers this class's methods delegate to are internal to the package and unexported, so a consumer below this reference class has dbarts.h and nothing else.
setPredictor - whole-matrix, single- or multi-column (via column), and per-observation (forceUpdate = "partial") - and updatePredictorPerObservationJointly accept a Bayesian causal forest, a multinomial sampler, and a heteroscedastic (variance) sampler on the same terms as an ordinary single-forest sampler. The acceptance criterion is a single conjunction over every tree of every forest of every chain of the sampler: a treatment forest, a multinomial sampler's per-category forests, and a variance forest are all checked together with the mean forest, never independently, so a change that a mean-forest tree would tolerate can still be rejected because it would empty a leaf in the treatment or variance forest, and vice versa. A rejected transactional whole-matrix or column update rolls every forest back to its pre-call state; under forceUpdate = "partial" the per-observation install mask reflects that same joint criterion, so an observation installs only where it empties no leaf anywhere in the sampler, and a rejected observation is rolled back in every forest, leaving the rest of the run untouched. The one exemption is a forest whose trees never split on the column being changed - a treatment or moderator forest restricted to a column subset, or a variance forest declared over its own predictor subset - which structurally cannot veto a change to a column outside its own reach; nothing needs to be done to obtain that exemption; it falls out of which columns the forest's trees actually use. updatePredictorPerObservationJointly applies the identical per-sampler conjunction across every sampler passed to it as well: an observation installs only where it would remain valid in the union of every sampler's forests, and it is declined in all of them otherwise.
Column names after a whole-matrix replacement: a transactional or forced whole-matrix setPredictor(x, ...) (column missing) carries column names onto the installed sampler$data@x. When x itself has column names they are matched to the sampler's, which it keeps, a name that is not the sampler's being refused, and a sampler with no column names takes x's; when it does not (a bare matrix, or a vector reshaped through dim), the sampler's existing column names are kept instead. Either way, a later by-name column reference on that sampler - setPredictor's own column argument given as a character string, or updatePredictorPerObservationJointly's shared-column match - continues to resolve against colnames(sampler$data@x) as it did before the replacement.
sampleTreesFromPrior and sampleLeafParametersFromPrior are MEAN-forest entries by contract: each leaves the variance forest of a heteroscedastic (variance) sampler exactly as it finds it, along with sigma, k and the family's latent block. sampleVarianceForestFromPrior is the variance forest's own, drawing its tree structures from the tree prior conditioned on carrying no empty leaf - the distribution the variance moves themselves price - and each leaf's factor from the calibrated inverse-chi-squared scale prior, then rebuilding from the drawn factors. A caller wanting a whole heteroscedastic chain at its prior calls all three; on a homoscedastic sampler this one draws nothing and returns, so a loop over families needs no guard.
installTrees seeds the sampler's forests from a donor instead of drawing trees from the prior, for scaling to more chains or embedding a fit in a larger sampler. Only the donor's trees, and its sigma, k and DART state where this sampler draws them, transfer: the sampler keeps its own model, as setState does. The donor's trees and leaf values, and its k and sigma where this sampler draws them, go in as stored on the internal scale and are not converted to this sampler's response: a donor fitted to a response on another scale seeds the same internal numbers, which the next draws move where this sampler's data say, and a donor whose response differs only by a rescaling seeds its own fit, rescaled. The predictors' frame goes the same way. A linear leaf's coefficients go in as stored, numbers per unit of this sampler's own centered and scaled covariates, and this sampler keeps its own center and scale, as a Gaussian-process leaf keeps its own center, scale and lengthscale, whichever cut grid the donor is on; the donor's are not read. Where the two standardize a covariate differently the seeded forest is then not the donor's function of it, and the next draws move it where this sampler's data say. A covariate that holds a single value is read at the center it holds, so between two single values the seeded fit is the donor's on the training rows. Each chain keeps its own random-number stream and redraws everything else, so several chains seeded from one donor stay overdispersed. DART weights go only between two DART fits and a variance forest only where both have one: a donor's that this sampler has no place for is left behind, and this sampler's own, where the donor has none or where the donor's hold 0 on a column this sampler's forest may split on, starts as a new fit's once the donor goes in, DART drawing its weights from the trees taken at the first sweep; neither is judged, and a donor that is declined leaves them as they were. A donor holding a value no chain could run from, as setState refuses one, is an error in both forms, and nothing is installed. A donor of constant leaves into linear ones gives each leaf its value as intercept and slopes of zero, the donor as it stands. A donor of linear leaves into constant ones, or into linear ones on another number of covariates, leaves its slopes behind, each leaf starting at the intercept the donor stores. A donor of Gaussian-process leaves where this sampler's are of another kind, or the reverse, or one fit to another number of rows, is an error naming the two, as is a donor fit to another number of predictors or one whose column is an unordered factor where this sampler's is not, or the reverse. A donor of fewer trees than this sampler is taken whole, its trees in its order and the rest starting as single leaves at zero, or at one in a variance forest. Under blocks, whatever the donor's tree count, each block in turn takes, in the donor's order and up to its count, the donor's trees not yet taken that it holds as they stand, the rest of its trees starting as single leaves, and where that leaves a tree out, the same is tried once more with the donor's single leaves offered last; a donor all of whose trees go in so is taken whole, and one fitted with the same blocks and counts goes in tree for tree. A donor of more trees, or under blocks one whose trees do not all go in so, gives those whose fitted values vary most over this sampler's rows, each row weighted by its case weight, in the donor's order, the mean and the variance forest choosing apart and each chain among the trees of the donor sample it takes; under blocks each block in turn takes up to its count of the trees that vary most within it as it holds them, never one it would hold as a single leaf when the donor holds it as more, and starts the rest as single leaves.
installTrees(donor) asks first. A donor every tree of which fits this sampler as stored is installed and the call returns TRUE. One that would have to be changed is not installed: the call returns FALSE and the sampler is as it was, its trees, drawn values, generators, kept draws and state field. A tree has to be changed when a split's threshold is not one of this sampler's cut points, as for a donor fitted to other rows; when a leaf holds none of this sampler's rows; when a split is on a column, or in an interaction, its forest does not allow; when it records a side for missing values on a column that has never held one here; or when a monotone forest's leaf values are out of order. A donor is also declined when it holds more trees than this sampler's forest or, under blocks, trees the blocks cannot take as they stand, when it holds linear slopes this sampler's leaves do not take, constant leaves or linear ones on another number of covariates, and when its Gaussian-process fits were recorded on other cut points. installTrees(donor, forceUpdate = TRUE) installs such a donor and returns NULL invisibly, whether or not anything was changed: a split off the cut points moves to the nearest one inside the range the splits above it leave or, with none left, becomes one leaf with everything beneath it; a split with a side no row reaches, and the first split from the root that its forest does not allow, likewise become one leaf, at the mean of the leaves it replaces weighted by the rows each held; a side is dropped; a monotone tree whose leaf values are out of order is cut back where they are; Gaussian-process fits start at zero; slopes the sampler does not take are left behind; and of a donor holding more trees, or under blocks one whose trees the blocks cannot all take as they stand, the trees whose fitted values vary most go in. The sampler's cut points and their weights are the same before and after. A side drawn for missing values is how a donor is read, not a change to it. On a column this sampler holds as an ordered factor a donor recorded on other cut points, a numeric column or a factor of another number of levels, is an error in both forms. bart's warm.start always forces.
A warm start biases the early draws toward the donor, so it shortens burn-in rather than removing it; keep drawing a non-zero number of burn-in samples before treating the chain as converged. Single-forest samplers only: a sampler carrying two or more forests (a Bayesian causal forest or any other amplitude model, and a multinomial sampler's K category forests) refuses the call by name, reporting its forest count, because the install is not tested at more than one forest - it reassembles the trees from a saved sample but takes the amplitudes from the donor's current state. Use growFromRoot to initialize such a sampler instead. A variance forest is not one of the counted forests, so a heteroscedastic sampler takes a warm start as any single-forest one does.
growFromRoot instead builds the sampler's initial forest by XBART-style root-down stochastic tree construction (He, Yalov and Hahn 2019): each of n.sweeps sweeps rebuilds every tree from the root, sampling each split from the integrated-likelihood weight of every candidate cut under the tree prior. This reaches a good fit in far fewer sweeps than the exact sampler, so it is a fast starting point rather than a posterior sampler - the exact MCMC sweeps own stationarity once run begins, and the posterior is unchanged. It is available for the constant-leaf model only; calling it on a linear or gp leaf prior is an error, not a silent fall-back, so initialize those forests with sampleTreesFromPrior instead. As with installTrees, the grown forest biases the early draws toward its fit, so shorten burn-in rather than skipping it. Each chain grows on its own random-number stream, so the result is independent of n.threads. Unlike installTrees it runs on a multi-forest sampler, each forest grown against its own residual inside the sweep and the forests' amplitudes drawn with them. A composable cross-sampler workflow follows for free: donor$growFromRoot(k) then target$installTrees(donor).
For run, a named-list with contents sigma (absent on a heteroscedastic sampler, below), train, test, and varcount (plus k, when the reported forest draws k in that run and absent when it is fixed, and varprobs when applicable). train is an array of dimension n.obs x n.samples x n.chains, and likewise test (or NULL if the sampler has no test data) and varcount are n.predictors x n.samples x n.chains; sigma is n.samples x n.chains. When n.chains is 1 the trailing chain dimension is dropped, so train is a plain n.obs x n.samples matrix and sigma a plain vector of length n.samples. On a multi-forest (forests) sampler varcount gains a forest axis between the predictors and the samples - n.predictors x n.forests x n.samples x n.chains, forest-major within a draw and the forests in the model's order - so each forest's own per-draw split counts arrive from one call rather than only the reported forest's; a single-forest sampler's array keeps exactly its n.predictors x n.samples x n.chains shape, and the same widening is what a family = "multinomial" sampler's per-category counts ride. This is the RAW run shape; the packaged fit bart builds reshapes it draws-first with the forest names on the trailing margin, as it does for the multinomial channel. $getForestVariableCounts reads the same quantity for the CURRENT state, one forest at a time. A Bayesian causal forest adds two more: forestFits, an n.obs x n.forests x n.samples x n.chains array of each forest's fitted values on the internal scale (the forests in the model's order), and glue, a sum(q) x n.samples x n.chains array of the amplitudes each draw combines them through, stacked forest-major and as wide as each forest's own basis (a Bayesian causal forest's , three rows), so both surfaces and their recombination come from a single call; train carries the combination on the response scale, or on the latent scale when the sampler was built under "probit" or "logistic", and test is filled with NaN (there is no test treatment vector to combine off-sample). No other model reports either element. A "nbinom" sampler adds one of its own: shape, the negative-binomial each draw is conditioned on, shaped exactly as sigma (a length n.samples vector at one chain, an n.samples x n.chains matrix otherwise) because it is the count analog of it - fixed at the value the sampler was created with under a fixed shape, and that sweep's grid draw otherwise. It is written from the same state storeState serializes and consumes no random numbers, so reading it costs a run nothing. No other family carries the element at all: it is absent from the list, not NULL within it, so run()$shape is NULL on every non-"nbinom" sampler and a test of the channel must be !is.null(...) rather than a comparison, which NULL would satisfy vacuously. A sampler built with family = student() adds resid.df on exactly the same terms - the degrees of freedom each draw is conditioned on, shaped as sigma, written from settled state and consuming no random numbers, absent from the list under any other error distribution - fixed at the value supplied to student(df = ), and that sweep's grid draw when the degrees of freedom are estimated. A heteroscedastic (variance forest) sampler carries no sigma element - absent, as shape is off "nbinom" - since its engine holds the scalar fixed; it adds variance, the per-observation variance surface on the original response scale, shaped as train, whose square root is the residual scale, and varianceTest, the same at the test rows (NULL without test data). A run can be interrupted with Ctrl-C: it stops between iterations, or inside an iteration's Polya-Gamma latent draws or a monotone leaf-order count, whose time grows with a logistic, negative-binomial or multinomial fit's counts or with a large tree, joining any worker threads first. It then raises R's interrupt condition, class c("interrupt", "condition"), as base R's own long computations do: nothing is printed as an error, try() and error handlers do not catch it, tryCatch(interrupt = ) does, and calling handlers, on.exit and finally run. A loop of fits inside try() stops at the interrupted one. The call returns no samples. The sampler's chains are left where they stopped and it can be run again; where the stop falls inside a pass over the trees (a slow monotone count, a latent refresh) that pass may be partly applied, each latent at this iteration's draw or the previous one, which is a valid state to run on from. The saved trees the stopped call wrote are dropped: predict and getTrees serve the earlier calls' draws it did not overwrite, oldest first. Unlike a base R interrupt, it offers no "resume" restart: the run is over. Under control@keepFits == FALSE, train, test, and (when the model carries them) the variance and forest channels come back NULL rather than an array - present in the list, holding nothing, unlike shape/resid.df above, which are absent outright when inapplicable; see callback above and dbartsControl's keepFits. A callback that returns nonzero ABORTS the run the same way an interrupt does: the results and the saved trees the call wrote are discarded and run signals an error, naming that a callback stopped it; that is an error, where an interrupt is not.
For setCutPoints, NULL invisibly. The change is always made, as in 0.9-x: there is no unforced form and no forceUpdate argument, and a split left with no cut point between the splits above it is merged, so the trees can change. It sets a grid, typically once before sampling. Inside a larger sampler whose draws move a column's values, let the grid follow them with setPredictor(updateCutPoints = ), which derives the grid a creation would for the new values, up to n.cuts, each time, and whose unforced form is refused, with the sampler as it was, when the trees cannot hold the new grid.
For setPredictor, TRUE if the new predictor was installed and FALSE if it was refused. An unforced update is refused, with no error and no warning, when it would leave a leaf empty in any tree of any forest of the sampler (see ‘Multi-forest and heteroscedastic predictor mutation’) or, under a monotone constraint, leave a tree's leaf values out of order. A refused update is rolled back, whether it named columns or replaced the whole matrix: the sampler's trees, fits, predictors and random number generator are as they were before the call. A forced update always installs and returns NULL invisibly: the value says whether a valid update was made, which has no meaning when it is forced. When forceUpdate is "partial", instead returns a logical vector of length equal to the number of observations, TRUE where that observation's new value was installed and FALSE where it was rolled back to its previous value to keep every tree of every forest valid.
For installTrees, TRUE if the donor was installed and FALSE if it was not, the sampler then being exactly as it was: it is FALSE when a tree a chain would take, or a leaf value, would have to be changed (see ‘Warm starts’). No warning is given. With forceUpdate = TRUE the donor is installed with the changes and the value is NULL, invisibly, whether or not anything was changed.
For setState, TRUE if the state was installed and FALSE if it was not, the sampler then being exactly as it was. It is FALSE when a tree of any chain would have to be changed to fit the sampler: a split whose threshold is not one of the sampler's cut points, a leaf that no row of the current predictors reaches, a split that the state holds outside the range the splits above it leave, a rule with a side for missing values on a column that has never held one, a split its forest's columns or interaction limit do not allow, or monotone leaf values out of order (see ‘Saving’). No warning is given. TRUE means the trees and leaf values are the stored ones. It does not promise the cut points or their weights, which stay the sampler's whatever the state records, so that a chain restored onto other weights or a finer grid is not the stored chain continued; the case weights and an aft censoring status, which stay the sampler's; the generator, which is left as the sampler's own when the state's is of another kind; or every kept draw, of which the newest that fit the sampler's store are taken. Nor does it cover a value the sampler holds fixed, which a state never changes. A state stored under another response mapping is installed as stored and reports TRUE. With forceUpdate = TRUE the state is installed, repaired where it has to be, and the value is NULL, invisibly, whether or not anything was repaired: a caller who needs to know calls without it first. copy and a reload install a state that way and report nothing.
Under keepTrees the draws predict, predictForests, getTrees and printTrees report come out OLDEST FIRST: the store keeps the most recent [email protected] recorded draws, so a sampler driven through several recorded run calls replays them in the order they were drawn and lines up draw for draw with the train/sigma channels those runs returned. A sampler that has recorded fewer draws than that reports only the draws it holds, and one that has recorded none - keepTrees set but nothing run since creation, a setControl that resized the store, or an installTrees warm start - is refused rather than answered from slots nothing has written.
predict keeps the current test matrix in place and uses the current set of tree splits. This function has two use cases. The first is when keepTrees of dbartsControl is TRUE, in which case the sampler should be run to completion and the function can be used to interrogate the existing fit. When keepTrees is FALSE, the function can be used to obtain the likelihood as part of a proposed new set of covariates in a Metropolis-Hastings step in a full-Bayes sampler. This would typically be followed by a call to setPredictor if the step is accepted.
Its return shape mirrors run()'s own train/test channel for a single-forest sampler, with two exceptions. An amplitude-coupled (multi-forest, including a Bayesian causal forest) sampler refuses predict outright rather than answering here - see getFitsWithoutOffset below, which already records the same refusal - so everything that follows describes a single-forest or multinomial sampler only. For a single-forest sampler: with saved trees to replay (keepTrees TRUE and at least one recorded draw), the result is an n.test x n.samples x n.chains array, the trailing chain dimension dropped to a plain n.test x n.samples matrix when n.chains is 1; without saved trees to replay, the CURRENT (live) trees are replayed once per chain instead, with no samples axis at all - a plain vector of length n.test at one chain, an n.test x n.chains matrix otherwise. A family = "multinomial" sampler's surface reports the K category probabilities instead: an n.test x K x n.samples (x n.chains) array, the K axis inserted between the rows and the samples. Unlike the single-forest case, this samples axis is never dropped: it is sized 1 rather than omitted when there are no saved trees to replay. A heteroscedastic (variance forest) single-forest sampler with saved trees to replay returns not a bare array but a named list list(mean = ..., variance = ...), both members the single-forest shape above; without saved trees there is nothing for the variance forest to replay, so the bare mean array returns alone, exactly as a non-heteroscedastic sampler's would.
For getTrees, a data.frame with one row per tree node in depth-first, left-hand-side pre-order, with columns forest (indexed from 1, present only on a sampler with more than one forest - a multinomial one, or one declared with forests = naming several - and then leading every other column, forest-major, at the default forest = NULL or a vector; any other sampler returns no forest column and accepts forest = 1), chain (present only when n.chains > 1), sample (present only for saved samples, and reporting the draw number asked for), tree, n (the number of observations in the node), var (the splitting variable, or -1 at a leaf), and value (the split value, or the leaf prediction). An ordinal rule's value is its cut point and observations with values less than or equal to it go left; on an ordered-factor column that cut point is an exact half-integer at a level boundary, so levels(x)[floor(value) + 1] is the last level going left (the split value is a 0-based code, R's levels is 1-based); a categorical rule carries no data value (its value is NA) and its split is reported in the directions column instead. When the sampler has any categorical predictors the result gains a directions column decoding each categorical rule into one "L"/"R" character per level, in level order (level k goes right when its character is "R"); ordinal rules and leaves are NA. When any predictor contains missing values the result gains a missing column giving the branch ("L"/"R") each rule sends missing values down; rules on complete columns and leaves are NA. Under a linear leaf prior each leaf's value is its intercept and the result gains one beta.<column> column per designated covariate holding that leaf's slope on the internal standardized scale; internal nodes are NA.
For getSigmas, a numeric vector of length equal to the number of chains, giving each chain's current residual standard deviation on the original response scale, or NULL on a heteroscedastic sampler, whose residual scale is the surface getVariance reports.
For getK, each chain's current k, the value run()$k records per draw when k is drawn in that run (a run records no k while it is fixed), read without running, as getSigmas reports sigma: after a run it is bitwise the last draw. A fixed k is reported once per chain, and a forest whose scale a calibration map sets reports 1; a forest with no basis stating neither sd nor a coefficient's prior reports the leaf prior's k, and those that share one prior total (see forest) each the group's one. It is k whatever terms the prior was named in, relative to getLeafPrior()$k.scale: under an sd-named prior, that scale over the spread in force. A numeric vector of length equal to the number of chains at one forest, or, at the default forest = NULL on a multi-forest sampler, an n.forests x n.chains matrix; a single-forest sampler's NULL read is bitwise its forest = 1 read.
For getShape, the shape parameter of the sampler's family currently in force, a numeric vector of length equal to the number of chains, and NULL on a family with none - the count analog of getSigmas. Only the negative-binomial family has one today, its : the variance is , a larger shape is closer to Poisson, and is size in rnbinom and theta in MASS and mgcv. It is the same scalar run()$shape records once per kept draw, read mid-sweep and without serializing state, so an outer sampler driving this one a sweep at a time reads it here; state[[chain]]$shape holds it only where it is drawn. Because the refusal for a family carrying no shape is a NULL and not an error, a caller distinguishing “no shape” from a value must test !is.null(...); comparing to an expected number would pass vacuously.
For getSumsOfSquaredResiduals, a numeric vector of length equal to the number of chains, giving each chain's residual sum of squares on the original response scale; a binary-response sampler reports on the latent scale instead. On a multi-forest (forests) sampler is the COMBINED location - the same quantity run()$train records - and not any one forest's own total. Two qualifications, both keyed to the response family rather than to the forest count. A logistic sampler's working response is with a Polya-Gamma variate redrawn every sweep, so what it reports is a function of that sweep's auxiliary variables and is not a residual sum of squares in any scale. A multinomial fit reports NaN: its coupling reports a category-by-observation probability slab rather than a location, so no residual sum of squares is defined - the NaN is deliberate, in place of the sum of squared category probabilities a bare substitution would have given.
For getLatents, NULL when the model augments nothing - a plain gaussian response - and, deliberately, on a multinomial one, which augments but reports nothing: its Polya-Gamma matrix is drawn every sweep, but each is an interleaved ONE-VS-REST augmentation variable refreshed against a margin that the other forests move within the same sweep, so the code driving the sampler, reading it between sweeps, reads a quantity whose conditioning it cannot reproduce, and the composition recipes reach the same posterior through the fits and the category offset without touching it. That decline is scoped to the augmentation families whose latent is a PRECISION refreshed against a moving margin; the location-valued latents below - probit's and ordinal's , and aft's imputed log survival time - are reported as documented. Otherwise the values the last sweep's trees were drawn from. Each sweep draws them first, after any change made between sweeps and before its trees, so between a setter and the next run they are the values from before the setter (setData starts them as creation does, an ordinal or negative-binomial sampler from the kept cutpoints or shape; an aft setResponse leaves a censored row at its new bound) and the next sweep draws them afresh. They are a plain vector of length equal to the number of observations when there is a single chain, or an observations-by-chains matrix otherwise, written into result when one was supplied. What that variable IS depends on the family and is not uniform. It is a LOCATION, on the sampler's own latent scale, for "probit" (the truncated normal ), "ordinal" (the same under the ordinal thresholds) and "aft" (the imputed log survival time), all of which the code driving the sampler regresses on directly. It is a PRECISION, one per observation, for "logistic" and "nbinom" (the Polya-Gamma ) and for a Student-t residual distribution (the scale-mixing ); these WEIGHT a working response and are not on the response scale at all, so differencing them against a fit is meaningless. Note the last case: a sampler whose family is "gaussian" but built with family = student() (see dbarts) does report latents, and they are precisions.
For getFitsWithoutOffset, the sampler's combined per-observation location on the response scale and without the installed offset, an n.observations x n.chains matrix. run()$train reports the same quantity with the offset folded in, so this value plus the installed offset is that one; there is deliberately no with-offset twin, since the offset is the caller's own. It is the read an outer sampler driving this one a sweep at a time needs: an incremental scheme updates its outer block against , and taking getLatents() minus run()$train instead is BIASED: a location latent is on the offset-inclusive scale, as the training channel is, so that difference is the residual alone and carries none of the offset's signal. A block that owns the offset regresses getLatents() - getFitsWithoutOffset() on its covariate. On a multi-forest (forests) sampler this is the only route, short of running the sampler, from R to the combined fit - getForestFits gives one forest's internal-scale totals and predict is refused. It is refused, naming the reason, on a multinomial sampler, whose reported channels are per-category softmax probabilities rather than one additive location; predict(x) serves that read, but reports the SAVED samples rather than the current state when the sampler was built with keepTrees.
For getVariance, a heteroscedastic (variance forest) sampler's current variance surface on the original response scale, an n.observations x n.chains matrix at the default test = FALSE and an n.test x n.chains matrix at test = TRUE. It is the mid-sweep read of the channels run() records as variance and varianceTest: at the state a recorded sweep left, the accessor and the channel agree exactly. What it reports is a VARIANCE, so a residual scale is its square root - it is the surface analog of getSigmas, which reports the scalar a homoscedastic sampler carries. NULL where those channels report nothing: on a homoscedastic sampler, and at test = TRUE with no test rows installed. Unlike predict, which addresses the saved samples, it reads the trees currently in force, so it answers after $sampleVarianceForestFromPrior() and needs no keepTrees.
For getForestFits, a multi-forest sampler's requested forest's current internal-scale fitted values, an n.observations x n.chains matrix, or, at the default forest = NULL, every forest stacked with the forest margin between the observations and the chains, n.observations x n.forests x n.chains (bitwise the forest = 1 read on a single-forest sampler). For getForestAmplitudes, the named forest's amplitudes - one per basis column - as a q x n.chains matrix, or, at the default forest = NULL, every forest's stacked forest-major into a sum(q) x n.chains matrix. A drawn one has prior median size 1, on a factor the difference between two levels' amplitudes, a level's own having 0.71. The vector is ragged: a Bayesian causal forest's forest 1 carries the single on its implicit intercept and its forest 2 the pair , so the stacked read is the of . For getForestVariableCounts, the requested forest's current per-predictor split counts, an n.predictors x n.chains integer matrix, or, at the default forest = NULL, every forest stacked the same way as getForestFits, n.predictors x n.forests x n.chains; its rows are named by the training matrix's column names when that matrix carries them (on margin 1 in both shapes), and left unnamed otherwise.
For predictForests, the off-sample twin of getForestFits: every forest replayed separately at x.test, as an n.test x n.forests x n.samples (x n.chains) array on the forests' internal scale, forest-major within a draw. It reports the saved samples when the sampler was built with keepTrees, and the current trees otherwise, exactly as predict does. Nothing but the forests' own totals is in it: no amplitude glue, no response transform and no offset, the last refused rather than ignored. That is the point of the channel rather than an omission - an amplitude coupling's location is response.shift + , and off the training rows only the caller knows the bases , so the whole recombination is theirs, with $getForestAmplitudes() and $getLeafPrior() supplying the rest. At the fit level it is packaged: predict on a bart object with type = "ev", "ppd" or "bart" performs the same recombination off this replay, taking the bases at the predicted rows through its own bases argument. Only a sampler that composes its forests through scalar amplitude glue reports per-forest fits; every other one is refused by name, a multinomial sampler included, whose raw per-category totals are perfectly well defined but whose reported quantity is a softmax probability that predict serves. The refusal is off-sample only: getForestFits is not gated the same way, so those same per-category totals stay readable AT the training rows, for the current trees and one draw, and it is the off-sample replay - which would have to hand back a level nothing identifies at rows the sampler never saw - that has no counterpart.
For getLeafPrior, the leaf prior a forest runs under, alone, as a named list: leaf.prior, the specification in the terms it was named in - a normal(), linear() or gp() object (see dbartsPriors) carrying one of k, a number or a chi() prior, or sd, a number or an invchi() prior, the family default when none was named - which goes back into setLeafPrior or a fitting function's leaf.prior as is; leaf.model, one of "constant", "monotone", "linear", or "gp"; prior.sd.of, what the sd is the sd of: "forest", "coefficient" (linear, per standardized covariate) or "amplitude" (gp); prior.mean; k.scale, the value k is relative to, so the spread in force on each chain is k.scale / getK() - the data's scale, which the family and the response transform fix and no spelling of the prior moves, so that under an sd-named prior k is k.scale over the sd; and response.scale and response.shift. A forest the calibration map does not set also carries, after leaf.prior, sd, its size in force in the response's units - k.scale over k at a fixed k, the number as stated where an sd was, and NA where k is drawn or the sd is under invchi(), which have no one number - and sd.stated, whether the leaf prior is named by an sd, at creation or through setLeafPrior. A fixed k is the one in force, read off the engine; an sd, a number or under invchi(), is reported as it was named. Every chain runs under the sampler's one prior and one response transform, which no state install moves, so every value is shared by the chains. A drawn k is chain state, read by getK. At the default forest = NULL a multi-forest sampler returns a list of one prior per forest, named by the forests' labels, a multinomial sampler's by the response's levels; a single-forest sampler's NULL read is bitwise its forest = 1 read. An NA spread is refused by setLeafPrior, setModel and the fitting functions. On a forest whose scale a multi-forest calibration map sets, k is pinned at 1 and leaf.prior is the statement of the forest's size: forest(sd = v), v the number as it was written, where an sd was stated, and forest() where none was. Its sd is the one setForest states. The list then begins with leaf.prior, sd, the forest's sd in force in the response's units - v itself, bit for bit, or the default's multiple of the response's scale times the unit the sampler derived at creation - sd.stated, TRUE where the size comes from an sd the user wrote at either level, the forest's own forest(sd = ) or, on a forest with no basis that states none, the fitting function's normal(sd = ), and FALSE for the default and for k, multiplier, what the forest multiplies, "none", "factor" or "numeric", and amplitude, fixed() where the forest's coefficient is held, student(df) where it is drawn under the Student-t prior its creation stated, normal() where a forest with no basis is drawn under the normal prior its creation stated, and absent where it is drawn under its default prior. prior.sd.of says what sd is the size of: "forest" for a forest with no basis, "level difference" for a factor and "forest, per unit of basis" for a numeric column, the size exactly where the coefficient is held, with " (at a coefficient of 1)" where it is drawn. A numeric forest's sd is per unit of its column and carries the column's name where the basis has one, and the list adds basis.scale, where the data object records one, the standard deviation of the column the default was taken from at creation, named as sd is. k.scale is the forest's own prior sd before its coefficient, in the response's units: the forest's sd, on every forest but a sharer. A forest with no basis stating neither sd nor a coefficient's prior, alone or sharing one prior total with others (see forest), reads as one forest does, under the fitting function's leaf prior: leaf.prior is that prior as named, sd the forest's part of the total in force, NA where k is drawn, sd.stated TRUE when the fitting function's leaf prior is named by an sd the user wrote, normal(sd = ), as it is on a sampler of one forest, and FALSE for the default and for k, multiplier "none", amplitude fixed(), prior.sd.of "forest" alone and "forest, shared" in a group, one left of a group included, and k.scale over the k its part.
On a forest whose scale the multi-forest CALIBRATION MAP sets, on a sampler built with forests = or a forest() formula term (see forest), k is pinned at 1, k.scale is the map's leaf scale, and the entries above that the map adds are absent (so NULL) on every other forest, a multinomial one included. A drawn coefficient is a multiplier with prior median size 1 - on a factor the difference between two levels' coefficients, a level's own having 0.71 - and on a numeric column through bcf's 0.674.
The spread (k.scale / k) describes the LEAF-PARAMETER scale of the forest total. It equals the prior standard deviation of at every for the constant leaf only; for the other three the prior of is x-dependent and the spread bounds it in a leaf-specific direction. Under "linear" it is a LOWER bound attained at the standardized covariate origin, with the spread in the internally standardized leaf covariates (a missing value maps to ); prior.mean is exact. Under "gp" it is an UPPER bound over , attained at rows that reproduce a leaf member and on over-cap leaves, and elsewhere decaying to zero as leaves the leaf's data cloud, where every prior draw equals prior.mean exactly. Under "monotone" it is a LOWER bound in the interior - the realized standard deviation runs a few per cent to about twenty per cent above it - and prior.mean is NOT the prior mean of under an active constraint: that marginal is skew, with an x-dependent mean tracking the constraint's direction across several the spread (see monotone in dbarts).
This is the authoritative reader of the prior in force. A named sd is absolute: the sampler holds it as k = k.scale / sd, or as the chi prior on k at that scale, and restates it whenever the response transform is re-anchored - setResponse, setOffset, setWeights or setActiveRows at updateScale = TRUE, setData, and setResponse and setOffset made by compiled code through dbarts.h, which has no entry for the other two - so a fixed sd, and the prior on a drawn one, keep their meaning in response units. A drawn sd's current value is k's: at a re-anchor it stays where it was on the internal scale, stretching with the leaves, and lags until the next draw, as a drawn k does. A k is relative to the response transform recorded at creation or at the last re-anchor, and moves only with it. A state install (setState, installTrees, copy, a reload) leaves the prior as it was.
For setLeafPrior, NULL invisibly. It changes the leaf prior's spread or the hyperprior it is drawn under, on every chain, and nothing else: not the response transform, not sigma (which setModel re-pins on a fixed-sigma gaussian sampler), not the tree prior or a DART split prior. Into a drawn prior - a chi or invchi prior - each chain keeps the spread in force at the call, whatever the prior before it, fixed or drawn and in either the k or the sd form: k.scale is the data's under every prior, so k is not touched, getK does not move, and the new prior acts from the next draw of k. A fixed k or sd stated sets the spread as written, a fixed sd as k = k.scale / sd. Because the write keeps the chains' spread, on a sampler that has not yet run it is not the start that creation under the new prior would make. The write takes effect on the next sweep, reinterpreting no leaf value already drawn; a write that reproduces what is already in force is skipped bitwise, so a read followed by a write cannot perturb a draw. It is total over the four leaf models, and a DART sampler is served. A multinomial sampler takes normal(k = ) and applies the k to every category forest, leaving the softmax map's leaf scale; a named sd or a k hyperprior is refused there, as at creation. On a sampler whose forests carry amplitudes the leaf.prior is the fitting function's, written on the forests it reaches as creation under it gives them. Where one forest has no basis it is written there whatever that forest states, a stated sd going: a k or a named sd as at creation, and on a forest stating a coefficient's prior, which has no k, the size the prior gives at the scale creation set - normal(sd = v) the size v, normal(k = v) that scale over v, a chi() prior on k that scale over its median, once, with no k drawn there - leaving the coefficient's prior and every leaf and coefficient drawn. Where several forests have no basis, those sharing one prior total take it, each keeping the part of it its creation gave it, so after a forest has left the group (see setForest) the sizes no longer add up to it, and those stating their own sd keep it. Where none shares, as where every forest has a basis or every forest with no basis states its sd, the default restated changes nothing and any other leaf.prior is refused, naming setForest(forest, sd = ). Into a drawn k a forest starts at the spread in force. A write changes the model. The write is recorded where re-creation reads it. The map's k.scale is recorded at creation too, so a re-creation after setResponse or setOffset at updateScale = FALSE states every forest against the same k.scale as the live sampler. A value that is not a single positive finite number is an error. A heteroscedastic sampler's variance forest is a separate leaf model, which setLeafPrior does not reach; setVarianceForest changes its settings. setModel changes everything else.
For getForest, every value in force on one forest as a plain named list, no class and no attribute, in setForest's order and with the names its kind takes: sd, the size getLeafPrior reports with no column's name on it, NULL where k is drawn or no one positive number is in force; power and base; amplitude, the coefficient's prior as fixed(), normal() or student(df), a forest with a basis stating none reading normal(), and a forest with no coefficient fixed(); and proposal.probs, n.perturb.cuts and treeShift, a forest stating none reading the control's. A value the forest takes from above reads like any other. do.call(s$setForest, c(list(f), s$getForest(f))) changes nothing, whether the forest states a value included. On a multinomial sampler the list has no sd or amplitude and covers every category forest, whichever is named. Tree counts and columns are not in it: print and getTrees show them.
For setForest, NULL invisibly. It changes the forest named, and on it only the names given, each meaning what it means in forest on that forest at creation. It acts from the next sweep and leaves the trees, leaf values and coefficients already drawn as they are; a write changes the model. A name left out or NULL changes nothing, and so does a value equal to the one in force, which leaves the forest following what it followed: a forest taking its depth from the fitting function goes on taking it, a forest sharing one prior total stays in the group, and a numeric forest's default goes on being read from its column. Each name is compared with the value in force before the call, whatever else the call changes, so an sd handed back beside amplitude = fixed() is no change; to pin a forest at its sd, state a different one or, where k is drawn, the same in a second call. A forest that states its sd or its depth is changed by stating another; nothing returns it to following the fitting function, short of a new sampler.
sd on a model of one forest is its size, written as setLeafPrior(normal(sd = )) writes it, in the terms of its leaf model. On a model of several it sets the forest's trees' scale: its size where the coefficient is held and its size at a coefficient of 1 where it is drawn, on a factor the size of the difference between two levels and on a numeric column the size per unit. A forest with no basis alone under the fitting function's leaf prior leaves that prior at an sd stated for it, its k then pinned at 1. A forest sharing one prior total with others leaves the group the same way, and those still sharing keep their parts of the total, set once at creation, and their sizes; nothing puts a forest back in the group but a new sampler. A multinomial sampler refuses sd as its creation does. power and base are the forest's depth, every category's on a multinomial sampler. amplitude changes the coefficient's prior between held, fixed(), and drawn, normal() or student(df), and between those two, on every chain. A hold sets the coefficient to its held value at the call - 1, or 0 at a factor's first level and 1 at its second - so getForestAmplitudes reads it at once; a release draws it from that value from the next sweep; a Student-t prior's mixing variance starts at the normal prior's and is kept where only the degrees of freedom change. No leaf and no trees' scale moves, except on a forest whose size the fitting function's leaf prior gives: a forest with no basis holding the whole of that prior, released, takes the size creation gives the statement, its k pinned at 1, and held again follows the leaf prior again, a drawn k starting at the spread in force; the last forest left of a group, released, states its part of the total in force as its sd, which getForest then reads. normal() writes a forest with a basis back to its default and fixed() one with no basis. The prior in force changes nothing, and fixed() on a forest with no coefficient, as a model of one forest or a sharer has none. student(df) or normal() is refused as at creation there, a sharer taking it with an sd in the same call, which takes the forest out of the group, and where the leaf prior would give the size and gives none, as a chi() prior on k with an infinite scale. A multinomial sampler takes fixed(), which changes nothing, as its creation does, and refuses student(df) and normal() as its creation does. proposal.probs, n.perturb.cuts and treeShift are the forest's own, and a later setControl leaves them.
vars, n.trees, interactions and blocks are refused by name whatever their value, being part of the model, and basis is refused naming setForestBasis, a basis being data. What creation refuses of a forest's statement is refused here for the same reason. Every check comes before any write, so a refused call changes nothing, its good names included. A multinomial model's forests take one statement: s$setForest(power = 4) reaches every category, with forest left out, and a position or a level is refused. Every change is recorded on the model, as creation with the statement records it, so a copy and a reload run what the sampler runs.
Where setForest and setTreePrior, setLeafPrior or setModel reach one setting of one forest, as on a model of one forest, the later write wins, whatever the forest stated. A heteroscedastic sampler's variance forest takes the mean forest's depth at creation and is on its own after that: setForest and setTreePrior leave it, setVarianceForest changes it, and setModel installs a power or base the model's variance record states as setVarianceForest does. A model records what each forest states, a write here included, so setModel on another sampler installs it.
For setTreePrior, NULL invisibly. It changes the fitting function's tree prior, as power, base and split.probs mean at creation, through setModel's route, so the two cannot differ. A name left out or NULL changes nothing, and so does a value equal to the one in force. power and base reach the forests with no basis that state none of their own and, where one forest has no basis, or on a multinomial sampler's category forests, those forests whatever they state, the later write winning; they make no forest state them, and nothing returns a forest that states its own to following, short of a new sampler. A name that reaches no forest is refused, naming the forests that state it and setForest. A split.probs vector changes the values and 1 restores equal ones; on a DART sampler dart(...) changes DART's settings, a setting left out taking creation's default; dart() on an ordinary sampler and a vector on a DART one change the model's structure and are refused, and a sampler of several forests takes equal probabilities only. A variance forest stays as it is.
For getVarianceForest, every value in force on the variance forest as a plain named list, power, base, proposal.probs and n.perturb.cuts, or NULL on a sampler with none. For setVarianceForest, NULL invisibly. It changes those settings by setForest's rules, each meaning what it means in varianceForest. vars and n.trees are refused by name, and a sampler with no variance forest refuses the call: whether there is one is part of the model.
For storeState, NULL invisibly; it is called for its side effect of capturing the sampler's current engine state into the serializable state field, which save then writes out. See ‘Saving’. What it writes is one draw's trees, about 13 bytes per node per tree per chain, which is 3.5 pct of a single draw's training predictions at 20,000 observations and 75 trees and falls like ; it exceeds those predictions only below a few hundred observations, and it is a small fraction of a whole run's yhat.train, not a multiple of it.
Read with $, as the methods are called. Treat them as read-only: assigning to a field changes only the R-side copy and leaves the underlying engine untouched, so the sampler's behavior does not follow. Route changes through the set* methods instead.
controlThe sampler's dbartsControl, carrying n.chains, n.threads, n.trees, keepTrees, updateState, and the rest. Replace with setControl.
modelA dbartsModel holding the parsed tree, leaf, and residual priors, together with any monotonicity, interaction, and block constraints. Replace with setModel.
dataA dbartsData holding the current predictors, response, test data, weights, and offset. Its x slot is stored columnar for data-frame input and so need not be a plain matrix; use extract(sampler, "predictors") for the numeric predictor matrix, which is what tree replay and getTrees count against. Replace with setData, or a piece at a time with the other set* methods; writing the field (sampler$data <- newData) stops and names setData, as such a write would change the R-side copy and not the sampler.
stateThe cached, serializable engine state, or NULL until one is materialized. It holds the chains and not the model: trees, leaf values, the quantities the sampler draws, the cut points the trees' split thresholds were stored on (the attribute cutPoints, a list with one entry per predictor column, NULL for a factor column that splits by subsets of its levels; with their weights, the attribute cutMass, where a column's cut points are not equally likely) and the leaf-covariate standardization they are read through, a record of the response mapping they were read under, which predictor columns could hold a missing value when it was stored, and the levels of each forest a factor multiplies (the attribute basisLevels) - no leaf prior and no value the sampler holds fixed (see ‘Saving’). It also carries each chain's generator state, so restoring it continues the same streams the sampler was drawing from, typically to the last few digits, not bitwise. The saved-tree store's write position and the number of draws it has recorded both ride it, so predict after a setState reports the same draws, in the same order, as before the store. Reading it forces the sampler's current state only the first time, before any value has been materialized; once set, it is a cached snapshot that a later mutation does not refresh automatically - call storeState again, or pass updateState = TRUE to the mutating call (see updateState above), to bring it forward. After a setState that put a state onto cut points, or weights of them, other than the ones the state records, the field holds the sampler's state as storeState() gives it and not the state as it was given, so that a copy or a reload has the sampler's cut points and trees. It is the only field save needs, and restoring one requires setState - see ‘Saving’.
pointerThe external pointer to the C++ engine. Internal; never manipulate it directly.
dbartsSampler is a reference class: its methods are not called as free functions but as $-dispatched calls on a sampler instance, e.g. sampler$run(100, 100) or sampler$setResponse(newY). The S4-method notation in ‘Usage’ below is an artifact of how reference-class methods are documented and does not reflect the calling syntax; see ‘Examples’.
updatePredictorPerObservationJointly for applying a shared per-observation predictor update across several samplers at once.
samplePriorPredictive for repeated prior draws of the hyperparameters, sampleTreesFromPrior, sampleLeafParametersFromPrior and predict on a private sampler, for calibrating priors before fitting.
dbarts-embedding for which channel an outer block writes, which fit it reads back, and whose prior is in force after a swap, and vignette("dbarts-as-a-component", package = "dbarts") for six worked compositions built from these methods.
# the embedded-Gibbs pattern: BART as a conditional model inside a larger # sampler, alternating its own draws with updates to its response between # calls to run() n <- 100 x <- matrix(runif(n * 2), n, 2) y <- x[, 1] - x[, 2] + rnorm(n, 0, 0.1) sampler <- dbarts( y ~ x, control = dbartsControl( n.chains = 1L, n.threads = 1L, n.burn = 0L, n.samples = 1L, updateState = TRUE ) ) ## first draw: response as given at creation samples <- sampler$run() str(samples$train) # a plain n.obs x n.samples matrix (n.chains == 1) ## an outer Gibbs step changes the response (e.g. after updating some ## other part of a joint model); the sampler picks the new target up on ## the next run() without being recreated newY <- y + rnorm(n, 0, 0.05) sampler$setResponse(newY) samples <- sampler$run() str(samples$train)# the embedded-Gibbs pattern: BART as a conditional model inside a larger # sampler, alternating its own draws with updates to its response between # calls to run() n <- 100 x <- matrix(runif(n * 2), n, 2) y <- x[, 1] - x[, 2] + rnorm(n, 0, 0.1) sampler <- dbarts( y ~ x, control = dbartsControl( n.chains = 1L, n.threads = 1L, n.burn = 0L, n.samples = 1L, updateState = TRUE ) ) ## first draw: response as given at creation samples <- sampler$run() str(samples$train) # a plain n.obs x n.samples matrix (n.chains == 1) ## an outer Gibbs step changes the response (e.g. after updating some ## other part of a joint model); the sampler picks the new target up on ## the next run() without being recreated newY <- y + rnorm(n, 0, 0.05) sampler$setResponse(newY) samples <- sampler$run() str(samples$train)
Resolves the control/model/data triple and family token that describe a sampler, without constructing one. Intended for packages that embed dbarts - in particular LinkingTo: dbarts packages that build a sampler in R from the returned pieces and hold its handle for the C API in ‘dbarts.h’ - and that supply their own design matrix.
dbartsSpec( data, control = dbarts::dbartsControl(), power = 2, base = 0.95, split.probs = NULL, leaf.prior = normal, proposal.probs = c( birth_death = 0.6, swap = 0, change = 0.4, perturb = 0, rule_gibbs = 0, birth = 0.5), monotone = NULL, interactions = NULL, blocks = NULL, variance = NULL, forests = NULL, n.trees = NULL, sigest = NULL, seed = NULL, family = c("auto", "gaussian", "student", "probit", "logistic", "aft", "multinomial", "ordinal", "nbinom"), weights.type = NULL, survival = NULL, tree.prior = NULL, parentEnv = parent.frame(), ...)dbartsSpec( data, control = dbarts::dbartsControl(), power = 2, base = 0.95, split.probs = NULL, leaf.prior = normal, proposal.probs = c( birth_death = 0.6, swap = 0, change = 0.4, perturb = 0, rule_gibbs = 0, birth = 0.5), monotone = NULL, interactions = NULL, blocks = NULL, variance = NULL, forests = NULL, n.trees = NULL, sigest = NULL, seed = NULL, family = c("auto", "gaussian", "student", "probit", "logistic", "aft", "multinomial", "ordinal", "nbinom"), weights.type = NULL, survival = NULL, tree.prior = NULL, parentEnv = parent.frame(), ...)
data |
A |
control, power, base, split.probs, tree.prior, leaf.prior, proposal.probs, monotone, interactions, blocks, variance, forests, n.trees, sigest, seed, family, weights.type, ...
|
As in |
survival |
For |
parentEnv |
The environment in which the prior and forest constructor arguments are evaluated; defaults to the caller's frame, which is almost always what is wanted. Pass explicitly when forwarding arguments from another function. |
dbarts does two separable things: it ingests a formula or a pair of matrices into a dbartsData, and it then resolves that data into a full sampler specification - choosing the response family, coding the response, applying the family's weight policy, estimating a starting sigma, parsing the priors, and recording on the model and data the monotonicity, interaction and block constraints, the forests and a variance forest, the residual degrees of freedom, and the survival status. dbartsData exposes the first half. This function exposes the second, and returns the pieces rather than a sampler.
Both entry points call the same resolution on the dbartsData they end up with, so a sampler built from this function's output draws the same samples as the equivalent dbarts call given the SAME data object. The two can still resolve a given family differently, because dbarts performs its own response ingestion first - coding a factor response into a count matrix, for instance - while this function does none: a call this function refuses for the raw response dbarts can still accept, by ingesting it into the shape this function requires.
The family element of the returned list names the family the sampler is built with, and the dbarts_family enumerator dbarts_sampler_family reports for it ("gaussian" names DBARTS_FAMILY_GAUSSIAN, and so on). "auto" asks this function to dispatch on the shape of the response, which is correct for "gaussian", "probit", and "ordinal" - each is inferable from the response coding or from an attribute - but is wrong for "aft" and "logistic", which are indistinguishable by shape from "gaussian" and "probit" respectively, and for "nbinom", which is never inferred (a count vector resolves to "gaussian"). Name the family and the question does not arise.
sigest defaults to NULL, which like "auto" estimates the starting sigma from the data's response, as dbarts does: a starting estimate or response scale a sampler wrote into the data object is not read, since a new fit is a new model (use the sampler's copy() for the same model again). A number states it, and "dense" or "sparse" names the routine. An explicit NA for sigest is a missing value and is refused. Cut points are taken from control only when the data does not already carry resolved per-column counts.
Families that require ingestion this function does not perform are unavailable: "hazard" needs person-period expansion, and "hurdle.lognormal" describes more than one sampler. "multinomial" is in this function's own vocabulary, but only for a data object whose response is already an counts matrix (see data above, and dbartsData's counts argument); given a factor-coded or plain numeric response instead, it is refused with a message naming the counts route, even though dbarts accepts the same factor by coding it into that shape first.
A list with components
control |
a |
model |
a |
data |
a |
family |
the resolved family token, never |
dbarts, dbartsData, dbartsControl, dbartsPriors
f <- function(x) { 10 * sin(pi * x[,1] * x[,2]) + 20 * (x[,3] - 0.5)^2 + 10 * x[,4] + 5 * x[,5] } set.seed(99) sigma <- 1.0 n <- 100 x <- matrix(runif(n * 10), n, 10) Ey <- f(x) y <- rnorm(n, Ey, sigma) data <- dbartsData(x, y) control <- dbartsControl(n.chains = 1L, n.samples = 20L, n.burn = 10L, updateState = FALSE) ## an ordinary specification, then the sampler it describes spec <- dbartsSpec(data, control = control, n.trees = 25L) spec$family sampler <- new("dbartsSampler", spec$control, spec$model, spec$data) samples <- sampler$run() ## additive-only fit, monotone in the fourth predictor constrained <- dbartsSpec(data, control = control, interactions = interactions(max.order = 1L), monotone = c(rep(0, 3), 1, rep(0, 6)), n.trees = 25L) attr(constrained$model, "interaction.max.order")f <- function(x) { 10 * sin(pi * x[,1] * x[,2]) + 20 * (x[,3] - 0.5)^2 + 10 * x[,4] + 5 * x[,5] } set.seed(99) sigma <- 1.0 n <- 100 x <- matrix(runif(n * 10), n, 10) Ey <- f(x) y <- rnorm(n, Ey, sigma) data <- dbartsData(x, y) control <- dbartsControl(n.chains = 1L, n.samples = 20L, n.burn = 10L, updateState = FALSE) ## an ordinary specification, then the sampler it describes spec <- dbartsSpec(data, control = control, n.trees = 25L) spec$family sampler <- new("dbartsSampler", spec$control, spec$model, spec$data) samples <- sampler$run() ## additive-only fit, monotone in the fourth predictor constrained <- dbartsSpec(data, control = control, interactions = interactions(max.order = 1L), monotone = c(rep(0, 3), 1, rep(0, 6)), n.trees = 25L) attr(constrained$model, "interaction.max.order")
Simulation-based calibration (Talts et al. 2018) over a one-sweep step you supply, for a
model you state as a prior draw and a simulation. For each replication it draws
from the prior, simulates data at it, runs the step, and ranks each scalar
functional's value at among its values over the retained draws. Under a
kernel that targets the posterior the prior and simulation imply, those ranks are uniform; a
systematic departure means the composition does not sample what it claims to - the defect class in
which a posterior mean is reported where a draw belongs. It is a diagnostic, not a fix.
dbartsValidateComposition(drawPrior, simulate, init, step, functionals, n.replications = 200L, n.draws = 200L, n.thin = 30L, n.burn = 200L, alpha = 0.05, seed = NULL)dbartsValidateComposition(drawPrior, simulate, init, step, functionals, n.replications = 200L, n.draws = 200L, n.thin = 30L, n.burn = 200L, alpha = 0.05, seed = NULL)
drawPrior |
A function of no arguments returning one draw |
simulate |
A function of |
init |
A function of |
step |
A function of the state returning the state after one sweep of the composed kernel - the whole Gibbs/Metropolis-Hastings scan, not one block of it. |
functionals |
A function of the state returning a numeric vector of scalar summaries to rank, the same ones in the same order at every state. They may be derived - a mean fit, a probability, an indicator - and need not be parameters; names, if given, label the report. |
n.replications |
Number of prior draw / simulation / refit replications. The rank resolution and the band both come from this. |
n.draws |
Number of draws retained per replication, |
n.thin |
Sweeps per retained draw. SBC assumes the retained draws are independent, so this should exceed
the composition's autocorrelation time; |
n.burn |
Sweeps discarded before the first retained draw. The default is not |
alpha |
Level of the uniformity band, Bonferroni-corrected within the call over the number of functionals
ranked, so that a whole call passes with probability about |
seed |
Seeds R's random number stream for the whole run, making it reproducible, and restores the
caller's stream on exit, as |
The verdict. The primary statistic is the maximum absolute difference between the ranks' empirical cdf and the uniform one, against a simultaneous band simulated from the null (Talts et al. 2018, fig. 1), which is already corrected for the multiple looks across the rank grid. A chi-square goodness of fit and a jittered Kolmogorov-Smirnov test are reported beside it as secondary signals; the verdict does not hinge on them.
Ties. A rank is the number of draws below , which is uniform only
for an atomless distribution. Every functional is ranked with the tie-break instead: draws and
alike carry an independent uniform tag, so an atom - an indicator, a
discrete parameter, a probability that underflows to zero - contributes a uniform increment rather
than piling every replication onto one rank. With no ties it is the plain count, exactly.
The blind spot. The validator compares the composition against the model drawPrior
and simulate state between them. It cannot detect an outer sampler whose prior draw and
simulation disagree with each other: a step that correctly targets the posterior of the wrong
model passes, because that model is the one being validated against. Nor does it localize a
failure to a block of the sweep; it reports which functionals are miscalibrated, not why.
An object of class dbartsCompositionValidation, a list with components ranks (the
n.replications by number-of-functionals integer matrix of ranks, columns named for the
functionals), L, n.replications, n.thin, n.burn, alpha,
alpha.adjusted (the Bonferroni-corrected level actually used), mean.rank.target
(), pass, and verdicts, a data frame of one row per functional carrying
its mean rank, ecdf-difference statistic, band, chi-square and KS p-values, and its "PASS"
or "FLAG" verdict. print reports the table.
Talts, S., Betancourt, M., Simpson, D., Vehtari, A., and Gelman, A. (2018) Validating Bayesian inference algorithms with simulation-based calibration. arXiv preprint arXiv:1804.06788.
dbartsSampler, the sampler a composition drives, and
dbartsAugmentation, the augmentation draws a composed step is built from.
# a conjugate normal-normal one-sweep step: theta ~ N(0, 1) and # y_i | theta ~ N(theta, 1) give theta | y ~ N(v * sum(y), v), v = 1 / (1 + n) n <- 5L v <- 1 / (1 + n) drawPrior <- function() c(theta = rnorm(1L)) simulateData <- function(theta0) rnorm(n, theta0[["theta"]], 1) initState <- function(theta0, data) list(theta = theta0[["theta"]], mean = v * sum(data), sd = sqrt(v)) functionals <- function(state) c(theta = state$theta, positive = as.numeric(state$theta > 0)) # the step draws the posterior outright, so its states are independent and its # init is exact at theta0: this call needs neither thinning nor burn-in stepExact <- function(state) { state$theta <- rnorm(1L, state$mean, state$sd) state } dbartsValidateComposition(drawPrior, simulateData, initState, stepExact, functionals, n.replications = 50L, n.draws = 100L, n.thin = 1L, n.burn = 0L, seed = 8L) # the defect class this exists to catch: the posterior MEAN reported where a # draw belongs. 'theta' flags; 'positive' is coarse enough to survive it, power # being per functional. stepMean <- function(state) { state$theta <- state$mean state } dbartsValidateComposition(drawPrior, simulateData, initState, stepMean, functionals, n.replications = 50L, n.draws = 100L, n.thin = 1L, n.burn = 0L, seed = 8L)# a conjugate normal-normal one-sweep step: theta ~ N(0, 1) and # y_i | theta ~ N(theta, 1) give theta | y ~ N(v * sum(y), v), v = 1 / (1 + n) n <- 5L v <- 1 / (1 + n) drawPrior <- function() c(theta = rnorm(1L)) simulateData <- function(theta0) rnorm(n, theta0[["theta"]], 1) initState <- function(theta0, data) list(theta = theta0[["theta"]], mean = v * sum(data), sd = sqrt(v)) functionals <- function(state) c(theta = state$theta, positive = as.numeric(state$theta > 0)) # the step draws the posterior outright, so its states are independent and its # init is exact at theta0: this call needs neither thinning nor burn-in stepExact <- function(state) { state$theta <- rnorm(1L, state$mean, state$sd) state } dbartsValidateComposition(drawPrior, simulateData, initState, stepExact, functionals, n.replications = 50L, n.draws = 100L, n.thin = 1L, n.burn = 0L, seed = 8L) # the defect class this exists to catch: the posterior MEAN reported where a # draw belongs. 'theta' flags; 'positive' is coarse enough to survive it, power # being per functional. stepMean <- function(state) { state$theta <- state$mean state } dbartsValidateComposition(drawPrior, simulateData, initState, stepMean, functionals, n.replications = 50L, n.draws = 100L, n.thin = 1L, n.burn = 0L, seed = 8L)
Returns the predictor matrix as the sampler currently sees it - one numeric column per predictor, with factor columns as their integer codes. This is the canonical source for tree replay: it is the same matrix getTrees uses to count training observations through saved trees.
## S3 method for class 'dbartsSampler' extract(object, type = "predictors", ...)## S3 method for class 'dbartsSampler' extract(object, type = "predictors", ...)
object |
|
type |
A character string; only |
... |
Unused; included for compatibility with the |
Data frame input is stored columnar in the sampler's data object, so its x slot need not be a plain matrix. extract materializes the numeric coding regardless of the storage form: numeric and logical columns as doubles, and factor columns - ordered or not - as their integer codes, 0 to one less than the number of levels, in level order. This is the same coding a hand-built predictor matrix supplies. The matrix is for tree replay and inspection: on a fit with a factor column, predict and the sampler's new-predictor entrances take a data frame, and a sampler built from the matrix reads every column as numeric.
After predictor mutation (setPredictor and relatives) the result reflects the sampler's current predictor values, not the originally ingested data. Each mutating call collects the accepted change into the sampler's data object directly; nothing is maintained per iteration, so the returned codes always reflect current values, materialized fresh on every call.
A numeric matrix with one row per training observation and one column per predictor, carrying the predictors' column names.
dbartsSampler, dbartsData, extract
df <- data.frame( x = runif(50L), g = factor(sample(c("a", "b", "c"), 50L, replace = TRUE)) ) df$y <- df$x + 0.5 * (df$g == "b") + rnorm(50L, 0, 0.1) sampler <- dbarts(y ~ x + g, df, control = dbartsControl( n.chains = 1L, n.threads = 1L, updateState = FALSE)) predictors <- dbarts::extract(sampler, "predictors") str(predictors) stopifnot(all(predictors[, "g"] == as.integer(df$g) - 1L))df <- data.frame( x = runif(50L), g = factor(sample(c("a", "b", "c"), 50L, replace = TRUE)) ) df$y <- df$x + 0.5 * (df$g == "b") + rnorm(50L, 0, 0.1) sampler <- dbarts(y ~ x + g, df, control = dbartsControl( n.chains = 1L, n.threads = 1L, updateState = FALSE)) predictors <- dbarts::extract(sampler, "predictors") str(predictors) stopifnot(all(predictors[, "g"] == as.integer(df$g) - 1L))
One forest of a model of several forests. Such a model fits the mean as a
sum of forests, each multiplied by columns of the data:
y ~ forest(x1 + x2) + forest(x1 + x2, basis = dose) is
,
where each is a forest and each a coefficient the
sampler draws. A forest is written as a term of a bart or
dbarts formula, as in that example, or as an element of the
forests list of dbarts or dbartsSpec:
forests = list(forest(), forest(basis = dose)). Either way
vars is the predictors the forest splits on and basis is what
it is multiplied by. Every setting is per forest and stated on the forest.
The constructor is not exported: it resolves by bare name inside the
arguments that take it, and elsewhere is written
dbartsForests$forest(...); see dbartsForests.
forest( vars = NULL, basis = NULL, sd = NULL, n.trees = NULL, base = NULL, power = NULL, amplitude = NULL, interactions = NULL, blocks = NULL, proposal.probs = NULL, n.perturb.cuts = NULL, treeShift = NULL)forest( vars = NULL, basis = NULL, sd = NULL, n.trees = NULL, base = NULL, power = NULL, amplitude = NULL, interactions = NULL, blocks = NULL, proposal.probs = NULL, n.perturb.cuts = NULL, treeShift = NULL)
vars |
The predictors this forest splits on. In short:
The rest of this item is the detail of each. In a formula given to In a A name of a predictor is that predictor, and anything else is
read where Any forest may be restricted, a single declared forest included: given the
same residual scale estimate, that fit is the fit on the named columns
alone, and its other columns report no splits. The estimate is taken from
every column unless |
basis |
What the forest is multiplied by. In short:
The rest of this item is the detail of each. What it does. With a basis of columns
Writing it. A basis is the right-hand side of a model formula,
without the tilde, and means what it means in
A basis is either one factor (or character or logical column) or numeric
columns; the two are not mixed in one forest. The forest does not center
or scale a basis, so a multiplier that should be standardized is written
so: One size. In this version a basis is one numeric column, or a
factor, a character or a logical vector of two levels, counted on the
rows the fit keeps once a level they leave empty is dropped. Three or more
levels are refused, with the form to write, a forest for each level but
the first: Which kind it is. The class of the basis decides whether the
forest multiplies levels or numbers, the same way at every place a basis
is given: The kind is fixed when the forest is created. A forest created with no
basis cannot be given one, and a forest of levels keeps the same levels,
in the same order, for as long as the sampler lives, so that coefficient
A level that no row the fit keeps has gives no column and no message,
written as code or handed over as a value: A missing value is looked for on the rows the fit keeps, after
Some forms a model formula would take are refused, each by name and with
what to write instead: Names of the columns. They are named as
Rows. A basis has a value for every row of New rows. Where a name is found. It depends on who wrote the code. In a call of
fs <- list(forest())
for (k in c(10, 30))
fs[[length(fs) + 1]] <- forest(x1, basis = I(dose / k))
is one forest multiplied by One case needs care: a column of A formula made elsewhere, held in a variable or handed over as above, is
read in the same way and at the same moment, when
fs <- list(forest())
for (k in c(10, 30)) {
f <- ~ I(dose / k)
fs[[length(fs) + 1]] <- forest(x1, basis = f)
}
each forest has its own A An argument that Code or a single string passed on to A value. What is handed over as an object, through
Where a name is read. A name is read from the data first and
then where A hazard fit. Under A lone forest carrying a |
n.trees, base, power
|
This forest's tree count and tree-structure prior. Each one stated here
governs this forest, and each one left out takes the default of the
forest's kind, whatever the forest's place. A forest with a |
sd |
The size of what this forest contributes, in the response's units: the
units of No basis. The forest enters as A factor (a factor, a character vector or a logical vector, of
two levels). The forest enters with one coefficient for each level, and
A number Where the coefficient is held, by Not stated, A treatment belongs in a factor or a logical vector, where A held coefficient cannot adapt to an A default is not a stated number: A live sampler restates it through
|
interactions, blocks
|
Optional |
amplitude |
The prior on this forest's coefficient: the one a forest with no
|
proposal.probs, n.perturb.cuts, treeShift
|
This forest's tree moves - its proposal mixture, perturb window and
level-shifting step - as |
With two forests, the second carrying a two-level factor basis, this is the
shape of the Bayesian causal forest
: a prognostic forest over every predictor, a modulating
forest over the columns vars allows, and the
amplitudes joining them, read back with
$getForestAmplitudes; is 1 unless the prognostic forest
states amplitude = student(1), as Bayesian causal forests' prior does, or
normal(). Gaussian, "probit" and "logistic"
responses; under a latent family the combination is the index rather than
the mean, on the link's own fixed scale, and "aft", "ordinal"
and "nbinom" are refused at creation naming what each is missing.
What the defaults put on the combined location, since under a latent family
that location IS the index and no drawn stands between it
and the fitted probabilities. At two forests of the shipped shape - one
carrying no basis - a probit model's prior puts
at 0.29,
the forest with no basis alone having the shipped single-forest binary
default's own 0.238. A forest's default does not depend on how many forests
the model has, so each forest added widens the prior on the combined
location. When every forest carries
a factor the induced prior standard deviation of the index is
latent units, 1.484 at
, which is 0.989 of the classic binary
leaf-scale budget; a numeric column at its default contributes 1.484 for
each standard deviation of the column the row is from 0. When one forest
carries none, its prior is the fitting function's leaf prior, whose
k is drawn and has no variance to enter that budget with, and the
others contribute
, 0.699 of the budget at
. Where many forests share one index, state their
sd. Read the values in force off
$getLeafPrior(f)'s sd entry, in the response's units.
Forests with no basis. One beside any other forests takes the
fitting function's leaf prior as its one forest does, whole: its k,
a chi() prior on k or normal(sd = ), held at 1 and with
$getLeafPrior(f) and $getK(f) reading as one forest's, so the
forest is what bart would fit, the other forests added. It
leaves that prior by stating sd, held at it, or
amplitude = normal() or student(), drawn. A model may hold any number, as
y ~ forest(x1) + forest(x2) + forest(x3) or a forests list. Two or more
of them that state no sd and no amplitude = normal() or student() share
one prior total, the size the fitting function gives its one forest: its
k or leaf.prior, k = 2 by default under a continuous
response and k drawn under chi(1.5, 2) under
"probit" and "logistic". Each of the forests
that share is held at 1 and takes an equal part, , of the
total's variance whatever its number of trees, so the sum has the one
forest's prior at every point and each forest 0.71 of its sd at two, 0.58
at three; a drawn k is one k for the group, and a named
leaf.prior = normal(sd = ) is the total's size. The model is the
one forest with its trees in blocks, a block for each
forest. The forests with no basis split the fitting function's
n.trees as blocks() splits a forest's trees, the first
ones taking one more: 38 and 37 of 75. A forest stating n.trees
keeps its own, outside the split, and its count says how finely it divides
its part, not how large the part is. The fitting function's
n.trees, power and base reach each such forest that
states none, and are refused only where every one states its own; its
interactions and blocks, a constraint on one forest, are
refused and stated on the forest they constrain. A forest that states
sd has that size and leaves the share, its coefficient held unless
it states amplitude = normal() or student().
amplitude = fixed() on a forest that shares is taken and changes
nothing; normal() and student() are refused there, since such a forest has no
coefficient of its own. $getLeafPrior(f) on it gives the fitting
function's leaf prior as leaf.prior, its part in force as
sd (NA where k is drawn) and prior.sd.of
"forest, shared", and $getK(f) the group's k.
The part of a group is set once, at creation. A forest of a group leaves
it by $setForest(forest, sd = ), at that size with its k
pinned at 1, and the forests still sharing keep their parts and sizes;
nothing puts it back but a new sampler. A total stated later, by
$setLeafPrior(leaf.prior) or $setModel, reaches the forests
still sharing, each at its creation part, so their sizes no longer add up
to it. One forest alone leaves the leaf prior by
$setForest(forest, sd = ) as by stating sd at creation, its
k then pinned at 1. Printed, a line after the forests' own gives
each forest's tree count and their total, and another which forests share,
or which one is left of a group.
The leaf scales of a forest with a basis and of one stating sd come
from the model's own calibration map rather than from the leaf prior, so a
k hyperprior, a non-default k and a named leaf-prior
sd are refused where every forest with no basis states its size, as
forest(x1 + x2, sd = 2), in the response's units as
normal(sd = ) is, and a linear or Gaussian-process leaf prior
wherever a second forest is declared. In a model of several forests this sd
states one forest's share of the combined location's prior, per unit of a
numeric basis, where normal(sd = ) states a single forest's whole
spread. Every value here is validated at fit time, and
anything today's engine cannot honor is refused there by name rather than
dropped.
In a bart or dbarts formula each
forest() term is one forest of the model, without a separate
forests = list:
y ~ forest(x1 + x2) + forest(x1 + x2, basis = z). A term stands at
the top of the formula's right-hand side, joined to the others by +;
a forest() crossed with another term, as z:forest(x1 + x2) or
z * forest(x1 + x2), is refused with the forest() to write in
its place. The first forest with no basis is the model's first, wherever it
is written; a forest's default tree
count and tree prior go by whether it has a basis and not by where
it is written. A forest with no basis may be left as plain
terms, y ~ x1 + x2 + forest(x1 + x2, basis = z), which is the same
model, but a formula's plain predictor terms beside a forest() with
no basis are refused, as two readings of one model.
Alone, y ~ forest(x1 + x2) is the single-forest fit
y ~ x1 + x2, in every family that takes a formula. The other forests
keep the order they are written in. forest() may also be written
there as dbartsForests$forest(). A term's predictors and its basis
are read as code; every other argument is evaluated where the formula was
written. The same basis written in a formula's term and in a forests
list is the same columns on the same rows, and so the same model.
A dbartsForest specification object, resolved when a sampler is built.
dbartsForests,
dbarts, bart, dbartsSpec,
interactions, blocks
bart's ‘Formula Terms’ section is the full term
grammar - the forests of a formula, a forest's predictors, and the refusal
list - of which the ‘Details’ paragraph above is the
constructor-side summary.
set.seed(0) n <- 100L x <- matrix(runif(n * 3), n, 3, dimnames = list(NULL, c("x1", "x2", "x3"))) z <- rbinom(n, 1L, 0.5) y <- 2 * x[, 1] + z * (1 + 2 * x[, 3]) + rnorm(n, 0, 0.2) sampler <- dbarts(x, y, forests = list(forest(), forest(x1 + x3, basis = factor(z), n.trees = 25L, sd = 1.5)), control = dbartsControl(n.chains = 1L, n.samples = 20L, n.burn = 20L), n.trees = 25L) samples <- sampler$run(20L, 20L) amplitudes <- sampler$getForestAmplitudes() # the induced prior sd of the combined location, read off the sampler rather # than recomputed from the call: forest 2 is the one carrying a basis calibration <- sampler$getLeafPrior(2L) basis <- sampler$data@bases[[2L]] # its coefficients' prior variance is 1/2 over 0.674^2 indexSd <- sqrt((calibration$k.scale / 0.674)^2 * 0.5 * rowSums(basis^2)) # the same model written in a formula, the first forest written out; the # columns of a basis are named as lm() would name them d <- data.frame(y = y, x1 = x[, 1], x2 = x[, 2], x3 = x[, 3], z = z, w = 50 + 10 * rnorm(n)) written <- dbarts(y ~ forest(x1 + x2 + x3) + forest(x1 + x3, basis = factor(z), n.trees = 25L, sd = 1.5), d, control = dbartsControl(n.chains = 1L), n.trees = 25L) colnames(written$data@bases[[2L]]) # a standardized multiplier: predict centers and scales the new rows by the # training rows' mean and sd of w fit <- bart(y ~ forest(x1 + x3) + forest(x1 + x3, basis = scale(w), n.trees = 10L), d, n.trees = 10L, n.samples = 10L, n.burn = 10L, n.chains = 1L, n.threads = 1L, keepTrees = TRUE) predict(fit, d[1:3, ]) # forests built in a loop: each keeps the number its own call was given forest <- dbartsForests$forest forests <- list(forest()) for (k in c(25, 100)) forests[[length(forests) + 1L]] <- forest(x1, basis = I(w / k)) looped <- dbarts(y ~ x1 + x3, d, forests = forests, control = dbartsControl(n.chains = 1L), n.trees = 10L) vapply(looped$data@bases[-1L], function(basis) basis[1L, 1L], 0) * c(25, 100) # two columns are a forest each, with a coefficient each; I() holds arithmetic perColumn <- dbarts(y ~ forest(x1 + x3) + forest(x1, basis = z) + forest(x1, basis = I(w / 50)), d, control = dbartsControl(n.chains = 1L), n.trees = 10L) lapply(perColumn$data@bases[-1L], colnames)set.seed(0) n <- 100L x <- matrix(runif(n * 3), n, 3, dimnames = list(NULL, c("x1", "x2", "x3"))) z <- rbinom(n, 1L, 0.5) y <- 2 * x[, 1] + z * (1 + 2 * x[, 3]) + rnorm(n, 0, 0.2) sampler <- dbarts(x, y, forests = list(forest(), forest(x1 + x3, basis = factor(z), n.trees = 25L, sd = 1.5)), control = dbartsControl(n.chains = 1L, n.samples = 20L, n.burn = 20L), n.trees = 25L) samples <- sampler$run(20L, 20L) amplitudes <- sampler$getForestAmplitudes() # the induced prior sd of the combined location, read off the sampler rather # than recomputed from the call: forest 2 is the one carrying a basis calibration <- sampler$getLeafPrior(2L) basis <- sampler$data@bases[[2L]] # its coefficients' prior variance is 1/2 over 0.674^2 indexSd <- sqrt((calibration$k.scale / 0.674)^2 * 0.5 * rowSums(basis^2)) # the same model written in a formula, the first forest written out; the # columns of a basis are named as lm() would name them d <- data.frame(y = y, x1 = x[, 1], x2 = x[, 2], x3 = x[, 3], z = z, w = 50 + 10 * rnorm(n)) written <- dbarts(y ~ forest(x1 + x2 + x3) + forest(x1 + x3, basis = factor(z), n.trees = 25L, sd = 1.5), d, control = dbartsControl(n.chains = 1L), n.trees = 25L) colnames(written$data@bases[[2L]]) # a standardized multiplier: predict centers and scales the new rows by the # training rows' mean and sd of w fit <- bart(y ~ forest(x1 + x3) + forest(x1 + x3, basis = scale(w), n.trees = 10L), d, n.trees = 10L, n.samples = 10L, n.burn = 10L, n.chains = 1L, n.threads = 1L, keepTrees = TRUE) predict(fit, d[1:3, ]) # forests built in a loop: each keeps the number its own call was given forest <- dbartsForests$forest forests <- list(forest()) for (k in c(25, 100)) forests[[length(forests) + 1L]] <- forest(x1, basis = I(w / k)) looped <- dbarts(y ~ x1 + x3, d, forests = forests, control = dbartsControl(n.chains = 1L), n.trees = 10L) vapply(looped$data@bases[-1L], function(basis) basis[1L, 1L], 0) * c(25, 100) # two columns are a forest each, with a coefficient each; I() holds arithmetic perColumn <- dbarts(y ~ forest(x1 + x3) + forest(x1, basis = z) + forest(x1, basis = I(w / 50)), d, control = dbartsControl(n.chains = 1L), n.trees = 10L) lapply(perColumn$data@bases[-1L], colnames)
Attempts to guess the number of CPU ‘cores’, both physical and logical.
guessNumCores(logical = FALSE)guessNumCores(logical = FALSE)
logical |
A logical value. When |
Because of different definitions of cores used by different manufacturers, the distinction between logical and physical cores is not universally recognized. This function will attempt to use operating system definitions when available, which should usually match the CPU itself.
An integer, or NA if no clear answer was obtained. The fitting functions take their default n.threads from this value, and where it is NA the default is one thread, with no message; an n.threads that is stated as NA is refused.
Vincent Dorie: [email protected].
## physical cores, the default used by dbartsControl(n.threads = ) guessNumCores() ## including hyperthreads guessNumCores(logical = TRUE)## physical cores, the default used by dbartsControl(n.threads = ) guessNumCores() ## including hyperthreads guessNumCores(logical = TRUE)
Build an interaction-constraint specification restricting which predictors
may jointly shape a BART fit. Pass the result as the interactions
argument of dbarts or bart. The constraint is
applied per forest, so in a multi-forest model one forest can be held
additive-or-low-order while another stays free. A multinomial fit applies it
to each of its category forests.
The constructor is not exported: it resolves by bare name inside the
arguments that take it, and elsewhere is written
dbartsForests$interactions(...); see dbartsForests.
interactions(max.order = NULL, groups = NULL, forbid = NULL)interactions(max.order = NULL, groups = NULL, forbid = NULL)
max.order |
Optional cap on the number of distinct predictors that may appear
together on any single root-to-leaf path. |
groups |
Optional co-occurrence allow-list: a list of predictor sets. Two named predictors may share a root-to-leaf path only if some group contains both; every other pair of named predictors is forbidden. Predictors named in no group are unconstrained. Each set is a character vector of model-matrix column names (a bare factor term name expands to its indicator columns) or a numeric vector of column indices. A single vector (rather than a list) is taken as one group. |
forbid |
Optional co-occurrence deny-list: a list whose entries each name two or
more predictors barred from ever sharing a root-to-leaf path (an entry of
more than two forbids every pair within it). Columns are named or indexed
as for |
All three restrictions lower to a single per-node admissibility rule over the
set of predictors already used by a node's ancestors: max.order bars a
new predictor once the path's distinct count reaches the cap, while
groups and forbid bar a predictor whose forbidden partner sits
above it. The constraint is hard (an availability ban), applied inside the
tree proposals, and a warm start cuts back a tree that breaks it, so a
constrained fit never visits a path that violates it; an unconstrained fit
is unaffected.
Names and indices resolve against the model matrix at fit time, where every
value is validated: an unrecognized name, an empty group, a max.order
below 1, and a reference to a column dropped from the design are each an
error there. Supplying none of the three arguments is instead an error
immediately, at construction: interactions() with no arguments never
produces an object to pass to dbarts/bart.
Monotone constraints (see dbarts's monotone) and
interaction constraints are orthogonal and may be combined.
A groups partition that is both disjoint and total
(every predictor named in exactly one group) already makes the fit
block-additive: the root split fixes each tree's group, and the
co-occurrence rule confines every descendant to that same group, so the
ensemble is exactly a sum of per-group functions
- a functional-ANOVA / grouped-GAMI
decomposition that holds at every MCMC state. Under this idiom each tree's
group is chosen adaptively (by its root draw each sweep), so the number of
trees devoted to a group floats with the data. blocks gives
the same decomposition with a fixed per-group tree count and a
static per-tree mask instead of an adaptive per-path allow-list; use it
when a group needs guaranteed representation or a deterministic layout.
A dbartsInteractions specification object, resolved when a sampler is
built.
dbartsForests,
dbarts, bart, blocks
set.seed(0) n <- 100L x <- matrix(runif(n * 3), n, 3, dimnames = list(NULL, c("x1", "x2", "x3"))) y <- 2 * x[, 1] + ifelse(x[, 2] > 0.5, 1, -1) + rnorm(n, 0, 0.2) df <- data.frame(y, x) ## additive fit: no tree splits on more than one predictor on any path fit.additive <- bart(y ~ x1 + x2 + x3, df, interactions = interactions(max.order = 1), n.trees = 25L, n.samples = 20L, n.burn = 20L, n.chains = 1L, verbose = FALSE) ## forbid x1 and x2 from ever interacting, but allow order-2 interactions ## among the rest fit.forbid <- bart(y ~ x1 + x2 + x3, df, interactions = interactions(max.order = 2, forbid = list(c("x1", "x2"))), n.trees = 25L, n.samples = 20L, n.burn = 20L, n.chains = 1L, verbose = FALSE)set.seed(0) n <- 100L x <- matrix(runif(n * 3), n, 3, dimnames = list(NULL, c("x1", "x2", "x3"))) y <- 2 * x[, 1] + ifelse(x[, 2] > 0.5, 1, -1) + rnorm(n, 0, 0.2) df <- data.frame(y, x) ## additive fit: no tree splits on more than one predictor on any path fit.additive <- bart(y ~ x1 + x2 + x3, df, interactions = interactions(max.order = 1), n.trees = 25L, n.samples = 20L, n.burn = 20L, n.chains = 1L, verbose = FALSE) ## forbid x1 and x2 from ever interacting, but allow order-2 interactions ## among the rest fit.forbid <- bart(y ~ x1 + x2 + x3, df, interactions = interactions(max.order = 2, forbid = list(c("x1", "x2"))), n.trees = 25L, n.samples = 20L, n.burn = 20L, n.chains = 1L, verbose = FALSE)
Converts a data frame with numeric and factor contents into a matrix, suitable for use with bartBT. Unlike in linear regression, factors containing more than two levels result in dummy variables being created for each level.
makeModelMatrixFromDataFrame(x, drop = TRUE) makeind(x, all = TRUE) makeTestModelMatrix(data, newdata)makeModelMatrixFromDataFrame(x, drop = TRUE) makeind(x, all = TRUE) makeTestModelMatrix(data, newdata)
x |
Data frame of explanatory variables. A column may be a |
drop |
Logical or list controlling whether or not columns that are constants or factor levels with no instances are omitted from the result. When a list, must be of length equal to
A test frame must give each factor the training frame's levels, in their order: the helper codes a factor by position, where the fit's own |
all |
Not currently implemented; retained for signature compatibility with |
data |
An existing |
newdata |
Test data frame. |
Character vectors are included as factors. If you have numeric data coded as characters, convert it using as.numeric first.
Note that if you have train and test data frames, it may be best to rbind the two together, apply makeModelMatrixFromDataFrame to the result, and then pull them back apart. Alternatively, save the drop attribute used in creating the training data and use it when creating a matrix from the test data, as in the example given below.
Use of these functions is not required when using bartBT, bart, or dbartsSampler; they exist to allow the user finer control and to assist with writing packages that separate the creation of training from test data.
A matrix with columns corresponding to the elements of the data frame. If drop = TRUE or is a list, the attribute drop on the result is set to the list used when creating the matrix.
If any column of x is sparse-backed (a Matrix::sparseVector, dgCMatrix, or sparseFactor), the result is instead an object of class dbartsMixedMatrix - not a matrix (is.matrix() is FALSE) - which keeps sparse columns unexpanded rather than densifying them. Call as.matrix on it to obtain an ordinary dense matrix.
Vincent Dorie: [email protected].
iv <- 1:10 rv <- runif(10) f <- factor(rep(seq.int(3), c(4L, 4L, 2L)), labels = c("alice", "bob", "charlie")) df <- data.frame(iv, rv, f) mm <- makeModelMatrixFromDataFrame(df) ## create test and train matrices with disjoint factor levels train.df <- df[1:8,] test.df <- df[9:10,] train.mm <- makeModelMatrixFromDataFrame(train.df) test.mm <- makeModelMatrixFromDataFrame(test.df, attr(train.mm, "drop"))iv <- 1:10 rv <- runif(10) f <- factor(rep(seq.int(3), c(4L, 4L, 2L)), labels = c("alice", "bob", "charlie")) df <- data.frame(iv, rv, f) mm <- makeModelMatrixFromDataFrame(df) ## create test and train matrices with disjoint factor levels train.df <- df[1:8,] test.df <- df[9:10,] train.mm <- makeModelMatrixFromDataFrame(train.df) test.mm <- makeModelMatrixFromDataFrame(test.df, attr(train.mm, "drop"))
Read the model's variables and the number of rows of a dbartsData object.
## S3 method for class 'dbartsData' model.frame(formula, ...) ## S3 method for class 'dbartsData' nobs(object, ...)## S3 method for class 'dbartsData' model.frame(formula, ...) ## S3 method for class 'dbartsData' nobs(object, ...)
formula, object
|
A |
... |
Not used. |
model.frame returns the model's variables over the rows in, after subset and the na.action, as model.frame of an lm fit does: the response first, factors as factors, the weights in a (weights) column and the offsets in the offset() and (offset) columns, with a terms record, so that model.response, model.weights and model.offset read them. Its "na.action" attribute is the object's. On an object that keeps its frame it is made from the frame, a poly() term with its coefficients; a sparse column (a sparseVector, sparseFactor or dgCMatrix) comes back as stored, at the rows in, and is never made dense, so the frame holds classes a frame for lm could not.
On an object with no frame (a sampler's data, keep.data = FALSE, the matrix interface, an environment) it is decoded from the block where that is exact: the response is returned in its recorded type and levels (a factor, a logical, a character vector, a Surv response where the object holds its time and status, the count matrix for a multinomial one) and named as the formula wrote it (log(price), and y where no formula did), a factor predictor as a factor over its declared levels, a matrix term such as poly(x, 2) or scale(x) as one matrix column again, named as the formula wrote it, with the column names the term gave (an unnamed matrix of two or more columns is named 1, 2, ..., where the frame lm gives leaves it unnamed), and a column the block holds sparse as a sparse vector, sparse factor or sparse matrix. The columns come in the formula's order, those the block holds sparse after the others, and a column no term of the formula names (a hazard sampler's period) after them. The block holds no more than the values, so a rejoined matrix has none of the attributes poly() or scale() give it (their class, coefficients and centers); the terms record carries them in its predvars, as lm's does. That record is the formula's, each sparse column listed as a term after the others, so that lm on the frame stops at it as it does on the frame a formula and data give; with no formula (the matrix interface), or where a hazard sampler added its period, the frame has none and model.response does not read it: its first column is the response.
nobs counts the rows in with a positive weight, as the build counted them, evaluating nothing again, as nobs of a fit and of an lm fit do; rows of weight 0 stay in the object, and a BART fit holds them in its trees.
A data frame, and a number.
Build a monotone-constraint specification making a BART fit monotone
increasing or decreasing in chosen predictors (monotone BART; Chipman,
George, McCulloch, and Shively 2022), and name the prior it is read under.
Pass the result as the monotone argument of dbarts,
bart or dbartsSpec; a plain direction vector
passed there is shorthand for monotone(directions) at the default
prior.
The constructor is not exported: it resolves by bare name inside the
arguments that take it, and elsewhere is written
dbartsForests$monotone(...); see dbartsForests.
monotone(directions, prior = c("joint", "leaf"))monotone(directions, prior = c("joint", "leaf"))
directions |
The per-predictor directions. A named vector selects predictors by
model-matrix column name, each element |
prior |
How the constraint enters the prior, |
Each tree is held monotone in the constrained predictors, so the sum of trees is too. The two priors differ in where the constraint acts.
"joint"The ordinary BART prior on the trees and their leaf values, conditioned
on every tree being monotone. A tree whose leaf values would seldom be
in order under the ordinary prior becomes less likely, so the
constrained predictors get about half the share of splits they get in an
unconstrained fit at 200 trees, and split counts understate their
importance (less so under "leaf").
"leaf"The ordinary tree prior, unchanged; given a tree, its leaf values are drawn from the ordinary prior restricted to values in order. A tree move may then count the orderings of the tree's leaves that the constraint allows.
"joint" is the default because in a simulation study the two
priors fit alike, and "joint" never counts leaf orderings while
sampling, so its moves are never slow. (Drawing leaf values from the prior,
as samplePriorPredictive does, counts under either prior.) Under
either prior a constrained fit takes several times the time per sweep of
the same fit without the constraint: 4.5 to 8.5 times in that study.
With very few trees a constrained sampler moves slowly between tree shapes under either prior: a tree that has picked up extra splits tends to keep them, and the constraint then holds their leaves apart, which can overstate how steep the fitted function is. Use more trees.
Under "leaf" the count is negligible at 10 or more trees, but with
one to five trees a tree can grow large enough that a count takes seconds
to minutes per move, and its memory grows with it, to hundreds of
megabytes for the largest counts seen. There is no limit: the run
finishes on the stated model, and afterwards a warning of class
"dbartsSlowCountWarning" reports counts that took more than about
a second and names the remedies, more trees or prior = "joint". A
count can be interrupted, which raises R's interrupt condition and leaves
the pass over the trees partly applied, and a
count that runs out of memory is an ordinary error; either way the
sampler is left in a valid state.
The tree prior is the fit's, as without a constraint: power = 2
and base = 0.95, unless others are given. The mBART
paper used power = 0.8, base = 0.25, which gives smaller
trees; in a simulation study under "joint" at 200 trees it gave
sharper and more accurate fits, but narrower intervals that under-covered
with plentiful, low-noise data, and at 50 trees it was less accurate with
such data and under-covered more often. Pass
them as power and base to opt in (see Examples).
The fit is monotone in a constrained predictor along every line on which that predictor is observed, the other predictors at any values, missing ones and every factor level included; nothing is claimed where the constrained predictor itself is missing.
New predictor values given to a sampler (see
dbartsSampler) can leave a tree's leaf values out of
order. The calls that always complete - setPredictor with
forceUpdate = TRUE (its default when the whole matrix is replaced),
setData, setCutPoints, setState with
forceUpdate = TRUE, and a warm start, installTrees with
forceUpdate = TRUE or bart's warm.start - collapse
such a tree where its leaf values are out of order, each collapsed part
one leaf at the mean of the leaves it replaces weighted by their rows, and
keep the rest, without a message; that suits burn-in and is not a draw
from the posterior.
An unforced update is refused instead, as one that would empty a leaf is.
One unforced change can leave a tree out of order: the first missing value
in an unordered factor column that has none. Two leaves that share no
level of the factor can both be reached by a missing value, and the
constraint then orders them. Which leaves a missing value reaches is
settled by the side each rule on the column draws when the value arrives
(see ‘Missing values in predictors’ in
dbartsSampler), so the same update
can keep the order under one draw and break it under another. What each
call does where the sides drawn leave a tree out of order:
setPredictor with forceUpdate = FALSE, the whole
data frame or named columns: returns FALSE. The sampler's trees,
fits, predictors and random number generator are as they were before
the call. As after any refused update, the draws that follow can
differ in their last digits from those it would otherwise have made.
setPredictor with forceUpdate = "partial" and
updatePredictorPerObservationJointly: each row that
brings the missing value is declined, and the other rows are installed.
A numeric column's first missing value breaks no order and is installed.
Such a refusal is not cured by proposing other values: a refused update
puts the generator back, so the same sides are drawn again until the
sampler has run, and where the data favor such trees a later draw can
break the order too. Code that proposes the value again until it is
accepted may never finish. The way to bring the value in is
forceUpdate = TRUE, which completes and collapses those trees as
above; the alternative is to leave the value as it was.
Only numeric and ordered columns are eligible: a direction on a categorical
(unordered factor) predictor is an error. Names, positions and every
direction are validated against the model matrix at fit time; prior
is matched when the specification is built. An all-zero specification fits
the unconstrained model.
A constraint forces birth/death-only tree proposals (a control
naming a non-default proposal.probs is then an error). The leaf
scale is fixed: k is 2 unless another number is given, or a fixed
sd may be named, and a hyperprior on either is an error. Linear and
Gaussian-process leaves, variance forests, multi-forest models and
family = "multinomial" are not supported under it. It may be
combined with interactions and blocks.
A dbartsMonotone specification object, a list of directions
and prior, resolved when a sampler is built. A fit records the prior
as monotone.prior, which print and summary show.
Chipman, H. A., George, E. I., McCulloch, R. E., and Shively, T. S. (2022) mBART: multidimensional monotone BART. Bayesian Analysis 17(2), 515–544.
dbartsForests, dbartsPriors,
dbarts, bart, interactions,
blocks
set.seed(0) n <- 100L x <- matrix(runif(n * 3), n, 3, dimnames = list(NULL, c("x1", "x2", "x3"))) y <- 2 * x[, 1] - x[, 2] + sin(2 * pi * x[, 3]) + rnorm(n, 0, 0.2) df <- data.frame(y, x) ## increasing in x1, decreasing in x2, free in x3, under the default prior fit <- bart(y ~ x1 + x2 + x3, df, monotone = monotone(c(x1 = "increasing", x2 = "decreasing")), n.trees = 25L, n.samples = 20L, n.burn = 20L, n.chains = 1L, verbose = FALSE) fit$monotone.prior ## the plain vector, positionally, is the same specification fit.plain <- bart(y ~ x1 + x2 + x3, df, monotone = c(1, -1, 0), n.trees = 25L, n.samples = 20L, n.burn = 20L, n.chains = 1L, verbose = FALSE) ## the "leaf" prior fit.leaf <- bart(y ~ x1 + x2 + x3, df, monotone = monotone(c(x1 = "increasing", x2 = "decreasing"), prior = "leaf"), n.trees = 25L, n.samples = 20L, n.burn = 20L, n.chains = 1L, verbose = FALSE) ## the mBART paper's tree prior, as an opt-in fit.mbart <- bart(y ~ x1 + x2 + x3, df, monotone = c(x1 = "increasing", x2 = "decreasing"), power = 0.8, base = 0.25, n.trees = 25L, n.samples = 20L, n.burn = 20L, n.chains = 1L, verbose = FALSE)set.seed(0) n <- 100L x <- matrix(runif(n * 3), n, 3, dimnames = list(NULL, c("x1", "x2", "x3"))) y <- 2 * x[, 1] - x[, 2] + sin(2 * pi * x[, 3]) + rnorm(n, 0, 0.2) df <- data.frame(y, x) ## increasing in x1, decreasing in x2, free in x3, under the default prior fit <- bart(y ~ x1 + x2 + x3, df, monotone = monotone(c(x1 = "increasing", x2 = "decreasing")), n.trees = 25L, n.samples = 20L, n.burn = 20L, n.chains = 1L, verbose = FALSE) fit$monotone.prior ## the plain vector, positionally, is the same specification fit.plain <- bart(y ~ x1 + x2 + x3, df, monotone = c(1, -1, 0), n.trees = 25L, n.samples = 20L, n.burn = 20L, n.chains = 1L, verbose = FALSE) ## the "leaf" prior fit.leaf <- bart(y ~ x1 + x2 + x3, df, monotone = monotone(c(x1 = "increasing", x2 = "decreasing"), prior = "leaf"), n.trees = 25L, n.samples = 20L, n.burn = 20L, n.chains = 1L, verbose = FALSE) ## the mBART paper's tree prior, as an opt-in fit.mbart <- bart(y ~ x1 + x2 + x3, df, monotone = c(x1 = "increasing", x2 = "decreasing"), power = 0.8, base = 0.25, n.trees = 25L, n.samples = 20L, n.burn = 20L, n.chains = 1L, verbose = FALSE)
The na.action that bart, dbarts and
dbartsData default to. It drops the rows whose
response is missing and keeps the rows whose predictors are.
na.keepPredictors(object, ...)na.keepPredictors(object, ...)
object |
A model frame, as |
... |
Ignored, for compatibility with the other |
BART routes a missing predictor value down a learned side of each split
rule (“Missingness Incorporated in Attributes”), so an incomplete
row is data rather than a hole and dropping it discards information the
model can use. A missing response, on the other hand, is nothing to fit.
This function is that distinction: na.omit would drop both.
rpart's na.rpart is the behavioral precedent.
The dropped rows are recorded exactly as na.exclude records
them - a named integer vector of class "exclude" - so the training
fits pad back to the caller's own row count through
naresid: fitted, residuals and
yhat.train.mean on the fit are as long as the data, NA where
a row was dropped, while yhat.train and extract hold the kept
rows only.
The base functions keep their usual meaning on these entry points:
na.omit drops any row with a missing value anywhere and
pads nothing, na.exclude drops the same rows and pads,
na.fail refuses any missing value, and
na.pass keeps every row - after which a missing response is
an error, since there is nothing to fit it against.
On the matrix (x.train, y.train) interface, where there is
no model frame, the na.action is applied to a frame standing for
the (response, predictors) pair, so every one of these functions means on
that interface what it means on the formula one.
object with the missing-response rows removed, carrying an
"na.action" attribute of class "exclude" naming them; or
object unchanged when no response value is missing.
Every predict method on a fit (predict.bart and
bart's four own classes) and
survivalProbabilities take an na.action for
newdata, defaulting to this function; NULL applies no
action, which on new data gives the default's result, and getOption("na.action") is never consulted.
A missing value in newdata is routable when its column can
hold missing values: it had them in training or, on a sampler, has been
given them since (see dbartsSampler). Every split rule on
that column then holds a side for them, and the row predicts like any
other. On a column that has never held one no rule holds a side, so the
value is unroutable. Only the default and na.pass look at
this:
na.keepPredictors predicts every routable row and refuses
an unroutable one, naming its columns;
na.pass predicts every routable row and returns NA
for an unroutable one;
na.omit drops every row with a missing value;
na.exclude drops the same rows and pads them back
as NA, so the result stays aligned with newdata, as the
fit-time record does (predict.lm instead treats it as
na.omit on new data);
na.fail refuses any missing value, naming its
columns.
Any other function is applied to a one-column frame that is NA on
the rows with a missing value, on every interface, and the rows it keeps
then meet the default's refusal. The result carries newdata's row
names and no "na.action" attribute. When no row survives, or
newdata has none, the result has the usual draw dimensions and
zero rows (NA rows under na.exclude and na.pass),
and R's random number stream is left as it was.
A per-row offset, weights or bases must match
newdata's rows and loses the rows na.action drops; a single
value passes through unaffected. A missing value in a per-row
offset or weights (an n x K category shift counts as
one, on a multinomial fit) marks its row incomplete exactly as an
unroutable predictor does, and every na.action above governs it the
same way: the default and na.fail refuse it by name, na.pass
returns NA for it, and na.omit/na.exclude drop it
(na.exclude padding it back). On a binomial fit given no
weights, a predictive draw's missing success or failure count in
newdata's response columns marks its row the same way, unless the
columns miss a count in every row and so are read as absent (see the
family item of bart). A missing value in a single
(length-one) offset or weights is always an error, whatever
na.action is, since there is then no row for it to mark. A missing
value in bases never marks its row: on a row that is incomplete
for its predictors, its offset or its weights, which the
na.action drops or returns NA for, it is passed by, and on
any other row it is an error, whatever na.action is.
With no newdata, predict answers the training rows, which
have no predictor to route, and a missing value in a per-row offset
or weights marks its row incomplete in the same way: every
na.action above governs it as it does at newdata, the
default and na.fail refusing it, na.pass returning the row
with NA draws, and na.omit and na.exclude dropping
it, na.exclude padding it back. Only the rows na.action keeps
are read and drawn, as at newdata, so under one seed a posterior
predictive draw is that of the call at newdata with the same action,
and with the rows dropped it is that of the call on the rows kept (except
for a multinomial fit on a matrix of counts, whose own rows draw a count
vector each where newdata draws one category), and a
single missing value is always an error. survivalProbabilities
answers a missing value in the offset it is given for the fit's own
subjects in the same way. The sampler's own
predict, predictForests and getTrees methods take no
na.action, keep the default, and check no per-row
offset.test for a missing value at all: an NA there reaches
the engine unrouted.
na.omit, na.exclude, naresid,
bart, dbartsData,
survivalProbabilities
df <- data.frame(y = c(1, NA, 3, 4), x = c(1, 2, NA, 4)) # the response row goes, the predictor row stays model.frame(y ~ x, df, na.action = na.keepPredictors) # and the fit's training values pad back to the data's own length fit <- bart( y ~ x, df, n.samples = 20L, n.burn = 20L, n.chains = 1L, verbose = FALSE ) length(fitted(fit)) == nrow(df)df <- data.frame(y = c(1, NA, 3, 4), x = c(1, 2, NA, 4)) # the response row goes, the predictor row stays model.frame(y ~ x, df, na.action = na.keepPredictors) # and the fit's training values pad back to the data's own length fit <- bart( y ~ x, df, n.samples = 20L, n.burn = 20L, n.chains = 1L, verbose = FALSE ) length(fitted(fit)) == nrow(df)
Fit a model with bart, or take a fit or sampler, and average its predictions over a set of rows with one variable (pdbart) or a pair of variables (pd2bart) set to each of a grid of values, so that a plot can display that variable's effect. By default the averages are on the scale of the model's linear predictor: if is binary with , the standard normal cdf, then the plots are on the scale; type chooses another.
pdbart( formula, data, xind = NULL, levs = NULL, levquants = c(0.05, seq(0.1, 0.9, 0.1), 0.95), pl = TRUE, plquants = c(0.05, 0.95), type = "auto", newdata = NULL, n.average.rows = NULL, average.weights = NULL, times = NULL, ...) ## S3 method for class 'pdbart' plot( x, xind = seq_along(x$fd), plquants = c(0.05, 0.95), cols = c('blue', 'black'), plot.type = c("dependence", "curves"), ...) pd2bart( formula, data, xind = NULL, levs = NULL, levquants = c(0.05, seq(0.1, 0.9, 0.1), 0.95), pl = TRUE, plquants = c(0.05, 0.95), type = "auto", newdata = NULL, n.average.rows = NULL, average.weights = NULL, times = NULL, ...) ## S3 method for class 'pd2bart' plot( x, plquants = c(0.05, 0.95), contour.color = 'white', justmedian = TRUE, plot.type = c("dependence", "curves"), ...)pdbart( formula, data, xind = NULL, levs = NULL, levquants = c(0.05, seq(0.1, 0.9, 0.1), 0.95), pl = TRUE, plquants = c(0.05, 0.95), type = "auto", newdata = NULL, n.average.rows = NULL, average.weights = NULL, times = NULL, ...) ## S3 method for class 'pdbart' plot( x, xind = seq_along(x$fd), plquants = c(0.05, 0.95), cols = c('blue', 'black'), plot.type = c("dependence", "curves"), ...) pd2bart( formula, data, xind = NULL, levs = NULL, levquants = c(0.05, seq(0.1, 0.9, 0.1), 0.95), pl = TRUE, plquants = c(0.05, 0.95), type = "auto", newdata = NULL, n.average.rows = NULL, average.weights = NULL, times = NULL, ...) ## S3 method for class 'pd2bart' plot( x, plquants = c(0.05, 0.95), contour.color = 'white', justmedian = TRUE, plot.type = c("dependence", "curves"), ...)
formula |
The data to fit, as |
data |
As |
xind |
Integer, character vector, or the right-hand side of a formula indicating which variables are to be plotted. In a formula fit, these are variables of the data, named, and every term built from one - |
levs |
Gives the values of a variable at which the plot is to be constructed. Must be a list, where the |
levquants |
If |
pl |
For |
plquants |
In the plots, beliefs about |
type |
The scale averaged on, one of
|
times |
On a survival |
plot.type |
On a result with times, |
newdata |
Rows to average over in place of the fit's own, coded as |
n.average.rows |
A number of the fit's rows to average over, drawn at random without replacement from those with a positive |
average.weights |
One finite, non-negative weight per row averaged over - per row of the fit, before any it gives a weight of 0 are left out, or per row of |
... |
In In |
x |
For |
cols |
Vector of two colors. The first color is for the median of |
contour.color |
Color for contours plotted on top of the image. |
justmedian |
A logical where if |
We divide the predictor vector into a subgroup of interest, and the complement . A prediction can then be written as . To estimate the effect of on the prediction, Friedman suggests the partial dependence function
where is the th observation of in the data. Note that will generally not be one of the observed data points. Using BART it is straightforward to then estimate and even obtain uncertainty bounds for . A draw of from the induced BART posterior on is obtained by simply computing as a byproduct of each MCMC draw . The median (or average) of these MCMC draws then yields an estimate of , and lower and upper quantiles can be used to obtain intervals for .
In pdbart consists of a single variable in and in pd2bart it is a pair of variables.
The rows averaged over are the fit's own unless newdata is given: those it was fit to, less any it gives a weight of 0, which for a binary response masks a row out, and less any dropped for a missing response. In a formula fit they are read from the data the fit's call names, re-evaluated, which a fit kept without its call cannot do; give newdata then. Each row's offset is added to its prediction once: the fit's offset expression or offset() term evaluated on the row with the variable set, or, for an offset given as a plain vector, the row's own value. A value is therefore the (weighted) row mean of predict(fit, rows, type = type) with the variable set.
On a hurdle fit the rows averaged over leave out the rows the fit gave a weight of 0, and each part adds its own offset: the zero part's to "prob", the positive part's to "bart", and both to "ev" and "ppd". A part's offset, a plain one entering the positive part, is evaluated on the rows as predict evaluates it; one given as a plain vector cannot be evaluated on newdata of another length, and the refusal names the part.
In pd2bart, when the fit has two predictors and one offset for every row, each grid point is a single row and is predicted once; newdata then gives only the default grid, and n.average.rows and average.weights have no effect, with a warning. type = "ppd", which draws noise for each row, always averages over the rows.
A data call fits through bart at its defaults, keeping trees and sampler, and predicts each grid value from the saved trees, so pdbart(x, y, seed = s) and pdbart(bart(x, y, seed = s, keepTrees = TRUE)) agree. pdbart(bartBT(x, y, keeptrees = TRUE)) gives the model dbarts 0.9-34 fit. The first data call in a session prints a message saying so; a call from package code does not.
pdbart and pd2bart serve gaussian, Student-t, probit, logistic, negative binomial and hurdle fits. Multinomial and ordinal fits, whose prediction is a probability per category, are refused; predict on rows with the variable set gives each category's. On accelerated failure time and hazard fits they average survival, the event probability or the cumulative hazard per subject at chosen times; on a hazard fit each subject's rows are expanded to the periods up to the largest time and replayed in chunks, so memory stays bounded. The work is the number of predictions, one being one person-period row under one draw at one grid value: subjects x periods up to the largest time x draws x grid values. It grows with that count (about ten minutes at 5e9) and no call refuses on it; to shrink it, use a coarser period grid (hazard(breaks = )), fewer subjects (newdata or n.average.rows), fewer grid values (levs or levquants), or an earlier largest time (times). newdata and n.average.rows there are subject rows, and the default time stays the training data's. In a formula hazard fit the subjects are read from the data the call names, as in any formula fit, and coded with their offset at each grid value; the period is never a predictor. Each refusal comes before anything is fit, whether the family is named, resolved by family = "auto" from the response, or that of a fit or sampler passed in.
This is a computationally intensive procedure. For example, in pdbart, to compute the partial dependence plot for 5 values, we need to compute for all possible and there would be of these where is the sample size. All of that computation would be done for each kept BART draw. For this reason thinning the draws with n.thin larger than 1 (eg. 10) makes the procedure much faster.
The plot methods produce the plots and don't return anything.
pdbart and pd2bart return lists with components given below. The list returned by pdbart is assigned class pdbart and the list returned by pd2bart is assigned class pd2bart. The class carries a plot method only; it is not a fit, so predict, extract, fitted, and residuals are not defined for it (fitted and residuals fall through to stats' defaults and return NULL).
fd |
A matrix whose For For On a survival The draws of every chain are merged, each chain's in turn. When the fit keeps its chains apart ( |
levs |
The list of levels used, each component corresponding to a variable. If argument |
xlbs |
A vector of character strings which are the plotting labels used for the variables. |
n.chains |
The number of chains. |
type |
The scale averaged on, as resolved: |
family |
The fit's family, which with |
times |
On a survival |
The remaining components are passed on from the fit, under bart's own names (see its ‘Value’ section) with one rename and several omissions - the fit's call is under bartcall rather than call, and not every bart component is carried over. For a continuous response the remaining components are bartcall, yhat.train, first.sigma, sigma, yhat.train.mean, sigest, y, and fit, the sampler, which keepSampler = FALSE leaves out. For a binary response only bartcall, yhat.train, y, and fit are present. For a hurdle fit, fit is a list of the two parts' samplers, zero and positive, and no draws are carried over. pd2bart follows the same rules. The function plot.bart can be applied to the object returned by pdbart or pd2bart to examine the BART run.
Hugh Chipman: [email protected].
Robert McCulloch: [email protected].
Chipman, H., George, E., and McCulloch, R. (2010) BART: Bayesian additive regression trees. The Annals of Applied Statistics, 4(1), 266–298. doi:10.1214/09-AOAS285.
Chipman, H., George, E., and McCulloch R. (2006) Bayesian Ensemble Learning. Advances in Neural Information Processing Systems 19, Scholkopf, Platt and Hoffman, Eds., MIT Press, Cambridge, MA, 265-272. https://www.rob-mcculloch.org/
Friedman, J.H. (2001) Greedy function approximation: A gradient boosting machine. The Annals of Statistics, 29, 1189–1232.
## simulate data f <- function(x) return(0.5 * x[,1] + 2 * x[,2] * x[,3]) sigma <- 0.2 n <- 100 set.seed(27) x <- matrix(2 * runif(n * 3) - 1, ncol = 3) colnames(x) <- c('rob', 'hugh', 'ed') Ey <- f(x) y <- rnorm(n, Ey, sigma) ## pdbart: one dimensional partial dependence plot pdb1 <- pdbart( x, y, xind = c(1, 2), levs = list(seq(-1, 1, 0.2), seq(-1, 1, 0.2)), pl = FALSE, n.thin = 10, n.trees = 100, n.chains = 2, n.threads = 1, seed = 99, verbose = FALSE ) ## pd2bart: two dimensional partial dependence plot pdb2 <- pd2bart( x, y, xind = c(2, 3), levquants = c(0.05, 0.1, 0.25, 0.5, 0.75, 0.9, 0.95), pl = FALSE, n.thin = 10, n.trees = 100, n.chains = 2, n.threads = 1, seed = 99, verbose = FALSE) ## the plot methods draw into the current device, so set up the layout and ## put the caller's graphical parameters back afterwards. The first two plot ## regions are for pdbart, the third for pd2bart. oldpar <- par(no.readonly = TRUE) par(mfrow = c(1, 3)) plot(pdb1, ylim = c(-0.6, 0.6)) plot(pdb2) par(oldpar) ## compare BART fit to linear model and truth = Ey lmFit <- lm(y ~ ., data.frame(x, y)) fitmat <- cbind(y, Ey, lmFit$fitted, pdb1$yhat.train.mean) colnames(fitmat) <- c('y', 'Ey', 'lm', 'bart') print(cor(fitmat)) ## example showing the use of a pre-fitted model df <- data.frame(y, x) bartFit <- bart( y ~ rob + hugh + ed, df, n.thin = 10, n.trees = 100, n.chains = 2, n.threads = 1, seed = 99, keepTrees = TRUE, verbose = FALSE) pdb3 <- pdbart(bartFit, xind = rob + ed, pl = FALSE) ## averaged over a subgroup's rows, with the grid from them pdb4 <- pdbart(bartFit, xind = "rob", newdata = df[df$hugh > 0, ], pl = FALSE) ## survival at three times on a discrete-time hazard fit, drawn both ways if (requireNamespace("survival", quietly = TRUE)) { time <- rexp(n, exp(x[, "rob"])) status <- rbinom(n, 1, 0.8) hazardFit <- bart( x, survival::Surv(time, status), family = hazard(breaks = c(0, quantile(time, seq(0.1, 1, 0.1)))), n.chains = 2, n.threads = 1, keepTrees = TRUE, verbose = FALSE) pdb5 <- pdbart(hazardFit, xind = "rob", times = quantile(time, c(0.25, 0.5, 0.75)), pl = FALSE) plot(pdb5) plot(pdb5, plot.type = "curves") }## simulate data f <- function(x) return(0.5 * x[,1] + 2 * x[,2] * x[,3]) sigma <- 0.2 n <- 100 set.seed(27) x <- matrix(2 * runif(n * 3) - 1, ncol = 3) colnames(x) <- c('rob', 'hugh', 'ed') Ey <- f(x) y <- rnorm(n, Ey, sigma) ## pdbart: one dimensional partial dependence plot pdb1 <- pdbart( x, y, xind = c(1, 2), levs = list(seq(-1, 1, 0.2), seq(-1, 1, 0.2)), pl = FALSE, n.thin = 10, n.trees = 100, n.chains = 2, n.threads = 1, seed = 99, verbose = FALSE ) ## pd2bart: two dimensional partial dependence plot pdb2 <- pd2bart( x, y, xind = c(2, 3), levquants = c(0.05, 0.1, 0.25, 0.5, 0.75, 0.9, 0.95), pl = FALSE, n.thin = 10, n.trees = 100, n.chains = 2, n.threads = 1, seed = 99, verbose = FALSE) ## the plot methods draw into the current device, so set up the layout and ## put the caller's graphical parameters back afterwards. The first two plot ## regions are for pdbart, the third for pd2bart. oldpar <- par(no.readonly = TRUE) par(mfrow = c(1, 3)) plot(pdb1, ylim = c(-0.6, 0.6)) plot(pdb2) par(oldpar) ## compare BART fit to linear model and truth = Ey lmFit <- lm(y ~ ., data.frame(x, y)) fitmat <- cbind(y, Ey, lmFit$fitted, pdb1$yhat.train.mean) colnames(fitmat) <- c('y', 'Ey', 'lm', 'bart') print(cor(fitmat)) ## example showing the use of a pre-fitted model df <- data.frame(y, x) bartFit <- bart( y ~ rob + hugh + ed, df, n.thin = 10, n.trees = 100, n.chains = 2, n.threads = 1, seed = 99, keepTrees = TRUE, verbose = FALSE) pdb3 <- pdbart(bartFit, xind = rob + ed, pl = FALSE) ## averaged over a subgroup's rows, with the grid from them pdb4 <- pdbart(bartFit, xind = "rob", newdata = df[df$hugh > 0, ], pl = FALSE) ## survival at three times on a discrete-time hazard fit, drawn both ways if (requireNamespace("survival", quietly = TRUE)) { time <- rexp(n, exp(x[, "rob"])) status <- rbinom(n, 1, 0.8) hazardFit <- bart( x, survival::Surv(time, status), family = hazard(breaks = c(0, quantile(time, seq(0.1, 1, 0.1)))), n.chains = 2, n.threads = 1, keepTrees = TRUE, verbose = FALSE) pdb5 <- pdbart(hazardFit, xind = "rob", times = quantile(time, c(0.25, 0.5, 0.75)), pl = FALSE) plot(pdb5) plot(pdb5, plot.type = "curves") }
Minimalist visualization of the branching and leaf contents of one tree
in a fitted bartBT/bart model, or in a
dbartsSampler.
A fit-level convenience wrapper around the sampler's plotTree
method, so the trees can be plotted without reaching into the sampler
stored on the fit.
bart's four own-class fits ("bartMultinomial",
"bartOrdinal", "bartNegbin", "bartHurdle") refuse
by name instead: their trees live on the sampler(s) those fits carry
(object$fit for the first three, object$zero$fit/
object$positive$fit for the hurdle), which plotTree can
be called on directly.
plotTree(object, ...) ## S3 method for class 'bart' plotTree( object, treeNum = 1L, chainNum, sampleNum, forest = NULL, ...) ## S3 method for class 'dbartsSampler' plotTree(object, ...) ## S3 method for class 'bartMultinomial' plotTree(object, ...) ## S3 method for class 'bartOrdinal' plotTree(object, ...) ## S3 method for class 'bartNegbin' plotTree(object, ...) ## S3 method for class 'bartHurdle' plotTree(object, ...)plotTree(object, ...) ## S3 method for class 'bart' plotTree( object, treeNum = 1L, chainNum, sampleNum, forest = NULL, ...) ## S3 method for class 'dbartsSampler' plotTree(object, ...) ## S3 method for class 'bartMultinomial' plotTree(object, ...) ## S3 method for class 'bartOrdinal' plotTree(object, ...) ## S3 method for class 'bartNegbin' plotTree(object, ...) ## S3 method for class 'bartHurdle' plotTree(object, ...)
object |
A fitted model of class |
treeNum |
An integer, the index of the tree to plot. |
chainNum |
An integer, the index of the chain to plot from. For a |
sampleNum |
An integer, the index of the saved sample to plot from. When omitted, the last sample is used (or the current working trees when the trees were not kept as samples). |
forest |
A number, the forest to plot from (1-indexed, as
|
... |
Additional arguments, including |
The rendering handles constant, linear, and Gaussian-process leaves. For a
multiple-chain fit, chainNum selects the chain. Equivalent to
calling the plotTree method on the underlying sampler, i.e.
object$fit$plotTree(...) for a bart fit.
Invisibly returns NULL; called for the side effect of drawing.
f <- function(x) 10 * sin(pi * x[,1] * x[,2]) + 20 * (x[,3] - 0.5)^2 + 10 * x[,4] + 5 * x[,5] set.seed(99) sigma <- 1.0 n <- 100 x <- matrix(runif(n * 10), n, 10) Ey <- f(x) y <- rnorm(n, Ey, sigma) fit <- bart(x, y, n.samples = 40L, n.burn = 10L, n.trees = 25L, n.chains = 1L, keepTrees = TRUE, verbose = FALSE) plotTree(fit, treeNum = 1L, sampleNum = 40L)f <- function(x) 10 * sin(pi * x[,1] * x[,2]) + 20 * (x[,3] - 0.5)^2 + 10 * x[,4] + 5 * x[,5] set.seed(99) sigma <- 1.0 n <- 100 x <- matrix(runif(n * 10), n, 10) Ey <- f(x) y <- rnorm(n, Ey, sigma) fit <- bart(x, y, n.samples = 40L, n.burn = 10L, n.trees = 25L, n.chains = 1L, keepTrees = TRUE, verbose = FALSE) plotTree(fit, treeNum = 1L, sampleNum = 40L)
Deprecated. rbart_vi and its methods run the implementation from dbarts 0.9-x, kept for one release, and are removed in dbarts 1.1-0. A warning (class dbartsDeprecatedWarning) says so the first time rbart_vi is called in a session. Grouped random effects live in the stan4bart package (stan4bart::stan4bart), whose prior on the group spread differs from the one used here, so a refit there moves the results rather than reproducing them.
Fits a varying intercept/random effect BART model. A fallback this function makes (running single-threaded, disabling verbose output for several threads, recycling group.by, drawing effects for unseen levels, a failed rejection sample) warns with class dbartsFallbackWarning, and the deprecated value argument and type = "post-mean" of predict warn with class dbartsDeprecatedWarning.
rbart_vi( formula, data, test, subset, weights, offset, offset.test = offset, group.by, group.by.test, prior = cauchy, sigest = NA_real_, sigdf = 3.0, sigquant = 0.90, k = 2.0, power = 2.0, base = 0.95, n.trees = 75L, n.samples = 1500L, n.burn = 1500L, n.chains = 4L, n.threads = min(dbarts::guessNumCores(), n.chains), combineChains = FALSE, n.cuts = 100L, useQuantiles = FALSE, n.thin = 5L, keepTrainingFits = TRUE, printEvery = 100L, printCutoffs = 0L, verbose = TRUE, keepTrees = TRUE, keepCall = TRUE, seed = NA_integer_, keepSampler = keepTrees, keepTestFits = TRUE, callback = NULL, ...) ## S3 method for class 'rbart' plot( x, plquants = c(0.05, 0.95), cols = c('blue', 'black'), ...) ## S3 method for class 'rbart' fitted( object, type = c("ev", "ppd", "bart", "ranef"), sample = c("train", "test"), ...) ## S3 method for class 'rbart' extract( object, type = c("ev", "ppd", "bart", "ranef", "trees"), sample = c("train", "test"), combineChains = TRUE, ...) ## S3 method for class 'rbart' predict( object, newdata, group.by, offset, type = c("ev", "ppd", "bart", "ranef"), combineChains = TRUE, ...) ## S3 method for class 'rbart' residuals(object, ...) ## S3 method for class 'rbart' print(x, ...) ## S3 method for class 'rbart' sigma(object, ...) ## S3 method for class 'rbart' nobs(object, ...)rbart_vi( formula, data, test, subset, weights, offset, offset.test = offset, group.by, group.by.test, prior = cauchy, sigest = NA_real_, sigdf = 3.0, sigquant = 0.90, k = 2.0, power = 2.0, base = 0.95, n.trees = 75L, n.samples = 1500L, n.burn = 1500L, n.chains = 4L, n.threads = min(dbarts::guessNumCores(), n.chains), combineChains = FALSE, n.cuts = 100L, useQuantiles = FALSE, n.thin = 5L, keepTrainingFits = TRUE, printEvery = 100L, printCutoffs = 0L, verbose = TRUE, keepTrees = TRUE, keepCall = TRUE, seed = NA_integer_, keepSampler = keepTrees, keepTestFits = TRUE, callback = NULL, ...) ## S3 method for class 'rbart' plot( x, plquants = c(0.05, 0.95), cols = c('blue', 'black'), ...) ## S3 method for class 'rbart' fitted( object, type = c("ev", "ppd", "bart", "ranef"), sample = c("train", "test"), ...) ## S3 method for class 'rbart' extract( object, type = c("ev", "ppd", "bart", "ranef", "trees"), sample = c("train", "test"), combineChains = TRUE, ...) ## S3 method for class 'rbart' predict( object, newdata, group.by, offset, type = c("ev", "ppd", "bart", "ranef"), combineChains = TRUE, ...) ## S3 method for class 'rbart' residuals(object, ...) ## S3 method for class 'rbart' print(x, ...) ## S3 method for class 'rbart' sigma(object, ...) ## S3 method for class 'rbart' nobs(object, ...)
group.by |
Grouping factor. Can be an integer vector/factor, or a reference to such in |
group.by.test |
Grouping factor for test data, of the same type as |
prior |
A function or symbolic reference to built-in priors. A built-in is named by symbol or string ( |
n.thin |
The number of tree jumps taken for every stored sample, but also the number of samples from the posterior of the standard deviation of the random effects before one is kept. |
keepTestFits |
Logical where, if false, test fits are obtained while running but not returned. Useful with |
callback |
Optional function of |
formula, data, test, subset, weights, offset, offset.test, sigest, sigdf, sigquant, k, power, base, n.trees, n.samples, n.burn, n.chains, n.threads, combineChains, n.cuts, useQuantiles, keepTrainingFits, printEvery, printCutoffs, verbose, keepTrees, keepCall, seed, keepSampler, ...
|
Same as in |
object |
A fitted |
newdata |
Same as |
type |
One of |
sample |
One of |
x, plquants, cols
|
Same as in |
A fit in which every predictor holds one value on the rows kept, with no forest having a basis, is refused, naming the columns, as by bart.
Fits a BART model with additive random intercepts, one for each factor level of group.by. For continuous responses:
.
For binary outcomes the response model is changed to . indexes observations, is the group index of observation , and come from a BART model, and are the independent and identically distributed random intercepts. Draws from the posterior of are made using a slice sampler, with a width dynamically determined by assessing the curvature of the posterior distribution at its mode.
Predicting random effects for groups not in the training sample is supported by sampling from their posterior predictive distribution, that is a draw is taken from . For out-of-sample groups in the test data, these random effect draws can be kept with the saved object. For those supplied to predict, they cannot and may change for subsequent calls.
Data are handled as in dbarts 0.9-x and not as bart does: a factor predictor is expanded to indicator columns, rows with missing values are dropped (na.omit), and the response must be continuous or binary.
See the generics section of bartBT. sigma(fit) is the posterior mean of the residual standard deviation, mean(fit$sigma), and 1 on a binary response, which has none; nobs(fit) counts the rows in the likelihood, those of positive weight. fitted, residuals, extract, sigma and nobs warn of an argument name they do not take, and then disregard it.
An object of class rbart. Contains all of the same elements of an object of class bart, as well as the elements:
ranef |
Samples from the posterior of the random effects. A array/matrix of posterior samples. The |
ranef.mean |
Posterior mean of random effects, derived by taking mean across group index of samples. |
tau |
Matrix of posterior samples of |
first.tau |
Burn-in draws of |
callback |
Optional results of |
Vincent Dorie: [email protected]
f <- function(x) { 10 * sin(pi * x[,1] * x[,2]) + 20 * (x[,3] - 0.5)^2 + 10 * x[,4] + 5 * x[,5] } set.seed(99) sigma <- 1.0 n <- 100 x <- matrix(runif(n * 10), n, 10) Ey <- f(x) y <- rnorm(n, Ey, sigma) n.g <- 10 g <- sample(n.g, length(y), replace = TRUE) sigma.b <- 1.5 b <- rnorm(n.g, 0, sigma.b) y <- y + b[g] df <- as.data.frame(x) colnames(df) <- paste0("x_", seq_len(ncol(x))) df$y <- y df$g <- g ## low numbers to reduce run time rbartFit <- suppressWarnings( rbart_vi(y ~ . - g, df, group.by = g, n.samples = 40L, n.burn = 10L, n.thin = 2L, n.chains = 1L, n.trees = 25L, n.threads = 1L))f <- function(x) { 10 * sin(pi * x[,1] * x[,2]) + 20 * (x[,3] - 0.5)^2 + 10 * x[,4] + 5 * x[,5] } set.seed(99) sigma <- 1.0 n <- 100 x <- matrix(runif(n * 10), n, 10) Ey <- f(x) y <- rnorm(n, Ey, sigma) n.g <- 10 g <- sample(n.g, length(y), replace = TRUE) sigma.b <- 1.5 b <- rnorm(n.g, 0, sigma.b) y <- y + b[g] df <- as.data.frame(x) colnames(df) <- paste0("x_", seq_len(ncol(x))) df$y <- y df$g <- g ## low numbers to reduce run time rbartFit <- suppressWarnings( rbart_vi(y ~ . - g, df, group.by = g, n.samples = 40L, n.burn = 10L, n.thin = 2L, n.chains = 1L, n.trees = 25L, n.threads = 1L))
The rank-normalized split R-hat (Vehtari, Gelman, Simpson, Carpenter and
Buerkner, 2021) of the draws of one quantity from several chains: the larger
of the bulk and the folded (tail) values. It is the statistic
summary.bart reports, and from four iterations on it returns
the value posterior::rhat does for the inputs that function takes
(see Details for the inputs where the two differ).
rhat(x)rhat(x)
x |
A numeric (or logical) matrix of the draws of one quantity, with a row for each iteration and a column for each chain. A vector is taken as one chain. |
Each chain is cut in two, the middle draw of an odd length dropped, and the draws are rank-normalized as one pool; the bulk value compares the half-chains' means and variances, and the tail value does the same on the draws folded about their median. R-hat compares each chain's spread with the pooled spread, so a value above 1 says the chains disagree.
The result is NA, as for posterior::rhat, when x has an
NA, NaN or constant draws, or has a single iteration. A
non-finite draw other than NA and NaN is ranked, as
posterior ranks it. An argument that is not numeric or logical, is an
array of more than two dimensions, or has no iteration or no chain is an
error. posterior refuses a data frame and a character vector too,
but takes a complex vector (and returns an infinite value with a warning
for a matrix with no chain); dbarts refuses those, as they are not draws.
With two or three iterations and several chains, posterior (1.7.0)
loses the dimension of its one-draw half-chains and treats each iteration as
a chain; dbarts returns NA, as a half-chain of one draw has no
variance. At four or more iterations the two agree to rounding.
R-hat should be read on the estimand reported: at the defaults BART's chains
routinely disagree on sigma, k and single predictions, while
averaged estimands, such as a subgroup's mean prediction or a contrast
between subgroups, mix far better. See summary.bart.
A single number, NA_real_ where the draws carry no information.
rhat
Call it as dbarts::rhat. Other packages export a function named
rhat: posterior and bayesplot (and brms
re-exports posterior's), and rstan exports Rhat.
Whichever is attached last masks the others, and bayesplot's takes a
fitted Stan model, not a matrix. The stan4bart package attaches
dbarts, so it brings this name in.
Vehtari, A., Gelman, A., Simpson, D., Carpenter, B. and Buerkner, P.-C.
(2021) Rank-normalization, folding, and localization: an improved
for assessing convergence of MCMC. Bayesian
Analysis 16(2), 667-718.
set.seed(1) draws <- matrix(rnorm(400), 100L, 4L) dbarts::rhat(draws) # four chains that disagree dbarts::rhat(draws + rep(0:3, each = 100L))set.seed(1) draws <- matrix(rnorm(400), 100L, 4L) dbarts::rhat(draws) # four chains that disagree dbarts::rhat(draws + rep(0:3, each = 100L))
Draws repeatedly from the prior a dbartsSampler runs under - the
hyperparameters that carry a prior, tree structure, leaf values, and optionally the observation
model - and evaluates the resulting forest at x.test.
Useful for calibrating priors before ever fitting to data, e.g. inspecting the implied prior on a
treatment effect . The sampler passed in is never modified.
samplePriorPredictive( sampler, x.test = NULL, n.samples = 200L, type = c("ev", "ppd"), offset.test = NULL, n.threads = [email protected] )samplePriorPredictive( sampler, x.test = NULL, n.samples = 200L, type = c("ev", "ppd"), offset.test = NULL, n.threads = sampler$control@n.threads )
sampler |
A |
x.test |
A matrix of predictors at which to evaluate the drawn forests, in the form accepted by
|
n.samples |
A positive integer giving the number of independent prior draws to return. |
type |
|
offset.test |
A numeric offset added to the forest sum, as in |
n.threads |
Forwarded to the underlying |
Each of the n.samples draws independently redraws the hyperparameters, every tree's
structure (sampleTreesFromPrior) and leaf values (sampleLeafParametersFromPrior)
from scratch, then evaluates the resulting forest at x.test - there is no MCMC dependence
between rows of the result, unlike a posterior sample from run.
The hyperparameters drawn are those the sampler draws: from its chi()
hyperprior (which normal(sd = invchi()) is), a Student-t df from its prior on the
family's grid when the df is estimated, a negative-binomial shape from its prior on its grid when
the shape is estimated, and an ordinal sampler's cutpoints (the first at 0, each gap log-normal),
one set per sample shared by every row. A fixed , df or shape is used as it stands.
An improper leaf prior, invchi() with scale 0 or chi() with an infinite scale, has
no prior draws and is refused.
Under split.probs = dart() the prior the sampler runs is not the stated Dirichlet on the
split probabilities alone: the sampler never holds a tree with an empty leaf, so its prior on the
split probabilities and the trees together is the stated one restricted to forests in which no
tree has an empty leaf. Each sample draws the concentration and the split probabilities from the
stated prior and every tree from the tree prior given them, and redraws the whole, split
probabilities included, while any tree has an empty leaf, with no limit on the attempts, so
every sample is an exact draw of that prior. How often a whole draw is kept falls with the number
of trees and rises with the number of rows: about one in a hundred at 60 rows, 8 columns and 200
trees, where 1,000 samples take a few seconds. With few rows and many trees the draw can take
long: at 8 columns, 1,000 samples take about a minute at 60 rows and 500 trees, and one and a
half to two and a half hours at 60 rows and 1,000 trees or at 30 rows and 500 trees. Once the
attempts made project a call longer than about a minute, a warning, printed when issued, gives the
share of draws kept so far and the projected time. The draw can be interrupted as a run is; the
sampler passed in is left as it was.
For type = "ppd" on a gaussian sampler, sigma is drawn once per sample from the model's
residual-variance prior: a scaled-inverse-chi-squared calibrated so that
when the prior is
chisq (see dbartsPriors), or the sampler's fixed value when the prior is
fixed.
A heteroscedastic sampler (dbarts's variance) has no single sigma to draw,
so the noise is its own surface: each sample additionally redraws the variance forest from its
prior (sampleVarianceForestFromPrior) and adds at the rows
being predicted, read there through
getVariance. The mean draws, and every type = "ev"
draw, are unaffected.
Prior draws are chain-free: the private sampler runs one chain whatever sampler's
n.chains, since there is no mixing or convergence concept for draws that are already
independent by construction.
Seeding follows from the private sampler being constructed fresh on every call. When the
control's seed is NULL (the default), the engine RNG
is seeded from R's random number stream at construction, so successive calls return independent
draws, and a set.seed beforehand makes the whole draw - forests and observation
layer alike - reproducible. When the control fixes seed, the engine stream is pinned:
every call replays the identical sequence of hyperparameters and forests, with only the R-side
"ppd" observation layer (sigma, the noise, counts and categories) still governed by
set.seed.
To compare the prior at two or more covariate settings with paired forests - as for a treatment
effect - stack the settings as rows of a single x.test and difference the corresponding
columns of the result; see ‘Examples’. Two separate calls draw independent sets of forests
(unless seed is fixed, as above) and so cannot be differenced meaningfully.
A matrix with n.samples rows and one column per row of x.test (or of the training
predictors, when x.test is NULL) - the combined-draws convention extract
uses for a single chain, with no chain dimension. For an ordinal or multinomial sampler
"ev" is an n.samples by rows by array of category probabilities, as is
"ppd" on a multinomial sampler whose response was written as a count matrix, holding the counts; category codes
are integers.
dbartsSampler for sampleTreesFromPrior, sampleLeafParametersFromPrior,
and predict, the building blocks this function composes. dbarts for
creating a sampler. extract for the same "ev"/"ppd" vocabulary applied to
posterior draws.
n <- 100 x <- matrix(runif(n * 2), n, 2) y <- x[, 1] - x[, 2] + rnorm(n, 0, 0.2) sampler <- dbarts(y ~ x, control = dbartsControl(n.chains = 1L, n.threads = 1L)) ## prior-predictive draws of a treatment effect f(x1) - f(x0), holding the ## other covariate fixed at its midpoint: calibrates the prior before ever ## touching y. Stacking both settings into one x.test pairs the forests, so ## the two columns of the result come from the same drawn function. xContrast <- rbind(c(0, 0.5), c(1, 0.5)) colnames(xContrast) <- colnames(sampler$data@x) f <- samplePriorPredictive(sampler, x.test = xContrast, n.samples = 500L) effect <- f[, 2] - f[, 1] hist(effect, main = "prior on the treatment effect", xlab = "f(x1) - f(x0)")n <- 100 x <- matrix(runif(n * 2), n, 2) y <- x[, 1] - x[, 2] + rnorm(n, 0, 0.2) sampler <- dbarts(y ~ x, control = dbartsControl(n.chains = 1L, n.threads = 1L)) ## prior-predictive draws of a treatment effect f(x1) - f(x0), holding the ## other covariate fixed at its midpoint: calibrates the prior before ever ## touching y. Stacking both settings into one x.test pairs the forests, so ## the two columns of the result come from the same drawn function. xContrast <- rbind(c(0, 0.5), c(1, 0.5)) colnames(xContrast) <- colnames(sampler$data@x) f <- samplePriorPredictive(sampler, x.test = xContrast, n.samples = 500L) effect <- f[, 2] - f[, 1] hist(effect, main = "prior on the treatment effect", xlab = "f(x1) - f(x0)")
Represents an unordered factor sparsely: entries at the given positions carry the supplied levels, while every other position implicitly carries a designated reference level. Analogous to Matrix::sparseVector, whose implicit entry is zero.
Accepted as a predictor by dbartsData through either interface: a data frame passed as x.train may mix dense numeric/factor columns with sparse ordinal columns (Matrix::sparseVector or dgCMatrix) and sparseFactor columns in any combination, and a formula's data accepts one too, named like any other column (including through .): a bare S4 column cannot survive model.frame, so dbartsData lifts it out of data first and re-attaches it, row-subset under subset and na.action, to the assembled predictor matrix afterward. A sparseFactor column enters as one categorical predictor and bins bitwise-identically to a dense factor of the same values.
A test frame (test, or newdata to predict) is read the way a dense-factor frame is: the model's terms are replayed on its dense columns (so a transformed term such as log(z) works and extra columns, the response included, are dropped) and its sparseFactor columns are used by name. The same holds for a test set (test/x.test): a sparseFactor test column is recoded over the training level table and stays resident - through creation and setTestPredictor - rather than densifying at ingestion. predict and getTrees(newdata = ) code it the same way and then route its rows through the trees off that storage, materializing no dense matrix of their own.
A sparseFactor (or any sparse-stored) column changes which routine makes the default starting sigma, not what it estimates: the residual standard deviation of the linear regression on the design, the factor entering as an indicator column for each level, by an exact sparse routine in place of lm's. The two agree to rounding except on nearly dependent columns; sigest = "dense" (dbarts, bart) asks for lm's.
sparseFactor(x, levels, reference, i, length)sparseFactor(x, levels, reference, i, length)
x |
The stored entries: a factor, a character vector, or integer level codes (which require an explicit |
levels |
Character vector of factor levels. Defaults to |
reference |
The level every unstored position carries. Must be an element of |
i |
Optional integer vector of 1-based positions at which the entries of |
length |
Total number of observations. Required alongside |
The constructor canonicalizes its input: entries are re-ordered by ascending position, entries whose level equals reference are dropped (they are the implicit value), and positions are stored 0-based in the i slot with 1-based level codes in the values slot. The remaining slots are levels, reference, and length.
show prints the length, the number of stored entries, the level table, and the reference level. length returns the observation count, which lets a sparseFactor be a data.frame column.
A sparseFactor answers the operations a data frame reaches a factor column with as a factor does. x[i] subsets by position (positive, negative, zero, logical and repeated indices) and returns a sparseFactor over the same levels, mapping the stored positions without densifying; drop = TRUE drops the levels no selected row takes, as does droplevels, so a vector of missing values only is left with none. An NA or out-of-range index selects a missing value. x[i] <- value and the double-bracket assignment take labels (as a character vector, factor or sparseFactor) and, as for a factor, store a missing value for NA and for a label that is not a level (with a warning), drop an NA index for a value of length one, and extend the vector past its end with missing values; length<- truncates or pads with missing values; levels(x) <- value renames the levels, the reference with them, merging repeated names as it does for a factor and dropping a level named NA, whose entries become missing. c(x, ...) combines with factors and sparseFactors over the union of their levels. as.character, as.vector and format give the level labels, as.integer the level codes, and levels (read from the class's slot), is.na, anyNA, xtfrm (so order and sort), unique, duplicated, rep, droplevels, summary, == and != (which refuse two factors with different level sets, as for factors) behave as for a factor, and str prints a factor's line. factor, as.factor and table read it through those methods, over the levels present. Together these let a data frame holding one be subset by row, assigned into, printed and str-ed. rbind of such frames returns the column as an ordinary factor; it needs R 4.6.0 or later, since earlier versions of base R's match refuse an S4 object. On any version, lengthening the first frame by row indexing, as in d[rep(seq_len(nrow(d)), 2), ], and assigning the other frames' rows into it binds them and keeps the column a sparseFactor, provided their labels are levels of the first frame's column.
A missing value is an explicit stored entry, and every method answers it as it does for a factor; show counts the missing entries, and a fit reads them as a missing predictor, bitwise as it reads the same rows of a dense factor. The one shape without a level is a vector whose every row is missing; its reference is NA. A level named NA, as addNA makes, is not supported: a missing value is not a level. A character index has no names to match and is refused. Not supported: complete.cases and na.fail on a data frame holding one, which fail in base R for any S4 column, and na.omit on such a frame, which keeps its missing rows (use d[!is.na(d$f), ]); complete.cases of a bare sparseFactor errors as well, while na.omit of one drops the missing entries as it does for a factor; a fit's na.action does handle them. Also not supported: c(f, x) with a factor f first, which c.factor answers with a list (put the sparseFactor first), rank, relevel, as.numeric (as.integer gives the level codes), rep_len and rep.int (rep works), and the exclude argument of droplevels, which is ignored; droplevels on a data frame leaves a sparseFactor column untouched, as base R touches only factor columns, so call it on the column. table drops the declared levels no row takes, where it keeps them for a factor; use levels(x) for the declared table. A data frame holding one cannot grow by assignment past its last row, since base R strips the class before the method is reached.
A Matrix::sparseVector or dgCMatrix column subsets in a data frame through Matrix's own method, but printing such a frame shows a placeholder for the column and warns of a corrupt data frame; that formatting belongs to Matrix. Use as.numeric on the column to display it.
An object of S4 class sparseFactor.
Vincent Dorie: [email protected].
f <- factor(c("a", "b", "a", "c", "a", "b")) sf <- sparseFactor(f, reference = "a") sf ## equivalently, supply only the non-reference entries and their positions sparseFactor(c("b", "c", "b"), levels = c("a", "b", "c"), reference = "a", i = c(2L, 4L, 6L), length = 6L)f <- factor(c("a", "b", "a", "c", "a", "b")) sf <- sparseFactor(f, reference = "a") sf ## equivalently, supply only the non-reference entries and their positions sparseFactor(c("b", "c", "b"), levels = c("a", "b", "c"), reference = "a", i = c(2L, 4L, 6L), length = 6L)
Reports a per-variable posterior summary of the scalar parameters
(sigma and the leaf prior's k or leaf.prior.sd) of a bartBT/bart fit, along
with split- and bulk/tail effective sample size,
computed by dbarts itself (no posterior dependency). A
heteroscedastic fit (dbarts's variance) has no
scalar residual scale and reports mean.s in place of
sigma; see vars.
bart's four own-class fits ("bartMultinomial",
"bartOrdinal", "bartNegbin", "bartHurdle"; see
bart) summarize through this same method, each exposing
the scalar posterior parameters that family carries rather than its
per-observation channels - never yhat.train itself. A chain-
separated (rather than pooled) view of these same draws is
extract, whose "sigma", "k", "leaf.prior.sd", and other
scalar types return a vector or, with combineChains = FALSE, a
chains-by-samples matrix. The table holds the parameters the fit
sampled; one line under it names each requested parameter the fit held
fixed, with its value, in the manner of summary.glm's dispersion
line. The summary of a fit of several forests adds the full block of what
each forest resolved to, after the table (see the sd argument of
forest), and the line under the table then leaves out each
forest's leaf.prior.sd, which the block gives. Under the block, each
forest with a basis has a line for the effect of one unit of its basis (for
a factor, of its second level against its first): its average over
the training rows in the likelihood, and its sd across rows, the
standard deviation of the effect across those rows, each with its posterior median and
the 5% to 95% interval stats uses. Both are computed for each draw
and the median taken last, on the scale the forests add on (the response's
units, or the probit or logit scale of a binary response), from
each forest's own fits times the coefficient on its basis, which is what
predict gives with the basis one unit higher less the basis as it
stands; a fit that kept no per-forest fits (keepFits = FALSE) says so
in one line instead. On a binary (probit or logistic), binomial or discrete-time
hazard response, a second line under each effect gives it as a probability: for
a factor the change in probability from its first level to its second, for a
numeric basis the slope of the probability per unit of the basis (as
marginaleffects::avg_slopes reports it), each an average and an sd
across rows computed per draw and row from the kept fits and averaged last,
so the average is the posterior of the mean change in probability. A 0/1
numeric basis has a slope that is not the 0 to 1 contrast, which
factor(z) as the basis gives exactly. A gaussian response has no such
line. Where the weights
are counts of identical rows (the count families' default, and gaussian with
weights.type = "frequency"), the average and the sd across rows, as
the forest line's column mean and sd, count each row at its count, as the
data written out row by row would. A binomial response, written as two
columns, counts each row at its trials times any such weight, and the
header then reads “over 371 trials (18 training rows)”.
## S3 method for class 'bart' summary(object, vars = c("sigma", "k", "leaf.prior.sd", "resid.df"), ...) ## S3 method for class 'summary.bart' print(x, ...)## S3 method for class 'bart' summary(object, vars = c("sigma", "k", "leaf.prior.sd", "resid.df"), ...) ## S3 method for class 'summary.bart' print(x, ...)
object, x
|
An object of class |
vars |
Character vector of fields to summarize. By default the leaf-scale
field follows how the leaf prior was named: On a heteroscedastic fit the For the four own-class fits, |
... |
Unused. |
An object of class summary.bart with elements call,
stats (a data frame with one row per requested sampled scalar, or
NULL if none of vars are present on the fit), vars,
and fixed, a named list of the requested parameters the fit held
fixed and their values (on a fit with several forests a vector with one
entry for each forest, k and leaf.prior.sd named by the
forests' labels), and, on a fit of
several forests that kept its fits, forests, the lines of the full block
that the print method gives after the table, and effects, where a
forest has a basis, a data frame with a row for each effect (columns
forest, label, effect, average,
average.q5, average.q95, spread, spread.q5 and
spread.q95, and, for a binary, binomial or hazard response,
probability.kind ("change" or "slope") and the same
six summaries prefixed probability., with the number of rows averaged
over and the scale as attributes "rows" and "scale") or the string "dropped"
for a fit that kept no per-forest fits. stats has columns variable, mean, median,
sd, mad, q5, q95, rhat,
ess_bulk, and ess_tail - the same columns
posterior::summarise_draws reports for a plain array, computed
without that package. Its print method shows each R-hat as a value, with
no bar and no note, and dbarts does not refuse to summarize a fit whose
chains disagree.
R-hat compares each chain's spread with the spread of the chains pooled, so
a value above 1 says the chains disagree; pooling them does not cure it. At
the defaults BART's chains routinely disagree on sigma, on k
and on a single row's prediction, so values above 1 there are expected, and
no single bar says whether a fit is usable. Averaged estimands, such as the
mean prediction over a subgroup or a contrast between two subgroups, mix far
better, so read R-hat on the estimand you report. extract with
combineChains = FALSE gives each chain's draws; the example computes
R-hat of a contrast this way, with rhat.
fit <- bart(y ~ x, data.frame(y = rnorm(100), x = rnorm(100)), n.chains = 2L, n.samples = 20L, n.burn = 20L, n.trees = 5L, n.threads = 1L, verbose = FALSE) summary(fit) # R-hat of the estimand reported: the difference between the mean prediction # for two subgroups, one value per draw and chain set.seed(1) n <- 200L x <- matrix(runif(n * 5L), n, 5L) y <- 10 * sin(pi * x[, 1L] * x[, 2L]) + 20 * (x[, 3L] - 0.5)^2 + 10 * x[, 4L] + 5 * x[, 5L] + rnorm(n) fit <- bart(x, y, n.chains = 4L, n.samples = 500L, n.burn = 100L, n.trees = 50L, n.threads = 1L, verbose = FALSE) # chains by samples by rows yhat <- dbarts::extract(fit, "ev", combineChains = FALSE) group <- x[, 1L] > 0.5 contrast <- apply(yhat[, , group, drop = FALSE], 1:2, mean) - apply(yhat[, , !group, drop = FALSE], 1:2, mean) dbarts::rhat(t(contrast)) # rhat() takes iterations by chainsfit <- bart(y ~ x, data.frame(y = rnorm(100), x = rnorm(100)), n.chains = 2L, n.samples = 20L, n.burn = 20L, n.trees = 5L, n.threads = 1L, verbose = FALSE) summary(fit) # R-hat of the estimand reported: the difference between the mean prediction # for two subgroups, one value per draw and chain set.seed(1) n <- 200L x <- matrix(runif(n * 5L), n, 5L) y <- 10 * sin(pi * x[, 1L] * x[, 2L]) + 20 * (x[, 3L] - 0.5)^2 + 10 * x[, 4L] + 5 * x[, 5L] + rnorm(n) fit <- bart(x, y, n.chains = 4L, n.samples = 500L, n.burn = 100L, n.trees = 50L, n.threads = 1L, verbose = FALSE) # chains by samples by rows yhat <- dbarts::extract(fit, "ev", combineChains = FALSE) group <- x[, 1L] > 0.5 contrast <- apply(yhat[, , group, drop = FALSE], 1:2, mean) - apply(yhat[, , !group, drop = FALSE], 1:2, mean) dbarts::rhat(t(contrast)) # rhat() takes iterations by chains
Posterior draws of the survival probability from a survival
fit: an accelerated failure time (AFT) log-normal fit produced by
bart with family = "aft",
or a discrete-time hazard fit produced by
bart with family = "hazard" (or
"hazard.logistic").
bart's four own-class fits ("bartMultinomial",
"bartOrdinal", "bartNegbin", "bartHurdle") refuse
by name instead: none of the four is a survival model, so none carries
a hazard channel.
survivalProbabilities(object, ...) ## S3 method for class 'bart' survivalProbabilities( object, times, newdata = NULL, offset = NULL, combineChains = TRUE, na.action = dbarts::na.keepPredictors, sample = c("train", "test"), bases = NULL, ... ) ## S3 method for class 'bartMultinomial' survivalProbabilities(object, ...) ## S3 method for class 'bartOrdinal' survivalProbabilities(object, ...) ## S3 method for class 'bartNegbin' survivalProbabilities(object, ...) ## S3 method for class 'bartHurdle' survivalProbabilities(object, ...)survivalProbabilities(object, ...) ## S3 method for class 'bart' survivalProbabilities( object, times, newdata = NULL, offset = NULL, combineChains = TRUE, na.action = dbarts::na.keepPredictors, sample = c("train", "test"), bases = NULL, ... ) ## S3 method for class 'bartMultinomial' survivalProbabilities(object, ...) ## S3 method for class 'bartOrdinal' survivalProbabilities(object, ...) ## S3 method for class 'bartNegbin' survivalProbabilities(object, ...) ## S3 method for class 'bartHurdle' survivalProbabilities(object, ...)
object |
A fitted |
times |
A numeric vector of times (on the original, non-logarithmic scale) at
which to evaluate the survival function. For a discrete-time hazard fit the
times are horizons on the period grid, and the default (when |
newdata |
Optional predictors at which to evaluate. When |
offset |
The offset at the subjects of |
combineChains |
A logical determining whether the chain dimension is collapsed into the draw dimension, as elsewhere in the package. |
na.action |
What to do with the subjects in |
sample |
Either |
bases |
For a fit of several forests with a basis, the basis at the subjects, as
|
... |
Not a formal on the method: a name belonging to a sibling generic
( |
Under the log-normal AFT model with
, the survival function is
where is the linear predictor - the
log-time-scale quantity that predict and
extract return for an "aft" fit, the
offset included - and
the residual standard deviation. The probability is evaluated
at every posterior draw of and , following the
package's convention that draw-level functions return draws: take means or
quantiles over the draw margin for point estimates and credible bands.
For a discrete-time hazard fit, the survival function is the cumulative product
where is the per-period hazard through the
fit's binary link and the subject's offset: the fit's own on
the training subjects, and on newdata the one formed from
offset as above. Because the training design is ragged (each
subject carries only its at-risk rows), the method ALWAYS re-expands its
subjects onto the full grid and replays the trees - so it requires
keepTrees = TRUE even for the training data (newdata = NULL).
With newdata, each new subject is expanded to one row per period and
its curve evaluated the same way. The one exception: a test set that
rode the fit call (the matrix interface's own hazard test
acceptance) was already person-period-expanded on the SAME training grid
at fit time, so its hazards are stored on the fit already -
sample = "test" on such a fit reads them directly with no
re-expansion and no trees needed. The call with no newdata is the
training subjects whether or not the fit carries a test set.
An array of survival probabilities. With combineChains = TRUE the
dimensions are draws times observations; with
combineChains = FALSE a chain dimension precedes them (chains
draws times observations), length
1 on a one-chain fit rather than dropped, as extract and
predict keep theirs. Observations are those of newdata, or
the training data when newdata is NULL, or with
sample = "test" the test set.
Vincent Dorie: [email protected].
set.seed(42) n <- 100L x <- matrix(runif(n * 2L), n, 2L) eventTime <- exp(x[, 1L] + 0.5 * rnorm(n)) censorTime <- exp(x[, 1L] + 0.25 + 0.5 * rnorm(n)) status <- as.numeric(eventTime <= censorTime) observedTime <- pmin(eventTime, censorTime) fit <- bart( x, cbind(observedTime, status), family = "aft", n.trees = 25L, n.burn = 50L, n.samples = 100L, n.chains = 1L, verbose = FALSE ) surv <- survivalProbabilities(fit, times = c(0.5, 1, 2)) dim(surv) # draws x times x observations ## posterior-mean survival curve and 90% band for the first observation apply(surv[, , 1L], 2L, mean) apply(surv[, , 1L], 2L, quantile, probs = c(0.05, 0.95))set.seed(42) n <- 100L x <- matrix(runif(n * 2L), n, 2L) eventTime <- exp(x[, 1L] + 0.5 * rnorm(n)) censorTime <- exp(x[, 1L] + 0.25 + 0.5 * rnorm(n)) status <- as.numeric(eventTime <= censorTime) observedTime <- pmin(eventTime, censorTime) fit <- bart( x, cbind(observedTime, status), family = "aft", n.trees = 25L, n.burn = 50L, n.samples = 100L, n.chains = 1L, verbose = FALSE ) surv <- survivalProbabilities(fit, times = c(0.5, 1, 2)) dim(surv) # draws x times x observations ## posterior-mean survival curve and 90% band for the first observation apply(surv[, , 1L], 2L, mean) apply(surv[, , 1L], 2L, quantile, probs = c(0.05, 0.95))
Applies a “partial” (per-observation) update of a single shared column to several
dbartsSampler objects at once, installing an observation's new value only when
it keeps every leaf node non-empty in every tree of every sampler.
updatePredictorPerObservationJointly(samplers, x, column, updateState = NULL)updatePredictorPerObservationJointly(samplers, x, column, updateState = NULL)
samplers |
A |
x |
The new values for the shared column, one per observation. For a numeric column, numbers; a
factor, or text that is not numerals, is refused for it. For a column the samplers hold as a
factor or an ordered factor, its labels: a factor, a character vector or a |
column |
A single integer or character string identifying the shared column; it cannot be missing. The column is matched by name across all samplers, so the shared variable may sit at different column positions in each. When given as an integer, it indexes the columns of the first sampler and the corresponding name is used to locate the column in the rest. |
updateState |
A logical determining if the local cache of each sampler's state should be updated after the
update completes. If |
This is the multi-sampler analog of the forceUpdate = "partial" mode of
setPredictor. A single sequential sweep installs each
observation in every sampler at once, and only if its new value keeps every leaf non-empty in every
tree of every forest of every chain of every sampler; otherwise that observation is rolled back to
its previous value in all of them. Under a monotone constraint a row that brings an
unordered factor column its first missing value is declined, in every sampler, where the sides drawn
for the column's rules would leave a tree's leaf values out of order in any of them; a numeric
column's first missing value breaks no order. A hazard fit's period column, its expansion of each
subject's time at risk, set with the response, is taken only unchanged, and refused otherwise before
anything moves; setData replaces it.
Any of the samplers may itself carry more than one forest - a
Bayesian causal forest, a multinomial sampler, or a heteroscedastic (variance) sampler - and
each of its forests is checked on the same terms as an ordinary single-forest sampler's mean forest
(see ‘Multi-forest and heteroscedastic predictor mutation’ in
dbartsSampler). Like the single-sampler partial mode, the update
never changes tree structure – it only re-routes observations.
This supports embedding several BART components that condition on a common latent predictor (for example, a shared ability or trait in an item-response model) within a larger Gibbs/Metropolis sampler.
A whole-matrix setPredictor call on one of the samplers, made earlier in the same script,
keeps that sampler's column names (see ‘Multi-forest and heteroscedastic predictor
mutation’, dbartsSampler), so this function's by-name
column matching continues to resolve against it afterward.
A logical vector of length equal to the number of observations, TRUE where the observation's
new value was installed and FALSE where it was rolled back to keep every tree valid. The
same accept/reject decision is applied to every sampler, so an installed observation takes the new
value in all of them; a rejected observation reverts to each sampler's own previous value. When the
samplers agreed on the shared column before the call, they therefore continue to agree afterward.
## two BART components conditioning on a common latent predictor 'theta', ## as an item-response model would: both must accept an observation's new ## value, or neither does set.seed(5) n <- 80L theta <- rnorm(n) w <- runif(n) df1 <- data.frame(theta = theta, w = w) df1$y <- theta + rnorm(n, 0, 0.2) df2 <- data.frame(v = runif(n), theta = theta) df2$y <- 0.5 * theta + rnorm(n, 0, 0.2) control <- dbartsControl(n.chains = 1L, n.threads = 1L, n.burn = 0L, n.samples = 1L, updateState = FALSE) s1 <- dbarts(y ~ theta + w, df1, control = control, n.trees = 25L) s2 <- dbarts(y ~ v + theta, df2, control = control, n.trees = 25L) invisible(s1$run()) invisible(s2$run()) ## 'theta' sits in a different column of each sampler; it is matched by name proposal <- theta + rnorm(n, 0, 0.1) installed <- updatePredictorPerObservationJointly( list(s1, s2), proposal, column = "theta") table(installed)## two BART components conditioning on a common latent predictor 'theta', ## as an item-response model would: both must accept an observation's new ## value, or neither does set.seed(5) n <- 80L theta <- rnorm(n) w <- runif(n) df1 <- data.frame(theta = theta, w = w) df1$y <- theta + rnorm(n, 0, 0.2) df2 <- data.frame(v = runif(n), theta = theta) df2$y <- 0.5 * theta + rnorm(n, 0, 0.2) control <- dbartsControl(n.chains = 1L, n.threads = 1L, n.burn = 0L, n.samples = 1L, updateState = FALSE) s1 <- dbarts(y ~ theta + w, df1, control = control, n.trees = 25L) s2 <- dbarts(y ~ v + theta, df2, control = control, n.trees = 25L) invisible(s1$run()) invisible(s2$run()) ## 'theta' sits in a different column of each sampler; it is matched by name proposal <- theta + rnorm(n, 0, 0.1) installed <- updatePredictorPerObservationJointly( list(s1, s2), proposal, column = "theta") table(installed)
Build the specification of the heteroscedastic variance forest (HBART;
Pratola, Chipman, George, and McCulloch 2020). Pass the result as the
variance argument of dbarts, dbartsSpec,
or bart - the same argument that already accepts the plain
selector (NULL/FALSE for none, TRUE/a one-sided
formula/a character or integer column selector for the predictors driving
the variance). This constructor is the other accepted type of that one
argument, adding the variance forest's own tree count and structure prior
alongside the column selection.
The constructor is not exported: it resolves by bare name inside the
arguments that take it, and elsewhere is written
dbartsForests$varianceForest(...); see dbartsForests.
varianceForest( vars = NULL, n.trees = NULL, base = NULL, power = NULL, proposal.probs = NULL, n.perturb.cuts = NULL)varianceForest( vars = NULL, n.trees = NULL, base = NULL, power = NULL, proposal.probs = NULL, n.perturb.cuts = NULL)
vars |
Which predictors drive the variance surface, written as
|
n.trees |
The number of variance trees. |
base, power
|
The variance forest's tree-structure prior. |
proposal.probs, n.perturb.cuts
|
The variance forest's proposal mixture and perturb window, as
|
A second ensemble models the residual variance surface as a
product of scaled-inverse-chi-squared (multiplicative) leaves, so
, coupled to the mean forest through
the per-observation precision. Gaussian and "aft" (survival)
responses and constant leaves only - the latent families route their own
precisions through the same channel; monotone constraints are not supported.
Under "aft" the surface is the dispersion of log survival time, and
a right-censored observation's latent log-time is redrawn at its own
. Every value is validated when a sampler is built.
A dbartsVarianceForest specification object, resolved when a
sampler is built.
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.
dbartsForests,
dbarts, dbartsSpec, bart
set.seed(0) n <- 200L x <- matrix(runif(n * 2), n, 2, dimnames = list(NULL, c("x1", "x2"))) s <- ifelse(x[, 1] > 0.5, 0.3, 1.2) y <- 2 * x[, 1] + s * rnorm(n) ## every predictor drives the variance, 20 variance trees fit <- bart(x, y, variance = varianceForest(n.trees = 20L), n.trees = 25L, n.samples = 20L, n.burn = 20L, n.chains = 1L, verbose = FALSE) ## restricted to x1, with its own tree-structure prior fit.restricted <- bart(x, y, variance = varianceForest(vars = ~x1, n.trees = 20L, base = 0.9, power = 1.5), n.trees = 25L, n.samples = 20L, n.burn = 20L, n.chains = 1L, verbose = FALSE) dbartsForests$varianceForest(vars = ~x1, n.trees = 20L, base = 0.9, power = 1.5)set.seed(0) n <- 200L x <- matrix(runif(n * 2), n, 2, dimnames = list(NULL, c("x1", "x2"))) s <- ifelse(x[, 1] > 0.5, 0.3, 1.2) y <- 2 * x[, 1] + s * rnorm(n) ## every predictor drives the variance, 20 variance trees fit <- bart(x, y, variance = varianceForest(n.trees = 20L), n.trees = 25L, n.samples = 20L, n.burn = 20L, n.chains = 1L, verbose = FALSE) ## restricted to x1, with its own tree-structure prior fit.restricted <- bart(x, y, variance = varianceForest(vars = ~x1, n.trees = 20L, base = 0.9, power = 1.5), n.trees = 25L, n.samples = 20L, n.burn = 20L, n.chains = 1L, verbose = FALSE) dbartsForests$varianceForest(vars = ~x1, n.trees = 20L, base = 0.9, power = 1.5)
Fits the BART model against varying k (or sd), power, base, and n.trees parameters using -fold or repeated random subsampling crossvalidation, sharing burn-in between parameter settings. Results are returned as an array of evaluations of a loss function on the held-out sets.
xbart( formula, data, subset, weights, offset, verbose = FALSE, n.samples = 200L, method = c("k-fold", "random subsample"), n.test = c(5, 0.2), n.reps = 40L, n.burn = c(200L, 150L), loss = c("rmse", "log", "mcr"), n.threads = dbarts::guessNumCores(), n.trees = 75L, k = NULL, sd = NULL, power = 2, base = 0.95, split.probs = NULL, drop = TRUE, sigest = NULL, seed = NULL, factors = c("categorical", "indicators"), family = c("auto", "gaussian", "probit", "logistic"), weights.type = NULL, leaf.prior = NULL, n.cuts = 100L, useQuantiles = FALSE, n.thin = 1L, storage = c("double", "single"), parallel = getOption("dbarts.parallel", "auto"), cl = NULL, control = dbarts::dbartsControl(), sigma = NULL, ...)xbart( formula, data, subset, weights, offset, verbose = FALSE, n.samples = 200L, method = c("k-fold", "random subsample"), n.test = c(5, 0.2), n.reps = 40L, n.burn = c(200L, 150L), loss = c("rmse", "log", "mcr"), n.threads = dbarts::guessNumCores(), n.trees = 75L, k = NULL, sd = NULL, power = 2, base = 0.95, split.probs = NULL, drop = TRUE, sigest = NULL, seed = NULL, factors = c("categorical", "indicators"), family = c("auto", "gaussian", "probit", "logistic"), weights.type = NULL, leaf.prior = NULL, n.cuts = 100L, useQuantiles = FALSE, n.thin = 1L, storage = c("double", "single"), parallel = getOption("dbarts.parallel", "auto"), cl = NULL, control = dbarts::dbartsControl(), sigma = NULL, ...)
sigma |
The 0.9-x spelling of |
... |
Not used for new code: the channel that lets a retired argument spelling ( |
control |
A |
formula |
An object of class |
data |
An optional data frame, list, or environment containing predictors to be used with the model. For backwards compatibility, can also be the |
subset |
An optional vector specifying a subset of observations to be used in the fitting process. |
weights |
An optional vector of weights to be used in the fitting process. For a gaussian response, BART fits a model with observations |
offset |
An optional vector specifying an offset from 0 for the relationship between the underlying function, |
verbose |
A logical determining if additional output is printed to the console, including the one-line message |
n.samples |
A positive integer, setting the number of posterior samples drawn for each fit of training data and used by the loss function. |
method |
Character string, either |
n.test |
For each fit, the test sample size or proportion. For method |
n.reps |
A positive integer setting the number of cross validation steps that will be taken. For |
n.burn |
Unlike the single-scalar |
loss |
Either one of the pre-set loss functions as character-strings (the default is |
n.threads |
Every (replication, fold) pair is an independent unit of work, and for |
parallel |
One of |
cl |
|
n.trees |
A vector of positive integers setting the BART hyperparameter for the number of trees in the sum-of-trees formulation. See |
k |
The grid for the BART hyperparameter setting the leaf-mean prior standard deviation: a vector of positive real numbers, each a cell of its own, or a |
sd |
The same grid axis stated in absolute spreads instead, exclusive with |
power |
A vector of positive real numbers, setting the BART hyperparameter for the tree prior's growth probability, given by |
base |
A vector of real numbers in |
split.probs |
Prior probabilities that a variable is used in a splitting rule, as in |
drop |
Logical, determining if dimensions with a single value are dropped from the result. |
sigest |
A positive numeric estimate of the residual standard deviation; one of |
seed |
Optional integer specifying the desired pRNG seed. |
factors |
How factor columns in a data frame enter the model; as in |
family |
The response model, resolved as in |
weights.type |
How |
leaf.prior |
An optional expression of the form A named |
n.cuts |
The number of decision rules used for each predictor, as |
useQuantiles |
Logical; as in |
n.thin |
A positive integer; as in |
storage |
A character string selecting the precision of the internal running residual, spelled and defaulted as in |
A fit in which every predictor holds one value on the rows kept, with no forest having a basis, is refused, naming the columns, as by bart.
Crossvalidates n.reps replications against the crossproduct of given hyperparameter vectors n.trees k power base. For each fit, either one fold is withheld as test data and n.test - 1 folds are used as training data or n * n.test observations are withheld as test data and n * (1 - n.test) used as training. A replication corresponds to fitting all folds in "k-fold" crossvalidation or a single fit with "random subsample". The training data is used to fit a model and make predictions on the test data which are used together with the test data itself to evaluate the loss function.
loss functions are either the default of average negative log-loss for binary outcomes and root-mean-squared error for continuous outcomes, misclassification rates for binary outcomes, or a function with arguments y.test, y.test.hat and weights. y.test.hat is of dimensions equal to length(y.test) n.samples, on the latent scale for binary outcomes. For a binary outcome the built-in "rmse" compares the response with the posterior mean probability (the link applied to each draw, then averaged), as "log" and "mcr" do, while a supplied function receives the latent draws. A third option is to pass a list of list(function, evaluationEnvironment), so as to provide default bindings. The binary losses "log" and "mcr" cannot apply to continuous responses. On a binomial response a row is read as its trials: y.test is its observed proportion (0 at a row of no trials), weights are its trials times its weight, and the built-in losses read each row so weighted, "log" as and "mcr" as the share of the row's trials on the wrong side of 0.5, which is what both losses give on the rows written out one trial each; "rmse" compares the proportion with the probability, a row weighted by its trials, and on the rows written out would add a term that depends on the data alone. A supplied function receives the same y.test and weights, and the latent draws.
An array with up to six dimensions, in order rep (length n.reps), n.trees, k (or sd), power, base, and loss. rep is always present. n.trees, k, power, and base are each omitted when drop is TRUE and the corresponding grid has length 1; with drop = FALSE they are always present, an absent k included, whose single cell is then named for the default it ran at. The trailing loss dimension, sized to however many values a single call to loss returns, is present only when that count is greater than one - independent of drop entirely; the default losses and an ordinary scalar-returning custom loss never contribute it. When none of the above survive, the result collapses to a plain vector of length n.reps. When the result remains an array, its dimnames name the swept values on each surviving hyperparameter axis - exact integer labels for n.trees, values rounded to 2 significant digits for the double-valued k/power/base axes, and the constructor call for a modeled k cell; the loss axis, when present, carries no per-slot names, and neither does rep.
For method "k-fold", each element is an average across the fits. For "random subsample", each element represents a single fit.
The result is a bare array with no class, so the fit generics - predict, extract, fitted, residuals - do not apply to it; it is a table of losses, not a fit.
Vincent Dorie: [email protected]
f <- function(x) { 10 * sin(pi * x[,1] * x[,2]) + 20 * (x[,3] - 0.5)^2 + 10 * x[,4] + 5 * x[,5] } set.seed(99) sigma <- 1.0 n <- 100 x <- matrix(runif(n * 10), n, 10) Ey <- f(x) y <- rnorm(n, Ey, sigma) mad <- function(y.test, y.test.hat, weights) { # note, weights are ignored mean(abs(y.test - apply(y.test.hat, 1L, mean))) } ## low iteration numbers to to run quickly xval <- xbart(x, y, n.samples = 15L, n.reps = 4L, n.burn = c(10L, 3L), n.trees = c(5L, 7L), k = c(1, 2, 4), power = c(1.5, 2), base = c(0.75, 0.8, 0.95), n.threads = 1L, loss = mad)f <- function(x) { 10 * sin(pi * x[,1] * x[,2]) + 20 * (x[,3] - 0.5)^2 + 10 * x[,4] + 5 * x[,5] } set.seed(99) sigma <- 1.0 n <- 100 x <- matrix(runif(n * 10), n, 10) Ey <- f(x) y <- rnorm(n, Ey, sigma) mad <- function(y.test, y.test.hat, weights) { # note, weights are ignored mean(abs(y.test - apply(y.test.hat, 1L, mean))) } ## low iteration numbers to to run quickly xval <- xbart(x, y, n.samples = 15L, n.reps = 4L, n.burn = c(10L, 3L), n.trees = c(5L, 7L), k = c(1, 2, 4), power = c(1.5, 2), base = c(0.75, 0.8, 0.95), n.threads = 1L, loss = mad)