stan4bart-generics {stan4bart}

Generic Functions for stan4bart Model Fits

Description

Commonly expected utility functions to derive useful quantities from fitted models.

Usage

## S3 method for class 'stan4bartFit'
extract(
  object,
  type = c("ev", "ppd", "fixef", "indiv.fixef", "ranef", "indiv.ranef",
           "indiv.bart", "sigma", "Sigma", "k", "varcount", "stan",
           "trees", "callback"),
  sample = c("train", "test"),
  combine_chains = TRUE,
  sample_new_levels = TRUE,
  include_warmup = FALSE,
  ...)
  
## S3 method for class 'stan4bartFit'
fitted(
  object,
  type = c("ev", "ppd", "fixef", "indiv.fixef", "ranef", "indiv.ranef",
           "indiv.bart", "sigma", "Sigma", "k", "varcount", "stan",
           "callback"),
  sample = c("train", "test"),
  sample_new_levels = TRUE,
  ...)

## S3 method for class 'stan4bartFit'
predict(
  object, newdata, offset,
  type = c("ev", "ppd", "indiv.fixef", "indiv.ranef", "indiv.bart"),
  combine_chains = TRUE,
  sample_new_levels = TRUE,
  ...)

Arguments

object

a fitted model resulting from a call to stan4bart.

type

a character vector; one of the options listed below.

sample

one of "train" or "test", indicating if the training or test data frames should be used.

combine_chains

logical controlling if chain information should be discarded and the result returned as a matrix instead of an array.

sample_new_levels

logical; if TRUE, levels out of the training sample will have random effects drawn from their posterior predictive distribution. If FALSE, their random effects will be fixed to 0.

include_warmup

logical or "only"; when TRUE/FALSE, warmup samples will or will not be included in the result respectively. When "only", only the warmup samples will be returned.

newdata

data frame for making out of sample predictions.

offset

optional vector which will be added to test predictors.

...

not currently in use, but provided to match signatures of other generics.

Details

extract is used to obtain raw samples using the training or test data, fitted averages those samples, and predict operates on data not available at the time of fitting. Note: predict requires that the model be fit with args_bart = list(keepTrees = TRUE).

Return type

The type argument accepts:

• "ev" - the individual level expected value, that is draws from E[Y \mid X^b, X^f, Z] \mid Y = f(X^b) + X^f\beta + Zb \mid Y where the expectation is with respect to the posterior distribution of the parameters given the data

• "ppd" - draws from the individual level posterior predictive distribution, generally speaking adding noise to the result for "ev" or simulating new Bernoulli trials.

• "fixef" - draws from the posterior of the fixed effects (also known as the “unmodeled” coefficients), \beta \mid Y

• "indiv.fixef" - draws from the posterior distribution of the individual level mean component deriving from the fixed effects, X^f\beta

• "ranef" - the random effects, varying intercepts and slopes, or “modeled” coefficients, b; b has substantial structure that is represented as the returned value, where coefficients are reported within their grouping factors

• "indiv.ranef" - individual level mean component deriving from the random effects, Zb

• "indiv.bart" - individual level mean component deriving from the BART model, f(X^b)

• "sigma" - for continuous responses, the residual standard error

• "Sigma" - when applicable, the covariance matrices of the random effects

• "stan" - raw matrix or array of Stan sampled transformed parameters.

• "trees" - a data frame of flatted trees; see the subsection on extracted trees in bart and note that stan4bart variable names can be found in the bartData@x element of a fitted stan4bart model

• "callback" - if a callback function was provided while fitting, the results of that for each sample

Value

extract and predict return either arrays of dimensions equal to n.observations x n.samples x n.chains when combine_chains is FALSE, or matrices of dimensions equal to n.observations x (n.samples * n.chains) when combine_chains is TRUE.

fitted returns a vector of the appropriate length by averaging the result of a call to extract.

Author(s)

Vincent Dorie: [e-mail].