jagshelper

Extracting and Visualizing Output from ‘jagsUI’

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’.

Commonly-used functions: Model construction and output summary

• 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.

Commonly-used functions: Assessing model convergence and appropriateness

• 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.

Commonly-used functions: Extracting simplified model output

• 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.

Commonly-used functions: Plotting model output

• 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.

Installation

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")