postPlot: Posterior distribution plot.

In matthewwolak/wolakR: Handy Tools that Save Me Time

Posterior distribution plot.

Description

Pretty plot of a posterior distribution that can include summary statistics, such as the posterior mean and credible interval as well as a prior density.

Usage

postPlot(
  posterior,
  bw = "nrd",
  plotHist = TRUE,
  histbreaks = 100,
  histcol = NULL,
  prior = NULL,
  prange = c("prior", "posterior"),
  main,
  sub,
  ylim,
  denslwd = 6,
  denslty = "solid",
  denscol = "black",
  hpdcol = "grey70",
  meanpch = 23,
  meanbg = "white",
  meancol = "red",
  modepch = 3,
  modebg = NA,
  modecol = "blue",
  priorlwd = 3,
  priorlty = "solid",
  priorcol = "green",
  at1 = NULL,
  at2 = NULL,
  labels1 = NULL,
  labels2 = NULL,
  plot = TRUE,
  ...
)

Arguments

posterior	Object containing a marginal posterior distribution from from which kernel density estimates can be calulated by the coda::density function.
bw	Either a numeric or character for calculating the smoothing bandwidth used in the kernel density estimation. If numeric, the value is used as the standard deviation of the smoothing kernel. If character, the string is used as a standard rule to choose the bandwith. See details in density. Note that the default value "nrd" is not the default used in density.
plotHist	Should a histogram of the density be plotted as well.
histbreaks	If plotHist = TRUE, then the number of breaks. See hist for details.
prior	The prior distribution for a line to be added to the plot. If NULL (the default) then no line is added. A prior is plotted if either a mcmc object or list with the prior density is supplied. See Details.
prange	Character argument specifying the relative range c("prior", "posterior") for the density estimation of the prior. The supplied argument must begin with either prior or posterior exactly, but can end with a numeric value indicating the relative range of the prior posterior to be used. See Details. Range adjustment currently only works when class mcmc provided to prior.#FIXME
main	Overall title for the plot. See plot and title.
sub	Sub-title for the plot. See plot and title.
ylim	Y-axis limits to the plotting region, passed to densplot. See plot.window.
denslwd, priorlwd	The line widths for the lines to be plotted representing the kernel density estimate of the posterior (denslwd) or prior (priorlwd). See par for details.
denslty, priorlty	The line type for the lines to be plotted representing the kernel density estimate of the posterior (denslty) or prior (priorlty). See par for details.
denscol, hpdcol, meancol, modecol, priorcol, histcol	The line colors for the plotted features representing the kernel density estimate (denscol), credible interval (hpdcol), posterior mean (meancol), posterior mode (modecol), prior density (priorcol), or histogram fill (histcol). See par for details.
meanpch, modepch	The point symbol to use for plotting the posterior mean (meanpch) and mode (modepch). See points for details.
meanbg, modebf	The background color for plotting symbols used for the posterior mean (meanbg) and mode (modebg). Only used if values for meanpch and modepch allow background colors. See points for details.
at1, at2	The points at which tick-marks are to be drawn on the x-axis (at1) and y-axis (at2). See axis for details.
labels1, labels2	Labels to be placed at the tick-marks of the x-axis (labels1) and and y-axis (labels2). See axis for details.
plot	Logical. If TRUE (default) the plotting is performed, otherwise the graphical output is suppressed.
...	Additional arguments passed to densplot, hist, and lines.

Details

To plot a prior distribution, prior should either specify an object of class mcmc that contains a simulated prior distribution or it should contain a list which contains the prior density (where the first two elements must be named x and y and contain the quantiles and densities, respectively.). Note that a function to generate the prior distribution may be specified. However, this must return either a mcmc or list object.

TODO: Add more about prior plotting, specifically how parameter expanded priors are simulated versus inverse-Wishart/Gamma are derived straight from their distribution functions. Also, note how density is calculated#TODO

If the prior is of class mcmc then the argument prange can be used to either extend or restrict the range over which the prior density estimation is conducted, in relation to the posterior distribution. The range alteration is done by specifying posteriorN, or appending the "posterior" character string with a numeric value indicating the desired adjustment of the range. Prior density will then be calculated after taking a subset of the current samples that fall in the range. Note, this process only makes sense when used in conjunction with posterior. By default, a 1 is used if there is no numeric suffix; indicating that a 1-to-1 mapping of the range should be used. Values of the suffix >1 will extend the range, while those <1 will contract it.

Value

A list returned invisibly (assign to an object to view):

call

The original call.

postDensity

List containing objects describing the posterior distribution. Items include a character indicating if the density was adjusted because of boundary constraints, an object of class "density", and an object of class "histogram".

priorDensity

List containing objects describing the prior distribution. Items include a character indicating if the density was adjusted because of boundary constraints and an object of class "density".

Warning

The use of the ... argument is untested. Arguments of the same name that are shared among densplot, hist, or lines will affect each of these aspects of the plot if supplied to postPlot. Proceed with caution!

Author(s)

[e-mail]

See Also

densplot, hist

Other MCMC posterior distribution helper functions: plot2mcmc(), postTable()

Examples

# Simulate two example MCMC chains:
## Both are standard normal distributions of only positive values
## However, one is on the boundary (near zero) while the other is not
normMCMC <- coda::mcmc(matrix(c(abs(rnorm(1000, 0.2, 1)), rnorm(1000, 10, 1)),
ncol = 2))
par(mfrow = c(2, 1))
  postPlot(normMCMC[, 1], ylim = c(0, 1))
  postPlot(normMCMC[, 2], ylim = c(0, 1))

# Now include an inverse Gamma prior, using the density function
postPlot(normMCMC[, 1], ylim = c(0,1),
  prior = dIW(seq(1e-16, 5, length = 1000), V = diag(1), nu = 1))

# Example with parameter expanded prior:
pepr <- coda::mcmc(rpeIW(1000, V = diag(2), nu = 2, alpha.mu = rep(0, 2),
  alpha.V = diag(2)*1000))
par(mfrow = c(2, 1))
  postPlot(normMCMC[, 1], ylim = c(0, 1),
    prior = pepr[,1], prange = "posterior6")
  postPlot(normMCMC[, 2], ylim = c(0, 1),
    prior = pepr[,4], prange = "posterior1.5") 
# different scalar to get same y-intercept

matthewwolak/wolakR documentation built on May 10, 2023, 1:27 p.m.