stanmodel-method-optimizing.RdObtain a point estimate by maximizing the joint posterior
from the model defined by class stanmodel.
<!-- %% optimizing(object, \dots) -->
# S4 method for stanmodel
optimizing(object, data = list(),
seed = sample.int(.Machine$integer.max, 1), init = 'random',
check_data = TRUE, sample_file = NULL,
algorithm = c("LBFGS", "BFGS", "Newton"),
verbose = FALSE, hessian = FALSE, as_vector = TRUE,
draws = 0, constrained = TRUE, importance_resampling = FALSE, ...)signature(object = "stanmodel")
stanmodel
given the data, initial values, etc.
An object of class stanmodel.
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.
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 with one exception. If specifying inits
using a list then only a single named list of values should be provided.
For example, to initialize a parameter alpha to value1 and
beta to value2 you can specify list(alpha = value1, beta = value2).
Logical, defaulting to TRUE. If TRUE
the data will be preprocessed; otherwise not.
See the Passing data to Stan section in stan.
A character string of file name for specifying where to
write samples for all parameters and other saved quantities.
If not provided, files are not created. When the folder specified
is not writable, tempdir() is used.
One of "Newton", "BFGS",
and "LBFGS" (the default) indicating which optimization algorithm
to use.
TRUE or FALSE (the default): flag indicating
whether to print intermediate output from Stan on the console, which might
be helpful for model debugging.
TRUE or FALSE (the default): flag indicating
whether to calculate the Hessian (via numeric differentiation of the
gradient function in the unconstrained parameter space).
TRUE (the default) or FALSE: flag indicating
whether a vector is used to store the point estimate found. A list can be
used instead by specifying it to be FALSE.
A non-negative integer (that defaults to zero) indicating how
many times to draw from a multivariate normal distribution whose parameters
are the mean vector and the inverse negative Hessian in the unconstrained
space. If draws > 0 and importance_resampling=TRUE
then log_p and log_g will be computed and returned
(see description in the Value section).
A logical scalar indicating, if draws > 0, whether
the draws should be transformed to the constrained space defined in the
parameters block of the Stan program. Defaults to TRUE.
A logical scalar (defaulting to FALSE)
indicating whether to do importance resampling to compute diagnostics on the
draws from the normal approximation to the posterior distribution.
If TRUE and draws > 0 then log_p
and log_g will be computed and returned (see description in the
Value section).
Other optional parameters:
iter (integer), the maximum number of iterations,
defaulting to 2000.
save_iterations (logical), a flag indicating whether to save
the iterations, defaulting to FALSE.
refresh (integer), the number of interations between
screen updates, defaulting to 100.
init_alpha (double), for BFGS and LBFGS,
the line search step size for first iteration, defaulting to 0.001.
tol_obj (double), for BFGS and LBFGS,
the convergence tolerance on changes in objective function value,
defaulting to 1e-12.
tol_rel_obj (double), for BFGS and LBFGS,
the convergence tolerance on relative changes in objective function value,
defaulting to 1e4.
tol_grad (double), for BFGS and LBFGS,
the convergence tolerance on the norm of the gradient, defaulting to 1e-8.
tol_rel_grad (double), for BFGS and LBFGS,
the convergence tolerance on the relative norm of the gradient, defaulting
to 1e7.
tol_param (double), for BFGS and LBFGS,
the convergence tolerance on changes in parameter value, defaulting to 1e-8.
history_size (integer), for LBFGS,
the number of update vectors to use in Hessian approximations,
defaulting to 5.
Refer to the manuals for both CmdStan and Stan for more details.
A list with components:
The point estimate found. Its form (vector or list)
is determined by the as_vector argument.
The value of the log-posterior (up to an additive constant,
the "lp__" in Stan) corresponding to par.
The value of the return code from the optimizer; anything that is not zero is problematic.
The Hessian matrix if hessian is TRUE
If draws > 0, the matrix of parameter draws
in the constrained or unconstrained space, depending on the value of
the constrained argument.
If draws > 0 and importance_resampling=TRUE,
a vector of length draws that contains the value of the
log-posterior evaluated at each row of theta_tilde.
If draws > 0, a vector of length draws that
contains the value of the logarithm of the multivariate normal density
evaluated at each row of theta_tilde.
If the optimization is not completed for reasons such as feeding wrong data,
it returns NULL.
if (FALSE) {
m <- stan_model(model_code = 'parameters {real y;} model {y ~ normal(0,1);}')
f <- optimizing(m, hessian = TRUE)
}