R: Class "dbartsSampler" of Discrete Bayesian Additive...

dbartsSampler-class {dbarts} | 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 = list(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 an entirely matrix of new 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 substitude.
`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 list containing the number 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 `load`ing 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.

[Package dbarts version 0.9-20 Index]