Merge pull request #871 from stan-dev/prep-v0.7.0

Prepare release of CmdStanR v0.7.0

.github/CONTRIBUTING.md

@@ -0,0 +1,56 @@
+# Contributing to cmdstanr
+
+This outlines how to propose a change to cmdstanr and is based on similar
+instructions for tidyverse packages, including the contributing guidelines
+generated by `usethis::use_tidy_contributing()`.
+
+## Fixing typos
+
+You can fix typos, spelling mistakes, or grammatical errors in the documentation
+directly using the GitHub web interface, as long as the changes are made in the
+_source_ file. This generally means you'll need to edit 
+[roxygen2 comments](https://roxygen2.r-lib.org/articles/roxygen2.html) in an `.R`, 
+not a `.Rd` file. You can find the `.R` file that generates the `.Rd` by reading
+the comment in the first line.
+
+## Bigger changes
+
+If you want to make a bigger change, it's a good idea to first file an issue and
+make sure someone from the team agrees that it’s needed. If you’ve found a bug,
+please file an issue that illustrates the bug with a minimal reproducible
+example (see e.g. the [tidyverse reprex instructions](https://www.tidyverse.org/help/#reprex)). 
+The tidyverse guide on [how to create a great issue](https://code-review.tidyverse.org/issues/) 
+has more advice.
+
+### Pull request process
+
+If you are new to creating pull requests here are some tips. Using the functions
+from the `usethis` package is not required but can be helpful if this process is
+new to you.
+
+*   Fork the package and clone onto your computer. If you haven't done this before, we recommend using `usethis::create_from_github("stan-dev/cmdstanr", fork = TRUE)`.
+
+*   Install all development dependencies with `devtools::install_dev_deps()`, and then make sure the package passes R CMD check by running `devtools::check()`. 
+    If R CMD check doesn't pass cleanly, it's a good idea to ask for help before continuing. 
+*   Create a Git branch for your pull request (PR). We recommend using `usethis::pr_init("brief-description-of-change")`.
+
+*   Make your changes, commit to git, and then create a PR by running `usethis::pr_push()`, and following the prompts in your browser.
+    The title of your PR should briefly describe the change.
+    The body of your PR should contain `Fixes #issue-number`.
+
+*  For user-facing changes, add a bullet to the top of `NEWS.md` (i.e. just below the first header). Follow the style already used in `NEWS.md`.
+
+### Code style
+
+*   New code should attempt to follow the style used in the package. When in doubt follow the tidyverse [style guide](https://style.tidyverse.org). 
+
+*  We use [roxygen2](https://cran.r-project.org/package=roxygen2), with [Markdown syntax](https://cran.r-project.org/web/packages/roxygen2/vignettes/rd-formatting.html), for documentation.  
+
+*  We use [testthat](https://cran.r-project.org/package=testthat) for unit tests. 
+   Contributions with test cases included are easier to accept.  
+
+## Code of Conduct
+
+Please note that the cmdstanr project follows the Stan project's 
+[Code of Conduct](https://discourse.mc-stan.org/t/announcing-our-new-stan-code-of-conduct/23764).
+By contributing to this project you agree to abide by its terms.

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: cmdstanr
 Title: R Interface to 'CmdStan'
-Version: 0.6.1.9000
-Date: 2023-08-25
+Version: 0.7.0
+Date: 2023-12-13
 Authors@R:
     c(person(given = "Jonah", family = "Gabry", role = c("aut", "cre"),
            email = "[email protected]"),
@@ -45,6 +45,7 @@ Imports:
     rlang (>= 0.4.7)
 Suggests:
     bayesplot,
+    ggplot2,
     knitr (>= 1.37),
     loo (>= 2.0.0),
     rmarkdown,

NEWS.md

@@ -1,4 +1,24 @@
-# cmdstanr 0.6.1.9000
+# cmdstanr 0.7.0
+
+## Major new features 
+
+* New `laplace` method by @jgabry in #800
+* New `pathfinder` method by @SteveBronder in #848
+
+## Other improvements and bug fixes
+
+* Add missing link to diagnose method in CmdStanModel doc by @jgabry in #833
+* Improvements to compile tests by @martinmodrak in #836
+* Changed the delay behavior in wsl_installed by @martinmodrak in #839
+* Update array syntax in website vignette by @andrjohns in #841
+* Compatibility fixes for cmdstan 2.33+ by @jgabry in #843
+* Suggest format method after error due to old syntax  by @jgabry in #852
+* Clarifications in R-markdown vignette by @jgcolman in #854
+* Update linux/wsl detection for install arch by @andrjohns in #856
+* Fix handling of single-length inits for containers by @andrjohns in #857
+* Add support/tests for exposing functions with tuples by @andrjohns in #860
+* Add support/tests for exporting functions with complex types by @andrjohns in #861
+* Add option for installing from release archive by @andrjohns in #866
 
 # cmdstanr 0.6.1
 

R/fit.R

@@ -362,12 +362,13 @@ CmdStanFit$set("public", name = "init_model_methods", value = init_model_methods
 #'
 #' @name fit-method-log_prob
 #' @aliases log_prob
-#' @description The `$log_prob()` method provides access to the Stan model's `log_prob` function
+#' @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 (logical) Whether to include the log-density
-#'   adjustments from un/constraining variables.
+#' @param unconstrained_variables (numeric) A vector of unconstrained parameters.
+#' @param jacobian (logical) Whether to include the log-density adjustments from
+#'   un/constraining variables.
+#' @param jacobian_adjustment Deprecated. Please use `jacobian` instead.
 #'
 #' @examples
 #' \dontrun{
@@ -380,7 +381,11 @@ CmdStanFit$set("public", name = "init_model_methods", value = init_model_methods
 #'   [unconstrain_variables()], [unconstrain_draws()], [variable_skeleton()],
 #'   [hessian()]
 #'
-log_prob <- function(unconstrained_variables, jacobian_adjustment = TRUE) {
+log_prob <- function(unconstrained_variables, jacobian = TRUE, jacobian_adjustment = NULL) {
+  if (!is.null(jacobian_adjustment)) {
+    warning("'jacobian_adjustment' is deprecated. Please use 'jacobian' instead.", call. = FALSE)
+    jacobian <- jacobian_adjustment
+  }
   if (is.null(private$model_methods_env_$model_ptr)) {
     stop("The method has not been compiled, please call `init_model_methods()` first",
         call. = FALSE)
@@ -390,7 +395,7 @@ log_prob <- function(unconstrained_variables, jacobian_adjustment = TRUE) {
           length(unconstrained_variables), " were provided!", call. = FALSE)
   }
   private$model_methods_env_$log_prob(private$model_methods_env_$model_ptr_,
-                                      unconstrained_variables, jacobian_adjustment)
+                                      unconstrained_variables, jacobian)
 }
 CmdStanFit$set("public", name = "log_prob", value = log_prob)
 
@@ -401,11 +406,7 @@ CmdStanFit$set("public", name = "log_prob", value = 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.
-#'
-#' @param unconstrained_variables (numeric) A vector of unconstrained parameters
-#'   to be passed to `grad_log_prob`.
-#' @param jacobian_adjustment (logical) Whether to include the log-density
-#'   adjustments from un/constraining variables.
+#' @inheritParams fit-method-log_prob
 #'
 #' @examples
 #' \dontrun{
@@ -418,7 +419,11 @@ CmdStanFit$set("public", name = "log_prob", value = log_prob)
 #'   [unconstrain_variables()], [unconstrain_draws()], [variable_skeleton()],
 #'   [hessian()]
 #'
-grad_log_prob <- function(unconstrained_variables, jacobian_adjustment = TRUE) {
+grad_log_prob <- function(unconstrained_variables, jacobian = TRUE, jacobian_adjustment = NULL) {
+  if (!is.null(jacobian_adjustment)) {
+    warning("'jacobian_adjustment' is deprecated. Please use 'jacobian' instead.", call. = FALSE)
+    jacobian <- jacobian_adjustment
+  }
   if (is.null(private$model_methods_env_$model_ptr)) {
     stop("The method has not been compiled, please call `init_model_methods()` first",
         call. = FALSE)
@@ -428,7 +433,7 @@ grad_log_prob <- function(unconstrained_variables, jacobian_adjustment = TRUE) {
           length(unconstrained_variables), " were provided!", call. = FALSE)
   }
   private$model_methods_env_$grad_log_prob(private$model_methods_env_$model_ptr_,
-                                            unconstrained_variables, jacobian_adjustment)
+                                            unconstrained_variables, jacobian)
 }
 CmdStanFit$set("public", name = "grad_log_prob", value = grad_log_prob)
 
@@ -439,11 +444,7 @@ CmdStanFit$set("public", name = "grad_log_prob", value = grad_log_prob)
 #' @aliases 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 (logical) Whether to include the log-density
-#'   adjustments from un/constraining variables.
+#' @inheritParams fit-method-log_prob
 #'
 #' @examples
 #' \dontrun{
@@ -456,7 +457,11 @@ CmdStanFit$set("public", name = "grad_log_prob", value = grad_log_prob)
 #'   [unconstrain_variables()], [unconstrain_draws()], [variable_skeleton()],
 #'   [hessian()]
 #'
-hessian <- function(unconstrained_variables, jacobian_adjustment = TRUE) {
+hessian <- function(unconstrained_variables, jacobian = TRUE, jacobian_adjustment = NULL) {
+  if (!is.null(jacobian_adjustment)) {
+    warning("'jacobian_adjustment' is deprecated. Please use 'jacobian' instead.", call. = FALSE)
+    jacobian <- jacobian_adjustment
+  }
   if (is.null(private$model_methods_env_$model_ptr)) {
     stop("The method has not been compiled, please call `init_model_methods()` first",
         call. = FALSE)
@@ -466,7 +471,7 @@ hessian <- function(unconstrained_variables, jacobian_adjustment = TRUE) {
           length(unconstrained_variables), " were provided!", call. = FALSE)
   }
   private$model_methods_env_$hessian(private$model_methods_env_$model_ptr_,
-                                      unconstrained_variables, jacobian_adjustment)
+                                      unconstrained_variables, jacobian)
 }
 CmdStanFit$set("public", name = "hessian", value = hessian)
 

R/model.R

@@ -1,6 +1,6 @@
 #' Create a new CmdStanModel object
 #'
-#' @description \if{html}{\figure{logo.png}{options: width="25px"}}
+#' @description \if{html}{\figure{logo.png}{options: width=25}}
 #'   Create a new [`CmdStanModel`] object from a file containing a Stan program
 #'   or from an existing Stan executable. The [`CmdStanModel`] object stores the
 #'   path to a Stan program and compiled executable (once created), and provides
@@ -93,7 +93,7 @@
 #' fit_optim <- mod$optimize(data = my_data_file, seed = 123)
 #' fit_optim$summary()
 #'
-#' # Run 'optimize' again with 'jacobian=TRUE' and then draw from laplace approximation
+#' # Run 'optimize' again with 'jacobian=TRUE' and then draw from Laplace approximation
 #' # to the posterior
 #' fit_optim <- mod$optimize(data = my_data_file, jacobian = TRUE)
 #' fit_laplace <- mod$laplace(data = my_data_file, mode = fit_optim, draws = 2000)
@@ -109,6 +109,11 @@
 #' fit_pf$summary()
 #' mcmc_hist(fit_pf$draws("theta"))
 #'
+#' # Run 'pathfinder' again with more paths, fewer draws per path,
+#' # better covariance approximation, and fewer LBFGSs iterations
+#' fit_pf <- mod$pathfinder(data = stan_data, num_paths=10, single_path_draws=40,
+#'                          history_size=50, max_lbfgs_iters=100)
+#'
 #' # Specifying initial values as a function
 #' fit_mcmc_w_init_fun <- mod$sample(
 #'   data = stan_data,
@@ -376,7 +381,7 @@ CmdStanModel <- R6::R6Class(
 #' @param pedantic (logical) Should pedantic mode be turned on? The default is
 #'   `FALSE`. Pedantic mode attempts to warn you about potential issues in your
 #'   Stan program beyond syntax errors. For details see the [*Pedantic mode*
-#'   chapter](https://mc-stan.org/docs/reference-manual/pedantic-mode.html) in
+#'   chapter](https://mc-stan.org/docs/stan-users-guide/pedantic-mode.html) in
 #'   the Stan Reference Manual. **Note:** to do a pedantic check for a model
 #'   without compiling it or for a model that is already compiled the
 #'   [`$check_syntax()`][model-method-check_syntax] method can be used instead.
@@ -792,7 +797,7 @@ CmdStanModel$set("public", name = "variables", value = variables)
 #' @param pedantic (logical) Should pedantic mode be turned on? The default is
 #'   `FALSE`. Pedantic mode attempts to warn you about potential issues in your
 #'   Stan program beyond syntax errors. For details see the [*Pedantic mode*
-#'   chapter](https://mc-stan.org/docs/reference-manual/pedantic-mode.html) in
+#'   chapter](https://mc-stan.org/docs/stan-users-guide/pedantic-mode.html) in
 #'   the Stan Reference Manual.
 #' @param include_paths (character vector) Paths to directories where Stan
 #'   should look for files specified in `#include` directives in the Stan
@@ -1268,7 +1273,7 @@ CmdStanModel$set("public", name = "sample", value = sample)
 #'
 #' @description The `$sample_mpi()` method of a [`CmdStanModel`] object is
 #'   identical to the `$sample()` method but with support for
-#'   [MPI](https://mc-stan.org/math/mpi.html). The target audience for MPI are
+#'   MPI (message passing interface). The target audience for MPI are
 #'   those with large computer clusters. For other users, the
 #'   [`$sample()`][model-method-sample] method provides both parallelization of
 #'   chains and threading support for within-chain parallelization.
@@ -1308,8 +1313,8 @@ CmdStanModel$set("public", name = "sample", value = sample)
 #' @return A [`CmdStanMCMC`] object.
 #'
 #' @template seealso-docs
-#' @seealso The Stan Math Library's MPI documentation
-#'   ([mc-stan.org/math/mpi](https://mc-stan.org/math/mpi.html)) for more
+#' @seealso The Stan Math Library's documentation
+#'   ([mc-stan.org/math](https://mc-stan.org/math/)) for more
 #'   details on MPI support in Stan.
 #'
 #' @examples
@@ -1539,7 +1544,7 @@ optimize <- function(data = NULL,
 CmdStanModel$set("public", name = "optimize", value = optimize)
 
 
-#' Run Stan's laplace algorithm
+#' Run Stan's Laplace algorithm
 #'
 #' @name model-method-laplace
 #' @aliases laplace
@@ -1828,12 +1833,15 @@ CmdStanModel$set("public", name = "variational", value = variational)
 #' @description The `$pathfinder()` method of a [`CmdStanModel`] object runs
 #'   Stan's Pathfinder algorithms. Pathfinder is a variational method for
 #'   approximately sampling from differentiable log densities. Starting from a
-#'   random initialization, Pathfinder locates normal approximations to the
-#'   target density along a quasi-Newton optimization path, with local
-#'   covariance estimated using the negative inverse Hessian estimates produced
-#'   by the L-BFGS optimizer. Pathfinder returns draws from the Gaussian
-#'   approximation with the lowest estimated Kullback-Leibler (KL) divergence to
-#'   the true posterior. See the
+#'   random initialization, Pathfinder locates normal approximations
+#'   to the target density along a quasi-Newton optimization path in
+#'   the unconstrained space, with local covariance estimated using
+#'   the negative inverse Hessian estimates produced by the LBFGS
+#'   optimizer. Pathfinder selects the normal approximation with the
+#'   lowest estimated Kullback-Leibler (KL) divergence to the true
+#'   posterior. Finally Pathfinder draws from that normal
+#'   approximation and returns the draws transformed to the
+#'   constrained scale. See the
 #'   [CmdStan User’s Guide](https://mc-stan.org/docs/cmdstan-guide/)
 #'   for more details.
 #'
@@ -1857,8 +1865,9 @@ CmdStanModel$set("public", name = "variational", value = variational)
 #'   pathfinder should return. The number of draws PSIS sampling samples from
 #'   will be equal to `single_path_draws * num_paths`.
 #' @param draws (positive integer) Number of draws to return after performing
-#'   pareto smooted importance sampling (PSIS). This must be smaller than
-#'   `single_path_draws * num_paths`.
+#'   pareto smooted importance sampling (PSIS). This should be smaller than
+#'   `single_path_draws * num_paths` (future versions of CmdStan will throw a
+#'   warning).
 #' @param num_paths (positive integer) Number of single pathfinders to run.
 #' @param max_lbfgs_iters (positive integer) The maximum number of iterations
 #'   for LBFGS.
@@ -1904,23 +1913,26 @@ pathfinder <- function(data = NULL,
     model_variables <- self$variables()
   }
   pathfinder_args <- PathfinderArgs$new(
-   init_alpha = init_alpha,
-   tol_obj = tol_obj,
-   tol_rel_obj = tol_rel_obj,
-   tol_grad = tol_grad,
-   tol_rel_grad = tol_rel_grad,
-   tol_param = tol_param,
-   history_size = history_size,
-   draws = draws,
-   single_path_draws = single_path_draws,
-   num_paths = num_paths,
-   max_lbfgs_iters = max_lbfgs_iters,
-   num_elbo_draws = num_elbo_draws,
-   save_single_paths = save_single_paths)
+    init_alpha = init_alpha,
+    tol_obj = tol_obj,
+    tol_rel_obj = tol_rel_obj,
+    tol_grad = tol_grad,
+    tol_rel_grad = tol_rel_grad,
+    tol_param = tol_param,
+    history_size = history_size,
+    draws = draws,
+    single_path_draws = single_path_draws,
+    num_paths = num_paths,
+    max_lbfgs_iters = max_lbfgs_iters,
+    num_elbo_draws = num_elbo_draws,
+    save_single_paths = save_single_paths
+  )
   args <- CmdStanArgs$new(
     method_args = pathfinder_args,
     stan_file = self$stan_file(),
     stan_code = suppressWarnings(self$code()),
+    model_methods_env = private$model_methods_env_,
+    standalone_env = self$functions,
     model_name = self$model_name(),
     exe_file = self$exe_file(),
     proc_ids = 1,

README.md

@@ -27,7 +27,7 @@ releases.
 * Modularity: CmdStanR runs Stan's algorithms and lets downstream modules do the
 analysis.
 
-* Flexible [BSD-3 license](https://opensource.org/licenses/BSD-3-Clause).
+* Flexible [BSD-3 license](https://opensource.org/license/bsd-3-clause/).
 
 
 ### Installation
@@ -61,14 +61,14 @@ CmdStanR_](https://mc-stan.org/cmdstanr/articles/cmdstanr.html) vignette.
 
 ### Contributing
 
-There is a lot of work still to be done and contributions are very welcome!
-If you are interested in contributing please comment on an open issue
-or open a new one if none are applicable.
+There is a lot of work still to be done and we welcome contributions from
+anyone! If you are interested in contributing please comment on an open issue or
+open a new one if none are applicable.
 
 ### License
 
 CmdStanR, like CmdStan and the core Stan C++ code, is licensed under the
 following licenses:
 
-- Code: BSD 3-clause (https://opensource.org/licenses/BSD-3-Clause)
+- Code: BSD 3-clause (https://opensource.org/license/bsd-3-clause/)
 - Documentation: CC-BY 4.0 (https://creativecommons.org/licenses/by/4.0/)

_pkgdown.yml

@@ -102,6 +102,7 @@ reference:
       - CmdStanMLE
       - CmdStanLaplace
       - CmdStanVB
+      - CmdStanPathfinder
       - CmdStanGQ
       - CmdStanDiagnose
       - starts_with("fit-method")