diff --git a/NEWS.md b/NEWS.md index 72a35474..0bcc5c0a 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,3 +1,10 @@ +# shinystan 2.5.0 + +* New website with online documentation: http://mc-stan.org/shinystan + +* Fixed problem with extracting info from fits reconstructed from CSV files (#128,#158), thanks to @martinmodrak + + # shinystan 2.4.0 * `launch_shinystan` is now an S3 generic with methods. This allows developers @@ -10,11 +17,14 @@ conflict. ### Fixes * Fix various issues resulting in errors for models fit using static HMC (thanks to Cole Monnahan). + * Deprecate `burnin` argument to `as.shinystan`. Use `warmup` instead. Only relevant for models _not_ fit using Stan. ### New features + * Add NUTS energy diagnostic plots to Diagnose page + * Allowing passing `sampler_params` to `as.shinystan`. This makes it possible to display sampler diagnositcs for HMC/NUTS even if not using Stan's implementation of those algorithms (thanks to Cole Monnahan). diff --git a/R/launch_shinystan.R b/R/launch_shinystan.R index 987f899b..5bfe4a87 100644 --- a/R/launch_shinystan.R +++ b/R/launch_shinystan.R @@ -35,7 +35,9 @@ #' @template seealso-as.shinystan #' @template seealso-update_sso #' @template seealso-demo -#' +#' +#' @template reference-muth +#' @template reference-bayesvis #' #' @examples #' \dontrun{ diff --git a/R/shinystan-objects.R b/R/shinystan-objects.R index 6c46ff57..c63973bb 100644 --- a/R/shinystan-objects.R +++ b/R/shinystan-objects.R @@ -40,6 +40,8 @@ #' @template seealso-generate_quantity #' @seealso \code{\link{shinystan-metadata}} to view or change metadata #' associated with a \code{shinystan} object. +#' +#' @template reference-muth #' shinystan <- setClass( Class = "shinystan", diff --git a/R/shinystan-package.R b/R/shinystan-package.R index 7c25b224..3cc003a1 100644 --- a/R/shinystan-package.R +++ b/R/shinystan-package.R @@ -11,7 +11,7 @@ # this program; if not, see . -#' 'ShinyStan' interface and \code{shinystan} R package +#' \pkg{shinystan} R package ('ShinyStan' graphical user interface) #' #' @docType package #' @name shinystan-package @@ -22,25 +22,27 @@ #' \emph{Stan Development Team} #' } #' -#' Applied Bayesian data analysis is primarily implemented through the Markov -#' chain Monte Carlo (MCMC) algorithms offered by various software packages. -#' When analyzing a posterior sample obtained by one of these algorithms the +#' Applied Bayesian data analysis is primarily implemented through the Markov +#' chain Monte Carlo (MCMC) algorithms offered by various software packages. +#' When analyzing a posterior sample obtained by one of these algorithms the #' first step is to check for signs that the chains have converged to the target -#' distribution and and also for signs that the algorithm might require tuning -#' or might be ill-suited for the given model. There may also be theoretical +#' distribution and and also for signs that the algorithm might require tuning +#' or might be ill-suited for the given model. There may also be theoretical #' problems or practical inefficiencies with the specification of the model. The -#' 'ShinyStan' app provides interactive plots and tables helpful for analyzing a +#' ShinyStan app provides interactive plots and tables helpful for analyzing a #' posterior sample, with particular attention to identifying potential problems #' with the performance of the MCMC algorithm or the specification of the model. -#' 'ShinyStan' is powered by the 'Shiny' web application framework by 'RStudio' -#' and works with the output of MCMC programs written in any programming -#' language (and has extended functionality for models fit using the \pkg{rstan} -#' package and the No-U-Turn sampler). +#' ShinyStan is powered by the Shiny web application framework by RStudio +#' (\url{http://shiny.rstudio.com/}) and works with the output of MCMC programs +#' written in any programming language (and has extended functionality for +#' models fit using the \pkg{rstan} package and the No-U-Turn sampler). #' -#' @section 'ShinyStan' has extended functionality for 'Stan' models: +#' @section ShinyStan has extended functionality for Stan models: #' -#' 'Stan' (\url{http://mc-stan.org}) models can be run in \R using the -#' \pkg{\link[rstan]{rstan}} and \pkg{\link[rstanarm]{rstanarm}} packages. +#' Stan (\url{http://mc-stan.org}) models can be run in \R using the +#' \pkg{\link[rstan]{rstan}} package. Other packages like +#' \pkg{\link[rstanarm]{rstanarm}} and \pkg{\link[brms]{brms}} provide +#' higher-level interfaces to Stan that use \pkg{rstan} internally. #' #' @section Saving and sharing: #' @@ -52,7 +54,7 @@ #' publication. #' #' The \code{\link{deploy_shinystan}} function lets you easily deploy your own -#' 'ShinyStan' apps online for any of your models using the shinyapps.io +#' ShinyStan apps online for any of your models using the shinyapps.io #' service from 'RStudio'. Each of your apps (each of your models) will have a #' unique url and will be compatible with most web browsers. #' @@ -66,15 +68,20 @@ #' Check out the demo using \code{\link{launch_shinystan_demo}} or try it with #' one of your own models using \code{\link{launch_shinystan}}. #' -#' @section Help and bug reports: +#' @section Resources: #' \itemize{ -#' \item 'Stan' forums (\url{http://discourse.mc-stan.org}) -#' \item 'ShinyStan' issue tracker (\url{https://github.com/stan-dev/shinystan/issues}) +#' \item Web page with online documentation +#' (\url{http://mc-stan.org/shinystan}) +#' \item Stan Forums on Discourse (\url{http://discourse.mc-stan.org}) +#' \item GitHub issue tracker (\url{https://github.com/stan-dev/shinystan/issues}) #' } #' #' @template seealso-as.shinystan #' @template seealso-demo #' @template seealso-launch +#' +#' @template reference-muth +#' @template reference-bayesvis #' #' @import ggplot2 #' @import methods diff --git a/man-roxygen/reference-bayesvis.R b/man-roxygen/reference-bayesvis.R new file mode 100644 index 00000000..df2ff0d1 --- /dev/null +++ b/man-roxygen/reference-bayesvis.R @@ -0,0 +1,4 @@ +#' @references Gabry, J., Simpson, D., Vehtari, A., Betancourt, M., and Gelman, +#' A. (2018). Visualization in Bayesian workflow. \emph{Journal of the Royal +#' Statistical Society Series A}, accepted for publication. arXiv preprint: +#' \url{http://arxiv.org/abs/1709.01449}. diff --git a/man-roxygen/reference-muth.R b/man-roxygen/reference-muth.R new file mode 100644 index 00000000..f720ca14 --- /dev/null +++ b/man-roxygen/reference-muth.R @@ -0,0 +1,5 @@ +#' @references +#' Muth, C., Oravecz, Z., and Gabry, J. (2018) +#' User-friendly Bayesian regression modeling: A tutorial with rstanarm and shinystan. +#' \emph{The Quantitative Methods for Psychology}. 14(2), 99--119. +#' \url{https://www.tqmp.org/RegularArticles/vol14-2/p099/p099.pdf} diff --git a/man/launch_shinystan.Rd b/man/launch_shinystan.Rd index bf9e10dc..7ce94988 100644 --- a/man/launch_shinystan.Rd +++ b/man/launch_shinystan.Rd @@ -74,6 +74,17 @@ sf_sso <- launch_shinystan(sf) # First create shinystan object (see ?as.shinystan) for full details) } +} +\references{ +Muth, C., Oravecz, Z., and Gabry, J. (2018) +User-friendly Bayesian regression modeling: A tutorial with rstanarm and shinystan. +\emph{The Quantitative Methods for Psychology}. 14(2), 99--119. +\url{https://www.tqmp.org/RegularArticles/vol14-2/p099/p099.pdf} + +Gabry, J., Simpson, D., Vehtari, A., Betancourt, M., and Gelman, + A. (2018). Visualization in Bayesian workflow. \emph{Journal of the Royal + Statistical Society Series A}, accepted for publication. arXiv preprint: + \url{http://arxiv.org/abs/1709.01449}. } \seealso{ \code{\link{as.shinystan}} for creating \code{shinystan} objects. diff --git a/man/shinystan-class.Rd b/man/shinystan-class.Rd index 2e229c4e..fe26aebd 100644 --- a/man/shinystan-class.Rd +++ b/man/shinystan-class.Rd @@ -41,6 +41,12 @@ models only).} \item{\code{misc}}{(\code{"list"}) Miscellaneous, for internal use.} }} +\references{ +Muth, C., Oravecz, Z., and Gabry, J. (2018) +User-friendly Bayesian regression modeling: A tutorial with rstanarm and shinystan. +\emph{The Quantitative Methods for Psychology}. 14(2), 99--119. +\url{https://www.tqmp.org/RegularArticles/vol14-2/p099/p099.pdf} +} \seealso{ \code{\link{as.shinystan}} for creating \code{shinystan} objects. diff --git a/man/shinystan-package.Rd b/man/shinystan-package.Rd index 43681e1d..86e15272 100644 --- a/man/shinystan-package.Rd +++ b/man/shinystan-package.Rd @@ -3,33 +3,35 @@ \docType{package} \name{shinystan-package} \alias{shinystan-package} -\title{'ShinyStan' interface and \code{shinystan} R package} +\title{\pkg{shinystan} R package ('ShinyStan' graphical user interface)} \description{ \if{html}{ \figure{stanlogo.png}{options: width="50px" alt="mc-stan.org"} \emph{Stan Development Team} } -Applied Bayesian data analysis is primarily implemented through the Markov -chain Monte Carlo (MCMC) algorithms offered by various software packages. -When analyzing a posterior sample obtained by one of these algorithms the +Applied Bayesian data analysis is primarily implemented through the Markov +chain Monte Carlo (MCMC) algorithms offered by various software packages. +When analyzing a posterior sample obtained by one of these algorithms the first step is to check for signs that the chains have converged to the target -distribution and and also for signs that the algorithm might require tuning -or might be ill-suited for the given model. There may also be theoretical +distribution and and also for signs that the algorithm might require tuning +or might be ill-suited for the given model. There may also be theoretical problems or practical inefficiencies with the specification of the model. The -'ShinyStan' app provides interactive plots and tables helpful for analyzing a +ShinyStan app provides interactive plots and tables helpful for analyzing a posterior sample, with particular attention to identifying potential problems with the performance of the MCMC algorithm or the specification of the model. -'ShinyStan' is powered by the 'Shiny' web application framework by 'RStudio' -and works with the output of MCMC programs written in any programming -language (and has extended functionality for models fit using the \pkg{rstan} -package and the No-U-Turn sampler). +ShinyStan is powered by the Shiny web application framework by RStudio +(\url{http://shiny.rstudio.com/}) and works with the output of MCMC programs +written in any programming language (and has extended functionality for +models fit using the \pkg{rstan} package and the No-U-Turn sampler). } -\section{'ShinyStan' has extended functionality for 'Stan' models}{ +\section{ShinyStan has extended functionality for Stan models}{ -'Stan' (\url{http://mc-stan.org}) models can be run in \R using the -\pkg{\link[rstan]{rstan}} and \pkg{\link[rstanarm]{rstanarm}} packages. +Stan (\url{http://mc-stan.org}) models can be run in \R using the +\pkg{\link[rstan]{rstan}} package. Other packages like +\pkg{\link[rstanarm]{rstanarm}} and \pkg{\link[brms]{brms}} provide +higher-level interfaces to Stan that use \pkg{rstan} internally. } \section{Saving and sharing}{ @@ -43,7 +45,7 @@ package and the No-U-Turn sampler). publication. The \code{\link{deploy_shinystan}} function lets you easily deploy your own - 'ShinyStan' apps online for any of your models using the shinyapps.io + ShinyStan apps online for any of your models using the shinyapps.io service from 'RStudio'. Each of your apps (each of your models) will have a unique url and will be compatible with most web browsers. } @@ -62,14 +64,27 @@ package and the No-U-Turn sampler). one of your own models using \code{\link{launch_shinystan}}. } -\section{Help and bug reports}{ +\section{Resources}{ \itemize{ - \item 'Stan' forums (\url{http://discourse.mc-stan.org}) - \item 'ShinyStan' issue tracker (\url{https://github.com/stan-dev/shinystan/issues}) + \item Web page with online documentation + (\url{http://mc-stan.org/shinystan}) + \item Stan Forums on Discourse (\url{http://discourse.mc-stan.org}) + \item GitHub issue tracker (\url{https://github.com/stan-dev/shinystan/issues}) } } +\references{ +Muth, C., Oravecz, Z., and Gabry, J. (2018) +User-friendly Bayesian regression modeling: A tutorial with rstanarm and shinystan. +\emph{The Quantitative Methods for Psychology}. 14(2), 99--119. +\url{https://www.tqmp.org/RegularArticles/vol14-2/p099/p099.pdf} + +Gabry, J., Simpson, D., Vehtari, A., Betancourt, M., and Gelman, + A. (2018). Visualization in Bayesian workflow. \emph{Journal of the Royal + Statistical Society Series A}, accepted for publication. arXiv preprint: + \url{http://arxiv.org/abs/1709.01449}. +} \seealso{ \code{\link{as.shinystan}} for creating \code{shinystan} objects.