Merge branch 'master' into pr/1138

Author: jgabry

.gitattributes

@@ -0,0 +1,2 @@
+* text=auto eol=lf
+*.rda binary

.github/workflows/R-CMD-check-wsl.yaml

@@ -81,7 +81,7 @@ jobs:
 
       - name: Upload check results
         if: failure()
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         with:
           name: wsl-backend-results
           path: check

.github/workflows/R-CMD-check.yaml

@@ -122,7 +122,7 @@ jobs:
 
       - name: Upload check results
         if: failure()
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         with:
           name: ${{ runner.os }}-r${{ matrix.config.r }}-results
           path: check

.github/workflows/Test-coverage.yaml

@@ -10,7 +10,9 @@ on:
 
 name: Test coverage
 
-permissions: read-all
+permissions:
+  contents: read
+  id-token: write
 
 jobs:
   test-coverage:
@@ -69,8 +71,6 @@ jobs:
           print(cov)
           covr::to_cobertura(cov)
         shell: Rscript {0}
-        env:
-          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
       - name: Test coverage (Windows)
         if: runner.os == 'Windows'
@@ -86,8 +86,6 @@ jobs:
           print(cov)
           covr::to_cobertura(cov)
         shell: Rscript {0}
-        env:
-          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
       - uses: codecov/codecov-action@v5
         with:
@@ -96,7 +94,7 @@ jobs:
           files: ./cobertura.xml
           plugins: noop
           disable_search: true
-          token: ${{ secrets.CODECOV_TOKEN }}
+          use_oidc: true
 
       - name: Show testthat output
         if: always()
@@ -107,7 +105,7 @@ jobs:
 
       - name: Upload test results
         if: failure()
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         with:
           name: coverage-test-failures
           path: ${{ runner.temp }}/package

NEWS.md

@@ -3,7 +3,6 @@
 * Removed deprecated items (replacements in parentheses):
   - `read_sample_csv()` (`read_cmdstan_csv()`)
   - `write_stan_tempfile()` (`write_stan_file()`)
-  - `model_params` element of `fit$metadata()` list (`variables` element)
   - `jacobian_adjustment` argument to `fit$log_prob()` and similar methods (`jacobian` argument)
   - `output_samples` argument to `model$variational()` (`draws` argument)
   - `hessian` argument to `fit$init_model_methods()` (`hessian` method always compiled now)

R/csv.R

