dbartsSampler-class: Class "dbartsSampler" of Discrete Bayesian Additive...
In vdorie/dbarts: Discrete Bayesian Additive Regression Trees Sampler

dbartsSampler-class

R Documentation

Class "dbartsSampler" of Discrete Bayesian Additive Regression Trees Sampler

Description

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.

Usage

## S4 method for signature 'dbartsSampler'
run(numBurnIn, numSamples, updateState = NA)
## S4 method for signature 'dbartsSampler'
sampleTreesFromPrior(updateState = NA)
## S4 method for signature 'dbartsSampler'
sampleNodeParametersFromPrior(updateState = NA)
## S4 method for signature 'dbartsSampler'
copy(shallow = FALSE)
## S4 method for signature 'dbartsSampler'
show()
## S4 method for signature 'dbartsSampler'
predict(x.test, offset.test)
## S4 method for signature 'dbartsSampler'
setControl(control)
## S4 method for signature 'dbartsSampler'
setModel(model)
## S4 method for signature 'dbartsSampler'
setData(data)
## S4 method for signature 'dbartsSampler'
setResponse(y, updateState = NA)
## S4 method for signature 'dbartsSampler'
setOffset(offset, updateScale = FALSE, updateState = NA)
## S4 method for signature 'dbartsSampler'
setSigma(sigma, updateState = NA)
## S4 method for signature 'dbartsSampler'
setPredictor(x, column, updateState = NA)
## S4 method for signature 'dbartsSampler'
setTestPredictor(x.test, column, updateState = NA)
## S4 method for signature 'dbartsSampler'
setTestPredictorAndOffset(x.test, offset.test, updateState = NA)
## S4 method for signature 'dbartsSampler'
setTestOffset(offset.test, updateState = NA)
## S4 method for signature 'dbartsSampler'
printTrees(treeNums)
## S4 method for signature 'dbartsSampler'
plotTree(
    treeNum, treePlotPars = c(
        nodeHeight = 12, nodeWidth = 40, nodeGap = 8),
    ...)

Arguments

`numBurnIn`	A non-negative integer determining how many iterations the sampler should skip before storing results. If missing or `NA`, the default is filled in from the sampler's `control` object.
`numSamples`	A positive integer determining how many posterior samples should be returned. If missing or `NA`, the default is also filled in from the control object.
`updateState`	A logical determining if the local cache of the sampler's state should be updated after the completion of the run. If `NA`, the default is also filled in from the control object.
`shallow`	A logical determining if the copy should retain the underlying data of the sampler (`TRUE`) or have its own copies (`FALSE`).
`control`	An object inheriting from `dbartsControl`.
`model`	An object inheriting from `dbartsModel`.
`data`	An object inheriting from `dbartsData`.
`y`	A numeric response vector of length equal to that with which the sampler was created.
`x`	A numeric predictor vector of length equal to that with which the sampler was created. Can be of a distinct number of rows for `setTestPredictor`.
`x.test`	A new matrix of test predictors, of the number of columns equal to that in the current model.
`offset`	A numeric vector of length equal to that with which the sampler was created, or `NULL`. If `offset.test` was set from `offset`, will attempt to update that as well.
`updateScale`	Logical indicating whether BART's internal scale should update with the new offset. Should only be `TRUE` during burn-in.
`offset.test`	A numeric vector of length equal to that of the test matrix, or `NULL`. Can be missing for `setTestPredictors`.
`sigma`	Numeric vector of residual standard deviations, one for each chain.
`column`	An integer or character string vector specifying which column/columns of the predictor matrix is to be replaced. If missing, the entire matrix is substituted.
`treeNums`	An integer vector listing the indices of the trees to print.
`treeNum`	An integer listing the indices of the tree to plot.
`treePlotPars`	A named numeric vector containing the quantities `nodeHeight`, `nodeWidth`, and `nodeGap`, all of which control aspects of the resulting plot.
`...`	Extra arguments to `plot`.

Details

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.

Saving

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 do this, one must “touch” the sampler's state object before saving, e.g. for the object sampler, execute invisible(sampler$state). This is in addition to guaranteeing that the state object is not NULL, which can be done by setting the sampler's control to an object with updateState as TRUE or passing TRUE as the updateState argument to any of the sampler's applicable methods.

Value

For run, a named-list with contents sigma, train, test, and varcount.

For setPredictor, TRUE/FALSE depending on whether or not the operation was successful. The operation can fail if the new predictor results in a tree with an empty leaf-node. If only single columns were replaced, on the update is rolled-back so that the sampler remains in a valid state.

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.