| Title: | Interactive Visual and Numerical Diagnostics and Posterior Analysis for Bayesian Models |
| Version: | 2.6.0 |
| Date: | 2022-03-02 |
| Maintainer: | Jonah Gabry <jsg2201@columbia.edu> |
| Description: | A graphical user interface for interactive Markov chain Monte Carlo (MCMC) diagnostics and plots and tables helpful for analyzing a posterior sample. The interface is powered by the 'Shiny' web application framework from 'RStudio' and works with the output of MCMC programs written in any programming language (and has extended functionality for 'Stan' models fit using the 'rstan' and 'rstanarm' packages). |
| URL: | https://mc-stan.org/shinystan/, https://discourse.mc-stan.org |
| BugReports: | https://github.com/stan-dev/shinystan/issues/ |
| License: | GPL (≥ 3) |
| Depends: | R (≥ 3.1.0), shiny (≥ 1.0.3) |
| Imports: | bayesplot (≥ 1.5.0), colourpicker, DT (≥ 0.2), dygraphs (≥ 1.1.1.2), ggplot2 (≥ 2.1.1), gridExtra, gtools, markdown (≥ 0.7.4), methods, reshape2, rstan (≥ 2.17.1), stats, shinyjs (≥ 0.6.0), shinythemes (≥ 1.0.1), threejs (≥ 0.2.1), utils, xtable, xts (≥ 0.9-7) |
| Suggests: | cmdstanr (≥ 0.4.0), coda, knitr (≥ 1.9), posterior (≥ 1.0.0), rmarkdown (≥ 0.8.1), rsconnect (≥ 0.4.2), rstanarm (≥ 2.17.4), testthat |
| Additional_repositories: | https://mc-stan.org/r-packages/ |
| LazyData: | true |
| Encoding: | UTF-8 |
| VignetteBuilder: | knitr |
| RoxygenNote: | 7.1.2 |
| NeedsCompilation: | no |
| Packaged: | 2022-03-02 19:40:48 UTC; jgabry |
| Author: | Jonah Gabry [aut, cre], Duco Veen [aut], Stan Development Team [ctb], Michael Andreae [ctb], Michael Betancourt [ctb], Bob Carpenter [ctb], Yuanjun Gao [ctb], Andrew Gelman [ctb], Ben Goodrich [ctb], Daniel Lee [ctb], Dongying Song [ctb], Rob Trangucci [ctb] |
| Repository: | CRAN |
| Date/Publication: | 2022-03-03 00:10:02 UTC |
shinystan R package ('ShinyStan' graphical user interface)
Description
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 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 problems or practical inefficiencies with the specification of the model. The 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 (https://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 rstan package and the No-U-Turn sampler).
ShinyStan has extended functionality for Stan models
Stan (https://mc-stan.org/) models can be run in R using the rstan package. Other packages like rstanarm and brms provide higher-level interfaces to Stan that use rstan internally.
Saving and sharing
The shinystan package allows you to store the basic components of an
entire project (code, posterior samples, graphs, tables, notes) in a single
object, a shinystan object (sso, for short).
Users can save many of the plots as ggplot2 objects for further
customization and easy integration in reports or post-processing for
publication.
The deploy_shinystan function lets you easily deploy your own
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.
License
The shinystan package is open source licensed under the GNU Public License, version 3 (GPLv3).
Demo
Check out the demo using launch_shinystan_demo or try it with
one of your own models using launch_shinystan.
Resources
Web page with online documentation (https://mc-stan.org/shinystan/)
Stan Forums on Discourse (https://discourse.mc-stan.org)
GitHub issue tracker (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. The Quantitative Methods for Psychology. 14(2), 99–119. https://www.tqmp.org/RegularArticles/vol14-2/p099/p099.pdf
Gabry, J. , Simpson, D. , Vehtari, A. , Betancourt, M. and Gelman, A. (2019), Visualization in Bayesian workflow. *J. R. Stat. Soc. A*, 182: 389-402. doi:10.1111/rssa.12378 ([journal version](https://rss.onlinelibrary.wiley.com/doi/full/10.1111/rssa.12378), [preprint arXiv:1709.01449](https://arxiv.org/abs/1709.01449), [code on GitHub](https://github.com/jgabry/bayes-vis-paper))
See Also
as.shinystan for creating shinystan objects.
launch_shinystan_demo to try a demo.
launch_shinystan to launch the 'ShinyStan' interface
using a particular shinystan object.
Create and test shinystan objects
Description
The as.shinystan function creates shinystan
objects that can be used with launch_shinystan and various
other functions in the shinystan package. as.shinystan is a
generic for which the shinystan package provides several methods.
Currently methods are provided for creating shinystan objects from
arrays, lists of matrices, stanfit objects (rstan),
stanreg objects (rstanarm), and mcmc.list objects
(coda).
is.shinystan tests if an object is a shinystan object.
Usage
as.shinystan(X, ...)
is.shinystan(X)
## S4 method for signature 'array'
as.shinystan(
X,
model_name = "unnamed model",
warmup = 0,
burnin = 0,
param_dims = list(),
model_code = NULL,
note = NULL,
sampler_params = NULL,
algorithm = NULL,
max_treedepth = NULL,
...
)
## S4 method for signature 'list'
as.shinystan(
X,
model_name = "unnamed model",
warmup = 0,
burnin = 0,
param_dims = list(),
model_code = NULL,
note = NULL,
sampler_params = NULL,
algorithm = NULL,
max_treedepth = NULL,
...
)
## S4 method for signature 'mcmc.list'
as.shinystan(
X,
model_name = "unnamed model",
warmup = 0,
burnin = 0,
param_dims = list(),
model_code = NULL,
note = NULL,
...
)
## S4 method for signature 'stanfit'
as.shinystan(X, pars, model_name = X@model_name, note = NULL, ...)
## S4 method for signature 'stanreg'
as.shinystan(X, ppd = TRUE, seed = 1234, model_name = NULL, note = NULL, ...)
## S4 method for signature 'CmdStanMCMC'
as.shinystan(X, pars = NULL, model_name = NULL, note = NULL, ...)
Arguments
X |
For |
... |
Arguments passed to the individual methods. |
model_name |
A string giving a name for the model. |
warmup |
The number of iterations to treat as warmup. Should be
|
burnin |
Deprecated. Use |
param_dims |
Rarely used and never necessary. A named list giving the
dimensions for all parameters. For scalar parameters use |
model_code |
Optionally, a character string with the code used to run
the model. This can also be added to your |
note |
Optionally, text to display on the Notepad page in the
'ShinyStan' GUI (stored in |
sampler_params, algorithm, max_treedepth |
Rarely used and never
necessary. If using the |
pars |
For stanfit objects (rstan), an optional character vector
specifying which parameters should be included in the |
ppd |
For |
seed |
Passed to |
Value
as.shinystan returns a shinystan object, which is an
instance of S4 class "shinystan".
is.shinystan returns TRUE if the tested object is a
shinystan object and FALSE otherwise.
Functions
-
as.shinystan,array-method: Create ashinystanobject from a 3-Darrayof simulations. The array should have dimensions corresponding to iterations, chains, and parameters, in that order. -
as.shinystan,list-method: Create ashinystanobject from alistof matrices. Eachmatrix(or 2-D array) should contain the simulations for an individual chain and all of the matrices should have the same number of iterations (rows) and parameters (columns). Parameters should have the same names and be in the same order. -
as.shinystan,mcmc.list-method: Create ashinystanobject from anmcmc.listobject (coda). -
as.shinystan,stanfit-method: Create ashinystanobject from astanfitobject (rstan). Fewer optional arguments are available for this method because all important information can be taken automatically from thestanfitobject. -
as.shinystan,stanreg-method: Create ashinystanobject from astanregobject (rstanarm). -
as.shinystan,CmdStanMCMC-method: Create ashinystanobject from aCmdStanMCMCobject (cmdstanr).
See Also
launch_shinystan to launch the 'ShinyStan' interface
using a particular shinystan object.
drop_parameters to remove parameters from a
shinystan object.
generate_quantity to add a new quantity to a
shinystan object.
Examples
## Not run:
sso <- as.shinystan(X, ...) # replace ... with optional arguments or omit it
launch_shinystan(sso)
## End(Not run)
## Not run:
########################
### list of matrices ###
########################
# Generate some fake data
chain1 <- cbind(beta1 = rnorm(100), beta2 = rnorm(100), sigma = rexp(100))
chain2 <- cbind(beta1 = rnorm(100), beta2 = rnorm(100), sigma = rexp(100))
sso <- as.shinystan(list(chain1, chain2))
launch_shinystan(sso)
# We can also specify some or all of the optional arguments
# note: in order to use param_dims we need to rename 'beta1' and 'beta2'
# to 'beta[1]' and 'beta[2]'
colnames(chain1) <- colnames(chain2) <- c(paste0("beta[",1:2,"]"), "sigma")
sso2 <- as.shinystan(list(chain1, chain2),
model_name = "Example", warmup = 0,
param_dims = list(beta = 2, sigma = 0))
launch_shinystan(sso2)
## End(Not run)
## Not run:
######################
### stanfit object ###
######################
library("rstan")
fit <- stan_demo("eight_schools")
sso <- as.shinystan(fit, model_name = "example")
## End(Not run)
## Not run:
######################
### stanreg object ###
######################
library("rstanarm")
example("example_model")
sso <- as.shinystan(example_model)
launch_shinystan(sso)
## End(Not run)
Deploy a 'ShinyStan' app on the web using 'shinyapps.io' by 'RStudio'
Description
Requires a (free or paid) 'ShinyApps' account. Visit https://www.shinyapps.io/ to sign up.
Usage
deploy_shinystan(sso, appName, account = NULL, ..., deploy = TRUE)
Arguments
sso |
|
appName |
The name to use for the application. Application names must be at least four characters long and may only contain letters, numbers, dashes and underscores. |
account |
shinyapps.io account username. Only required if more than one account is configured on the system. |
... |
Optional arguments. See Details. |
deploy |
Should the app be deployed? The only reason for this to be
|
Details
In ..., the arguments ppcheck_data and
ppcheck_yrep can be specified. ppcheck_data should be a
vector of observations to use for graphical posterior predictive checking
and ppcheck_yrep should be a character string naming the parameter
in sso containing the posterior predictive simulations/replications.
The value of ppcheck_yrep is only used to preselect the appropriate
parameter/generated quantity to use for the posterior predictive checking.
ppcheck_yrep (but not ppcheck_data) can also be set
interactively on shinyapps.io when using the app.
Value
Invisibly, TRUE if deployment succeeded
(did not encounter an error) or, if deploy argument is set to
FALSE, the path to the temporary directory containing the app ready
for deployment (also invisibly).
See Also
The example in the Deploying to shinyapps.io vignette that comes with this package.
https://www.shinyapps.io/ to sign up for a free or paid 'ShinyApps' account and for details on how to configure your account on your local system using the rsconnect package from 'RStudio'.
Examples
## Not run:
# For this example assume sso is the name of the \code{shinystan} object for
# the model you want to use. Assume also that you want to name your app
# 'my-model' and that your shinyapps.io username is 'username'.
deploy_shinystan(sso, appName = "my-model", account = "username")
# If you only have one ShinyApps account configured then you can also omit
# the 'account' argument.
deploy_shinystan(sso, appName = "my-model")
## End(Not run)
Drop parameters from a shinystan object
Description
Remove selected parameters from a shinystan object. This is useful if
you have a very large shinystan object when you only want to look at a
subset of parameters. With a smaller shinystan object,
launch_shinystan will be faster and you should experience
better performance (responsiveness) after launching when using the
'ShinyStan' app.
Usage
drop_parameters(sso, pars)
Arguments
sso |
|
pars |
A character vector of parameter names. If the name of a
non-scalar (e.g. vector, matrix) parameter is included in |
Value
sso, with pars dropped.
See Also
generate_quantity to add a new quantity to a
shinystan object.
Examples
# Using example shinystan object 'eight_schools'
print(eight_schools@param_names)
# Remove the scalar parameters mu and tau
sso <- drop_parameters(eight_schools, pars = c("mu", "tau"))
print(sso@param_names)
# Remove all elements of the parameter vector theta
sso <- drop_parameters(sso, pars = "theta")
print(sso@param_names)
Add new quantity to shinystan object
Description
Add to shinystan object a new parameter as a function of one or two existing parameters.
Usage
generate_quantity(sso, param1, param2, fun, new_name)
Arguments
sso |
|
param1 |
Name of first parameter as character string. |
param2 |
Optional. Name of second parameter as character string. |
fun |
Function to call, i.e. |
new_name |
Name for the new parameter as character string. |
Value
sso, updated. See Examples.
See Also
drop_parameters to remove parameters from a
shinystan object.
Examples
# Using example shinystan object 'eight_schools'
sso <- eight_schools
sso <- generate_quantity(sso, fun = function(x) x^2,
param1 = "tau", new_name = "tau_sq")
sso <- generate_quantity(sso, fun = "-",
param1 = "theta[1]", param2 = "theta[2]",
new_name = "theta1minus2")
Launch the 'ShinyStan' app
Description
Launch the 'ShinyStan' app in the default web browser. 'RStudio' users also have the option of launching the app in the pop-up Viewer.
Usage
launch_shinystan(object, ...)
## Default S3 method:
launch_shinystan(object, ..., rstudio = getOption("shinystan.rstudio"))
## S3 method for class 'shinystan'
launch_shinystan(object, ..., rstudio = getOption("shinystan.rstudio"))
Arguments
object |
The object to use. For the default method this can be an object
of class |
... |
Optional arguments passed to |
rstudio |
Only relevant for 'RStudio' users. The default ( |
Value
The launch_shinystan function is used for the side effect of
starting the 'ShinyStan' app, but it also returns a shinystan
object, an instance of S4 class "shinystan".
References
Muth, C., Oravecz, Z., and Gabry, J. (2018) User-friendly Bayesian regression modeling: A tutorial with rstanarm and shinystan. The Quantitative Methods for Psychology. 14(2), 99–119. https://www.tqmp.org/RegularArticles/vol14-2/p099/p099.pdf
Gabry, J. , Simpson, D. , Vehtari, A. , Betancourt, M. and Gelman, A. (2019), Visualization in Bayesian workflow. *J. R. Stat. Soc. A*, 182: 389-402. doi:10.1111/rssa.12378 ([journal version](https://rss.onlinelibrary.wiley.com/doi/full/10.1111/rssa.12378), [preprint arXiv:1709.01449](https://arxiv.org/abs/1709.01449), [code on GitHub](https://github.com/jgabry/bayes-vis-paper))
See Also
as.shinystan for creating shinystan objects.
update_sso to update a shinystan object created
by a previous version of the package.
launch_shinystan_demo to try a demo.
Examples
## Not run:
#######################################
# Example 1: 'sso' is a shinystan object
#######################################
# Just launch shinystan
launch_shinystan(sso)
# Launch shinystan and replace sso with an updated version of itself
# if any changes are made to sso while using the app
sso <- launch_shinystan(sso)
# Launch shinystan but save any changes made to sso while running the app
# in a new shinystan object sso2. sso will remained unchanged.
sso2 <- launch_shinystan(sso)
#######################################
# Example 2: 'sf' is a stanfit object
#######################################
# Just launch shinystan
launch_shinystan(sf)
# Launch shinystan and save the resulting shinystan object
sf_sso <- launch_shinystan(sf)
# Now sf_sso is a shinystan object and so Example 1 (above) applies when
# using sf_sso.
#######################################
# Example 3: 'fit' is an mcmc.list, array or list of matrices
#######################################
# First create shinystan object (see ?as.shinystan) for full details)
## End(Not run)
'ShinyStan' demo
Description
'ShinyStan' demo
Usage
launch_shinystan_demo(
demo_name = "eight_schools",
rstudio = getOption("shinystan.rstudio"),
...
)
Arguments
demo_name |
The name of the demo. Currently
|
rstudio |
Only relevant for 'RStudio' users. The default ( |
... |
Optional arguments passed to |
Value
An S4 shinystan object.
See Also
launch_shinystan to launch the 'ShinyStan' interface
using a particular shinystan object.
as.shinystan for creating shinystan objects.
Examples
## Not run:
# launch demo but don't save a shinystan object
launch_shinystan_demo()
# launch demo and save the shinystan object for the demo
sso_demo <- launch_shinystan_demo()
## End(Not run)
rename_model (deprecated)
Description
This function is deprecated and will be removed in a future release. Please
use the model_name function instead.
Usage
rename_model(sso, new_model_name)
Arguments
sso, new_model_name |
Use the |
Get summary statistics from shinystan object
Description
From a shinystan object get rhat, effective sample size, posterior quantiles, means, standard deviations, sampler diagnostics, etc.
Usage
retrieve(sso, what, ...)
Arguments
sso |
|
what |
What do you want to get? See Details, below. |
... |
Optional arguments, in particular |
Details
The argument what can take on the values below. 'Args:
arg' means that arg can be specified in ... for this
value of what.
"rhat","Rhat","r_hat", or"R_hat"returns: Rhat statistics. Args:
pars"N_eff","n_eff","neff","Neff","ess", or"ESS"returns: Effective sample sizes. Args:
pars"mean"returns: Posterior means. Args:
pars"sd"returns: Posterior standard deviations. Args:
pars"se_mean"or"mcse"returns: Monte Carlo standard error. Args:
pars"median"returns: Posterior medians. Args:
pars."quantiles"or any string with"quant"in it (not case sensitive)returns: 2.5%, 25%, 50%, 75%, 97.5% posterior quantiles. Args:
pars."avg_accept_stat"or any string with"accept"in it (not case sensitive)returns: Average value of "accept_stat" (which itself is the average acceptance probability over the NUTS subtree). Args:
inc_warmup"prop_divergent"or any string with"diverg"in it (not case sensitive)returns: Proportion of divergent iterations for each chain. Args:
inc_warmup"max_treedepth"or any string with"tree"or"depth"in it (not case sensitive)returns: Maximum treedepth for each chain. Args:
inc_warmup"avg_stepsize"or any string with"step"in it (not case sensitive)returns: Average stepsize for each chain. Args:
inc_warmup
Note
Sampler diagnostics (e.g. "avg_accept_stat") only available for
models originally fit using Stan.
Examples
# Using example shinystan object 'eight_schools'
sso <- eight_schools
retrieve(sso, "rhat")
retrieve(sso, "mean", pars = c('theta[1]', 'mu'))
retrieve(sso, "quantiles")
retrieve(sso, "max_treedepth") # equivalent to retrieve(sso, "depth"), retrieve(sso, "tree"), etc.
retrieve(sso, "prop_divergent")
retrieve(sso, "prop_divergent", inc_warmup = TRUE)
S4 shinystan objects
Description
See as.shinystan for documentation on creating
shinystan objects and eight_schools for an example
object.
Slots
model_name(
"character") Model name.param_names(
"character") Parameter names.param_dims(
"list") Parameter dimensions.posterior_sample(
"array") MCMC sample.summary(
"matrix") Summary stats forposterior_sample.sampler_params(
"list") Sampler parameters (for certain Stan models only).n_chain(
"integer") Number of chains.n_iter(
"integer") Number of iterations per chain.n_warmup(
"integer") Number of warmup iterations per chain.user_model_info(
"character") Notes to display on the Notepad page in the 'ShinyStan' GUI.model_code(
"character") Model code to display on the Model Code page in the 'ShinyStan' GUI.misc(
"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. The Quantitative Methods for Psychology. 14(2), 99–119. https://www.tqmp.org/RegularArticles/vol14-2/p099/p099.pdf
See Also
as.shinystan for creating shinystan objects.
drop_parameters to remove parameters from a
shinystan object.
generate_quantity to add a new quantity to a
shinystan object.
shinystan-metadata to view or change metadata
associated with a shinystan object.
View or change metadata associated with a shinystan object
Description
View or change metadata associated with a shinystan object
Usage
sso_info(sso)
model_code(sso, code = NULL)
notes(sso, note = NULL, replace = FALSE)
model_name(sso, name = NULL)
Arguments
sso |
|
code |
A string, containing model code to be added, that can be
used as an argument to |
note |
A string containing a note to add to any existing notes
or replace existing notes, depending on the value of |
replace |
If |
name |
A string giving the new model name to use. |
Value
sso_info prints basic metadata including number of parameters,
chains, iterations, warmup iterations, etc. It does not return anything.
model_code returns or replaces model code stored in a
shinystan object. If code is NULL then any existing
model code stored in sso is returned as a character string. If
code is specified then an updated shinystan object is
returned with code added. For shinystan objects created from
stanfit (rstan) and stanreg (rstanarm) objects, model code is
automatically taken from that object and does not need to be added
manually. From within the 'ShinyStan' interface model code can be viewed on
the Model Code page.
notes returns, amends, or replaces notes stored in a
shinystan object. If note is NULL then any existing
notes stored in sso are returned as a character string. If
note is specified then an updated shinystan object is
returned with either note added to the previous notes (if
replace=FALSE) or overwritten by note (if replace =
TRUE). From within the 'ShinyStan' interface, notes are viewable on the
Notepad page.
model_name returns or replaces the model name associated with
a shinystan object. If name is NULL then the current
model name is returned. If name is specified then sso is
returned with an updated model name.
See Also
as.shinystan for creating shinystan objects.
drop_parameters to remove parameters from a
shinystan object.
generate_quantity to add a new quantity to a
shinystan object.
Examples
# use eight_schools example object
sso <- eight_schools
################
### sso_info ###
################
sso_info(sso)
##################
### model_code ###
##################
# view model code in example shinystan object 'eight_schools'
cat(model_code(sso))
# change the model code in sso
# some jags style code
my_code <- "
model {
for (i in 1:length(Y)) {
Y[i] ~ dpois(lambda[i])
log(lambda[i]) <- inprod(X[i,], theta[])
}
for (j in 1:J) {
theta[j] ~ dt(0.0, 1.0, 1.0)
}
}
"
sso <- model_code(sso, my_code)
cat(model_code(sso))
#############
### notes ###
#############
# view existing notes
notes(sso)
# add a note to the existing notes
sso <- notes(sso, "New note")
notes(sso)
cat(notes(sso))
# replace existing notes
sso <- notes(sso, "replacement note", replace = TRUE)
notes(sso)
##################
### model_name ###
##################
# view model name
model_name(sso)
# change model name
sso <- model_name(sso, "some other name")
identical(model_name(sso), "some other name")
Update an object created by the previous version of shinystan
Description
If you encounter any errors when using a shinystan object (sso)
created by a previous version of shinystan, you might need to run
update_sso. If update_sso does not resolve the problem and
you still have the object (e.g. stanfit, stanreg, mcmc.list) from which
sso was originally created, you can create a new shinystan object
using as.shinystan.
Usage
update_sso(sso)
Arguments
sso |
Value
If sso is already compatible with your version of
shinystan then sso itself is returned and a message is printed
indicating that sso is already up-to-date. Otherwise an updated
version of sso is returned unless an error is encountered.
See Also
as.shinystan for creating shinystan objects.
Examples
## Not run:
sso_new <- update_sso(sso)
## End(Not run)