Tools are provided to streamline Bayesian analyses in ‘JAGS’ using the ‘jagsUI’ package. Included are functions for extracting output in simpler format, functions for streamlining assessment of convergence, and functions for producing summary plots of output. Also included is a function that provides a simple template for running ‘JAGS’ from ‘R’.
skeleton() prints an example ‘JAGS’ model and
associated ‘jagsUI’ code to the console, along with code to simulate a
corresponding dataset. This is intended to serve as a template that can
be altered as needed by the user.
nparam() and nbyname() give the total
number of parameter nodes and the number (or array dimensions) per
parameter name, respectively. It can be useful to know how many
parameter nodes have been saved before performing further model
diagnostics.
check_Rhat() and check_neff() give the
proportion of parameter nodes to meet a given threshold of
Rhat (Gelman-Rubin convergence diagnostic) or
n.eff (effective sample size), respectively.
plotRhats() plots all Rhat values from
a model output (or alternately n.eff), which can serve as a
quick visualization to assess whether adequate convergence has been
achieved.
tracedens_jags() produces trace plots and overlayed
by-chain kernel densities of all parameter nodes, or a subset given by
the user.
Note that functions are also provided to give trace plots or by-chain
kernel densities by themselves, with inputs of ‘jagsUI’ output objects,
data.frames, or single vectors.
traceworstRhat() is a wrapper of
tracedens_jags() that produces trace plots of the parameter
nodes with the worst (largest) associated values of Rhat,
or alternately, the smallest values of n.eff. This can be
useful if a model contains vectors or arrays of many parameter
nodes.
pairstrace_jags() gives methods for plotting
two-dimensional trace plots, scatter plots, or contour plots, in which
each possible pairing of parameter nodes are plotted with respect to one
another. In addition to convergence, this may provide a graphical check
for correlation between parameter nodes, or problematic posterior
surface shapes.
cor_jags() and plotcor_jags()
respectively return and plot correlation matrices for all or a subset of
parameter nodes.
qq_postpred() produces a quantile-quantile plot from
the posterior predictive distributions associated with a vector of data.
This can be visually interpreted in a similar manner to a traditional
Q-Q plot, with an appropriately-specified model producing a plot that
falls along the x=y line. While not intended as an omnibus posterior
predictive check, this plot might be useful in detecting
overparameterization, poor convergence, or a mis-specified error model.
It should be noted that this function depends on the existence of a
matrix of posterior predictive samples, which is up to the user. This
can be specified within JAGS, or via appropriate simulation from the
posterior samples.
ts_postpred() produces an envelope plot of the
centered posterior predictive distribution associated with a vector of
data (most likely a time series), which is defined as the difference
between the posterior predictive distribution and posterior predictive
medians. This may be used to explore possible temporal features not
visible using qq_postpred().
plot_postpred() is a wrapper that combines several
calls of envelope() and ts_postpred() for a
sequence of different variables expressed on the x-axis, potentially
highlighting different features of the dataset or model
structure.
kfold() provides automated k-fold or leave-one-out
cross validation for a specified component of a JAGS data object, for a
specified JAGS model. The intended utility of this function is
comparison of predictive power between a set of candidate models, rather
than the fit or appropriateness of a single model.
jags_df() extracts the MCMC iterations from a
‘jagsUI’ output object as a data.frame, which may be
preferable to some users.
pull_post() extracts a subset of columns of a
posterior formatted as a data.frame.
envelope() overlays a set of credible interval
envelopes (default values are 50% and 95%) and a median line, for a
sequence of parameter nodes. This function is intended for plotting the
posterior densities of a vector of parameter nodes in which order does
matter, such as in a time series.
overlayenvelope() is a wrapper for
envelope() allowing for multiple envelope plots to be
overlayed.
caterpillar() overlays a set of credible interval
bars (default values are 50% and 95%) and median markings, for a set of
parameter nodes side-by-side. This function is intended for plotting the
posterior densities of a vector of parameter nodes in which order may
not matter, such as a set of random effects.
crossplot() provides methods for bivariate plotting
of a single pair of parameters or paired vectors of parameter nodes.
Options are given to add credible intervals in the x- and y- directions,
credible intervals along the principal component axes, or approximate
smoothed credible polygons.
comparecat() produces an interleaved caterpillar
plot for multiple ‘jagsUI’ output objects or data.frames,
in which parameter nodes with the same name across output objects are
plotted next to one another. The intent of this function is to allow
comparison among multiple candidate models.
comparedens() is similar in use to
comparecat(), but instead plots left- and right-facing
vertically-oriented kernel densities for TWO model output objects, with
parameter nodes with the same names plotted facing one another.
comparepriors() is a wrapper of
comparedens(), but compares all distributions of parameters
with names ending in "_prior" with the corresponding
posterior distributions.
plotdens() produces a kernel density plot of a
single parameter node, or overlays kernel densities for multiple
parameter nodes.
The development version is currently available on Github, and can be installed in R with the following code:
install.packages("devtools",dependencies=T)
devtools::install_github("mbtyers/jagshelper")