Merge pull request #1115 from stan-dev/fix-optimize-doc

fix optimize doc Jacobian description

Author: jgabry

DESCRIPTION

@@ -32,7 +32,7 @@ URL: https://mc-stan.org/cmdstanr/, https://discourse.mc-stan.org
 BugReports: https://github.com/stan-dev/cmdstanr/issues
 Encoding: UTF-8
 LazyData: true
-RoxygenNote: 7.3.2
+RoxygenNote: 7.3.3
 Roxygen: list(markdown = TRUE, r6 = FALSE)
 SystemRequirements: CmdStan (https://mc-stan.org/users/interfaces/cmdstan)
 Depends:

R/fit.R

@@ -1812,11 +1812,13 @@ 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.
-#'   This object will either contain a penalized maximum likelihood estimate
-#'   (MLE) or a maximum a posteriori estimate (MAP), depending on the value of
-#'   the `jacobian` argument when the model is fit (and whether the model has
-#'   constrained parameters). See [`$optimize()`][model-method-optimize] and the
-#'   CmdStan User's Guide for more details.
+#'   The name "MLE" (used for historical reasons) is a bit misleading since this
+#'   object will contain parameter estimates corresponding to either a mode in
+#'   the constrained parameter space _or_ the unconstrained parameter space,
+#'   depending on the value of the `jacobian` argument when the model is fit
+#'   (and whether the model has constrained parameters). See
+#'   [`$optimize()`][model-method-optimize] and the CmdStan User's Guide for
+#'   more details.
 #'
 #' @section Methods: `CmdStanMLE` objects have the following associated methods,
 #'   all of which have their own (linked) documentation pages.

R/model.R

@@ -1447,14 +1447,18 @@ CmdStanModel$set("public", name = "sample_mpi", value = sample_mpi)
 #' @family CmdStanModel methods
 #'
 #' @description The `$optimize()` method of a [`CmdStanModel`] object runs
-#'   Stan's optimizer to obtain a (penalized) maximum likelihood estimate (MLE)
-#'   or a maximum a posteriori estimate (MAP), depending on the value of the
-#'   `jacobian` argument. For models with constrained parameters, when the
-#'   Jacobian adjustment is *not* applied, the point estimate corresponds to a
-#'   penalized MLE, and when the Jacobian adjustment is applied the point
-#'   estimate corresponds to the MAP (posterior mode) of the model we would fit
-#'   if we were instead doing MCMC sampling. The Jacobian adjustment has no
-#'   affect if the model has only unconstrained parameters. See the
+#'   Stan's optimizer to find a posterior mode. If the Jacobian adjustment is
+#'   not included (the default), the optimization returns parameter values that
+#'   correspond to a mode of the target in the constrained space (if such mode
+#'   exists). Thus this option is useful for any optimization where we want to
+#'   find the mode in the original constrained parameter space. If the Jacobian
+#'   adjustment is included, the optimization returns parameter values that
+#'   correspond to a mode in the unconstrained space. This is useful, for
+#'   example, if we want to make a distributional approximation of the posterior
+#'   at the mode (see, [Laplace sampling][model-method-laplace], for which the
+#'   Jacobian adjustment needs to be included for correct results). If the model
+#'   has only unconstrained parameters, there is no effect from including the
+#'   Jacobian. See the
 #'   [CmdStan User's Guide](https://mc-stan.org/docs/cmdstan-guide/index.html)
 #'   for more details.
 #'
@@ -1477,13 +1481,12 @@ CmdStanModel$set("public", name = "sample_mpi", value = sample_mpi)
 #'   the CmdStan User's Guide. The default values can also be obtained by
 #'   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`, meaning optimization
-#'   yields the (regularized) maximum likelihood estimate. Setting it to `TRUE`
-#'   yields the maximum a posteriori estimate. See the
-#'   [Maximum Likelihood Estimation](https://mc-stan.org/docs/cmdstan-guide/maximum-likelihood-estimation.html)
-#'   section of 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`.
+#'   constrained variables. For historical reasons, the default is `FALSE`,
+#'   meaning optimization finds a mode of the target in the original constrained
+#'   parameter space. Setting it to `TRUE` finds a mode in the unconstrained
+#'   space. See 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.
@@ -2372,4 +2375,4 @@ resolve_exe_path <- function(
     exe <- self_exe_file
   }
   exe
-}
+}