plot_RA_5bm: Reference analysis plot based on a data frame using 5...

In ra4bayesmeta: Reference Analysis for Bayesian Meta-Analysis

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

Description

Plots the four proper benchmark heterogeneity priors proposed in the Supplementary Material of 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_5bm(df, tau.prior=list(), type="pri.tau",
            improper.prior = NULL, show.sigma.i = FALSE,
            xlim, ylim,
            m_J=NA, M_J=NA, upper.J=3, digits.J=2,
            m_inf=NA, M_inf=NA, rlmc0=0.0001, rlmc1=0.9999,
            legend=FALSE, pos.legend="topright", legend.tau.prior=c(),
            xlab = NULL, bty = "o",
            mu.mean=0, mu.sd=4)

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 position 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.
m_J	parameter value m=m_J of the SGC(m) prior, which induces a marignal posterior for the heterogeneity standard deviation tau close to Jeffreys reference posterior (wrt the Hellinger distance). If set to NA (the default), this parameter is computed using the function m_j_sgc and some other parameters.
M_J	parameter value M=M_J of the SIGC(M) prior, which induces a marignal posterior for the heterogeneity standard deviation tau close to Jeffreys reference posterior (wrt the Hellinger distance). If set to NA (the default), this parameter is computed using the function M_j_sigc and some other parameters.
upper.J	upper bound for the parameters M_J and m_J. Real number in (1,\infty). Is required only if M_J=NA or m_J=NA.
digits.J	specifies the desired precision of the parameter values M_J and m_J, i.e. to how many digits these two values should be determined. Possible values are 1,2,3. Defaults to 2. Is required only if M_J=NA or m_J=NA.
m_inf	parameter value m=m_{inf} of the SGC(m) prior, such that the median relative latent model complexity (RLMC) is close to 0. If set to NA (the default), this parameter is computed using the function m_inf_sgc, such that the median RLMC is approximately equal to rlmc0.
M_inf	parameter value M=M_{inf} of the SIGC(M) prior, such that the median relative latent model complexity (RLMC) is close to 1. If set to NA (the default), this parameter is computed using the function M_inf_sigc, such that the median RLMC is approximately equal to rlmc1.
rlmc0	RLMC target value for the SGC(m_{inf}) benchmark prior (typically close to 0). Is required only if m_inf=NA.
rlmc1	RLMC target value for the SIGC(M_{inf}) benchmark prior (typically close to 1). Is required only if M_inf=NA.
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".
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 five heterogeneity benchmark priors used are introduced in the Supplementary Material of Ott et al. (2021, Sections 2.2.1, 2.5 and 2.6, see also Section 3.4 of Ott et al. (2021) for Jeffreys reference prior), where they are denoted by SGC(m_{inf}), SIGC(M_J), SGC(m_J), SIGC(M_{inf}) and Jeffreys. Note that the latter Jeffreys reference prior 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.

Value

No return value, produces graphical output only.

Warning

This function may take several minutes to run if the parameter m_J and/or M_J is not specified, especially if the desired precision is digits.J=2 or even digits.J=3.

A warning message will be displayed if one of the parameters m_inf, M_J, m_J or M_inf has a value larger than 5*10^6, since this may lead to numerical problems in the bayesmeta function used for computation of the marginal posteriors.

References

Ott, M., Plummer, M., Roos, M. (2021). Supplementary Material: How vague is vague? How informative is informative? Reference analysis for Bayesian meta-analysis. Statistics in Medicine. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1002/sim.9076")}

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. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1002/sim.9076")}

See Also

fit_models_RA_5bm, plot_RA_fits

Examples

# for aurigular acupuncture (AA) data set with two
# actual half-normal and half-Cauchy heterogeneity priors
data(aa)
 
# prior densities
# warning: it takes ca. 8 min. to run this function
# (computation is much faster if m_J and M_J are specified)
plot_RA_5bm(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
# warning: it takes ca. 7 min. to run this function
plot_RA_5bm(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)"))
            

ra4bayesmeta documentation built on Oct. 7, 2023, 1:07 a.m.