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

plot_RA_5bm {ra4bayesmeta}

R Documentation

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. 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. doi:10.1002/sim.9076

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)"))

[Package ra4bayesmeta version 1.0-8 Index]