ra4bayesmeta (version 1.0-8)

plot_RA: Reference analysis plot based on a data frame using 2 benchmarks: Plot heterogeneity benchmark priors and the corresponding marginal posteriors

Description

Plots the proper half-normal benchmark heterogeneity prior proposed in Ott et al. (2021) and the corresponding marginal benchmark posteriors for different parameters in the NNHM. Also displays the marginal Jeffreys reference posterior, which is induced by an improper reference prior. Displays the specified actual heterogeneity priors in tau.prior and the corresponding marginal posteriors as well.

Usage

plot_RA(df, tau.prior = list(),
        type = "pri.tau", improper.prior = NULL, show.sigma.i = FALSE,
        xlim, ylim, legend = FALSE,
        pos.legend = "topright", legend.tau.prior = c(),
        xlab = NULL, bty = "o",
        scale.hn0 = 1/500, mu.mean = 0, mu.sd = 4)

Value

No return value, produces graphical output only.

Arguments

df

data frame with one column "y" containing the (transformed) effect estimates for the individual studies and one column "sigma" containing the standard errors of these estimates.

tau.prior

list (maximum length 5) of prior specifications, which are either functions returning the probability densities of the actual priors of interest for the heterogeneity parameter tau or character strings specifying priors implemented in the bayesmeta function. See the documentation of the argument tau.prior of the bayesmeta function for details.

type

specifies if heterogeneity priors or marginal posterior densities for a given parameter should be plotted. Options are "pri.tau" for heterogeneity priors, "post.mu" for the marg. posterior of the main effect mu, "post.tau" for the marg. posterior of the heterogeneity tau and "post.theta.new" for the marg. posterior of the predicted effect theta_new in a new study.

improper.prior

vector of integers specifying the positions of the improper priors in the list tau.prior or NULL (the default). Determines which prior densities should not be plotted. Applies only to type = "pri.tau".

show.sigma.i

logical. Specifies if the standard errors of the estimates for the individual studies (the entries of the column "sigma" in the data frame df) should be added to the density plot as dots. Defaults to FALSE. Applies only to type = "pri.tau".

xlim

a vector of two real numbers. Limits of the x-axis. (First number >= 0 for densities for tau.)

ylim

a vector of two real non-negative numbers. Limits of the y-axis.

legend

logical. Specifies if a legend should be added to the plot. Defaults to FALSE.

pos.legend

a character string specifing the position of the legend in the plot. Options are all the keywords accepted by the legend function in the graphics package, i.e. "bottomright", "bottom", "bottomleft", "left", "topleft", "top", "topright", "right" and "center".

legend.tau.prior

a vector of character strings or expressions of the same length as the list tau.prior. Determines the legend entries corresponding to the actual heterogeneity priors specified in tau.prior, in the same order as the priors in that list.

xlab

x-axis label. If unspecified or set to NULL (the default), a default label specifying the paramter of interest is used.

bty

the type of box to be drawn around the legend. The allowed values are "o" (the default) and "n".

scale.hn0

scale parameter of the half-normal benchmark prior (usually a small number to obtain an anti-conservative benchmark which has most of its probability mass close to 0). Defaults to 0.002.

mu.mean

mean of the normal prior for the effect mu.

mu.sd

standard deviation of the normal prior for the effect mu.

Details

The two heterogeneity benchmark priors used are introduced in Ott et al. (2021, Section 3.4) and they are denoted by HN0 and J. Note that the latter Jeffreys reference prior J is improper, but leads to a proper posterior if there are at least two studies in the meta-analysis data set.

The default values for mu.mean and mu.sd are suitable for effects mu on the log odds (ratio) scale.

If you wish to adapt the colors, line types or line widths of the plotted densities, we suggest to compute the models fits first by using the function fit_models_RA and then to apply the more flexible function plot_RA_fits operating on model fits of class bayesmeta.

References

Ott, M., Plummer, M., Roos, M. (2021). How vague is vague? How informative is informative? Reference analysis for Bayesian meta-analysis. Statistics in Medicine 40, 4505--4521. tools:::Rd_expr_doi("10.1002/sim.9076")

See Also

plot_RA_fits, plot_RA_5bm, fit_models_RA

Examples

# for aurigular acupuncture (AA) data set with two
# actual half-normal and half-Cauchy heterogeneity priors
data(aa)
# it takes a few seconds to run each of the following functions
# prior densities
plot_RA(df=aa, tau.prior=list(function(t)dhalfnormal(t, scale=1),
                              function(t)dhalfcauchy(t, scale=1)),
        type="pri.tau", xlim=c(0,2), ylim=c(0,3), legend=TRUE,
        legend.tau.prior=c("HN(1)", "HC(1)"))

# marginal posterior for the effect mu
plot_RA(df=aa, tau.prior=list(function(t)dhalfnormal(t, scale=1),
                              function(t)dhalfcauchy(t, scale=1)),
        type="post.mu", xlim=c(-1.5,2), ylim=c(0,3), legend=TRUE,
        legend.tau.prior=c("HN(1)", "HC(1)"))