plotPriorPost: Plotting, Summarizing and Comparing the Prior and Posterior...

In bomeara/treevo: Using ABC to Understand Trait Evolution

Plotting, Summarizing and Comparing the Prior and Posterior Distributions

Description

Assorted functions for visualizing and summarizing the prior and posterior probability distributions associated with ABC analyses.

Usage

plotPrior(
  priorFn = match.arg(arg = priorFn, choices = c("fixed", "uniform", "normal",
    "lognormal", "gamma", "exponential"), several.ok = FALSE),
  priorVariables,
  plotQuants = TRUE,
  plotLegend = TRUE
)

plotUnivariatePosteriorVsPrior(
  posteriorCurve,
  priorCurve,
  label = "parameter",
  trueValue = NULL,
  ...
)

getUnivariatePriorCurve(
  priorFn,
  priorVariables,
  nPoints = 1e+05,
  from = NULL,
  to = NULL,
  alpha = 0.8,
  coda = FALSE,
  verboseMultimodal = TRUE,
  ...
)

getUnivariatePosteriorCurve(
  acceptedValues,
  from = NULL,
  to = NULL,
  alpha = 0.8,
  coda = FALSE,
  verboseMultimodal = TRUE,
  ...
)

Arguments

priorFn	Prior Shape of the distribution; one of either "fixed", "uniform", "normal", "lognormal", "gamma", or "exponential".
priorVariables	Variables needed to describe the shape of the distribution, dependent on priorFn: priorFn = "uniform" priorVariables = c(min, max) priorFn = "normal" priorVariables = c(mean, standard deviation) priorFn = "lognormal" priorVariables = c(mean, standard deviation) priorFn = "gamma" priorVariables = c(shape, scale) priorFn = "exponential" priorVariables = c(rate)
plotQuants	If TRUE, plots line segments at the quantiles
plotLegend	If TRUE, plots legend box with quantile values
posteriorCurve	Kernal density estimates for the posterior distribution from getUnivariatePosteriorCurve.
priorCurve	Kernal density estimates for the prior distribution from getUnivariatePriorCurve.
label	Horizontal X-axis label for the plot.
trueValue	True parameter value, if any such exists and is known (usually only true of simulations).
...	For getUnivariatePriorCurve and getUnivariatePosteriorCurve, this can contain additional arguments passed to density, for use in both calculating the kernal density estimate for finding the curve, and for estimating the highest density interval. A user may want to mess with this to adjust bandwidth, et cetera. For plotUnivariatePosteriorVsPrior, this passes additional commands to the initial call plot, and thus can set things like a main plotting title, among other things.
nPoints	Number of points to draw.
from	Lower bound, if any. By default this is NULL and thus ignored.
to	Upper bound, if any. By default this is NULL and thus ignored.
alpha	The threshold used for defining the highest density frequency cut-off. If the highest density interval is applied to a Bayesian MCMC posterior sample, then the interval is effectively calculated for this value as a posterior probability density.
coda	Default is FALSE. If TRUE, unimodal highest density regions will instead be calculated using HPDinterval from package coda, which is similar to the function quantile in that it calculates only a single interval.
verboseMultimodal	If TRUE, the function will print a message indicating when the inferred highest density interval is discontinuous, and thus likely reflects that the supplied data is multimodal.
acceptedValues	Vector of accepted particle values.

Details

Function plotPrior visualizes the shape of various prior probability distributions available in TreEvo ABC analyses, while getUnivariatePriorCurve returns density coordinates and summary statistics from user-selected prior probability distribution.

Similarly, function getUnivariatePosteriorCurve returns density coordinates and summary statistics from the posterior distribution of an ABC analysis.

Both getUnivariatePriorCurve and getUnivariatePosteriorCurve also calculate the highest density intervals for their respective parameters, using the function highestDensityInterval.

Function plotUnivariatePosteriorVsPrior plots the univariate density distributions from the prior and posterior against each other for comparison, along with the highest density intervals (HDI) for both.

The summaries calculated from getUnivariatePriorCurve and getUnivariatePosteriorCurve are used as the input for plotUnivariatePosteriorVsPrior, hence the relationship of these functions to each other, and why they are listed together here.

Value

plotPrior and plotUnivariatePosteriorVsPrior produce plots of the respective distributions (see above).

getUnivariatePriorCurve returns a list of x and y density coordinates, mean, and the highest density intervals (HDI) for their respective distribution.

getUnivariatePosteriorCurve does the same for a posterior sample of parameter estimates, returning a list of x and y density coordinates, mean, and the highest posterior density intervals (HPD).

Author(s)

Brian O'Meara and Barb Banbury

See Also

Highest posterior densities are calculated via highestDensityInterval.

plotPosteriors Plots multiple posteriors against their priors and potential known values.

Examples

data(simRunExample)

# examples with plotPrior

plotPrior(
    priorFn = "exponential", 
    priorVariables = c(10))
    
plotPrior(
    priorFn = "normal", 
    priorVariables = c(1, 2))
    
plotPrior(
    priorFn = "gamma", 
    priorVariables = c(2, .2),
    plotQuants = FALSE, 
    plotLegend = FALSE)

# examples of getting density coordinates and
  # summary statistics from distributions

priorKernal <- getUnivariatePriorCurve(
    priorFn = "normal", 
    priorVariables = c(28, 2), 
    nPoints = 100000, 
    from = NULL, 
    to = NULL, 
    alpha = 0.95)

postKernal <- getUnivariatePosteriorCurve(
    acceptedValues = 
        resultsBMExample[[1]]$particleDataFrame$starting_1, 
    from = NULL, 
    to = NULL, 
    alpha = 0.95)

priorKernal
postKernal

# let's compare this (supposed) prior
  # against the posterior in a plot

plotUnivariatePosteriorVsPrior(
    posteriorCurve = postKernal, 
    priorCurve = priorKernal, 
    label = "parameter", 
    trueValue = NULL)

# cool!

bomeara/treevo documentation built on Aug. 19, 2023, 6:52 p.m.