1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
|
\docType{methods}
\name{vb}
\alias{vb}
\alias{vb,stanmodel-method}
\title{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 \code{\link{stan}} or \code{\link{sampling}} for
final inferences and only using \code{vb} to get a rough idea of the parameter
distributions.
}
\usage{
%% vb(object, \dots)
\S4method{vb}{stanmodel}(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,
\dots)
}
\section{Methods}{
\describe{
\item{vb}{\code{signature(object = "stanmodel")}
Call Stan's variational Bayes methods
for the model defined by S4 class \code{stanmodel}
given the data, initial values, etc.
}
}
}
\arguments{
\item{object}{An object of class \code{\linkS4class{stanmodel}}.}
\item{data}{A named \code{list} or \code{environment}
providing the data for the model or a character vector
for all the names of objects used as data.
See the \strong{Passing data to Stan} section in \code{\link{stan}}.}
\item{pars}{If not \code{NA}, then a character vector naming parameters,
which are included in the output if \code{include = TRUE} and excluded
if \code{include = FALSE}. By default, all parameters are included.}
\item{include}{Logical scalar defaulting to \code{TRUE} indicating
whether to include or exclude the parameters given by the
\code{pars} argument. If \code{FALSE}, only entire multidimensional
parameters can be excluded, rather than particular elements of them.}
\item{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, \code{as.integer} will be applied to it.
If \code{as.integer} produces \code{NA}, the seed is generated randomly.
The seed can also be specified as a character string of digits, such as
\code{"12345"}, which is converted to integer.}
\item{init}{Initial values specification. See the detailed documentation for
the init argument in \code{\link{stan}}.}
\item{check_data}{Logical, defaulting to \code{TRUE}. If \code{TRUE}
the data will be preprocessed; otherwise not.
See the \strong{Passing data to Stan} section in \code{\link{stan}}.}
\item{sample_file}{A character string of file name for specifying where to
write samples for \emph{all} parameters and other saved quantities.
This defaults to a temporary file.}
\item{algorithm}{Either \code{"meanfield"} (the default) or \code{"fullrank"},
indicating which variational inference algorithm is used. The \code{"meanfield"}
option uses a fully factorized Gaussian for the approximation whereas the
\code{fullrank} option uses a Gaussian with a full-rank covariance matrix
for the approximation. Details and additional references are available in
the Stan manual.}
\item{importance_resampling}{Logical scalar (defaulting to \code{FALSE}) indicating
whether to do importance resampling to adjust the draws at the optimum
to be more like draws from the posterior distribution}
\item{keep_every}{Integer scalar (defaulting to 1) indicating the interval
by which to thin the draws when \code{imporance_resampling = TRUE}}
\item{\dots}{Other optional parameters:
\itemize{
\item \code{iter} (positive \code{integer}), the maximum number
of iterations, defaulting to 10000.
\item \code{grad_samples} (positive \code{integer}), the number of samples
for Monte Carlo estimate of gradients, defaulting to 1.
\item \code{elbo_samples} (positive \code{integer}), the number of samples
for Monte Carlo estimate of ELBO (objective function), defaulting to 100.
(ELBO stands for "the evidence lower bound".)
\item \code{eta} (\code{double}), positive stepsize weighting parameter
for variational inference but is ignored if adaptation is engaged, which
is the case by default.
\item \code{adapt_engaged} (\code{logical}), a flag indicating whether to
automatically adapt the stepsize, defaulting to \code{TRUE}.
\item \code{tol_rel_obj} (positive \code{double}), the convergence tolerance
on the relative norm of the objective, defaulting to 0.01.
\item \code{eval_elbo} (positive \code{integer}), evaluate ELBO every Nth
iteration, defaulting to 100.
\item \code{output_samples} (positive \code{integer}), number of posterior
samples to draw and save, defaults to 1000.
\item \code{adapt_iter} (positive \code{integer}), the maximum number of
iterations to adapt the stepsize, defaulting to 50. Ignored if
\code{adapt_engaged = FALSE}.
}
Refer to the manuals for both CmdStan and Stan for more details.
}
}
\value{
An object of \code{\link{stanfit-class}}.
}
\seealso{
\code{\linkS4class{stanmodel}}
The manuals of CmdStan and Stan.
}
\references{
The Stan Development Team
\emph{Stan Modeling Language User's Guide and Reference Manual}.
\url{https://mc-stan.org}.
The Stan Development Team
\emph{CmdStan Interface User's Guide}.
\url{https://mc-stan.org}.
}
\examples{\dontrun{
m <- stan_model(model_code = 'parameters {real y;} model {y ~ normal(0,1);}')
f <- vb(m)
}}
|
