A few more doc edits to the jacobian sections

Author: jgabry

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())

R/model.R

@@ -1597,11 +1597,12 @@ 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. The `jacobian` setting must match the value used
-#'   when running optimization so that both use the same target density. This
-#'   setting 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/) for more details.
+#'   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
 #'   installed version of CmdStan. See the [CmdStan User’s
@@ -1626,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

man/fit-method-lp.Rd

@@ -326,6 +326,8 @@ are called in a similar way to the `$sample()` method demonstrated above.
 
 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_optim <- mod$optimize(data = data_list, seed = 123)
@@ -342,8 +344,8 @@ mcmc_hist(fit$draws("theta")) +
 ```
 
 For optimization, by default the mode is calculated without the Jacobian
-adjustment for constrained variables. The default finds a mode of the target in
-the constrained parameter space, whereas `jacobian = TRUE` finds a mode of the
+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.
@@ -360,10 +362,12 @@ fit_optim_jacobian <- 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. The Laplace `jacobian` setting must
+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-sampling.html)
+[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_optim_jacobian` object from above as the `mode`