diff --git a/DESCRIPTION b/DESCRIPTION index ac155bf6..cb7e1618 100644 --- a/DESCRIPTION +++ b/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: diff --git a/R/fit.R b/R/fit.R index a2126a49..58005ca6 100644 --- a/R/fit.R +++ b/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. diff --git a/R/model.R b/R/model.R index 1fe14615..b7a61ed5 100644 --- a/R/model.R +++ b/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 -} \ No newline at end of file +} diff --git a/man/CmdStanMLE.Rd b/man/CmdStanMLE.Rd index 541f9c15..0fbfedab 100644 --- a/man/CmdStanMLE.Rd +++ b/man/CmdStanMLE.Rd @@ -6,11 +6,13 @@ \description{ A \code{CmdStanMLE} object is the fitted model object returned by the \code{\link[=model-method-optimize]{$optimize()}} method of a \code{\link{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 \code{jacobian} argument when the model is fit (and whether the model has -constrained parameters). See \code{\link[=model-method-optimize]{$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 \emph{or} the unconstrained parameter space, +depending on the value of the \code{jacobian} argument when the model is fit +(and whether the model has constrained parameters). See +\code{\link[=model-method-optimize]{$optimize()}} and the CmdStan User's Guide for +more details. } \section{Methods}{ \code{CmdStanMLE} objects have the following associated methods, diff --git a/man/model-method-optimize.Rd b/man/model-method-optimize.Rd index 70f79c15..6f36bdf1 100644 --- a/man/model-method-optimize.Rd +++ b/man/model-method-optimize.Rd @@ -162,13 +162,12 @@ the CmdStan User's Guide. The default values can also be obtained by running \code{cmdstanr_example(method="optimize")$metadata()}.} \item{jacobian}{(logical) Whether or not to use the Jacobian adjustment for -constrained variables. For historical reasons, the default is \code{FALSE}, meaning optimization -yields the (regularized) maximum likelihood estimate. Setting it to \code{TRUE} -yields the maximum a posteriori estimate. See the -\href{https://mc-stan.org/docs/cmdstan-guide/maximum-likelihood-estimation.html}{Maximum Likelihood Estimation} -section of the CmdStan User's Guide for more details. -For use later with \code{\link[=model-method-laplace]{$laplace()}} the \code{jacobian} -argument should typically be set to \code{TRUE}.} +constrained variables. For historical reasons, the default is \code{FALSE}, +meaning optimization finds a mode of the target in the original constrained +parameter space. Setting it to \code{TRUE} finds a mode in the unconstrained +space. See the CmdStan User's Guide for more details. For use later with +\code{\link[=model-method-laplace]{$laplace()}} the \code{jacobian} argument should +typically be set to \code{TRUE}.} \item{init_alpha}{(positive real) The initial step size parameter.} @@ -210,14 +209,18 @@ A \code{\link{CmdStanMLE}} object. } \description{ The \verb{$optimize()} method of a \code{\link{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 -\code{jacobian} argument. For models with constrained parameters, when the -Jacobian adjustment is \emph{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, \link[=model-method-laplace]{Laplace sampling}, 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 \href{https://mc-stan.org/docs/cmdstan-guide/index.html}{CmdStan User's Guide} for more details.