R: Run Stan's variational algorithm for approximate posterior...

vb {rstan} | R Documentation

## Run Stan's variational algorithm for approximate posterior sampling

### Description

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.

### Usage

      ## S4 method for signature '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,
        ...)

### 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`.

### 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.

### References

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

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

### See Also

`stanmodel`

The manuals of CmdStan and Stan.

### Examples

    ## Not run:
    m <- stan_model(model_code = 'parameters {real y;} model {y ~ normal(0,1);}')
    f <- vb(m)

    ## End(Not run)

[Package rstan version 2.21.2 Index]