diff --git a/R/fit.R b/R/fit.R index 00b239fb8..d44dc246b 100644 --- a/R/fit.R +++ b/R/fit.R @@ -787,8 +787,8 @@ CmdStanFit$set("public", name = "constrain_variables", value = constrain_variabl #' fit_mcmc <- cmdstanr_example("logistic") #' head(fit_mcmc$lp()) #' -#' fit_mle <- cmdstanr_example("logistic", method = "optimize") -#' fit_mle$lp() +#' fit_optim <- cmdstanr_example("logistic", method = "optimize") +#' fit_optim$lp() #' #' fit_vb <- cmdstanr_example("logistic", method = "variational") #' plot(fit_vb$lp(), fit_vb$lp_approx()) @@ -1176,13 +1176,13 @@ CmdStanFit$set("public", name = "metric_files", value = metric_files) #' fit_vb <- cmdstanr_example("logistic", method = "variational") #' fit_vb$time() #' -#' fit_mle <- cmdstanr_example("logistic", method = "optimize", jacobian = TRUE) -#' fit_mle$time() +#' fit_optim <- cmdstanr_example("logistic", method = "optimize", jacobian = TRUE) +#' fit_optim$time() #' -#' # use fit_mle to draw samples from laplace approximation -#' fit_laplace <- cmdstanr_example("logistic", method = "laplace", mode = fit_mle) +#' # use fit_optim to draw samples from laplace approximation +#' fit_laplace <- cmdstanr_example("logistic", method = "laplace", mode = fit_optim) #' fit_laplace$time() # just time for drawing sample not for running optimize -#' fit_laplace$time()$total + fit_mle$time()$total # total time +#' fit_laplace$time()$total + fit_optim$time()$total # total time #' } #' time <- function() { @@ -1216,8 +1216,8 @@ CmdStanFit$set("public", name = "time", value = time) #' out <- fit_mcmc$output() #' str(out) #' -#' fit_mle <- cmdstanr_example("logistic", method = "optimize") -#' fit_mle$output() +#' fit_optim <- cmdstanr_example("logistic", method = "optimize") +#' fit_optim$output() #' #' fit_vb <- cmdstanr_example("logistic", method = "variational") #' fit_vb$output() @@ -1245,8 +1245,8 @@ CmdStanFit$set("public", name = "output", value = output) #' fit_mcmc <- cmdstanr_example("logistic", method = "sample") #' str(fit_mcmc$metadata()) #' -#' fit_mle <- cmdstanr_example("logistic", method = "optimize") -#' str(fit_mle$metadata()) +#' fit_optim <- cmdstanr_example("logistic", method = "optimize") +#' str(fit_optim$metadata()) #' #' fit_vb <- cmdstanr_example("logistic", method = "variational") #' str(fit_vb$metadata()) @@ -1972,14 +1972,12 @@ CmdStanMCMC$set("public", name = "num_chains", value = num_chains) #' #' @description A `CmdStanMLE` object is the fitted model object returned by the #' [`$optimize()`][model-method-optimize] method of a [`CmdStanModel`] object. -#' Following CmdStan's terminology, the object contains an MLE if optimization -#' was run with `jacobian=FALSE` and a MAP estimate if it was run with -#' `jacobian=TRUE`. The name "MLE" is retained for historical reasons. More -#' precisely, the estimates correspond to a mode in either the constrained -#' parameter space or the unconstrained parameter space, depending on the -#' value of `jacobian` (and whether the model has constrained parameters). -#' The `jacobian` argument does not control whether prior terms are included; -#' all contributions to the Stan program's target are included under either +#' The name "MLE" is retained for historical reasons. With +#' `jacobian = FALSE`, the point estimate is a mode of the target in the +#' constrained parameter space. With `jacobian = TRUE`, it is a mode of the +#' corresponding density in the unconstrained parameter space. The `jacobian` +#' argument does not control whether prior terms are included; all +#' contributions to the Stan program's target are included under either #' setting. See [`$optimize()`][model-method-optimize] and the CmdStan User's #' Guide for more details. #' @@ -2069,19 +2067,18 @@ CmdStanMLE <- R6::R6Class( #' @name fit-method-mle #' @aliases mle #' @description The `$mle()` method is only available for [`CmdStanMLE`] -#' objects. It returns the point estimate as a numeric vector with one element -#' per variable. The returned vector does *not* include `lp__`, the -#' target log density evaluated by Stan, up to an additive constant. `lp__` is -#' available via the [`$lp()`][fit-method-lp] method and also included in the +#' objects. The method name is retained for historical reasons. It returns the +#' point estimate as a numeric vector with one element per variable. The +#' returned vector does *not* include `lp__`, the target log density evaluated +#' by Stan, up to an additive constant. `lp__` is available via the +#' [`$lp()`][fit-method-lp] method and also included in the #' [`$draws()`][fit-method-draws] method. #' -#' Following CmdStan's terminology, for models with constrained parameters -#' that are fit with `jacobian=TRUE`, this point estimate is called a maximum -#' a posteriori (MAP) estimate rather than an MLE. More precisely, -#' `jacobian=FALSE` finds a mode of the target in the constrained parameter -#' space and `jacobian=TRUE` finds a mode in the unconstrained parameter -#' space. See [`$optimize()`][model-method-optimize] and the CmdStan User's -#' Guide for more details. +#' With `jacobian = FALSE`, the point estimate is a mode of the target in the +#' constrained parameter space. With `jacobian = TRUE`, it is a mode of the +#' corresponding density in the unconstrained parameter space. See +#' [`$optimize()`][model-method-optimize] and the CmdStan User's Guide for more +#' details. #' #' @param variables (character vector) The variables (parameters, transformed #' parameters, and generated quantities) to include. If NULL (the default) diff --git a/R/model.R b/R/model.R index 876590422..60269d2a8 100644 --- a/R/model.R +++ b/R/model.R @@ -1457,25 +1457,19 @@ CmdStanModel$set("public", name = "sample_mpi", value = sample_mpi) #' @family CmdStanModel methods #' #' @description The `$optimize()` method of a [`CmdStanModel`] object runs -#' Stan's optimizer. Following CmdStan's terminology, optimization without -#' the Jacobian adjustment (the default) returns a maximum likelihood estimate -#' (MLE), whereas optimization with the adjustment returns a maximum a -#' posteriori (MAP) estimate. More precisely, without the adjustment the +#' Stan's optimizer. Without the Jacobian adjustment (the default), #' optimization finds a mode of the target in the original constrained -#' parameter space (if the mode exists), whereas with the adjustment it -#' finds a mode of the corresponding density in the unconstrained parameter -#' space. +#' parameter space (if the mode exists). With the adjustment, it finds a mode +#' of the corresponding density in the unconstrained parameter space. #' #' The `jacobian` argument does not determine whether prior terms are #' included. Every contribution to the Stan program's `target`, including -#' prior terms, is included under either setting. The MLE or MAP -#' interpretation therefore depends on both the contents of the target and the -#' parameterization. The Jacobian adjustment is particularly useful when -#' making a distributional approximation in the unconstrained space (see -#' [Laplace sampling][model-method-laplace]). If the model has only -#' unconstrained parameters, including the Jacobian has no effect. See the -#' [CmdStan User's Guide](https://mc-stan.org/docs/cmdstan-guide/index.html) -#' for more details. +#' prior terms, is included under either setting. The Jacobian adjustment is +#' particularly useful when making a distributional approximation in the +#' unconstrained space (see [Laplace sampling][model-method-laplace]). If the +#' model has only unconstrained parameters, including the Jacobian has no +#' effect. See the [CmdStan User's +#' Guide](https://mc-stan.org/docs/cmdstan-guide/index.html) for more details. #' #' Any argument left as `NULL` will default to the default value used by the #' installed version of CmdStan. See the [CmdStan User’s @@ -1496,13 +1490,12 @@ CmdStanModel$set("public", name = "sample_mpi", value = sample_mpi) #' running `cmdstanr_example(method="optimize")$metadata()`. #' @param jacobian (logical) Whether or not to use the Jacobian adjustment for #' constrained variables. For historical reasons, the default is `FALSE`. -#' CmdStan refers to the estimates obtained with `FALSE` and `TRUE` as MLE and -#' MAP estimates, respectively. More precisely, `FALSE` finds a mode of the -#' target in the constrained parameter space and `TRUE` finds a mode in the -#' unconstrained space. This argument does not control whether prior terms are -#' included. See the **Description** section and the CmdStan User's Guide for -#' more details. For use later with [`$laplace()`][model-method-laplace], the -#' `jacobian` argument should typically be set to `TRUE`. +#' `FALSE` finds a mode of the target in the constrained parameter space and +#' `TRUE` finds a mode in the unconstrained space. This argument does not +#' control whether prior terms are included. See the **Description** section +#' and the CmdStan User's Guide for more details. For use later with +#' [`$laplace()`][model-method-laplace], the `jacobian` argument should +#' typically be set to `TRUE`. #' @param init_alpha (positive real) The initial step size parameter. #' @param tol_obj (positive real) Convergence tolerance on changes in objective function value. #' @param tol_rel_obj (positive real) Convergence tolerance on relative changes in objective function value. @@ -1604,16 +1597,11 @@ CmdStanModel$set("public", name = "optimize", value = optimize) #' #' @description The `$laplace()` method of a [`CmdStanModel`] object produces a #' sample from a normal approximation centered at the mode of a distribution -#' in the unconstrained space. Following CmdStan's terminology, if the mode is -#' a maximum a posteriori (MAP) estimate, the samples provide an estimate of -#' the mean and standard deviation of the posterior distribution. If the mode -#' is a maximum likelihood estimate (MLE), the sample provides an estimate of -#' the standard error of the likelihood. Whether the mode is called MAP or MLE -#' depends on the value of the `jacobian` argument when running optimization. -#' This terminology does not imply that `jacobian` controls whether prior -#' terms are included; it controls the parameterization of the density, while -#' the Stan program determines the contents of the target. See the -#' [CmdStan User’s Guide](https://mc-stan.org/docs/cmdstan-guide/) +#' in the unconstrained space. When the mode was found with the Jacobian +#' adjustment, the draws provide an estimate of the mean and standard +#' deviation of the posterior distribution. See the `jacobian` argument below +#' for how this setting relates to the value used when running optimization, +#' and the [CmdStan User’s Guide](https://mc-stan.org/docs/cmdstan-guide/) #' for more details. #' #' Any argument left as `NULL` will default to the default value used by the @@ -1639,7 +1627,7 @@ CmdStanModel$set("public", name = "optimize", value = optimize) #' @param draws (positive integer) The number of draws to take. #' @param jacobian (logical) Whether or not to enable the Jacobian adjustment #' for constrained parameters. The default is `TRUE`. See the -#' [Laplace Sampling](https://mc-stan.org/docs/cmdstan-guide/laplace-sampling.html) +#' [Laplace Sampling](https://mc-stan.org/docs/cmdstan-guide/laplace_sample_config.html) #' section of the CmdStan User's Guide for more details. If `mode` is not #' `NULL` then the value of `jacobian` must match the value used when #' optimization was originally run so the mode and the Laplace approximation diff --git a/man/CmdStanMLE.Rd b/man/CmdStanMLE.Rd index 91c73e561..cf23092c0 100644 --- a/man/CmdStanMLE.Rd +++ b/man/CmdStanMLE.Rd @@ -6,14 +6,12 @@ \description{ A \code{CmdStanMLE} object is the fitted model object returned by the \code{\link[=model-method-optimize]{$optimize()}} method of a \code{\link{CmdStanModel}} object. -Following CmdStan's terminology, the object contains an MLE if optimization -was run with \code{jacobian=FALSE} and a MAP estimate if it was run with -\code{jacobian=TRUE}. The name "MLE" is retained for historical reasons. More -precisely, the estimates correspond to a mode in either the constrained -parameter space or the unconstrained parameter space, depending on the -value of \code{jacobian} (and whether the model has constrained parameters). -The \code{jacobian} argument does not control whether prior terms are included; -all contributions to the Stan program's target are included under either +The name "MLE" is retained for historical reasons. With +\code{jacobian = FALSE}, the point estimate is a mode of the target in the +constrained parameter space. With \code{jacobian = TRUE}, it is a mode of the +corresponding density in the unconstrained parameter space. The \code{jacobian} +argument does not control whether prior terms are included; all +contributions to the Stan program's target are included under either setting. See \code{\link[=model-method-optimize]{$optimize()}} and the CmdStan User's Guide for more details. diff --git a/man/fit-method-lp.Rd b/man/fit-method-lp.Rd index 4c598a113..25dc27924 100644 --- a/man/fit-method-lp.Rd +++ b/man/fit-method-lp.Rd @@ -60,8 +60,8 @@ distribution on the unconstrained space. fit_mcmc <- cmdstanr_example("logistic") head(fit_mcmc$lp()) -fit_mle <- cmdstanr_example("logistic", method = "optimize") -fit_mle$lp() +fit_optim <- cmdstanr_example("logistic", method = "optimize") +fit_optim$lp() fit_vb <- cmdstanr_example("logistic", method = "variational") plot(fit_vb$lp(), fit_vb$lp_approx()) diff --git a/man/fit-method-metadata.Rd b/man/fit-method-metadata.Rd index e249c2391..2d9802f21 100644 --- a/man/fit-method-metadata.Rd +++ b/man/fit-method-metadata.Rd @@ -20,8 +20,8 @@ fitting the model. See \strong{Examples} and \code{\link[=read_cmdstan_csv]{read fit_mcmc <- cmdstanr_example("logistic", method = "sample") str(fit_mcmc$metadata()) -fit_mle <- cmdstanr_example("logistic", method = "optimize") -str(fit_mle$metadata()) +fit_optim <- cmdstanr_example("logistic", method = "optimize") +str(fit_optim$metadata()) fit_vb <- cmdstanr_example("logistic", method = "variational") str(fit_vb$metadata()) diff --git a/man/fit-method-mle.Rd b/man/fit-method-mle.Rd index 072d8503c..1cb0c063f 100644 --- a/man/fit-method-mle.Rd +++ b/man/fit-method-mle.Rd @@ -17,19 +17,18 @@ A numeric vector. See \strong{Examples}. } \description{ The \verb{$mle()} method is only available for \code{\link{CmdStanMLE}} -objects. It returns the point estimate as a numeric vector with one element -per variable. The returned vector does \emph{not} include \code{lp__}, the -target log density evaluated by Stan, up to an additive constant. \code{lp__} is -available via the \code{\link[=fit-method-lp]{$lp()}} method and also included in the +objects. The method name is retained for historical reasons. It returns the +point estimate as a numeric vector with one element per variable. The +returned vector does \emph{not} include \code{lp__}, the target log density evaluated +by Stan, up to an additive constant. \code{lp__} is available via the +\code{\link[=fit-method-lp]{$lp()}} method and also included in the \code{\link[=fit-method-draws]{$draws()}} method. -Following CmdStan's terminology, for models with constrained parameters -that are fit with \code{jacobian=TRUE}, this point estimate is called a maximum -a posteriori (MAP) estimate rather than an MLE. More precisely, -\code{jacobian=FALSE} finds a mode of the target in the constrained parameter -space and \code{jacobian=TRUE} finds a mode in the unconstrained parameter -space. See \code{\link[=model-method-optimize]{$optimize()}} and the CmdStan User's -Guide for more details. +With \code{jacobian = FALSE}, the point estimate is a mode of the target in the +constrained parameter space. With \code{jacobian = TRUE}, it is a mode of the +corresponding density in the unconstrained parameter space. See +\code{\link[=model-method-optimize]{$optimize()}} and the CmdStan User's Guide for more +details. } \examples{ \dontrun{ diff --git a/man/fit-method-output.Rd b/man/fit-method-output.Rd index bfa8a9eda..a4bc4b287 100644 --- a/man/fit-method-output.Rd +++ b/man/fit-method-output.Rd @@ -32,8 +32,8 @@ fit_mcmc$output(1) out <- fit_mcmc$output() str(out) -fit_mle <- cmdstanr_example("logistic", method = "optimize") -fit_mle$output() +fit_optim <- cmdstanr_example("logistic", method = "optimize") +fit_optim$output() fit_vb <- cmdstanr_example("logistic", method = "variational") fit_vb$output() diff --git a/man/fit-method-time.Rd b/man/fit-method-time.Rd index c2a3011ab..7e5dfe489 100644 --- a/man/fit-method-time.Rd +++ b/man/fit-method-time.Rd @@ -39,13 +39,13 @@ fit_mcmc$time() fit_vb <- cmdstanr_example("logistic", method = "variational") fit_vb$time() -fit_mle <- cmdstanr_example("logistic", method = "optimize", jacobian = TRUE) -fit_mle$time() +fit_optim <- cmdstanr_example("logistic", method = "optimize", jacobian = TRUE) +fit_optim$time() -# use fit_mle to draw samples from laplace approximation -fit_laplace <- cmdstanr_example("logistic", method = "laplace", mode = fit_mle) +# use fit_optim to draw samples from laplace approximation +fit_laplace <- cmdstanr_example("logistic", method = "laplace", mode = fit_optim) fit_laplace$time() # just time for drawing sample not for running optimize -fit_laplace$time()$total + fit_mle$time()$total # total time +fit_laplace$time()$total + fit_optim$time()$total # total time } } diff --git a/man/model-method-laplace.Rd b/man/model-method-laplace.Rd index aab83fe96..e0b6ab415 100644 --- a/man/model-method-laplace.Rd +++ b/man/model-method-laplace.Rd @@ -166,7 +166,7 @@ taken to run the \verb{$optimize()} method.} \item{jacobian}{(logical) Whether or not to enable the Jacobian adjustment for constrained parameters. The default is \code{TRUE}. See the -\href{https://mc-stan.org/docs/cmdstan-guide/laplace-sampling.html}{Laplace Sampling} +\href{https://mc-stan.org/docs/cmdstan-guide/laplace_sample_config.html}{Laplace Sampling} section of the CmdStan User's Guide for more details. If \code{mode} is not \code{NULL} then the value of \code{jacobian} must match the value used when optimization was originally run so the mode and the Laplace approximation @@ -200,16 +200,11 @@ A \code{\link{CmdStanLaplace}} object. \description{ The \verb{$laplace()} method of a \code{\link{CmdStanModel}} object produces a sample from a normal approximation centered at the mode of a distribution -in the unconstrained space. Following CmdStan's terminology, if the mode is -a maximum a posteriori (MAP) estimate, the samples provide an estimate of -the mean and standard deviation of the posterior distribution. If the mode -is a maximum likelihood estimate (MLE), the sample provides an estimate of -the standard error of the likelihood. Whether the mode is called MAP or MLE -depends on the value of the \code{jacobian} argument when running optimization. -This terminology does not imply that \code{jacobian} controls whether prior -terms are included; it controls the parameterization of the density, while -the Stan program determines the contents of the target. See the -\href{https://mc-stan.org/docs/cmdstan-guide/}{CmdStan User’s Guide} +in the unconstrained space. When the mode was found with the Jacobian +adjustment, the draws provide an estimate of the mean and standard +deviation of the posterior distribution. See the \code{jacobian} argument below +for how this setting relates to the value used when running optimization, +and the \href{https://mc-stan.org/docs/cmdstan-guide/}{CmdStan User’s Guide} for more details. Any argument left as \code{NULL} will default to the default value used by the diff --git a/man/model-method-optimize.Rd b/man/model-method-optimize.Rd index b176b3783..0bd0f8a17 100644 --- a/man/model-method-optimize.Rd +++ b/man/model-method-optimize.Rd @@ -162,13 +162,12 @@ running \code{cmdstanr_example(method="optimize")$metadata()}.} \item{jacobian}{(logical) Whether or not to use the Jacobian adjustment for constrained variables. For historical reasons, the default is \code{FALSE}. -CmdStan refers to the estimates obtained with \code{FALSE} and \code{TRUE} as MLE and -MAP estimates, respectively. More precisely, \code{FALSE} finds a mode of the -target in the constrained parameter space and \code{TRUE} finds a mode in the -unconstrained space. This argument does not control whether prior terms are -included. See the \strong{Description} section and the CmdStan User's Guide for -more details. For use later with \code{\link[=model-method-laplace]{$laplace()}}, the -\code{jacobian} argument should typically be set to \code{TRUE}.} +\code{FALSE} finds a mode of the target in the constrained parameter space and +\code{TRUE} finds a mode in the unconstrained space. This argument does not +control whether prior terms are included. See the \strong{Description} section +and the CmdStan User's Guide for more details. For use later with +\code{\link[=model-method-laplace]{$laplace()}}, the \code{jacobian} argument should +typically be set to \code{TRUE}.} \item{init_alpha}{(positive real) The initial step size parameter.} @@ -211,25 +210,18 @@ A \code{\link{CmdStanMLE}} object. } \description{ The \verb{$optimize()} method of a \code{\link{CmdStanModel}} object runs -Stan's optimizer. Following CmdStan's terminology, optimization without -the Jacobian adjustment (the default) returns a maximum likelihood estimate -(MLE), whereas optimization with the adjustment returns a maximum a -posteriori (MAP) estimate. More precisely, without the adjustment the +Stan's optimizer. Without the Jacobian adjustment (the default), optimization finds a mode of the target in the original constrained -parameter space (if the mode exists), whereas with the adjustment it -finds a mode of the corresponding density in the unconstrained parameter -space. +parameter space (if the mode exists). With the adjustment, it finds a mode +of the corresponding density in the unconstrained parameter space. The \code{jacobian} argument does not determine whether prior terms are included. Every contribution to the Stan program's \code{target}, including -prior terms, is included under either setting. The MLE or MAP -interpretation therefore depends on both the contents of the target and the -parameterization. The Jacobian adjustment is particularly useful when -making a distributional approximation in the unconstrained space (see -\link[=model-method-laplace]{Laplace sampling}). If the model has only -unconstrained parameters, including the Jacobian has no effect. See the -\href{https://mc-stan.org/docs/cmdstan-guide/index.html}{CmdStan User's Guide} -for more details. +prior terms, is included under either setting. The Jacobian adjustment is +particularly useful when making a distributional approximation in the +unconstrained space (see \link[=model-method-laplace]{Laplace sampling}). If the +model has only unconstrained parameters, including the Jacobian has no +effect. See the \href{https://mc-stan.org/docs/cmdstan-guide/index.html}{CmdStan User's Guide} for more details. Any argument left as \code{NULL} will default to the default value used by the installed version of CmdStan. See the \href{https://mc-stan.org/docs/cmdstan-guide/}{CmdStan User’s Guide} for more details on the diff --git a/vignettes/cmdstanr.Rmd b/vignettes/cmdstanr.Rmd index dd6d42cd2..86c287b5e 100644 --- a/vignettes/cmdstanr.Rmd +++ b/vignettes/cmdstanr.Rmd @@ -324,33 +324,34 @@ are called in a similar way to the `$sample()` method demonstrated above. ### Optimization -Following CmdStan's terminology, we can find the (penalized) maximum likelihood -estimate (MLE) using [`$optimize()`](https://mc-stan.org/cmdstanr/reference/model-method-optimize.html). +We can find a mode of the target using +[`$optimize()`](https://mc-stan.org/cmdstanr/reference/model-method-optimize.html). +The point estimate is extracted with the `$mle()` method (the method name is +retained for historical reasons). ```{r optimize} -fit_mle <- mod$optimize(data = data_list, seed = 123) -fit_mle$print() # includes lp__ (log prob calculated by Stan program) -fit_mle$mle("theta") +fit_optim <- mod$optimize(data = data_list, seed = 123) +fit_optim$print() # includes lp__ (log prob calculated by Stan program) +fit_optim$mle("theta") ``` -Here's a plot comparing the penalized MLE to the posterior distribution of +Here's a plot comparing the optimized point estimate to the posterior of `theta`. -```{r plot-mle, message = FALSE} +```{r plot-optim, message = FALSE} mcmc_hist(fit$draws("theta")) + - vline_at(fit_mle$mle("theta"), size = 1.5) + vline_at(fit_optim$mle("theta"), size = 1.5) ``` For optimization, by default the mode is calculated without the Jacobian -adjustment for constrained variables. Including the Jacobian adjustment by setting `jacobian=TRUE` produces a maximum a posteriori (MAP) estimate. More precisely, the default -finds a mode of the target in the constrained parameter space, whereas -`jacobian=TRUE` finds a mode of the corresponding density in the unconstrained -space. See the -[Maximum Likelihood Estimation](https://mc-stan.org/docs/cmdstan-guide/maximum-likelihood-estimation.html) +adjustment for constrained variables, which finds a mode of the target in the +constrained parameter space, whereas `jacobian = TRUE` finds a mode of the +corresponding density in the unconstrained space. See the +[Jacobian adjustments](https://mc-stan.org/docs/cmdstan-guide/optimize_config.html#jacobian-adjustments) section of the CmdStan User's Guide for more details. -```{r optimize-map} -fit_map <- mod$optimize( +```{r optimize-jacobian} +fit_optim_jacobian <- mod$optimize( data = data_list, jacobian = TRUE, seed = 123 @@ -361,23 +362,21 @@ fit_map <- mod$optimize( The [`$laplace()`](https://mc-stan.org/cmdstanr/reference/model-method-laplace.html) method produces a sample from a normal approximation centered at the mode of a -distribution in the unconstrained space. Following CmdStan's terminology, if -the mode is a MAP estimate, the draws provide an estimate of the mean and -standard deviation of the posterior distribution. If the mode is an MLE, the -draws provide an estimate of the standard error of the likelihood. Whether -the mode is called MAP or MLE depends on the value of the `jacobian` argument -when running optimization. The Laplace `jacobian` setting must match the setting -used for optimization so that both use the same target density. See the -[Laplace Sampling](https://mc-stan.org/docs/cmdstan-guide/laplace-sampling.html) +distribution in the unconstrained space. When the mode was found with the +Jacobian adjustment, the draws provide an estimate of the mean and standard +deviation of the posterior distribution. The Laplace `jacobian` setting must +match the setting used for optimization so that both use the same target +density. See the +[Laplace Sampling](https://mc-stan.org/docs/cmdstan-guide/laplace_sample_config.html) chapter of the CmdStan User's Guide for more details. -Here we pass in the `fit_map` object from above as the `mode` argument. If -`mode` is omitted then optimization will be run internally before taking draws -from the normal approximation. +Here we pass in the `fit_optim_jacobian` object from above as the `mode` +argument. If `mode` is omitted then optimization will be run internally before +taking draws from the normal approximation. ```{r laplace} fit_laplace <- mod$laplace( - mode = fit_map, + mode = fit_optim_jacobian, draws = 4000, data = data_list, seed = 123,