diff --git a/R/fit.R b/R/fit.R index f9dd4d8d2..c9f043eef 100644 --- a/R/fit.R +++ b/R/fit.R @@ -309,14 +309,16 @@ CmdStanFit$set("public", name = "init", value = init) #' @description The `$init_model_methods()` method compiles and initializes the #' `log_prob`, `grad_log_prob`, `constrain_variables`, `unconstrain_variables` #' and `unconstrain_draws` functions. These are then available as methods of -#' the fitted model object. This requires the `Rcpp` package. +#' the fitted model object. This requires the additional `Rcpp` and +#' `RcppEigen` packages, which are not required for fitting models using +#' CmdStanR. #' #' Note: there may be many compiler warnings emitted during compilation but #' these can be ignored so long as they are warnings and not errors. #' #' @param seed (integer) The random seed to use when initializing the model. -#' @param verbose (boolean) Whether to show verbose logging during compilation. -#' @param hessian (boolean) Whether to expose the (experimental) hessian method. +#' @param verbose (logical) Whether to show verbose logging during compilation. +#' @param hessian (logical) Whether to expose the (experimental) hessian method. #' #' @examples #' \dontrun{ @@ -359,9 +361,10 @@ CmdStanFit$set("public", name = "init_model_methods", value = init_model_methods #' @aliases log_prob #' @description The `$log_prob()` method provides access to the Stan model's `log_prob` function #' -#' @param unconstrained_variables (numeric) A vector of unconstrained parameters to be passed to `log_prob` -#' @param jacobian_adjustment (bool) Whether to include the log-density adjustments from -#' un/constraining variables +#' @param unconstrained_variables (numeric) A vector of unconstrained parameters +#' to be passed to `log_prob`. +#' @param jacobian_adjustment (logical) Whether to include the log-density +#' adjustments from un/constraining variables. #' #' @examples #' \dontrun{ @@ -393,12 +396,12 @@ CmdStanFit$set("public", name = "log_prob", value = log_prob) #' #' @name fit-method-grad_log_prob #' @aliases grad_log_prob -#' @description The `$grad_log_prob()` method provides access to the -#' Stan model's `log_prob` function and its derivative +#' @description The `$grad_log_prob()` method provides access to the Stan +#' model's `log_prob` function and its derivative. #' #' @param unconstrained_variables (numeric) A vector of unconstrained parameters #' to be passed to `grad_log_prob`. -#' @param jacobian_adjustment (bool) Whether to include the log-density +#' @param jacobian_adjustment (logical) Whether to include the log-density #' adjustments from un/constraining variables. #' #' @examples @@ -431,12 +434,12 @@ CmdStanFit$set("public", name = "grad_log_prob", value = grad_log_prob) #' #' @name fit-method-hessian #' @aliases hessian -#' @description The `$hessian()` method provides access to the -#' Stan model's `log_prob`, its derivative, and its hessian +#' @description The `$hessian()` method provides access to the Stan model's +#' `log_prob`, its derivative, and its hessian. #' #' @param unconstrained_variables (numeric) A vector of unconstrained parameters #' to be passed to `hessian`. -#' @param jacobian_adjustment (bool) Whether to include the log-density +#' @param jacobian_adjustment (logical) Whether to include the log-density #' adjustments from un/constraining variables. #' #' @examples @@ -468,8 +471,8 @@ CmdStanFit$set("public", name = "hessian", value = hessian) #' #' @name fit-method-unconstrain_variables #' @aliases unconstrain_variables -#' @description The `$unconstrain_variables()` method transforms input parameters to -#' the unconstrained scale +#' @description The `$unconstrain_variables()` method transforms input +#' parameters to the unconstrained scale. #' #' @param variables (list) A list of parameter values to transform, in the same #' format as provided to the `init` argument of the `$sample()` method. @@ -521,11 +524,12 @@ CmdStanFit$set("public", name = "unconstrain_variables", value = unconstrain_var #' #' @name fit-method-unconstrain_draws #' @aliases unconstrain_draws -#' @description The `$unconstrain_draws()` method transforms all parameter draws to the -#' unconstrained scale. The method returns a list for each chain, containing the parameter -#' values from each iteration on the unconstrained scale. If called with no arguments, then -#' the draws within the fit object are unconstrained. Alternatively, either an existing -#' draws object or a character vector of paths to CSV files can be passed. +#' @description The `$unconstrain_draws()` method transforms all parameter draws +#' to the unconstrained scale. The method returns a list for each chain, +#' containing the parameter values from each iteration on the unconstrained +#' scale. If called with no arguments, then the draws within the fit object +#' are unconstrained. Alternatively, either an existing draws object or a +#' character vector of paths to CSV files can be passed. #' #' @param files (character vector) The paths to the CmdStan CSV files. These can #' be files generated by running CmdStanR or running CmdStan directly. @@ -598,17 +602,17 @@ unconstrain_draws <- function(files = NULL, draws = NULL) { } CmdStanFit$set("public", name = "unconstrain_draws", value = unconstrain_draws) -#' Return the variable skeleton needed by the utils::relist function to re-structure a -#' vector of constrained parameter values to a named list +#' Return the variable skeleton for `relist` #' #' @name fit-method-variable_skeleton #' @aliases variable_skeleton #' @description The `$variable_skeleton()` method returns the variable skeleton -#' -#' @param transformed_parameters (boolean) Whether to include transformed parameters -#' in the skeleton (defaults to TRUE) -#' @param generated_quantities (boolean) Whether to include generated quantities -#' in the skeleton (defaults to TRUE) +#' needed by `utils::relist()` to re-structure a vector of constrained +#' parameter values to a named list. +#' @param transformed_parameters (logical) Whether to include transformed +#' parameters in the skeleton (defaults to `TRUE`). +#' @param generated_quantities (logical) Whether to include generated quantities +#' in the skeleton (defaults to `TRUE`). #' #' @examples #' \dontrun{ @@ -638,14 +642,14 @@ CmdStanFit$set("public", name = "variable_skeleton", value = variable_skeleton) #' #' @name fit-method-constrain_variables #' @aliases constrain_variables -#' @description The `$constrain_variables()` method transforms input parameters to -#' the constrained scale +#' @description The `$constrain_variables()` method transforms input parameters +#' to the constrained scale. #' #' @param unconstrained_variables (numeric) A vector of unconstrained parameters #' to constrain. -#' @param transformed_parameters (boolean) Whether to return transformed +#' @param transformed_parameters (logical) Whether to return transformed #' parameters implied by newly-constrained parameters (defaults to TRUE). -#' @param generated_quantities (boolean) Whether to return generated quantities +#' @param generated_quantities (logical) Whether to return generated quantities #' implied by newly-constrained parameters (defaults to TRUE). #' #' @examples @@ -1435,10 +1439,10 @@ CmdStanMCMC <- R6::R6Class( #' @name fit-method-loo #' @aliases loo #' @description The `$loo()` method computes approximate LOO-CV using the -#' \pkg{loo} package. This is a simple wrapper around [loo::loo.array()] -#' provided for convenience and requires computing the pointwise -#' log-likelihood in your Stan program. See the \pkg{loo} package -#' [vignettes](https://mc-stan.org/loo/articles/) for details. +#' \pkg{loo} package. In order to use this method you must compute and save +#' the pointwise log-likelihood in your Stan program. See [loo::loo.array()] +#' 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 @@ -1451,13 +1455,20 @@ CmdStanMCMC <- R6::R6Class( #' but will result in a warning from the \pkg{loo} package. #' * If `r_eff` is anything else, that object will be passed as the `r_eff` #' argument to [loo::loo.array()]. -#' @param moment_match (boolean) Whether to use a moment-matching correction for -#' for problematic observations. +#' @param moment_match (logical) Whether to use a +#' [moment-matching][loo::loo_moment_match()] correction for problematic +#' observations. The default is `FALSE`. Using `moment_match=TRUE` will result +#' in compiling the additional methods described in +#' [fit-method-init_model_methods]. This allows CmdStanR to automatically +#' supply the functions for the `log_lik_i`, `unconstrain_pars`, +#' `log_prob_upars`, and `log_lik_i_upars` arguments to +#' [loo::loo_moment_match()]. #' @param ... Other arguments (e.g., `cores`, `save_psis`, etc.) passed to #' [loo::loo.array()] or [loo::loo_moment_match.default()] #' (if `moment_match` = `TRUE` is set). #' -#' @return The object returned by [loo::loo.array()]. +#' @return The object returned by [loo::loo.array()] or +#' [loo::loo_moment_match.default()]. #' #' @seealso The \pkg{loo} package website with #' [documentation](https://mc-stan.org/loo/reference/index.html) and diff --git a/man/cmdstanr-package.Rd b/man/cmdstanr-package.Rd index b093d1fbb..5a07aec2c 100644 --- a/man/cmdstanr-package.Rd +++ b/man/cmdstanr-package.Rd @@ -33,15 +33,10 @@ algorithms, and writing results to output files. \subsection{Advantages of RStan}{ \itemize{ -\item Advanced features. We are working on making these available outside of -RStan but currently they are only available to R users via RStan: -\itemize{ -\item \code{rstan::log_prob()} -\item \code{rstan::grad_log_prob()} -\item \code{rstan::expose_stan_functions()} -} \item Allows other developers to distribute R packages with \emph{pre-compiled} Stan programs (like \strong{rstanarm}) on CRAN. +\item Avoids use of R6 classes, which may result in more familiar syntax for +many R users. } } @@ -53,7 +48,6 @@ is complicated for RStan, often requiring non-trivial changes to the \strong{StanHeaders}. With CmdStanR the latest improvements in Stan will be available from R immediately after updating CmdStan using \code{cmdstanr::install_cmdstan()}. -\item Fewer installation issues (e.g., no need to mess with Makevars files). \item Running Stan via external processes results in fewer unexpected crashes, especially in RStudio. \item Less memory overhead. diff --git a/man/fit-method-constrain_variables.Rd b/man/fit-method-constrain_variables.Rd index 78c5b8098..73cdee6fa 100644 --- a/man/fit-method-constrain_variables.Rd +++ b/man/fit-method-constrain_variables.Rd @@ -15,15 +15,15 @@ constrain_variables( \item{unconstrained_variables}{(numeric) A vector of unconstrained parameters to constrain.} -\item{transformed_parameters}{(boolean) Whether to return transformed +\item{transformed_parameters}{(logical) Whether to return transformed parameters implied by newly-constrained parameters (defaults to TRUE).} -\item{generated_quantities}{(boolean) Whether to return generated quantities +\item{generated_quantities}{(logical) Whether to return generated quantities implied by newly-constrained parameters (defaults to TRUE).} } \description{ -The \verb{$constrain_variables()} method transforms input parameters to -the constrained scale +The \verb{$constrain_variables()} method transforms input parameters +to the constrained scale. } \examples{ \dontrun{ diff --git a/man/fit-method-grad_log_prob.Rd b/man/fit-method-grad_log_prob.Rd index ef42d6c3d..1d2cc0de6 100644 --- a/man/fit-method-grad_log_prob.Rd +++ b/man/fit-method-grad_log_prob.Rd @@ -12,12 +12,12 @@ grad_log_prob(unconstrained_variables, jacobian_adjustment = TRUE) \item{unconstrained_variables}{(numeric) A vector of unconstrained parameters to be passed to \code{grad_log_prob}.} -\item{jacobian_adjustment}{(bool) Whether to include the log-density +\item{jacobian_adjustment}{(logical) Whether to include the log-density adjustments from un/constraining variables.} } \description{ -The \verb{$grad_log_prob()} method provides access to the -Stan model's \code{log_prob} function and its derivative +The \verb{$grad_log_prob()} method provides access to the Stan +model's \code{log_prob} function and its derivative. } \examples{ \dontrun{ diff --git a/man/fit-method-hessian.Rd b/man/fit-method-hessian.Rd index fe384c9d9..a5efe2b17 100644 --- a/man/fit-method-hessian.Rd +++ b/man/fit-method-hessian.Rd @@ -12,12 +12,12 @@ hessian(unconstrained_variables, jacobian_adjustment = TRUE) \item{unconstrained_variables}{(numeric) A vector of unconstrained parameters to be passed to \code{hessian}.} -\item{jacobian_adjustment}{(bool) Whether to include the log-density +\item{jacobian_adjustment}{(logical) Whether to include the log-density adjustments from un/constraining variables.} } \description{ -The \verb{$hessian()} method provides access to the -Stan model's \code{log_prob}, its derivative, and its hessian +The \verb{$hessian()} method provides access to the Stan model's +\code{log_prob}, its derivative, and its hessian. } \examples{ \dontrun{ diff --git a/man/fit-method-init_model_methods.Rd b/man/fit-method-init_model_methods.Rd index 165e804a6..c600d6701 100644 --- a/man/fit-method-init_model_methods.Rd +++ b/man/fit-method-init_model_methods.Rd @@ -11,15 +11,17 @@ init_model_methods(seed = 0, verbose = FALSE, hessian = FALSE) \arguments{ \item{seed}{(integer) The random seed to use when initializing the model.} -\item{verbose}{(boolean) Whether to show verbose logging during compilation.} +\item{verbose}{(logical) Whether to show verbose logging during compilation.} -\item{hessian}{(boolean) Whether to expose the (experimental) hessian method.} +\item{hessian}{(logical) Whether to expose the (experimental) hessian method.} } \description{ The \verb{$init_model_methods()} method compiles and initializes the \code{log_prob}, \code{grad_log_prob}, \code{constrain_variables}, \code{unconstrain_variables} and \code{unconstrain_draws} functions. These are then available as methods of -the fitted model object. This requires the \code{Rcpp} package. +the fitted model object. This requires the additional \code{Rcpp} and +\code{RcppEigen} packages, which are not required for fitting models using +CmdStanR. Note: there may be many compiler warnings emitted during compilation but these can be ignored so long as they are warnings and not errors. diff --git a/man/fit-method-log_prob.Rd b/man/fit-method-log_prob.Rd index c35e48431..494135bd5 100644 --- a/man/fit-method-log_prob.Rd +++ b/man/fit-method-log_prob.Rd @@ -8,10 +8,11 @@ log_prob(unconstrained_variables, jacobian_adjustment = TRUE) } \arguments{ -\item{unconstrained_variables}{(numeric) A vector of unconstrained parameters to be passed to \code{log_prob}} +\item{unconstrained_variables}{(numeric) A vector of unconstrained parameters +to be passed to \code{log_prob}.} -\item{jacobian_adjustment}{(bool) Whether to include the log-density adjustments from -un/constraining variables} +\item{jacobian_adjustment}{(logical) Whether to include the log-density +adjustments from un/constraining variables.} } \description{ The \verb{$log_prob()} method provides access to the Stan model's \code{log_prob} function diff --git a/man/fit-method-loo.Rd b/man/fit-method-loo.Rd index 5bbb1492f..7b84ffde5 100644 --- a/man/fit-method-loo.Rd +++ b/man/fit-method-loo.Rd @@ -23,22 +23,29 @@ but will result in a warning from the \pkg{loo} package. argument to \code{\link[loo:loo]{loo::loo.array()}}. }} -\item{moment_match}{(boolean) Whether to use a moment-matching correction for -for problematic observations.} +\item{moment_match}{(logical) Whether to use a +\link[loo:loo_moment_match]{moment-matching} correction for problematic +observations. The default is \code{FALSE}. Using \code{moment_match=TRUE} will result +in compiling the additional methods described in +\link{fit-method-init_model_methods}. This allows CmdStanR to automatically +supply the functions for the \code{log_lik_i}, \code{unconstrain_pars}, +\code{log_prob_upars}, and \code{log_lik_i_upars} arguments to +\code{\link[loo:loo_moment_match]{loo::loo_moment_match()}}.} \item{...}{Other arguments (e.g., \code{cores}, \code{save_psis}, etc.) passed to \code{\link[loo:loo]{loo::loo.array()}} or \code{\link[loo:loo_moment_match]{loo::loo_moment_match.default()}} (if \code{moment_match} = \code{TRUE} is set).} } \value{ -The object returned by \code{\link[loo:loo]{loo::loo.array()}}. +The object returned by \code{\link[loo:loo]{loo::loo.array()}} or +\code{\link[loo:loo_moment_match]{loo::loo_moment_match.default()}}. } \description{ The \verb{$loo()} method computes approximate LOO-CV using the -\pkg{loo} package. This is a simple wrapper around \code{\link[loo:loo]{loo::loo.array()}} -provided for convenience and requires computing the pointwise -log-likelihood in your Stan program. See the \pkg{loo} package -\href{https://mc-stan.org/loo/articles/}{vignettes} for details. +\pkg{loo} package. In order to use this method you must compute and save +the pointwise log-likelihood in your Stan program. See \code{\link[loo:loo]{loo::loo.array()}} +and the \pkg{loo} package \href{https://mc-stan.org/loo/articles/}{vignettes} +for details. } \examples{ diff --git a/man/fit-method-unconstrain_draws.Rd b/man/fit-method-unconstrain_draws.Rd index 6764ecb53..b78e03f03 100644 --- a/man/fit-method-unconstrain_draws.Rd +++ b/man/fit-method-unconstrain_draws.Rd @@ -14,11 +14,12 @@ be files generated by running CmdStanR or running CmdStan directly.} \item{draws}{A \verb{posterior::draws_*} object.} } \description{ -The \verb{$unconstrain_draws()} method transforms all parameter draws to the -unconstrained scale. The method returns a list for each chain, containing the parameter -values from each iteration on the unconstrained scale. If called with no arguments, then -the draws within the fit object are unconstrained. Alternatively, either an existing -draws object or a character vector of paths to CSV files can be passed. +The \verb{$unconstrain_draws()} method transforms all parameter draws +to the unconstrained scale. The method returns a list for each chain, +containing the parameter values from each iteration on the unconstrained +scale. If called with no arguments, then the draws within the fit object +are unconstrained. Alternatively, either an existing draws object or a +character vector of paths to CSV files can be passed. } \examples{ \dontrun{ diff --git a/man/fit-method-unconstrain_variables.Rd b/man/fit-method-unconstrain_variables.Rd index 69c6e308e..cfbf64efa 100644 --- a/man/fit-method-unconstrain_variables.Rd +++ b/man/fit-method-unconstrain_variables.Rd @@ -12,8 +12,8 @@ unconstrain_variables(variables) format as provided to the \code{init} argument of the \verb{$sample()} method.} } \description{ -The \verb{$unconstrain_variables()} method transforms input parameters to -the unconstrained scale +The \verb{$unconstrain_variables()} method transforms input +parameters to the unconstrained scale. } \examples{ \dontrun{ diff --git a/man/fit-method-variable_skeleton.Rd b/man/fit-method-variable_skeleton.Rd index 2116d0ad2..fa8c6955c 100644 --- a/man/fit-method-variable_skeleton.Rd +++ b/man/fit-method-variable_skeleton.Rd @@ -3,20 +3,21 @@ \name{fit-method-variable_skeleton} \alias{fit-method-variable_skeleton} \alias{variable_skeleton} -\title{Return the variable skeleton needed by the utils::relist function to re-structure a -vector of constrained parameter values to a named list} +\title{Return the variable skeleton for \code{relist}} \usage{ variable_skeleton(transformed_parameters = TRUE, generated_quantities = TRUE) } \arguments{ -\item{transformed_parameters}{(boolean) Whether to include transformed parameters -in the skeleton (defaults to TRUE)} +\item{transformed_parameters}{(logical) Whether to include transformed +parameters in the skeleton (defaults to \code{TRUE}).} -\item{generated_quantities}{(boolean) Whether to include generated quantities -in the skeleton (defaults to TRUE)} +\item{generated_quantities}{(logical) Whether to include generated quantities +in the skeleton (defaults to \code{TRUE}).} } \description{ The \verb{$variable_skeleton()} method returns the variable skeleton +needed by \code{utils::relist()} to re-structure a vector of constrained +parameter values to a named list. } \examples{ \dontrun{