Merge pull request #794 from stan-dev/next-release

cmdstanr v0.6.0

Author: jgabry

.Rbuildignore

@@ -7,8 +7,8 @@
 ^docs$
 ^pkgdown$
 ^man-roxygen$
-^dev-helpers\.R$
 ^LICENSE\.md$
 ^\.appveyor\.yml$
 ^\.github$
 ^vignettes/articles-online-only$
+^release-prep\.R$

.gitignore

@@ -4,6 +4,6 @@
 .Ruserdata
 .vscode/*
 
-design-questions/*
 inst/doc
 dev-helpers.R
+release-prep.R

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: cmdstanr
 Title: R Interface to 'CmdStan'
-Version: 0.5.3
-Date: 2022-04-24
+Version: 0.6.0
+Date: 2023-07-25
 Authors@R:
     c(person(given = "Jonah", family = "Gabry", role = c("aut", "cre"),
            email = "[email protected]"),

NEWS.md

@@ -1,3 +1,37 @@
+# cmdstanr 0.6.0
+
+### Major new features
+
+* New `expose_functions()` method to expose Stan functions to R by @andrjohns in #702. See `?expose_functions`.
+* New methods for accessing log_prob, grad_log_prob, hessian, un/constrain variables by @andrjohns in #701. See `?init_model_methods`. 
+
+### Other changes
+
+* mod$variables works w includes in precompile state (fix #680) by @MKyhos in #682
+* Update broken link for Stan OpenCL support page by @erictleung in #686
+* Add newline to check syntax output by @rok-cesnovar in #689
+* Allow exposing functions without sampling by @andrjohns in #705
+* Expose skeleton by @andrjohns in #706
+* WSL - Run cmdstan and models under WSL filesystem by @andrjohns in #696
+* Bugfix - Deep copy method/function environments by @andrjohns in #709
+* Add option for including jacobian adjustments in hessian method by @andrjohns in #710
+* WSL Optimisations and Bugfixes for CI by @andrjohns in #711
+* add stancflags from make/local by @rok-cesnovar in #690
+* Update co-authors by @andrjohns in #715
+* Update model methods parameter naming and extract skeleton function by @andrjohns in #724
+* Add method for unconstraining all parameter draws by @andrjohns in #729
+* Improve efficiency of variable matching by @sbfnk in #736
+* Add verbosity to download output and errors by @andrjohns in #745
+* Update handling of show_messages, add show_exceptions by @andrjohns in #746
+* Rtools43 support by @andrjohns in #755
+* Add stanc M1 make patch, suppress boost warnings by @andrjohns in #756
+* more examples of summary method by @gravesti in #751
+* Fix model$format and model$check_syntax for compiled models with include-paths by @adrian-lison in #775
+* Generalise RTools config/support by @andrjohns in #777
+* New posterior vignette by @gravesti in #719
+* Add moment-matching support to $loo() method by @andrjohns in #778
+* replace \ with function by @jsocolar in #789
+
 # cmdstanr 0.5.3
 
 ### New features

R/csv.R

@@ -422,7 +422,7 @@ read_cmdstan_csv <- function(files,
 #' Read CmdStan CSV files from sampling into \R
 #'
 #' Deprecated. Use [read_cmdstan_csv()] instead.
-#'
+#' @keywords internal
 #' @export
 #' @param files,variables,sampler_diagnostics Deprecated. Use
 #'   [read_cmdstan_csv()] instead.

R/example.R

@@ -188,7 +188,7 @@ write_stan_file <- function(code,
 #' Write Stan code to a temporary file
 #'
 #' This function is deprecated. Please use [write_stan_file()] instead.
-#'
+#' @keywords internal
 #' @export
 #' @inheritParams write_stan_file
 write_stan_tempfile <- function(code, dir = tempdir()) {

R/fit.R

@@ -82,7 +82,7 @@ CmdStanFit <- R6::R6Class(
       invisible(self)
     },
     expose_functions = function(global = FALSE, verbose = FALSE) {
-      expose_functions(self$functions, global, verbose)
+      expose_stan_functions(self$functions, global, verbose)
       invisible(NULL)
     }
   ),
@@ -301,12 +301,18 @@ init <- function() {
 CmdStanFit$set("public", name = "init", value = init)
 
 #' Compile additional methods for accessing the model log-probability function
-#' and parameter constraining and unconstraining. This requires the `Rcpp` package.
+#' and parameter constraining and unconstraining.
 #'
 #' @name fit-method-init_model_methods
 #' @aliases init_model_methods
-#' @description The `$init_model_methods()` compiles and initializes the
-#' `log_prob`, `grad_log_prob`, `constrain_variables`, and `unconstrain_variables` functions.
+#'
+#' @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.
+#'
+#'   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.
@@ -317,6 +323,9 @@ CmdStanFit$set("public", name = "init", value = init)
 #' fit_mcmc <- cmdstanr_example("logistic", method = "sample")
 #' fit_mcmc$init_model_methods()
 #' }
+#' @seealso [log_prob()], [grad_log_prob()], [constrain_variables()],
+#'   [unconstrain_variables()], [unconstrain_draws()], [variable_skeleton()],
+#'   [hessian()]
 #'
 init_model_methods <- function(seed = 0, verbose = FALSE, hessian = FALSE) {
   if (os_is_wsl()) {
@@ -358,9 +367,13 @@ CmdStanFit$set("public", name = "init_model_methods", value = init_model_methods
 #' \dontrun{
 #' fit_mcmc <- cmdstanr_example("logistic", method = "sample")
 #' fit_mcmc$init_model_methods()
-#' fit_mcmc$log_prob(unconstrained_variables = c(0.5, 1.2, 1.1, 2.2, 1.1))
+#' fit_mcmc$log_prob(unconstrained_variables = c(0.5, 1.2, 1.1, 2.2))
 #' }
 #'
+#' @seealso [log_prob()], [grad_log_prob()], [constrain_variables()],
+#'   [unconstrain_variables()], [unconstrain_draws()], [variable_skeleton()],
+#'   [hessian()]
+#'
 log_prob <- function(unconstrained_variables, jacobian_adjustment = TRUE) {
   if (is.null(private$model_methods_env_$model_ptr)) {
     stop("The method has not been compiled, please call `init_model_methods()` first",
@@ -383,18 +396,22 @@ CmdStanFit$set("public", name = "log_prob", value = log_prob)
 #' @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 adjustments from
-#' un/constraining variables
+#' @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
+#'   adjustments from un/constraining variables.
 #'
 #' @examples
 #' \dontrun{
 #' fit_mcmc <- cmdstanr_example("logistic", method = "sample")
 #' fit_mcmc$init_model_methods()
-#' fit_mcmc$grad_log_prob(unconstrained_variables = c(0.5, 1.2, 1.1, 2.2, 1.1))
+#' fit_mcmc$grad_log_prob(unconstrained_variables = c(0.5, 1.2, 1.1, 2.2))
 #' }
 #'
+#' @seealso [log_prob()], [grad_log_prob()], [constrain_variables()],
+#'   [unconstrain_variables()], [unconstrain_draws()], [variable_skeleton()],
+#'   [hessian()]
+#'
 grad_log_prob <- function(unconstrained_variables, jacobian_adjustment = TRUE) {
   if (is.null(private$model_methods_env_$model_ptr)) {
     stop("The method has not been compiled, please call `init_model_methods()` first",
@@ -417,18 +434,22 @@ CmdStanFit$set("public", name = "grad_log_prob", value = grad_log_prob)
 #' @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 adjustments from
-#' un/constraining variables
+#' @param unconstrained_variables (numeric) A vector of unconstrained parameters
+#'   to be passed to `hessian`.
+#' @param jacobian_adjustment (bool) Whether to include the log-density
+#'   adjustments from un/constraining variables.
 #'
 #' @examples
 #' \dontrun{
-#' fit_mcmc <- cmdstanr_example("logistic", method = "sample")
-#' fit_mcmc$init_model_methods()
-#' fit_mcmc$hessian(unconstrained_variables = c(0.5, 1.2, 1.1, 2.2, 1.1))
+#' # fit_mcmc <- cmdstanr_example("logistic", method = "sample")
+#' # fit_mcmc$init_model_methods(hessian = TRUE)
+#' # fit_mcmc$hessian(unconstrained_variables = c(0.5, 1.2, 1.1, 2.2))
 #' }
 #'
+#' @seealso [log_prob()], [grad_log_prob()], [constrain_variables()],
+#'   [unconstrain_variables()], [unconstrain_draws()], [variable_skeleton()],
+#'   [hessian()]
+#'
 hessian <- function(unconstrained_variables, jacobian_adjustment = TRUE) {
   if (is.null(private$model_methods_env_$model_ptr)) {
     stop("The method has not been compiled, please call `init_model_methods()` first",
@@ -450,8 +471,8 @@ CmdStanFit$set("public", name = "hessian", value = hessian)
 #' @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
+#' @param variables (list) A list of parameter values to transform, in the same
+#'   format as provided to the `init` argument of the `$sample()` method.
 #'
 #' @examples
 #' \dontrun{
@@ -460,6 +481,10 @@ CmdStanFit$set("public", name = "hessian", value = hessian)
 #' fit_mcmc$unconstrain_variables(list(alpha = 0.5, beta = c(0.7, 1.1, 0.2)))
 #' }
 #'
+#' @seealso [log_prob()], [grad_log_prob()], [constrain_variables()],
+#'   [unconstrain_variables()], [unconstrain_draws()], [variable_skeleton()],
+#'   [hessian()]
+#'
 unconstrain_variables <- function(variables) {
   if (is.null(private$model_methods_env_$model_ptr)) {
     stop("The method has not been compiled, please call `init_model_methods()` first",
@@ -521,6 +546,10 @@ CmdStanFit$set("public", name = "unconstrain_variables", value = unconstrain_var
 #' unconstrained_draws <- fit_mcmc$unconstrain_draws(draws = fit_mcmc$draws())
 #' }
 #'
+#' @seealso [log_prob()], [grad_log_prob()], [constrain_variables()],
+#'   [unconstrain_variables()], [unconstrain_draws()], [variable_skeleton()],
+#'   [hessian()]
+#'
 unconstrain_draws <- function(files = NULL, draws = NULL) {
   if (!is.null(files) || !is.null(draws)) {
     if (!is.null(files) && !is.null(draws)) {
@@ -565,6 +594,7 @@ unconstrain_draws <- function(files = NULL, draws = NULL) {
       self$unconstrain_variables(variables = par_list)
     })
   })
+  unconstrained
 }
 CmdStanFit$set("public", name = "unconstrain_draws", value = unconstrain_draws)
 
@@ -587,6 +617,10 @@ CmdStanFit$set("public", name = "unconstrain_draws", value = unconstrain_draws)
 #' fit_mcmc$variable_skeleton()
 #' }
 #'
+#' @seealso [log_prob()], [grad_log_prob()], [constrain_variables()],
+#'   [unconstrain_variables()], [unconstrain_draws()], [variable_skeleton()],
+#'   [hessian()]
+#'
 variable_skeleton <- function(transformed_parameters = TRUE, generated_quantities = TRUE) {
   if (is.null(private$model_methods_env_$model_ptr)) {
     stop("The method has not been compiled, please call `init_model_methods()` first",
@@ -607,19 +641,24 @@ CmdStanFit$set("public", name = "variable_skeleton", value = variable_skeleton)
 #' @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 parameters
-#'  implied by newly-constrained parameters (defaults to TRUE)
+#' @param unconstrained_variables (numeric) A vector of unconstrained parameters
+#'   to constrain.
+#' @param transformed_parameters (boolean) Whether to return transformed
+#'   parameters implied by newly-constrained parameters (defaults to TRUE).
 #' @param generated_quantities (boolean) Whether to return generated quantities
-#'  implied by newly-constrained parameters (defaults to TRUE)
+#'   implied by newly-constrained parameters (defaults to TRUE).
 #'
 #' @examples
 #' \dontrun{
 #' fit_mcmc <- cmdstanr_example("logistic", method = "sample")
 #' fit_mcmc$init_model_methods()
-#' fit_mcmc$constrain_variables(unconstrained_variables = c(0.5, 1.2, 1.1, 2.2, 1.1))
+#' fit_mcmc$constrain_variables(unconstrained_variables = c(0.5, 1.2, 1.1, 2.2))
 #' }
 #'
+#' @seealso [log_prob()], [grad_log_prob()], [constrain_variables()],
+#'   [unconstrain_variables()], [unconstrain_draws()], [variable_skeleton()],
+#'   [hessian()]
+#'
 constrain_variables <- function(unconstrained_variables, transformed_parameters = TRUE,
                             generated_quantities = TRUE) {
   if (is.null(private$model_methods_env_$model_ptr)) {
@@ -1233,6 +1272,20 @@ CmdStanFit$set("public", name = "code", value = code)
 #'  [`$time()`][fit-method-time]  |  Report total and chain-specific run times. |
 #'  [`$return_codes()`][fit-method-return_codes]  |  Return the return codes from the CmdStan runs. |
 #'
+#'  ## Expose Stan functions and additional methods to R
+#'
+#'  |**Method**|**Description**|
+#'  |:----------|:---------------|
+#'  [`$expose_functions()`][fit-method-expose_functions] |  Expose Stan functions for use in R. |
+#'  [`$init_model_methods()`][fit-method-init_model_methods] | Expose methods for log-probability, gradients, parameter constraining and unconstraining. |
+#'  [`$log_prob()`][fit-method-log_prob] | Calculate log-prob. |
+#'  [`$grad_log_prob()`][fit-method-grad_log_prob] | Calculate log-prob and gradient. |
+#'  [`$hessian()`][fit-method-hessian] | Calculate log-prob, gradient, and hessian. |
+#'  [`$constrain_variables()`][fit-method-constrain_variables] | Transform a set of unconstrained parameter values to the constrained scale. |
+#'  [`$unconstrain_variables()`][fit-method-unconstrain_variables] | Transform a set of parameter values to the unconstrained scale. |
+#'  [`$unconstrain_draws()`][fit-method-unconstrain_draws] | Transform all parameter draws to the unconstrained scale. |
+#'  [`$variable_skeleton()`][fit-method-variable_skeleton] | Helper function to re-structure a vector of constrained parameter values. |
+#'
 CmdStanMCMC <- R6::R6Class(
   classname = "CmdStanMCMC",
   inherit = CmdStanFit,
@@ -1718,6 +1771,20 @@ CmdStanMCMC$set("public", name = "num_chains", value = num_chains)
 #'  [`$output()`][fit-method-output]  |  Pretty print the output that was printed to the console. |
 #'  [`$return_codes()`][fit-method-return_codes]  |  Return the return codes from the CmdStan runs. |
 #'
+#'  ## Expose Stan functions and additional methods to R
+#'
+#'  |**Method**|**Description**|
+#'  |:----------|:---------------|
+#'  [`$expose_functions()`][fit-method-expose_functions] |  Expose Stan functions for use in R. |
+#'  [`$init_model_methods()`][fit-method-init_model_methods] | Expose methods for log-probability, gradients, parameter constraining and unconstraining. |
+#'  [`$log_prob()`][fit-method-log_prob] | Calculate log-prob. |
+#'  [`$grad_log_prob()`][fit-method-grad_log_prob] | Calculate log-prob and gradient. |
+#'  [`$hessian()`][fit-method-hessian] | Calculate log-prob, gradient, and hessian. |
+#'  [`$constrain_variables()`][fit-method-constrain_variables] | Transform a set of unconstrained parameter values to the constrained scale. |
+#'  [`$unconstrain_variables()`][fit-method-unconstrain_variables] | Transform a set of parameter values to the unconstrained scale. |
+#'  [`$unconstrain_draws()`][fit-method-unconstrain_draws] | Transform all parameter draws to the unconstrained scale. |
+#'  [`$variable_skeleton()`][fit-method-variable_skeleton] | Helper function to re-structure a vector of constrained parameter values. |
+#'
 CmdStanMLE <- R6::R6Class(
   classname = "CmdStanMLE",
   inherit = CmdStanFit,
@@ -1821,6 +1888,20 @@ CmdStanMLE$set("public", name = "mle", value = mle)
 #'  [`$output()`][fit-method-output]  |  Pretty print the output that was printed to the console. |
 #'  [`$return_codes()`][fit-method-return_codes]  |  Return the return codes from the CmdStan runs. |
 #'
+#'  ## Expose Stan functions and additional methods to R
+#'
+#'  |**Method**|**Description**|
+#'  |:----------|:---------------|
+#'  [`$expose_functions()`][fit-method-expose_functions] |  Expose Stan functions for use in R. |
+#'  [`$init_model_methods()`][fit-method-init_model_methods] | Expose methods for log-probability, gradients, parameter constraining and unconstraining. |
+#'  [`$log_prob()`][fit-method-log_prob] | Calculate log-prob. |
+#'  [`$grad_log_prob()`][fit-method-grad_log_prob] | Calculate log-prob and gradient. |
+#'  [`$hessian()`][fit-method-hessian] | Calculate log-prob, gradient, and hessian. |
+#'  [`$constrain_variables()`][fit-method-constrain_variables] | Transform a set of unconstrained parameter values to the constrained scale. |
+#'  [`$unconstrain_variables()`][fit-method-unconstrain_variables] | Transform a set of parameter values to the unconstrained scale. |
+#'  [`$unconstrain_draws()`][fit-method-unconstrain_draws] | Transform all parameter draws to the unconstrained scale. |
+#'  [`$variable_skeleton()`][fit-method-variable_skeleton] | Helper function to re-structure a vector of constrained parameter values. |
+#'
 CmdStanVB <- R6::R6Class(
   classname = "CmdStanVB",
   inherit = CmdStanFit,