vb {rstan} | R Documentation

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

### Description

Approximately draw from a posterior distribution using variational inference. 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"), ...)

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

`...`

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.16.2 Index]