Remove confusing references to MAP and MLE

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)

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