@@ -328,7 +328,7 @@ read_cmdstan_csv <- function(files,
   model_param_dims <- variable_dims(metadata$variables)
   metadata$stan_variable_sizes <- model_param_dims
   metadata$stan_variables <- names(model_param_dims)
-
+  metadata$model_params <- metadata$variables # for backwards compatibility
   if (metadata$method == "sample") {
     if (is.null(format)) {
       format <- "draws_array"

R/fit.R

@@ -768,6 +768,15 @@ lp_approx <- function() {
 #' The `$print()` method returns the fitted model object itself (invisibly),
 #' which is the standard behavior for print methods in \R.
 #'
+#' @references
+#' * Vehtari, A., Gelman, A., Simpson, D., Carpenter, B., and Buerkner, P.-C.
+#'   (2021). Rank-normalization, folding, and localization: An improved R-hat
+#'   for assessing convergence of MCMC (with discussion).
+#'   *Bayesian Analysis*, 16(2), 667-718. doi:10.1214/20-BA1221.
+#' * Vehtari, A. (2021). Comparison of MCMC effective sample size estimators.
+#'   https://avehtari.github.io/rhat_ess/ess_comparison.html
+#'   (for ESS diagnostics such as `ess_bulk` and `ess_tail`).
+#'
 #' @seealso [`CmdStanMCMC`], [`CmdStanMLE`], [`CmdStanLaplace`], [`CmdStanVB`], [`CmdStanGQ`]
 #'
 #' @examples
@@ -1524,6 +1533,19 @@ CmdStanMCMC <- R6::R6Class(
 #' @return The object returned by [loo::loo.array()] or
 #'   [loo::loo_moment_match.default()].
 #'
+#' @references
+#' * Vehtari, A., Gelman, A., and Gabry, J. (2017). Practical Bayesian model
+#'   evaluation using leave-one-out cross-validation and WAIC.
+#'   *Statistics and Computing*, 27(5), 1413-1432.
+#'   doi:10.1007/s11222-016-9696-4.
+#' * Vehtari, A., Simpson, D., Gelman, A., Yao, Y., and Gabry, J. (2024).
+#'   Pareto smoothed importance sampling.
+#'   *Journal of Machine Learning Research*, 25(72), 1-58.
+#' * Paananen, T., Piironen, J., Buerkner, P.-C., and Vehtari, A. (2021).
+#'   Implicitly adaptive importance sampling.
+#'   *Statistics and Computing*, 31, 16. doi:10.1007/s11222-020-09982-2
+#'   (for `moment_match = TRUE`).
+#'
 #' @seealso The \pkg{loo} package website with
 #'   [documentation](https://mc-stan.org/loo/reference/index.html) and
 #'   [vignettes](https://mc-stan.org/loo/articles/).

R/model.R

@@ -1105,7 +1105,19 @@ CmdStanModel$set("public", name = "format", value = format)
 #'
 #' @return A [`CmdStanMCMC`] object.
 #'
-#' @template seealso-docs
+#' @references
+#' * Hoffman, M. D., and Gelman, A. (2014). The No-U-Turn sampler:
+#'   adaptively setting path lengths in Hamiltonian Monte Carlo.
+#'   *Journal of Machine Learning Research*, 15(47), 1593-1623.
+#' * Betancourt, M. (2017). A conceptual introduction to Hamiltonian Monte Carlo.
+#'   arXiv:1701.02434. Appendix A describes Stan's dynamic HMC/NUTS implementation.
+#' * Stan Development Team. Stan Reference Manual (Algorithms section):
+#'   https://mc-stan.org/docs/reference-manual/
+#' * Stan Development Team. Stan documentation:
+#'   https://mc-stan.org/users/documentation/
+#' * Stan Development Team. CmdStan User's Guide:
+#'   https://mc-stan.org/docs/cmdstan-guide/
+#'
 #' @inherit cmdstan_model examples
 #'
 sample <- function(data = NULL,
@@ -1280,7 +1292,19 @@ CmdStanModel$set("public", name = "sample", value = sample)
 #'
 #' @return A [`CmdStanMCMC`] object.
 #'
-#' @template seealso-docs
+#' @references
+#' * Hoffman, M. D., and Gelman, A. (2014). The No-U-Turn sampler:
+#'   adaptively setting path lengths in Hamiltonian Monte Carlo.
+#'   *Journal of Machine Learning Research*, 15(47), 1593-1623.
+#' * Betancourt, M. (2017). A conceptual introduction to Hamiltonian Monte Carlo.
+#'   arXiv:1701.02434. Appendix A describes Stan's dynamic HMC/NUTS implementation.
+#' * Stan Development Team. Stan Reference Manual (Algorithms section):
+#'   https://mc-stan.org/docs/reference-manual/
+#' * Stan Development Team. Stan documentation:
+#'   https://mc-stan.org/users/documentation/
+#' * Stan Development Team. CmdStan User's Guide:
+#'   https://mc-stan.org/docs/cmdstan-guide/
+#'
 #' @seealso The Stan Math Library's documentation
 #'   ([mc-stan.org/math](https://mc-stan.org/math/)) for more
 #'   details on MPI support in Stan.
@@ -1440,7 +1464,14 @@ CmdStanModel$set("public", name = "sample_mpi", value = sample_mpi)
 #'
 #' @return A [`CmdStanMLE`] object.
 #'
-#' @template seealso-docs
+#' @references
+#' * Stan Development Team. Stan Reference Manual (Algorithms section, optimization):
+#'   https://mc-stan.org/docs/reference-manual/
+#' * Stan Development Team. Stan documentation:
+#'   https://mc-stan.org/users/documentation/
+#' * Stan Development Team. CmdStan User's Guide:
+#'   https://mc-stan.org/docs/cmdstan-guide/
+#'
 #' @inherit cmdstan_model examples
 #'
 optimize <- function(data = NULL,
@@ -1562,7 +1593,14 @@ CmdStanModel$set("public", name = "optimize", value = optimize)
 #'
 #' @return A [`CmdStanLaplace`] object.
 #'
-#' @template seealso-docs
+#' @references
+#' * Stan Development Team. Stan Reference Manual (Algorithms section, Laplace approximation):
+#'   https://mc-stan.org/docs/reference-manual/
+#' * Stan Development Team. Stan documentation:
+#'   https://mc-stan.org/users/documentation/
+#' * Stan Development Team. CmdStan User's Guide:
+#'   https://mc-stan.org/docs/cmdstan-guide/
+#'
 #' @examples
 #' \dontrun{
 #' file <- file.path(cmdstan_path(), "examples/bernoulli/bernoulli.stan")
@@ -1727,7 +1765,17 @@ CmdStanModel$set("public", name = "laplace", value = laplace)
 #'
 #' @return A [`CmdStanVB`] object.
 #'
-#' @template seealso-docs
+#' @references
+#' * Kucukelbir, A., Tran, D., Ranganath, R., Gelman, A., and Blei, D. M.
+#'   (2017). Automatic differentiation variational inference.
+#'   *Journal of Machine Learning Research*, 18(14), 1-45.
+#' * Stan Development Team. Stan Reference Manual (Algorithms section, variational inference):
+#'   https://mc-stan.org/docs/reference-manual/
+#' * Stan Development Team. Stan documentation:
+#'   https://mc-stan.org/users/documentation/
+#' * Stan Development Team. CmdStan User's Guide:
+#'   https://mc-stan.org/docs/cmdstan-guide/
+#'
 #' @inherit cmdstan_model examples
 #'
 variational <- function(data = NULL,
@@ -1867,7 +1915,17 @@ CmdStanModel$set("public", name = "variational", value = variational)
 #'   pathfinder runs in multi-pathfinder.
 #' @return A [`CmdStanPathfinder`] object.
 #'
-#' @template seealso-docs
+#' @references
+#' * Zhang, L., Carpenter, B., Gelman, A., and Vehtari, A. (2022).
+#'   Pathfinder: parallel quasi-Newton variational inference.
+#'   *Journal of Machine Learning Research*, 23(306), 1-49.
+#' * Stan Development Team. Stan Reference Manual (Algorithms section, Pathfinder):
+#'   https://mc-stan.org/docs/reference-manual/
+#' * Stan Development Team. Stan documentation:
+#'   https://mc-stan.org/users/documentation/
+#' * Stan Development Team. CmdStan User's Guide:
+#'   https://mc-stan.org/docs/cmdstan-guide/
+#'
 #' @inherit cmdstan_model examples
 #'
 pathfinder <- function(data = NULL,

R/utils.R

@@ -950,6 +950,32 @@ compile_functions <- function(env, verbose = FALSE, global = FALSE) {
     prep_fun_cpp(funs[ind], fun_end, env$hpp_code)
   })
 
+  reserved_names <- unique(
+    unlist(
+      lapply(stan_funs, function(stan_fun) {
+        regmatches(
+          stan_fun,
+          gregexpr("(?<=_stan_)[[:alnum:]_]+", stan_fun, perl = TRUE)
+        )[[1]]
+      }),
+      use.names = FALSE
+    )
+  )
+
+  if (length(reserved_names) > 0) {
+    stop(
+      paste0(
+        "expose_functions() can't expose this Stan function because the function ",
+        "name and/or one or more argument names use a reserved keyword ",
+        "(typically in the C++ toolchain used to compile Stan). Please rename ",
+        "the function/arguments in your Stan functions block and try again. ",
+        "Conflicting names: ",
+        paste(reserved_names, collapse = ", ")
+      ),
+      call. = FALSE
+    )
+  }
+
   env$fun_names <- sapply(seq_len(length(funs) - 1), function(ind) {
     get_function_name(funs[ind], funs[ind + 1], env$hpp_code)
   })