Merge pull request #1148 from stan-dev/citations

Added references for some functions

Author: jgabry

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

@@ -1097,7 +1097,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,
@@ -1247,7 +1259,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.
@@ -1407,7 +1431,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,
@@ -1529,7 +1560,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")
@@ -1694,7 +1732,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,
@@ -1834,7 +1882,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,