plot_postpred: Diagnostic plots from posterior predictive distribution

In jagshelper: Extracting and Visualizing Output from 'jagsUI'

Diagnostic plots from posterior predictive distribution

Description

This is a wrapper function that produces a sequence of plots illustrating the posterior predictive distribution. Optional plots are:

• An envelope plot of the posterior predictive distribution as a time series, overlayed with the data values (if plot_data=TRUE is used)

• The centered posterior predictive distributions, as plotted by ts_postpred, and overlayed with the data residuals (if plot_residuals=TRUE is used)

• The approximate residual standard deviation, calculated from a moving window of 10 data points in sequence. (if plot_sd=TRUE is used)

These three plots are repeated, for a sequence of different variables expressed on the x-axis, potentially highlighting different features of the dataset or model structure:

• The data sequence (if ⁠whichplots=⁠ contains 1)

• The ⁠x=⁠ variable supplied (if ⁠whichplots=⁠ contains 2)

• The ⁠y=⁠ variable supplied (if ⁠whichplots=⁠ contains 3)

• The fitted values, as estimated by the posterior predictive median (if ⁠whichplots=⁠ contains 4)

While not an omnibus posterior predictive check, this plot can be useful for detecting an overparameterized model, or else improper specification of observation error.

It should be noted that this function will only produce meaningful results with a vector of data, as opposed to a single value.

The posterior predictive distribution can be specified in two possible ways: either a single output object from jagsUI with an associated parameter name, or as a matrix or data.frame of posterior samples.

Usage

plot_postpred(
  ypp,
  y,
  p = NULL,
  x = NULL,
  whichplots = c(1, 2, 4),
  plot_data = TRUE,
  plot_residuals = TRUE,
  plot_sd = TRUE,
  pch = 1,
  pointcol = 1,
  lines = FALSE,
  ...
)

Arguments

ypp	Either a matrix or data.frame of posterior samples, or an output object returned from jagsUI and a supplied parameter name
y	The associated data vector
p	A character name, if a jagsUI object is passed to ypp
x	The time measurements associated with time series y. If the default NULL is accepted, associated plots will be suppressed.
whichplots	A vector of which sets of plots to produce (that is, with respect to which variables on the x-axis). See above for details. Defaults to c(1, 2, 4).
plot_data	Whether to produce plots associated with the data (⁠y=⁠) time series and untransformed posterior predictive distribution. Defaults to TRUE.
plot_residuals	Whether to produce plots associated with the residual time series and posterior predictive residuals. Defaults to TRUE.
plot_sd	Whether to produce plots of the moving-window standard deviation of the residuals. Defaults to TRUE.
pch	Plotting character for points, which will accept a vector input. See points. Defaults to 1.
pointcol	Plotting color for points. Defaults to 1.
lines	Whether to add a line linking data time series points. Defaults to FALSE.
...	Additional arguments to envelope

Value

NULL

Note

This function assumes the existence of a matrix of posterior predictive samples corresponding to a data vector, the construction of which must be left to the user. This can be accomplished within JAGS, or using appropriate simulation from the posterior samples.

Author(s)

Matt Tyers

See Also

qq_postpred, ts_postpred, check_Rhat, check_neff, traceworstRhat, plotRhats

Examples

# first, a quick look at the example data...
str(SS_data)
str(SS_out$sims.list$ypp)

# recommended usage
parmfrow <- par("mfrow") # storing graphics state
par(mfcol = c(3,3))  # a recommended setting to organize plots

plot_postpred(ypp=SS_out, p="ypp", y=SS_data$y, x=SS_data$x)

par(mfrow = parmfrow) # resetting graphics state

jagshelper documentation built on Oct. 22, 2024, 1:06 a.m.