Discrete Bayesian Additive Regression Tree sampler

This learner implements BART algorithm in C++, using the dbarts package. BART is a Bayesian sum-of-trees model in which each tree is constrained by a prior to be a weak learner.

Format

R6Class object.

Value

Learner object with methods for training and prediction. See Lrnr_base for documentation on learners.

Parameters

x.test: Explanatory variables for test (out of sample) data. bart will generate draws of \(f(x)\) for each \(x\) which is a row of x.test.
sigest: For continuous response models, an estimate of the error variance, \(\sigma^2\), used to calibrate an inverse-chi-squared prior used on that parameter. If not supplied, the least-squares estimate is derived instead. See sigquant for more information. Not applicable when \(y\) is binary.
sigdf: Degrees of freedom for error variance prior. Not applicable when \(y\) is binary.
sigquant: The quantile of the error variance prior that the rough estimate (sigest) is placed at. The closer the quantile is to 1, the more aggresive the fit will be as you are putting more prior weight on error standard deviations (\(\sigma\)) less than the rough estimate. Not applicable when \(y\) is binary.
k: For numeric \(y\), k is the number of prior standard deviations \(E(Y|x) = f(x)\) is away from \(\pm 0.5\). The response (y.train) is internally scaled to range from \(-0.5\) to \(0.5\). For binary \(y\), k is the number of prior standard deviations \(f(x)\) is away from \(\pm 3\). In both cases, the bigger \(k\) is, the more conservative the fitting will be.
power: Power parameter for tree prior.
base: Base parameter for tree prior.
binaryOffset: sed for binary \(y\). When present, the model is \(P(Y = 1 \mid x) = \Phi(f(x) + \mathrm{binaryOffset})\), allowing fits with probabilities shrunk towards values other than \(0.5\).
weights: An optional vector of weights to be used in the fitting process. When present, BART fits a model with observations \(y \mid x \sim N(f(x), \sigma^2 / w)\), where \(f(x)\) is the unknown function.
ntree: The number of trees in the sum-of-trees formulation.
ndpost: The number of posterior draws after burn in, ndpost / keepevery will actually be returned.
nskip: Number of MCMC iterations to be treated as burn in.
printevery: As the MCMC runs, a message is printed every printevery draws.
keepevery: Every keepevery draw is kept to be returned to the user. Useful for “thinning” samples.
keeptrainfits: If TRUE the draws of \(f(x)\) for \(x\) corresponding to the rows of x.train are returned.
usequants: When TRUE, determine tree decision rules using estimated quantiles derived from the x.train variables. When FALSE, splits are determined using values equally spaced across the range of a variable. See details for more information.
numcut: The maximum number of possible values used in decision rules (see usequants, details). If a single number, it is recycled for all variables; otherwise must be a vector of length equal to ncol(x.train). Fewer rules may be used if a covariate lacks enough unique values.
printcutoffs: The number of cutoff rules to printed to screen before the MCMC is run. Given a single integer, the same value will be used for all variables. If 0, nothing is printed.
verbose: Logical; if FALSE supress printing.
nchain: Integer specifying how many independent tree sets and fits should be calculated.
nthread: Integer specifying how many threads to use. Depending on the CPU architecture, using more than the number of chains can degrade performance for small/medium data sets. As such some calculations may be executed single threaded regardless.
combinechains: Logical; if TRUE, samples will be returned in arrays of dimensions equal to nchain \(\times\) ndpost \(\times\) number of observations.
keeptrees: Logical; must be TRUE in order to use predict with the result of a bart fit.
keepcall: Logical; if FALSE, returned object will have call set to call("NULL"), otherwise the call used to instantiate BART.
serializeable: Logical; if TRUE, loads the trees into R memory so the fit object can be saved and loaded. See the section on "Saving" in bart NB: This is not currently working

Common Parameters

Individual learners have their own sets of parameters. Below is a list of shared parameters, implemented by Lrnr_base, and shared by all learners.

covariates: A character vector of covariates. The learner will use this to subset the covariates for any specified task
outcome_type: A variable_type object used to control the outcome_type used by the learner. Overrides the task outcome_type if specified
...: All other parameters should be handled by the invidual learner classes. See the documentation for the learner class you're instantiating

Examples

set.seed(123)

# load example data
data(cpp_imputed)
covs <- c("apgar1", "apgar5", "parity", "gagebrth", "mage", "meducyrs")

# create sl3 task
task <- sl3_Task$new(cpp_imputed, covariates = covs, outcome = "haz")
dbart_learner <- make_learner(Lrnr_dbarts, ndpost = 200)

# train dbart learner and make predictions
dbart_fit <- dbart_learner$train(task)
preds <- dbart_fit$predict()