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.
# 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"), …)
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
.
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.
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.
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.
Initial values specification. See the detailed documentation for
the init argument in stan
.
Logical, defaulting to TRUE
. If TRUE
the data will be preprocessed; otherwise not.
See the Note section in stan
.
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.
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.
An object of stanfit-class
.
signature(object = "stanmodel")
stanmodel
given the data, initial values, etc.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.
The manuals of CmdStan and Stan.
# NOT RUN {
m <- stan_model(model_code = 'parameters {real y;} model {y ~ normal(0,1);}')
f <- vb(m)
# }
Run the code above in your browser using DataLab