Learn R Programming

brms (version 2.12.0)

extract_draws.brmsfit: Extract Data and Posterior Draws

Description

This method helps in preparing brms models for certin post-processing tasks most notably various forms of predictions. Unless you are a package developer, you will rarely need to call extract_draws directly.

Usage

# S3 method for brmsfit
extract_draws(
  x,
  newdata = NULL,
  re_formula = NULL,
  allow_new_levels = FALSE,
  sample_new_levels = "uncertainty",
  incl_autocor = TRUE,
  oos = NULL,
  resp = NULL,
  nsamples = NULL,
  subset = NULL,
  nug = NULL,
  smooths_only = FALSE,
  offset = TRUE,
  newdata2 = NULL,
  new_objects = NULL,
  point = NULL,
  ...
)

extract_draws(x, ...)

Arguments

x

An R object typically of class 'brmsfit'.

newdata

An optional data.frame for which to evaluate predictions. If NULL (default), the original data of the model is used. NA values within factors are interpreted as if all dummy variables of this factor are zero. This allows, for instance, to make predictions of the grand mean when using sum coding.

re_formula

formula containing group-level effects to be considered in the prediction. If NULL (default), include all group-level effects; if NA, include no group-level effects.

allow_new_levels

A flag indicating if new levels of group-level effects are allowed (defaults to FALSE). Only relevant if newdata is provided.

sample_new_levels

Indicates how to sample new levels for grouping factors specified in re_formula. This argument is only relevant if newdata is provided and allow_new_levels is set to TRUE. If "uncertainty" (default), include group-level uncertainty in the predictions based on the variation of the existing levels. If "gaussian", sample new levels from the (multivariate) normal distribution implied by the group-level standard deviations and correlations. This options may be useful for conducting Bayesian power analysis. If "old_levels", directly sample new levels from the existing levels.

incl_autocor

A flag indicating if correlation structures originally specified via autocor should be included in the predictions. Defaults to TRUE.

oos

Optional indices of observations for which to compute out-of-sample rather than in-sample predictions. Only required in models that make use of response values to make predictions, that is currently only ARMA models.

resp

Optional names of response variables. If specified, predictions are performed only for the specified response variables.

nsamples

Positive integer indicating how many posterior samples should be used. If NULL (the default) all samples are used. Ignored if subset is not NULL.

subset

A numeric vector specifying the posterior samples to be used. If NULL (the default), all samples are used.

nug

Small positive number for Gaussian process terms only. For numerical reasons, the covariance matrix of a Gaussian process might not be positive definite. Adding a very small number to the matrix's diagonal often solves this problem. If NULL (the default), nug is chosen internally.

smooths_only

Logical; If TRUE only draws related to the computation of smooth terms will be extracted.

offset

Logical; Indicates if offsets should be included in the predictions. Defaults to TRUE.

newdata2

A named list of objects containing new data, which cannot be passed via argument newdata. Required for some objects used in autocorrelation structures, or stanvars.

new_objects

Deprecated alias of newdata2.

point

Shall the returned object contain only point estimates of the parameters instead of their posterior samples? Defaults to NULL in which case no point estimate is computed. Alternatively, may be set to "mean" or "median". This argument is primarily implemented to ensure compatibility with the loo_subsample method.

...

Further arguments passed to validate_newdata.

Value

An object of class 'brmsdraws' or 'mvbrmsdraws', depending on whether a univariate or multivariate model is passed.