Merge pull request #1060 from stan-dev/doc-clarifications

Doc clarifications

Author: jgabry

R/fit.R

@@ -1497,10 +1497,10 @@ CmdStanMCMC <- R6::R6Class(
 #'   and the \pkg{loo} package [vignettes](https://mc-stan.org/loo/articles/)
 #'   for details.
 #'
-#' @param variables (character vector) The name(s) of the variable(s) in the
-#'   Stan program containing the pointwise log-likelihood. The default is to
-#'   look for `"log_lik"`. This argument is passed to the
-#'   [`$draws()`][fit-method-draws] method.
+#' @param variables (string) The name of the variable in the Stan program
+#'   containing the pointwise log-likelihood. The default is to look for
+#'   `"log_lik"`. This argument is passed to the [`$draws()`][fit-method-draws]
+#'   method.
 #' @param r_eff (multiple options) How to handle the `r_eff` argument for `loo()`:
 #'   * `TRUE` (the default) will automatically call [loo::relative_eff.array()]
 #'   to compute the `r_eff` argument to pass to [loo::loo.array()].
@@ -1539,6 +1539,9 @@ CmdStanMCMC <- R6::R6Class(
 #'
 loo <- function(variables = "log_lik", r_eff = TRUE, moment_match = FALSE, ...) {
   require_suggested_package("loo")
+  if (length(variables) != 1) {
+    stop("Only a single variable name is allowed for the 'variables' argument.", call. = FALSE)
+  }
   LLarray <- self$draws(variables, format = "draws_array")
   if (is.logical(r_eff)) {
     if (isTRUE(r_eff)) {
@@ -1806,6 +1809,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.
+#'   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.
@@ -1875,17 +1883,22 @@ CmdStanMLE <- R6::R6Class(
   )
 )
 
-#' Extract (penalized) maximum likelihood estimate after optimization
+#' Extract point estimate after optimization
 #'
 #' @name fit-method-mle
 #' @aliases mle
-#' @description The `$mle()` method is only available for [`CmdStanMLE`] objects.
-#' It returns the penalized maximum likelihood estimate (posterior mode) as a
-#' numeric vector with one element per variable. The returned vector does *not*
-#' include `lp__`, the total log probability (`target`) accumulated in the
-#' model block of the Stan program, which is available via the
-#' [`$lp()`][fit-method-lp] method and also included in the
-#' [`$draws()`][fit-method-draws] method.
+#' @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 total log
+#'   probability (`target`) accumulated in the model block of the Stan program,
+#'   which is available via the [`$lp()`][fit-method-lp] method and also
+#'   included in the [`$draws()`][fit-method-draws] method.
+#'
+#'   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)
@@ -1910,6 +1923,7 @@ mle <- function(variables = NULL) {
 }
 CmdStanMLE$set("public", name = "mle", value = mle)
 
+
 # CmdStanLaplace ---------------------------------------------------------------
 #' CmdStanLaplace objects
 #'

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

man/CmdStanMLE.Rd

@@ -276,6 +276,11 @@ test_that("loo method works if log_lik is available", {
   fit_bernoulli <- testing_fit("bernoulli_log_lik")
   expect_s3_class(suppressWarnings(fit_bernoulli$loo(cores = 1, save_psis = TRUE)), "loo")
   expect_s3_class(suppressWarnings(fit_bernoulli$loo(r_eff = FALSE)), "loo")
+
+  expect_error(
+    fit_bernoulli$loo(variables = c("log_lik", "beta")),
+    "Only a single variable name is allowed"
+  )
 })
 
 test_that("loo method works with moment-matching", {