diff --git a/R/fit.R b/R/fit.R index ca5d6fdb..1c2df276 100644 --- a/R/fit.R +++ b/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/). diff --git a/R/model.R b/R/model.R index 2b87f7ea..068d3e0a 100644 --- a/R/model.R +++ b/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, diff --git a/man/fit-method-loo.Rd b/man/fit-method-loo.Rd index d2ccb471..f9dcb7c9 100644 --- a/man/fit-method-loo.Rd +++ b/man/fit-method-loo.Rd @@ -60,6 +60,21 @@ loo_result <- fit$loo(cores = 2) print(loo_result) } +} +\references{ +\itemize{ +\item Vehtari, A., Gelman, A., and Gabry, J. (2017). Practical Bayesian model +evaluation using leave-one-out cross-validation and WAIC. +\emph{Statistics and Computing}, 27(5), 1413-1432. +doi:10.1007/s11222-016-9696-4. +\item Vehtari, A., Simpson, D., Gelman, A., Yao, Y., and Gabry, J. (2024). +Pareto smoothed importance sampling. +\emph{Journal of Machine Learning Research}, 25(72), 1-58. +\item Paananen, T., Piironen, J., Buerkner, P.-C., and Vehtari, A. (2021). +Implicitly adaptive importance sampling. +\emph{Statistics and Computing}, 31, 16. doi:10.1007/s11222-020-09982-2 +(for \code{moment_match = TRUE}). +} } \seealso{ The \pkg{loo} package website with diff --git a/man/fit-method-summary.Rd b/man/fit-method-summary.Rd index 787feb2a..20eee6d4 100644 --- a/man/fit-method-summary.Rd +++ b/man/fit-method-summary.Rd @@ -73,6 +73,17 @@ fit$print(c("alpha", "beta"), var2 = ~var(as.vector(.x))) } +} +\references{ +\itemize{ +\item 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). +\emph{Bayesian Analysis}, 16(2), 667-718. doi:10.1214/20-BA1221. +\item Vehtari, A. (2021). Comparison of MCMC effective sample size estimators. +https://avehtari.github.io/rhat_ess/ess_comparison.html +(for ESS diagnostics such as \code{ess_bulk} and \code{ess_tail}). +} } \seealso{ \code{\link{CmdStanMCMC}}, \code{\link{CmdStanMLE}}, \code{\link{CmdStanLaplace}}, \code{\link{CmdStanVB}}, \code{\link{CmdStanGQ}} diff --git a/man/model-method-laplace.Rd b/man/model-method-laplace.Rd index 52d68413..7161731a 100644 --- a/man/model-method-laplace.Rd +++ b/man/model-method-laplace.Rd @@ -224,17 +224,17 @@ bayesplot::mcmc_hist(fit_laplace$draws("theta")) } -\seealso{ -The CmdStanR website -(\href{https://mc-stan.org/cmdstanr/}{mc-stan.org/cmdstanr}) for online -documentation and tutorials. - -The Stan and CmdStan documentation: +\references{ \itemize{ -\item Stan documentation: \href{https://mc-stan.org/users/documentation/}{mc-stan.org/users/documentation} -\item CmdStan User’s Guide: \href{https://mc-stan.org/docs/cmdstan-guide/}{mc-stan.org/docs/cmdstan-guide} +\item Stan Development Team. Stan Reference Manual (Algorithms section, Laplace approximation): +https://mc-stan.org/docs/reference-manual/ +\item Stan Development Team. Stan documentation: +https://mc-stan.org/users/documentation/ +\item Stan Development Team. CmdStan User's Guide: +https://mc-stan.org/docs/cmdstan-guide/ } - +} +\seealso{ Other CmdStanModel methods: \code{\link{model-method-check_syntax}}, \code{\link{model-method-compile}}, diff --git a/man/model-method-optimize.Rd b/man/model-method-optimize.Rd index 6f36bdf1..0b9a3c86 100644 --- a/man/model-method-optimize.Rd +++ b/man/model-method-optimize.Rd @@ -349,17 +349,17 @@ fit_optim_w_init_list$init() } } -\seealso{ -The CmdStanR website -(\href{https://mc-stan.org/cmdstanr/}{mc-stan.org/cmdstanr}) for online -documentation and tutorials. - -The Stan and CmdStan documentation: +\references{ \itemize{ -\item Stan documentation: \href{https://mc-stan.org/users/documentation/}{mc-stan.org/users/documentation} -\item CmdStan User’s Guide: \href{https://mc-stan.org/docs/cmdstan-guide/}{mc-stan.org/docs/cmdstan-guide} +\item Stan Development Team. Stan Reference Manual (Algorithms section, optimization): +https://mc-stan.org/docs/reference-manual/ +\item Stan Development Team. Stan documentation: +https://mc-stan.org/users/documentation/ +\item Stan Development Team. CmdStan User's Guide: +https://mc-stan.org/docs/cmdstan-guide/ } - +} +\seealso{ Other CmdStanModel methods: \code{\link{model-method-check_syntax}}, \code{\link{model-method-compile}}, diff --git a/man/model-method-pathfinder.Rd b/man/model-method-pathfinder.Rd index ff7260bb..a43dda65 100644 --- a/man/model-method-pathfinder.Rd +++ b/man/model-method-pathfinder.Rd @@ -365,17 +365,20 @@ fit_optim_w_init_list$init() } } -\seealso{ -The CmdStanR website -(\href{https://mc-stan.org/cmdstanr/}{mc-stan.org/cmdstanr}) for online -documentation and tutorials. - -The Stan and CmdStan documentation: +\references{ \itemize{ -\item Stan documentation: \href{https://mc-stan.org/users/documentation/}{mc-stan.org/users/documentation} -\item CmdStan User’s Guide: \href{https://mc-stan.org/docs/cmdstan-guide/}{mc-stan.org/docs/cmdstan-guide} +\item Zhang, L., Carpenter, B., Gelman, A., and Vehtari, A. (2022). +Pathfinder: parallel quasi-Newton variational inference. +\emph{Journal of Machine Learning Research}, 23(306), 1-49. +\item Stan Development Team. Stan Reference Manual (Algorithms section, Pathfinder): +https://mc-stan.org/docs/reference-manual/ +\item Stan Development Team. Stan documentation: +https://mc-stan.org/users/documentation/ +\item Stan Development Team. CmdStan User's Guide: +https://mc-stan.org/docs/cmdstan-guide/ } - +} +\seealso{ Other CmdStanModel methods: \code{\link{model-method-check_syntax}}, \code{\link{model-method-compile}}, diff --git a/man/model-method-sample.Rd b/man/model-method-sample.Rd index 72fba048..53bef269 100644 --- a/man/model-method-sample.Rd +++ b/man/model-method-sample.Rd @@ -428,17 +428,22 @@ fit_optim_w_init_list$init() } } -\seealso{ -The CmdStanR website -(\href{https://mc-stan.org/cmdstanr/}{mc-stan.org/cmdstanr}) for online -documentation and tutorials. - -The Stan and CmdStan documentation: +\references{ \itemize{ -\item Stan documentation: \href{https://mc-stan.org/users/documentation/}{mc-stan.org/users/documentation} -\item CmdStan User’s Guide: \href{https://mc-stan.org/docs/cmdstan-guide/}{mc-stan.org/docs/cmdstan-guide} +\item Hoffman, M. D., and Gelman, A. (2014). The No-U-Turn sampler: +adaptively setting path lengths in Hamiltonian Monte Carlo. +\emph{Journal of Machine Learning Research}, 15(47), 1593-1623. +\item Betancourt, M. (2017). A conceptual introduction to Hamiltonian Monte Carlo. +arXiv:1701.02434. Appendix A describes Stan's dynamic HMC/NUTS implementation. +\item Stan Development Team. Stan Reference Manual (Algorithms section): +https://mc-stan.org/docs/reference-manual/ +\item Stan Development Team. Stan documentation: +https://mc-stan.org/users/documentation/ +\item Stan Development Team. CmdStan User's Guide: +https://mc-stan.org/docs/cmdstan-guide/ } - +} +\seealso{ Other CmdStanModel methods: \code{\link{model-method-check_syntax}}, \code{\link{model-method-compile}}, diff --git a/man/model-method-sample_mpi.Rd b/man/model-method-sample_mpi.Rd index b33464f4..a6479b2e 100644 --- a/man/model-method-sample_mpi.Rd +++ b/man/model-method-sample_mpi.Rd @@ -320,17 +320,22 @@ only define the number of processes. To use \code{n_procs} processes specify } } -\seealso{ -The CmdStanR website -(\href{https://mc-stan.org/cmdstanr/}{mc-stan.org/cmdstanr}) for online -documentation and tutorials. - -The Stan and CmdStan documentation: +\references{ \itemize{ -\item Stan documentation: \href{https://mc-stan.org/users/documentation/}{mc-stan.org/users/documentation} -\item CmdStan User’s Guide: \href{https://mc-stan.org/docs/cmdstan-guide/}{mc-stan.org/docs/cmdstan-guide} +\item Hoffman, M. D., and Gelman, A. (2014). The No-U-Turn sampler: +adaptively setting path lengths in Hamiltonian Monte Carlo. +\emph{Journal of Machine Learning Research}, 15(47), 1593-1623. +\item Betancourt, M. (2017). A conceptual introduction to Hamiltonian Monte Carlo. +arXiv:1701.02434. Appendix A describes Stan's dynamic HMC/NUTS implementation. +\item Stan Development Team. Stan Reference Manual (Algorithms section): +https://mc-stan.org/docs/reference-manual/ +\item Stan Development Team. Stan documentation: +https://mc-stan.org/users/documentation/ +\item Stan Development Team. CmdStan User's Guide: +https://mc-stan.org/docs/cmdstan-guide/ } - +} +\seealso{ The Stan Math Library's documentation (\href{https://mc-stan.org/math/}{mc-stan.org/math}) for more details on MPI support in Stan. diff --git a/man/model-method-variational.Rd b/man/model-method-variational.Rd index 4313dcec..56101213 100644 --- a/man/model-method-variational.Rd +++ b/man/model-method-variational.Rd @@ -336,17 +336,20 @@ fit_optim_w_init_list$init() } } -\seealso{ -The CmdStanR website -(\href{https://mc-stan.org/cmdstanr/}{mc-stan.org/cmdstanr}) for online -documentation and tutorials. - -The Stan and CmdStan documentation: +\references{ \itemize{ -\item Stan documentation: \href{https://mc-stan.org/users/documentation/}{mc-stan.org/users/documentation} -\item CmdStan User’s Guide: \href{https://mc-stan.org/docs/cmdstan-guide/}{mc-stan.org/docs/cmdstan-guide} +\item Kucukelbir, A., Tran, D., Ranganath, R., Gelman, A., and Blei, D. M. +(2017). Automatic differentiation variational inference. +\emph{Journal of Machine Learning Research}, 18(14), 1-45. +\item Stan Development Team. Stan Reference Manual (Algorithms section, variational inference): +https://mc-stan.org/docs/reference-manual/ +\item Stan Development Team. Stan documentation: +https://mc-stan.org/users/documentation/ +\item Stan Development Team. CmdStan User's Guide: +https://mc-stan.org/docs/cmdstan-guide/ } - +} +\seealso{ Other CmdStanModel methods: \code{\link{model-method-check_syntax}}, \code{\link{model-method-compile}},