a few more edits to MLE doc

Author: jgabry

R/fit.R

@@ -1808,12 +1808,11 @@ 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.
-#'   The name "MLE" may be somewhat misleading because the `$optimize()` method
-#'   can compute either a penalized maximum likelihood estimate or a maximum a
-#'   posteriori estimate, depending on the value of the `jacobian` argument when
-#'   the model is fit. Additionally, for models without constrained parameters,
-#'   the penalized MLE and the posterior mode are equivalent, as the Jacobian
-#'   adjustment has no effect.
+#'   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.
 #'
 #' @section Methods: `CmdStanMLE` objects have the following associated methods,
 #'   all of which have their own (linked) documentation pages.
@@ -1894,12 +1893,11 @@ CmdStanMLE <- R6::R6Class(
 #'   which is available via the [`$lp()`][fit-method-lp] method and also
 #'   included in the [`$draws()`][fit-method-draws] method.
 #'
-#'   The name `mle` may be somewhat misleading because the `$optimize()` method
-#'   can compute either a penalized maximum likelihood estimate or a maximum a
-#'   posteriori estimate, depending on the value of the `jacobian` argument when
-#'   the model is fit. Additionally, for models without constrained parameters,
-#'   the penalized MLE and the posterior mode are equivalent, as the Jacobian
-#'   adjustment has no effect.
+#'   For models with constrained parameters that are fit with `jacobian=TRUE`,
+#'   the `$mle()` method actually returns the maximum a posteriori (MAP)
+#'   estimate (posterior mode) rather than the MLE. 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

@@ -1444,8 +1444,14 @@ 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 or a
-#'   maximum a posteriori estimate (if `jacobian=TRUE`). See the
+#'   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
 #'   [CmdStan User's Guide](https://mc-stan.org/docs/cmdstan-guide/index.html)
 #'   for more details.
 #'
@@ -1455,6 +1461,7 @@ CmdStanModel$set("public", name = "sample_mpi", value = sample_mpi)
 #'   default arguments. The default values can also be obtained by checking the
 #'   metadata of an example model, e.g.,
 #'   `cmdstanr_example(method="optimize")$metadata()`.
+#'
 #' @template model-common-args
 #' @param threads (positive integer) If the model was
 #'   [compiled][model-method-compile] with threading support, the number of

cmdstanr.Rproj

@@ -1,4 +1,5 @@
 Version: 1.0
+ProjectId: b2cb035a-82d0-45fa-b984-ec75db1e1feb
 
 RestoreWorkspace: Default
 SaveWorkspace: Default