Run Stan's variational algorithm for approximate posterior sampling

Approximately draw from a posterior distribution using variational inference.

This is still considered an experimental feature. We recommend calling stan or sampling for final inferences and only using vb to get a rough idea of the parameter distributions.

<!-- %% vb(object, \dots)   -->
  # S4 method for stanmodel
vb(object, data = list(), pars = NA, include = TRUE,
    seed = sample.int(.Machine$integer.max, 1), 
    init = 'random', check_data = TRUE, 
    sample_file = tempfile(fileext = '.csv'),
    algorithm = c("meanfield", "fullrank"), 
    importance_resampling = FALSE, keep_every = 1,
    ...)

Methods

vb

signature(object = "stanmodel")

Call Stan's variational Bayes methods for the model defined by S4 class stanmodel given the data, initial values, etc.

Arguments

object

An object of class stanmodel.

data

A named list or environment providing the data for the model or a character vector for all the names of objects used as data. See the Passing data to Stan section in stan.

pars

If not NA, then a character vector naming parameters, which are included in the output if include = TRUE and excluded if include = FALSE. By default, all parameters are included.

include

Logical scalar defaulting to TRUE indicating whether to include or exclude the parameters given by the pars argument. If FALSE, only entire multidimensional parameters can be excluded, rather than particular elements of them.

seed

The seed for random number generation. The default is generated from 1 to the maximum integer supported by R on the machine. Even if multiple chains are used, only one seed is needed, with other chains having seeds derived from that of the first chain to avoid dependent samples. When a seed is specified by a number, as.integer will be applied to it. If as.integer produces NA, the seed is generated randomly. The seed can also be specified as a character string of digits, such as "12345", which is converted to integer.

init

Initial values specification. See the detailed documentation for the init argument in stan.

check_data

Logical, defaulting to TRUE. If TRUE the data will be preprocessed; otherwise not. See the Passing data to Stan section in stan.

sample_file

A character string of file name for specifying where to write samples for all parameters and other saved quantities. This defaults to a temporary file.

algorithm

Either "meanfield" (the default) or "fullrank", indicating which variational inference algorithm is used. The "meanfield" option uses a fully factorized Gaussian for the approximation whereas the fullrank option uses a Gaussian with a full-rank covariance matrix for the approximation. Details and additional references are available in the Stan manual.

importance_resampling

Logical scalar (defaulting to FALSE) indicating whether to do importance resampling to adjust the draws at the optimum to be more like draws from the posterior distribution

keep_every

Integer scalar (defaulting to 1) indicating the interval by which to thin the draws when imporance_resampling = TRUE

...

Other optional parameters:

• iter (positive integer), the maximum number of iterations, defaulting to 10000.

• grad_samples (positive integer), the number of samples for Monte Carlo estimate of gradients, defaulting to 1.

• elbo_samples (positive integer), the number of samples for Monte Carlo estimate of ELBO (objective function), defaulting to 100. (ELBO stands for "the evidence lower bound".)

• eta (double), positive stepsize weighting parameter for variational inference but is ignored if adaptation is engaged, which is the case by default.

• adapt_engaged (logical), a flag indicating whether to automatically adapt the stepsize, defaulting to TRUE.

• tol_rel_obj (positive double), the convergence tolerance on the relative norm of the objective, defaulting to 0.01.

• eval_elbo (positive integer), evaluate ELBO every Nth iteration, defaulting to 100.

• output_samples (positive integer), number of posterior samples to draw and save, defaults to 1000.

• adapt_iter (positive integer), the maximum number of iterations to adapt the stepsize, defaulting to 50. Ignored if adapt_engaged = FALSE.

Refer to the manuals for both CmdStan and Stan for more details.

Value

An object of stanfit-class.

See also

stanmodel

The manuals of CmdStan and Stan.

References

The Stan Development Team Stan Modeling Language User's Guide and Reference Manual. https://mc-stan.org.

The Stan Development Team CmdStan Interface User's Guide. https://mc-stan.org.

Examples

if (FALSE) {
m <- stan_model(model_code = 'parameters {real y;} model {y ~ normal(0,1);}')
f <- vb(m)
}