summarizePosterior: Summarize Posterior Distribution for a Free Parameter

In bomeara/treevo: Using ABC to Understand Trait Evolution

Summarize Posterior Distribution for a Free Parameter

Description

This function summarizes the distribution of parameter estimates from the posterior of an ABC analysis using the doRun functions in TreEvo, for all freely varying parameters. Only the final generation is considered. This summary includes the mean, standard deviation and Highest Posterior Density (at a 0.8 alpha) for each parameter.

Usage

summarizePosterior(
  particleDataFrame,
  alpha = 0.8,
  coda = FALSE,
  verboseMultimodal = TRUE,
  stopIfFlat = TRUE,
  ...
)

Arguments

particleDataFrame	A particleDataFrame object, as found among the output from doRun functions.
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.
stopIfFlat	If TRUE (the default), the function will terminate and return an error if the distribution appears to be flat, with a high number of tied values in the posterior. If FALSE, the function will instead attempt to move forward, while returning a warning instead. The latter option is mainly implemented so internal calls to highestDensityInterval do not block otherwise long-running analyses.
...	Additional arguments passed to density. A user may want to mess with this to adjust bandwidth, et cetera.

Value

Returns a list, wherein each element of the list is secondary list containing the weighted mean, standard deviation, and a matrix giving the highest density intervals (e.g. the highest posterior density intervals). Because posterior estimates of parameter values may be multimodal, multiple sets of bounds may be reported for complex posterior distributions, which each constitute one row of the output matrix. See highestDensityInterval for details.

Author(s)

David W Bapst

See Also

This function is essentially a wrapper for independently applying a few summary statistics and applying highestDensityInterval to multiple parameter estimates, taken from the last generation of an ABC analysis in TreEvo. As each parameter is handled independently, the returned HPD intervals may not properly account for covariation among parameter estimates from the posterior. If testing whether a given observation is within a given density of the posterior or not, please look at function testMultivarOutlierHDR.

Examples

# example with output from doRun_prc
data(simRunExample)

# alpha = 0.95
summarizePosterior(
     resultsBMExample[[1]]$particleDataFrame, 
     alpha = 0.95)

# you might be tempted to use alphas like 95%, 
    # but with bayesian statistics
# we often don't sample the distribution well enough to know
    # its shape to exceeding detail. 
    # alpha = 0.8 may be more reasonable.
summarizePosterior(
    resultsBMExample[[1]]$particleDataFrame, 
    alpha = 0.8)

# or even better, for coverage purposes, maybe 0.5
summarizePosterior(
    resultsBMExample[[1]]$particleDataFrame, 
    alpha = 0.5)

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