Package 'ra4bayesmeta' reference manual

Title:	Reference Analysis for Bayesian Meta-Analysis
Description:	Functionality for performing a principled reference analysis in the Bayesian normal-normal hierarchical model used for Bayesian meta-analysis, as described in Ott, Plummer and Roos (2021) <doi:10.1002/sim.9076>. Computes a reference posterior, induced by a minimally informative improper reference prior for the between-study (heterogeneity) standard deviation. Determines additional proper anti-conservative (and conservative) prior benchmarks. Includes functions for reference analyses at both the posterior and the prior level, which, given the data, quantify the informativeness of a heterogeneity prior of interest relative to the minimally informative reference prior and the proper prior benchmarks. The functions operate on data sets which are compatible with the 'bayesmeta' package.
Authors:	Manuela Ott [aut, cre], Malgorzata Roos [aut]
Maintainer:	Manuela Ott <[email protected]>
License:	GPL (>= 2)
Version:	1.0-8
Built:	2025-01-28 02:37:27 UTC
Source:	https://github.com/cran/ra4bayesmeta

Reference Analysis for Bayesian Meta-Analysis

Description

Functionality for performing a principled reference analysis in the Bayesian normal-normal hierarchical model (NNHM) used for Bayesian meta-analysis. Focuses on the choice of the prior for the between-study (heterogeneity) standard deviation $\tau$ . Implements the methodology proposed in Ott et al. (2021).

The posterior reference analysis applies the Hellinger distance to quantify the informativeness of an actual heterogeneity prior of interest by comparing the corresponding marginal posteriors (for different parameters in the NNHM) with posterior benchmarks. The prior reference analysis quantifies the informativeness of an actual heterogeneity prior given the data by computing its Hellinger distance to prior benchmarks.

The main posterior benchmark used is Jeffreys reference posterior induced by a minimally informative improper reference prior (denoted by J) for the heterogeneity. Two alternative proposals for additional posterior benchmarks are implemented. The first, simpler proposal is described in Ott et al. (2021) and uses a benchmark induced by an anti-conservative half-normal heterogeneity prior (denoted by HN0). This benchmark allows us to discriminate between anti-conservative and conservative heterogeneity priors with respect to the reference prior. The second, more involved proposal is introduced in the Supplementary Material of Ott et al. (2021) and uses up to four additional benchmarks induced by proper priors. These benchmarks allow us to discriminate between strongly anti-conservative, reference affine, and strongly conservative heterogeneity priors. All four benchmark priors belong to two closely related parametric families, the so-called "square-root generalized conventional" (SGC) and "inverse square-root generalized conventional" (SIGC) distributions, which are derived from prior distributions for variance components described in Berger & Deely (1988). Note that most of these prior benchmarks also depend on the data set considered.

Functions which implement this second proposal use 3 benchmarks for the posterior reference analysis (Jeffreys reference posterior and two additional benchmarks induced by a highly anti-conservative heterogeneity prior SGC( $m_{inf}$ ) and a highly conservative heterogeneity prior SIGC( $M_{inf}$ ), respectively) and 5 benchmarks for the prior reference analysis (Jeffreys reference prior and 4 proper priors) and have a corresponding suffix _3bm or _5bm. The corresponding functions without such a suffix implement the first proposal based on 2 heterogeneity benchmark priors (the half-normal and Jeffreys reference prior).

The main functions post_RA and post_RA_3bm perform the reference analysis at the posterior level based on a data frame as input. The functions fit_models_RA and fit_models_RA_5bm compute the benchmark heterogeneity priors and corresponding (marginal) posteriors for a given data frame. The more flexible functions post_RA_fits and pri_RA_fits perform the reference analysis at the posterior level and prior level based on the provided benchmark and actual model fits (of class bayesmeta), so that alternative benchmarks heterogeneity priors can also be used. Functions for plotting the densities of the heterogeneity priors and marginal posteriors for different parameters are also provided. The functions operate on data frames which are compatible with the bayesmeta R package on CRAN.

Details

Package: ra4bayesmeta

Type: Package

Title: Reference Analysis for Bayesian Meta-Analysis

Version: 1.0-8

Date: 2023-10-06

Author: Manuela Ott [aut, cre], Malgorzata Roos [aut]

Maintainer: Manuela Ott <[email protected]>

Depends: bayesmeta

License: GPL (>=2)

Author(s)

Manuela Ott, Malgorzata Roos

Maintainer: Manuela Ott <[email protected]>

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

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

Berger, J. O., Deely, J. (1988). A Bayesian approach to ranking and selection of related means with alternatives to analysis-of-variance methodology. Journal of the American Statistical Association 83(402), 364–373.

Examples

# auricular acupuncture (AA) data set
data(aa)

# it takes several seconds to run each of the following functions
# posterior reference analysis
# for standard HN and HC heterogeneity priors
# using the HN0 and J benchmarks
post_RA(df=aa, tau.prior=
               list(function(t)dhalfnormal(t, scale=1),
                    function(t)dhalfcauchy(t, scale=1)))

# posterior reference analysis
# for standard HN and HC heterogeneity priors
# using 3 benchmarks (SGC(m_inf), J and SIGC(M_inf) priors)
post_RA_3bm(df=aa, tau.prior=
                   list(function(t)dhalfnormal(t, scale=1),
                        function(t)dhalfcauchy(t, scale=1)))


# plot the marginal posteriors for the effect mu
# using the HN0 and J benchmarks
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,1.5), ylim=c(0,2.5),
        legend=TRUE, legend.tau.prior=c("HN(1)", "HC(1)"))
         
# auricular acupuncture (AA) data set
data(aa)

# it takes several seconds to run each of the following functions
# posterior reference analysis
# for standard HN and HC heterogeneity priors
# using the HN0 and J benchmarks
post_RA(df=aa, tau.prior=
               list(function(t)dhalfnormal(t, scale=1),
                    function(t)dhalfcauchy(t, scale=1)))

# posterior reference analysis
# for standard HN and HC heterogeneity priors
# using 3 benchmarks (SGC(m_inf), J and SIGC(M_inf) priors)
post_RA_3bm(df=aa, tau.prior=
                   list(function(t)dhalfnormal(t, scale=1),
                        function(t)dhalfcauchy(t, scale=1)))


# plot the marginal posteriors for the effect mu
# using the HN0 and J benchmarks
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,1.5), ylim=c(0,2.5),
        legend=TRUE, legend.tau.prior=c("HN(1)", "HC(1)"))

Auricular acupuncture data

Description

Meta-analysis data set including 4 randomized, controlled trials comparing treatment completion among cocaine dependents treated with auricular acupuncture versus sham acupuncture.

Usage

data(aa)data(aa)

Format

A data frame with 4 observations on the following 7 variables:

study: character string, label of the study
f.t: integer, number of persons who did not complete treatment among those treated with auricular acupuncture
n.t: integer, number of persons treated with auricular acupuncture
f.c: integer, number of persons who did not complete treatment among those treated with sham acupuncture
n.c: integer, number of persons treated with sham acupuncture (control group)
y: numeric, log odds ratio estimates for the individual trials
sigma: numeric, standard error of the log odds ratio estimate for the individual trials

Details

This data set was originally analyzed by Gates et al. (2006) and reanalyzed by Bodnar et al. (2017).

The log odds ratio estimates and standard errors were computed using the escalc function in the package metafor.

Source

Bodnar, O., Link, A., Arendacka, B., Possolo, A., Elster, C. (2017). Bayesian estimation in random effects meta-analysis using a non-informative prior. Statistics in Medicine 36, 378–399.

References

Gates S, Smith LA, Foxcroft D. Auricular acupuncture for cocaine dependence. Cochrane Database of Systematic Reviews 2006, Issue 1. Art. No.: CD005192. doi:10.1002/14651858.CD005192.pub2

Examples

data(aa)
str(aa)
# forest plot
forest(x=aa$y, sei=aa$sigma, xlab="log odds ratio")
data(aa)
str(aa)
# forest plot
forest(x=aa$y, sei=aa$sigma, xlab="log odds ratio")

Acute otitis media data

Description

Meta-analysis data set including 5 studies on treatment failure of short course (less than 7 days) versus long course (> 7 days) antibiotics for acute otitis media in children. The outcome considered is treatment failure at 8-19 days.

Usage

data(aom)data(aom)

Format

A data frame with 5 observations on the following 7 variables:

study: character string, label of the study
f.t: integer, number of patients for whom the short course antibiotics treatment failed
n.t: integer, number of patients receiving short course antibiotics
f.c: integer, number of patients for whom the long course antibiotics treatment failed
n.c: integer, number of patients receiving long course antibiotics
y: numeric, log odds ratio estimates for the individual studies
sigma: numeric, standard error of the log odds ratio estimate for the individual studies

Details

This data set has been analyzed in Kozyrskyj et al. (2000) and reanalyzed by Lambert et al. (2005). Senn (2007, Section 2) discusses problems in this data set. In particular, one arm of one study has been included twice in the data set.

The counts f.t, n.t, f.c and n.c and the names of the studies are taken from Senn (2007), who reproduces the data set given in Kozyrskyj et al. (2000, Analysis 2.2). The log odds ratio estimates and standard errors were computed using the escalc function in the package metafor and are identical to the estimates used in Lambert et al. (2005).

Source

Senn, S. (2007). Trying to be precise about vagueness. Statistics in Medicine, 26, 1417–1430. doi:10.1002/sim.2639

References

Kozyrskyj, A., Klassen, T. P., Moffatt, M., Harvey K. (2000). Short-course antibiotics for acute otitis media. Cochrane Database of Systematic Reviews, Issue 2, Art. No.: CD001095. doi:10.1002/14651858.CD001095

Lambert, P., Sutton, A., Burton, P., Abrams, K., Jones, D. (2005). How vague is vague? A simulation study of the impact of the use of vague prior distributions in MCMC using WinBUGS. Statistics in Medicine 24(15), 2401–2428. doi:10.1002/sim.2112

Examples

data(aom)
str(aom)
# forest plot
forest(x=aom$y, sei=aom$sigma, xlab="log odds ratio")
data(aom)
str(aom)
# forest plot
forest(x=aom$y, sei=aom$sigma, xlab="log odds ratio")

Calibration of the Hellinger distance

Description

By default (if output="shift"), this function returns the mean of a unit-variance normal distribution, such that the Hellinger distance between this distribution and the standard normal distribution equals the given value. Offers the option to return the area of overlap (if output="ao") between these two unit-variance normal distributions instead. Gives an intuitive interpretation of Hellinger distance values.

Usage

cal_h_dist(h, output="shift")
cal_h_dist(h, output="shift")

Arguments

`h`	vector of Hellinger distances, consisting of real numbers in [0,1]
`output`	either `"shift"` or `"ao"`. Specifies if the output should be given as the shift between two unit-varaince normal distributions or as the area of overlap (AO) between these unit-varaince normal distributions

Details

For a given Hellinger distance h, there is a mean $\mu(h)$ , such that

$H(N(\mu(h), 1), N(0, 1))=h,$

where H denotes the Hellinger distance. See Roos et al. (2015), Sect. 2.2 for details.

If output="shift", the function returns the shift $\mu(h)$ between the two unit-variance normal distributions. If output="ao", the function returns the area of overlap between the $N(\mu(h), 1)$ and $N(0, 1)$ distributions. This area of overlap is given by

$AO(\mu(h)) = \Phi(\mu(h)/2 ;\mu(h), 1) + 1 - \Phi(\mu(h)/2 ;0, 1),$

where $\Phi(. ;\mu, \sigma^2)$ denotes the cumulative distribution function of the normal distribution with mean $\mu$ and variance $\sigma^2$ . See Ott et al. (2021, Section 3.5) for more information on this area of overlap calibration.

Value

A vector of means (if output="shift") or areas of overlap (if output="ao"), respectively.

References

Roos, M., Martins, T., Held, L., Rue, H. (2015). Sensitivity analysis for Bayesian hierarchical models. Bayesian Analysis 10(2), 321–349. https://projecteuclid.org/euclid.ba/1422884977

Examples

# calibration in terms of shifts
cal_h_dist(h=c(0.1, 0.5, 0.9))
# calibration in terms of areas of overlap
cal_h_dist(h=c(0.1, 0.5, 0.9), output="ao")
# calibration in terms of shifts
cal_h_dist(h=c(0.1, 0.5, 0.9))
# calibration in terms of areas of overlap
cal_h_dist(h=c(0.1, 0.5, 0.9), output="ao")

Density function of the square-root generalized conventional (SGC) benchmark prior

Description

Density function of the SGC distribution described in the Supplementary Material of Ott et al. (2021).

Usage

dsgc(x, m, C)
dsgc(x, m, C)

Arguments

`x`	vector of quantiles.
`m`	real number in $(1,\infty)$ .
`C`	non-negative real number.

Details

The density function with domain $[0, \infty)$ is given by

$\pi(x) = 2(m-1)Cx(1+Cx^2)^{-m}$

for $x >= 0$ . This is the transformation of the density function for variance components given in equation (2.15) in Berger & Deely (1988) to the standard deviation scale. See the Supplementary Material of Ott et al. (2021), Section 2.2, for more information.

For meta-analsis data sets, Ott et al. (2021) choose $C=\sigma_{ref}^{-2}$ , where $\sigma_{ref}$ is the reference standard deviation (see function sigma_ref) of the data set, which is defined as the geometric mean of the standard deviations of the individual studies.

Value

Value of the density function at locations x, where $x >= 0$ . Vector of non-negative real numbers.

References

Examples

dsgc(x=c(0.1,0.5,1), m=1.2, C=10)
dsgc(x=c(0.1,0.5,1), m=1.2, C=10)

Density function of the square-root inverse generalized conventional (SIGC) benchmark prior

Description

Density function of the SIGC distribution described in the Supplementary Material of Ott et al. (2021).

Usage

dsigc(x, M, C)
dsigc(x, M, C)

Arguments

`x`	vector of quantiles.
`M`	real number in $(1,\infty)$ .
`C`	non-negative real number.

Details

The density function with domain $[0, \infty)$ is given by

$\pi(x) = 4(M-1)Cx^{-5}(1+Cx^{-4})^{-M}$

for $x >= 0$ . This density is obtained if the density function for variance components given in equation (2.15) in Berger & Deely (1988) is assigned to the precision (i.e. the inverse of the variance) and then transformed to the standard deviation scale. See the Supplementary Material of Ott et al. (2021), Section 2.2, for more information.

Value

Value of the density function at locations x, where $x >= 0$ . Vector of non-negative real numbers.

References

Examples

dsigc(x=c(0.1,0.5,1), M=1.2, C=10)
dsigc(x=c(0.1,0.5,1), M=1.2, C=10)

Model fitting for reference analysis using 2 benchmarks: Posterior inference for benchmark and actual heterogeneity priors

Description

Computes the posterior distribution of the parameters in a random-effects meta-analysis (expressed as a normal-normal hierarchical model) for two benchmark heterogeneity priors and the actual heterogeneity prior(s) specified. Applies the function bayesmeta from the package bayesmeta.

Usage

fit_models_RA(df, tau.prior = list(), scale.hn0 = 1/500,
              mu.mean = 0, mu.sd = 4, interval.type = "central")
fit_models_RA(df, tau.prior = list(), scale.hn0 = 1/500,
              mu.mean = 0, mu.sd = 4, interval.type = "central")

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 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.
`scale.hn0`	scale parameter of the half-normal benchmark prior (usually small, so that the benchmark is anti-conservative).
`mu.mean`	mean of the normal prior for the effect mu.
`mu.sd`	standard deviation of the normal prior for the effect mu.
`interval.type`	the type of (credible, prediction, shrinkage) interval to be returned by default. Either "central" for equal-tailed intervals or "shortest" for shortest intervals. Defaults to "central". See also the corresponding argument in the `bayesmeta` function.

Details

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

Decreasing the scale parameter scale.hn0 of the half-normal benchmarks leads to a more anti-conservative (i.e. its mass is more concentrated near 0) HN0 benchmark prior. However, scale.hn0 cannot be chosen arbitrarily small since too small values lead to numerical problems in the bayesmeta function used to fit the models. To verify how anti-conservative the HN0 benchmark is, one can compare the marginal posterior for the overall mean parameter mu with the corresponding posterior for the fixed effects model, e.g. by using the function plot_RA. The better the match between these two marginal posteriors, the more anti-conservative the HN0 benchmark is.

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

Value

A list containing the model fits, namely a list of lists of class bayesmeta. This list has length $2$ + length(tau.prior) and contains one element for each heterogeneity prior considered (2 benchmark priors and the actual priors specified), in the following order:

`fit.hn0`	for the half-normal HN0 benchmark prior with scale parameter `scale.hn0`
`fit.j`	for Jeffreys (improper) reference prior
`fit.actual_1`	for the first prior in the list `tau.prior` (if specified)
`fit.actual_2`	for the second prior in the list `tau.prior` (if specified)
`...`	...
`fit.actual_n`	for the nth prior in the list `tau.prior` (if specified)

See bayesmeta in the package bayesmeta for information on the structure of the lists of class bayesmeta.

Warning

If fit_models_RA ends with an error or warning, we recommend to increase the value of the parameter scale.hn0 for the anti-conservative benchmark prior.

References

Examples

# for aurigular acupuncture (AA) data set
data(aa)  
# one actual half-normal and the "DuMouchel" heterogeneity prior
# it takes a few seconds to run this function
fit_models_RA(df=aa, tau.prior=list(function(t)dhalfnormal(t, scale=0.5),
                                    "DuMouchel"))
                                    
# for aurigular acupuncture (AA) data set
data(aa)  
# one actual half-normal and the "DuMouchel" heterogeneity prior
# it takes a few seconds to run this function
fit_models_RA(df=aa, tau.prior=list(function(t)dhalfnormal(t, scale=0.5),
                                    "DuMouchel"))

Model fitting for reference analysis using 5 benchmarks: Posterior inference for benchmark and actual heterogeneity priors

Description

Computes the posterior distribution of the parameters in a random-effects meta-analysis (expressed as a normal-normal hierarchical model) for each of five benchmark heterogeneity priors and the actual heterogeneity prior(s) specified. Applies the function bayesmeta from the package bayesmeta.

Usage

fit_models_RA_5bm(df, tau.prior=list(), compute.J.bm=TRUE,
                  m_J=NA, M_J=NA, upper.J=3, digits.J=2,
                  m_inf=NA, M_inf=NA, rlmc0=0.0001, rlmc1=0.9999,
                  mu.mean=0, mu.sd=4)
fit_models_RA_5bm(df, tau.prior=list(), compute.J.bm=TRUE,
                  m_J=NA, M_J=NA, upper.J=3, digits.J=2,
                  m_inf=NA, M_inf=NA, rlmc0=0.0001, rlmc1=0.9999,
                  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 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.
`compute.J.bm`	logical. Specifies if the parameter values of the two benchmarks priors SGC( $m_J$ ) and SIGC( $M_J$ ) and the corresponding marginal posteriors should be computed. Defaults to `TRUE`.
`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 the arguments `df`, `upper.J`, `digits.J`, `mu.mean` and `mu.sd`.
`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 the arguments `df`, `upper.J`, `digits.J`, `mu.mean` and `mu.sd`.
`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`.
`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 "Jeffreys" refers to Jeffreys reference prior, which is improper, but leads to a proper posterior if there are at least two studies in the meta-analysis data set.

If the fits induced by the SIGC( $M_J$ ) and SGC( $m_J$ ) benchmarks are not needed for the analysis (such as for the posterior reference analysis proposed in the Supplementary Material of Ott et al. (2021), see for example Table 8 for illustration), specifying compute.J.bm=FALSE may reduce the computation time by several minutes.

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

Value

A list with two elements: The first element named "fits" is a list containing the model fits and the second element called "par" is a named vector giving the parameter values of the benchmark priors. The vector "par" has the following five components: m_inf, M_J, m_J, M_inf and C.

The element "fits" is a list of lists of class bayesmeta. This list has length $5$ + length(tau.prior) and contains one element for each heterogeneity prior considered (5 benchmark priors and the actual priors specified), in the following order:

`fit.SGC.m_inf`	for SGC(`m_inf`) benchmark prior
`fit.SIGC.M_J`	for SIGC(`M_J`) benchmark prior
`fit.SGC.m_J`	for SGC(`m_J`) benchmark prior
`fit.SIGC.M_inf`	for SIGC(`M_inf`) benchmark prior
`fit.j`	for Jeffreys (improper) reference prior
`fit.actual_1`	for the first prior in the list `tau.prior` (if specified)
`fit.actual_2`	for the second prior in the list `tau.prior` (if specified)
`...`	...
`fit.actual_n`	for the nth prior in the list `tau.prior` (if specified)

See bayesmeta in the package bayesmeta for information on the structure of the lists of class bayesmeta.

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.

If fit_models_RA ends with an error or warning, we recommend to check the values of the parameters M_J, m_J and M_inf for the benchmark priors. The choice of these parameters can be studied by using the functions M_j_sigc, m_j_sgc and M_inf_sigc. If one of the parameters m_inf, M_J, m_J or M_inf has a value larger than 5*10^6, a warning message will be displayed, since such large parameter values may lead to numerical problems in the bayesmeta function.

References

Examples

# for aurigular acupuncture (AA) data set with one
# actual half-normal and the "DuMouchel" heterogeneity prior
data(aa)
# warning: it takes ca. 7 min. to run this function
fit_models_RA_5bm(df=aa, tau.prior=list(function(t)dhalfnormal(t, scale=1),
                                        "DuMouchel"))

# computation is much faster if m_J and M_J are specified
fit_models_RA_5bm(df=aa, tau.prior=list(function(t)dhalfnormal(t, scale=1),
                                        "DuMouchel"),
                  m_J = 1.35, M_J = 1.3)

# for aurigular acupuncture (AA) data set with one
# actual half-normal and the "DuMouchel" heterogeneity prior
data(aa)
# warning: it takes ca. 7 min. to run this function
fit_models_RA_5bm(df=aa, tau.prior=list(function(t)dhalfnormal(t, scale=1),
                                        "DuMouchel"))

# computation is much faster if m_J and M_J are specified
fit_models_RA_5bm(df=aa, tau.prior=list(function(t)dhalfnormal(t, scale=1),
                                        "DuMouchel"),
                  m_J = 1.35, M_J = 1.3)

Hellinger distance between two probability densities

Description

Computes the Hellinger distance between the two probability density functions specified using numerical integration.

Usage

H(dens1, dens2, lower=-Inf)
H(dens1, dens2, lower=-Inf)

Arguments

`dens1`	function returning the first probability density.
`dens2`	function returning the second probability density.
`lower`	lower end of the common domain of two density functions. Usually equal to $-\infty$ or 0.

Details

The Hellinger distance is defined in Le Cam (1986) and also given in Roos et al. (2015, Sect. 2.1).

Value

A real number in [0,1].

References

Le Cam, L. (1986). Asymptotic Methods in Statistical Decision Theory. Springer.

Roos, M., Martins, T., Held, L., Rue, H. (2015). Sensitivity analysis for Bayesian hierarchical models. Bayesian Analysis 10(2), 321–349. https://projecteuclid.org/euclid.ba/1422884977

Examples

H(dens1=function(x) dhalfnormal(x, scale=0.5),
  dens2=function(x) dhalfnormal(x, scale=1), lower=0)
H(dens1=function(x) dhalfnormal(x, scale=0.5),
  dens2=function(x) dhalfcauchy(x, scale=1), lower=0)
H(dens1=function(x) dhalfnormal(x, scale=0.5),
  dens2=function(x) dhalfnormal(x, scale=1), lower=0)
H(dens1=function(x) dhalfnormal(x, scale=0.5),
  dens2=function(x) dhalfcauchy(x, scale=1), lower=0)

Hellinger distance between marignal posterior densities of two bayesmeta fits

Description

Computes the Hellinger distance between the marginal posterior densities extracted from two bayesmeta fits, for the selected parameter of interest. Offers the option to select between integral-based and approximate moment-based computation of Hellinger distances.

Usage

H_fits(fit1, fit2, parameter = "mu", individual = NA,
       method = "integral")
H_fits(fit1, fit2, parameter = "mu", individual = NA,
       method = "integral")

Arguments

`fit1`	first model fit of class bayesmeta, computed with the `bayesmeta` function in the package bayesmeta.
`fit2`	second model fit of class bayesmeta, computed with the `bayesmeta` function in the package bayesmeta.
`parameter`	parameter for which the the marginal posterior densities should be compared. Possible values are `"mu", "tau", "theta_new"` and `"theta"` (`"theta"` refers to the random effects and is used in combination with the individual argment).
`individual`	integer $<= k$ , where $k$ is the number of studies in the meta-analysis data set. Specifies which random effect parameter to consider (according to the order of the studies in the data set). Is used only if `parameter = "theta"`.
`method`	method for Hellinger distance computation. Either `"integral"` for integral-based computation or `"moment"` for approximate moment-based calculation using a normal approximation. Defaults to `"integral"`.

Details

In the random effects model for meta-analysis, the parameter mu is the overall mean parameter, tau is the between-study (heterogeneity) standard deviation, theta_new is the predicted effect for a new study and theta_i is the random effect parameter for study i.

If integral-based computation (method = "integral") of Hellinger distances is selected (the default), numerical integration is applied to obtain the Hellinger distance between the two marginal posterior densities (by using the function H). If moment-based computation (method = "moment") is selected, the marginal densities are first approximated by normal densities with the same means and standard deviations and then the Hellinger distance between these normal densities can be obtained by an analytical formula (implemented in the function H_normal).

Value

A real number in [0,1].

Warning

If the integral-based method is used to compute Hellinger distances (method = "integral"), numerical problems may occur in some cases, which may lead to implausible outputs. Therefore, we generally recommend to double-check the results of the integral-based method using the moment-based method (method = "moment") - especially if the former results are implausibe. If large differences between the two methods are observed, we recommend to rely on the moment-based method unless a normal approximation of the involved densities is inappropriate.

Examples

data(aa)  
 # fit under Jeffreys reference heterogeneity prior
fit1 <- bayesmeta(y = aa[ , "y"], sigma = aa[, "sigma"],
                  mu.prior.mean = 0, mu.prior.sd = 4,
                  tau.prior = "Jeffreys")
# fit under standard half-normal heterogeneity prior
fit2 <- bayesmeta(y = aa[ , "y"], sigma = aa[, "sigma"],
                  mu.prior.mean = 0, mu.prior.sd = 4,
                  tau.prior = function(t) dhalfnormal(t, scale = 1))
# Hellinger distance between the marginal posteriors for mu
H_fits(fit1, fit2)
# moment-based calculation
H_fits(fit1, fit2, method = "moment")
# Hellinger distance between the marginal posteriors for theta_2
# (random effect parameter)
H_fits(fit1, fit2, parameter = "theta", individual = 2)

data(aa)  
 # fit under Jeffreys reference heterogeneity prior
fit1 <- bayesmeta(y = aa[ , "y"], sigma = aa[, "sigma"],
                  mu.prior.mean = 0, mu.prior.sd = 4,
                  tau.prior = "Jeffreys")
# fit under standard half-normal heterogeneity prior
fit2 <- bayesmeta(y = aa[ , "y"], sigma = aa[, "sigma"],
                  mu.prior.mean = 0, mu.prior.sd = 4,
                  tau.prior = function(t) dhalfnormal(t, scale = 1))
# Hellinger distance between the marginal posteriors for mu
H_fits(fit1, fit2)
# moment-based calculation
H_fits(fit1, fit2, method = "moment")
# Hellinger distance between the marginal posteriors for theta_2
# (random effect parameter)
H_fits(fit1, fit2, parameter = "theta", individual = 2)

Approximate moment-based Hellinger distance computation between two probability densities

Description

Computes the Hellinger distance between the two probability densities with the given means and standard deviations using a normal approximation and moment-matching. Applies a moment-based analytical formula, which is exact for normal densities.

Usage

H_normal(mean1, sd1, mean2, sd2)
H_normal(mean1, sd1, mean2, sd2)

Arguments

`mean1`	mean of the first density.
`sd1`	standard deviation of the first density.
`mean2`	mean of the second density.
`sd2`	standard deviation of the second density.

Details

The Hellinger distance between two normal densities can be computed analytically and it only depends on the means and the standard deviations of these two densities. Any density can be approximated to the first order by a normal distribution. Thus, this moment-based formula can also be applied to non-normal densities to obtain an approximate estimate of the Hellinger distance. This approximation relies on moment-matching, i.e. the non-normal densities are approximated by normal densities with the same means and standard deviations. See Roos et al. (2021), Section 3.3, for the formula and for additional information.

Note that the Hellinger distance is invariant with respect to one-to-one transformations of both densities. For the between-study standard deviation $\tau$ , the density of $log(\tau)$ can be approximated by a normal density.

Value

A real number in [0,1].

References

Roos, M., Hunanyan, S., Bakka, H., & Rue, H. (2021). Sensitivity and identification quantification by a relative latent model complexity perturbation in Bayesian meta-analysis. Biometrical Journal 63, 1555–1574. doi:10.1002/bimj.202000193

Examples

H_normal(mean1 = 0, sd1 = 1, mean2 = 1, sd2 = 2)
H_normal(mean1 = 0, sd1 = 1, mean2 = 1, sd2 = 2)

Optimization function for the SGC(m) prior: Adjust the prior to a target relative latent model complexity (RLMC)

Description

Computes the parameter value $m=m_{inf}$ of the SGC( $m$ ) prior, such that the relative latent model complexity (RLMC) with respect to the reference threshold is approximately rlmc. The reference threshold is chosen as the (1-alpha)-quantile of the SGC( $m_{inf}$ ) prior.

Usage

m_inf_sgc(rlmc, alpha=0.5)
m_inf_sgc(rlmc, alpha=0.5)

Arguments

`rlmc`	target RLMC value. Real number in $(0,1)$ .
`alpha`	determines the (1-`alpha`)-quantile of the SGC( $m$ ) prior, which is used as reference threshold. Defaults to 0.5 (i.e. the median).

Details

See the Supplementary Material of Ott et al. (2021), Section 2.3.1, for the formulas and explanations. Note that the parameter value $m_{inf}$ does not depend on the data set considered.

Value

Parameter value $m=m_{inf}$ of the SGC( $m$ ) prior. Real number > 1.

References

Examples

# extreme RLMC target value close to 0 used in Ott et al. (2021)
m_inf_sgc(rlmc=0.0001)

# 25% quantile instead of the median as ref. threshold
m_inf_sgc(rlmc=0.0001, alpha=0.75)
# extreme RLMC target value close to 0 used in Ott et al. (2021)
m_inf_sgc(rlmc=0.0001)

# 25% quantile instead of the median as ref. threshold
m_inf_sgc(rlmc=0.0001, alpha=0.75)

Optimization function for the SIGC(M) prior: Adjust the prior to a target relative latent model complexity (RLMC)

Description

Computes the parameter value $M=M_{inf}$ of the SIGC( $M$ ) prior, such that the relative latent model complexity (RLMC) with respect to the reference threshold is approximately rlmc. The reference threshold is chosen as the (1-alpha)-quantile of the SIGC( $M_{inf}$ ) prior.

Usage

M_inf_sigc(rlmc, df, alpha=0.5, truncation=5*10^6)
M_inf_sigc(rlmc, df, alpha=0.5, truncation=5*10^6)

Arguments

`rlmc`	target RLMC value. Real number in $(0,1)$ .
`df`	data frame with one column "sigma" containing the standard errors of the estimates for the individual studies.
`alpha`	determines the (1-`alpha`)-quantile of the SIGC( $M$ ) prior, which is used as reference threshold. Defaults to 0.5 (i.e. the median).
`truncation`	upper bound for the parameter value $M$ . Defaults to the empirically determined value 5*10^6.

Details

See the Supplementary Material of Ott et al. (2021), Section 2.3.2, for the formulas and explanations. Note that the parameter value $M_{inf}$ does depend on the data set considered.

Value

Parameter value $M=M_{inf}$ of the SIGC( $M$ ) prior. Real number > 1.

Warning

Occasionally, the formula for $M_{inf}$ given in the Supplementary Material of Ott et al. (2021, Section 2.3.2) yields values larger than 5*10^6. This can cause numerical problems in the bayesmeta function. Therefore, we truncate the parameter value at the empirically determined threshold 5*10^6 by default.

References

Examples

# extreme RLMC target value close to 1 used in Ott et al. (2021)
# for the aurigular acupuncture (AA) data set
data(aa)
M_inf_sigc(df=aa, rlmc=0.9999)
# for the respiratory tract infections (RTI) data set
data(rti)
M_inf_sigc(df=rti, rlmc=0.9999)

# 75% quantile instead of the median as ref. threshold
M_inf_sigc(df=rti, rlmc=0.9999, alpha=0.25)
# extreme RLMC target value close to 1 used in Ott et al. (2021)
# for the aurigular acupuncture (AA) data set
data(aa)
M_inf_sigc(df=aa, rlmc=0.9999)
# for the respiratory tract infections (RTI) data set
data(rti)
M_inf_sigc(df=rti, rlmc=0.9999)

# 75% quantile instead of the median as ref. threshold
M_inf_sigc(df=rti, rlmc=0.9999, alpha=0.25)

Optimization function for the SGC(m) prior: Approximate Jeffreys reference posterior

Description

Numerically determines the parameter value $m=m_J$ of the SGC( $m$ ) prior, such that the Hellinger distance between the marginal posteriors for the heterogeneity standard deviation $\tau$ induced by the SGC( $m_J$ ) and Jeffreys (improper) reference prior is minimal.

Usage

m_j_sgc(df, upper=3, digits=2, mu.mean=0, mu.sd=4)
m_j_sgc(df, upper=3, digits=2, 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.
`upper`	upper bound for parameter $m$ . Real number in $(1,\infty)$ .
`digits`	specifies the desired precision of the parameter value $m=m_J$ , i.e. to how many digits this value should be determined. Possible values are 1,2,3. Defaults to 2.
`mu.mean`	mean of the normal prior for the effect mu.
`mu.sd`	standard deviation of the normal prior for the effect mu.

Details

See the Supplementary Material of Ott et al. (2021, Section 2.6) for details.

Value

Parameter value $m=m_J$ of the SGC( $m$ ) prior. Real number > 1.

Warning

This function takes several minutes to run if the desired precision is digits=2 and even longer for higher precision.

References

Examples

# for aurigular acupuncture (AA) data set
data(aa)
# warning: it takes ca. 2 min. to run this function
m_j_sgc(df=aa, digits=1)

# for aurigular acupuncture (AA) data set
data(aa)
# warning: it takes ca. 2 min. to run this function
m_j_sgc(df=aa, digits=1)

Optimization function for the SIGC(m) prior: Approximate Jeffreys reference posterior

Description

Numerically determines the parameter value $M=M_J$ of the SIGC( $M$ ) prior, such that the Hellinger distance between the marginal posteriors for the heterogeneity standard deviation $\tau$ induced by the SIGC( $M_J$ ) prior and Jeffreys (improper) reference prior is minimal.

Usage

M_j_sigc(df, upper=3, digits=2, mu.mean=0, mu.sd=4)
M_j_sigc(df, upper=3, digits=2, 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.
`upper`	upper bound for parameter $M$ . Real number in $(1,\infty)$ .
`digits`	specifies the desired precision of the parameter value $M=M_J$ , i.e. to how many digits this value should be determined. Possible values are 1,2,3. Defaults to 2.
`mu.mean`	mean of the normal prior for the effect mu.
`mu.sd`	standard deviation of the normal prior for the effect mu.

Details

See the Supplementary Material of Ott et al. (2021, Section 2.6) for details.

Value

Parameter value $M=M_J$ of the SIGC(M) prior. Real number > 1.

Warning

This function takes several minutes to run if the desired precision is digits=2 and even longer for higher precision.

For some data sets, the optimal parameter value $M=M_J$ is very large (e.g. of order 9*10^5). If this function returns $M_J$ =upper, then the optimal parameter value may be larger than upper.

References

Examples

# for aurigular acupuncture (AA) data set
data(aa)
# warning: it takes ca. 2 min. to run this function
M_j_sigc(df=aa, digits=1)

# for aurigular acupuncture (AA) data set
data(aa)
# warning: it takes ca. 2 min. to run this function
M_j_sigc(df=aa, digits=1)

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

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.

Value

No return value, produces graphical output only.

References

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

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

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

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

Reference analysis plot based on bayesmeta fits: Plot heterogeneity benchmark priors and the corresponding marginal posteriors

Description

Plots the benchmark heterogeneity priors inducing the specified model fits fits.bm and the corresponding marginal benchmark posteriors for different parameters in the NNHM. Also displays the actual heterogeneity priors inducing the specified actual model fits fits.actual and the corresponding marginal posteriors. All bayesmeta fits should be based on the same data set.

Usage

plot_RA_fits(fits.actual, fits.bm, type="pri.tau", xlim, ylim,
             legend=FALSE, pos.legend="topright",
             legend.tau.prior=c(), bty="o",
             col.actual=c("red","lightpink3","darkgreen","green",
                          "violetred")[1:length(fits.actual)],
             col.bm=c("cyan","black","blue","darkgray",
                      "dodgerblue")[1:length(fits.bm)],
             lty.actual=rep(2, times=length(col.actual)),
             lty.bm=rep(1, times=length(col.bm)),
             lwd.actual=rep(2, times=length(col.actual)),
             lwd.bm=rep(2, times=length(col.bm)))
plot_RA_fits(fits.actual, fits.bm, type="pri.tau", xlim, ylim,
             legend=FALSE, pos.legend="topright",
             legend.tau.prior=c(), bty="o",
             col.actual=c("red","lightpink3","darkgreen","green",
                          "violetred")[1:length(fits.actual)],
             col.bm=c("cyan","black","blue","darkgray",
                      "dodgerblue")[1:length(fits.bm)],
             lty.actual=rep(2, times=length(col.actual)),
             lty.bm=rep(1, times=length(col.bm)),
             lwd.actual=rep(2, times=length(col.actual)),
             lwd.bm=rep(2, times=length(col.bm)))

Arguments

`fits.actual`	a list of model fits (max. 5 fits) of class bayesmeta, computed with the `bayesmeta` function in the package bayesmeta.
`fits.bm`	a list of model fits (max. 5 fits) of class bayesmeta, computed with the `bayesmeta` function in the package bayesmeta. To be used as benchmarks.
`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.
`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 with one entry for each fit in `fits.actual` and `fits.bm` (i.e. a vector of length length(`fits.actual`)+length(`fits.bm`)). Determines the legend entries corresponding to the actual und benchmark fits specified, in the same order as in the list c(`fits.actual`, `fits.bm`).
`bty`	the type of box to be drawn around the legend. The allowed values are "o" (the default) and "n".
`col.actual`	vector of color specifications for the lines representing the actual fits in `fits.actual`, in the same order as in that list. Vector of minimum length `length(fits.actual)`.
`col.bm`	vector of color specifications for the lines representing the benchmark fits in `fits.bm`, in the same order as in that list. Vector of minimum length `length(fits.bm)`.
`lty.actual`	vector of line type specifications for the lines representing the actual fits in `fits.actual`, in the same order as in that list. Vector of minimum length `length(fits.actual)`.
`lty.bm`	vector of line type specifications for the lines representing the benchmark fits in `fits.bm`, in the same order as in that list. Vector of minimum length `length(fits.bm)`.
`lwd.actual`	numeric vector specifying the width of the lines representing the actual fits in `fits.actual`, in the same order as in that list. Vector of minimum length `length(fits.actual)`.
`lwd.bm`	numeric vector specifying the width of the lines representing the benchmark fits in `fits.bm`, in the same order as in that list. Vector of minimum length `length(fits.bm)`.

Details

Two alternative suggestions for posterior benchmarks are provided in Ott et al. (2021, Section 3.4) and its Supplementary Material (Section 2.5) and they can be computed using the functions fit_models_RA and fit_models_RA_5bm, respectively.

Value

No return value, produces graphical output only.

References

Examples

# for aurigular acupuncture (AA) data set with two
# actual half-normal and half-Cauchy heterogeneity priors
data(aa)
  
# compute the model fits
fits <- fit_models_RA(df=aa, tau.prior=list(function(t)dhalfnormal(t, scale=1),
                                            function(t)dhalfcauchy(t, scale=1)))
# plot the HN0 benchmark prior (do not show the improper J benchmark)
fits.bm.pri <- fits[1]
# benchmark fits under HN0 and J priors
fits.bm.post <- fits[1:2]
fits.actual <- fits[3:4]

# prior densities
plot_RA_fits(fits.actual=fits.actual, fits.bm=fits.bm.pri,
             type="pri.tau", xlim=c(0, 2), ylim=c(0, 3),
             legend=TRUE,
             legend.tau.prior=c("HN(1)", "HC(1)", "HN0"))

# marginal posterior for the effect mu
plot_RA_fits(fits.actual=fits.actual, fits.bm=fits.bm.post,
             type="post.mu", xlim=c(-1.5, 1.5), ylim=c(0, 3),
             legend=TRUE,
             legend.tau.prior=c("HN(1)", "HC(1)",
             "HN0", "J"))
             
# for aurigular acupuncture (AA) data set with two
# actual half-normal and half-Cauchy heterogeneity priors
data(aa)
  
# compute the model fits
fits <- fit_models_RA(df=aa, tau.prior=list(function(t)dhalfnormal(t, scale=1),
                                            function(t)dhalfcauchy(t, scale=1)))
# plot the HN0 benchmark prior (do not show the improper J benchmark)
fits.bm.pri <- fits[1]
# benchmark fits under HN0 and J priors
fits.bm.post <- fits[1:2]
fits.actual <- fits[3:4]

# prior densities
plot_RA_fits(fits.actual=fits.actual, fits.bm=fits.bm.pri,
             type="pri.tau", xlim=c(0, 2), ylim=c(0, 3),
             legend=TRUE,
             legend.tau.prior=c("HN(1)", "HC(1)", "HN0"))

# marginal posterior for the effect mu
plot_RA_fits(fits.actual=fits.actual, fits.bm=fits.bm.post,
             type="post.mu", xlim=c(-1.5, 1.5), ylim=c(0, 3),
             legend=TRUE,
             legend.tau.prior=c("HN(1)", "HC(1)",
             "HN0", "J"))

Normal posterior for the overall mean parameter in the fixed effects model

Description

This function computes the mean and the standard deviation of the normal posterior distribution for the overall mean parameter mu in the fixed effects model.

Usage

post_mu_fe(df, mu.mean = 0, mu.sd = 4)
post_mu_fe(df, 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.
`mu.mean`	mean of the normal prior for the overall mean parameter mu. Defaults to 0.
`mu.sd`	standard deviation of the normal prior for the overall mean parameter mu. Defaults to 4.

Details

For the fixed effects model, the normal posterior for the overall mean parameter mu can be computed analytically (under the common assumption of a normal prior on mu) since this is a conjugate Bayesian normal-normal model. See for example Ott et al. (2021), Equation (2) for the formula (mu.mean corresponds to $\nu$ and mu.sd corresponds to $\gamma$ ).

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

Value

A list with two elements: the first element "mean" and the second element "sd", which refer to the mean and the standard deviation of the normal posterior of mu.

References

Roever C. Bayesian random-effects meta-analysis using the bayesmeta R package (2020). Journal of Statistical Software 93(6), 1–51.

Examples

# load the aurigular acupuncture (AA) data set
data(aa)
# normal prior for log odds ratios suggested by Roever (2020)
post_mu_fe(df=aa, mu.mean=0, mu.sd=4)
# load the aurigular acupuncture (AA) data set
data(aa)
# normal prior for log odds ratios suggested by Roever (2020)
post_mu_fe(df=aa, mu.mean=0, mu.sd=4)

Posterior reference analysis based on a data frame using 2 benchmarks

Description

Computes a table of posterior estimates and informativeness values for the marginal posterior distributions of different parameters in the NNHM induced by the actual heterogeneity priors specified in tau.prior. Also provides the same estimates for the posterior benchmarks proposed in Ott et al. (2021).

Usage

post_RA(df, tau.prior = list(function(x) dhalfnormal(x, scale = 1)),
        show.re = FALSE,
        estimate = "median", ci.method = "central",
        H.dist.method = "integral",
        scale.hn0 = 1/500, mu.mean = 0, mu.sd = 4)
post_RA(df, tau.prior = list(function(x) dhalfnormal(x, scale = 1)),
        show.re = FALSE,
        estimate = "median", ci.method = "central",
        H.dist.method = "integral",
        scale.hn0 = 1/500, 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 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.
`show.re`	logical. If `TRUE`, the estimates for the random effect parameters $\theta_i$ are also shown. Defaults to `FALSE`.
`estimate`	type of posterior point estimate. Either `"median"` for the posterior median or `"mean"` for the posterior mean. Defaults to `"median"`.
`ci.method`	method for computation of 95% credible intervals (CrIs). Either `"central"` for equal-tailed CrIs or `"shortest"` for shortest CrIs. Defaults to `"central"`.
`H.dist.method`	method for computation of Hellinger distances between marginal posterior densities. Either `"integral"` for integral-based computation or `"moment"` for approximate moment-based calculation using a normal approximation. Defaults to `"integral"`.
`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. Defaults to 0.
`mu.sd`	standard deviation of the normal prior for the effect mu. Defaults to 4.

Details

The two posterior benchmarks used are introduced in Ott et al. (2021, Section 3.4), where they are denoted by $po_{J}(\Psi)$ and $po_{HN0}(\Psi)$ . Here, $\Psi \in \{ \mu, \tau, \theta_1, ..., \theta_k, \theta_{new} \}$ denotes the parameter of interest in the NNHM, where $\theta_{i}$ is the random effect in the $i$ th study and $\theta_{new}$ the predicted effect for a new study. For the overall mean parameter $\mu$ , we additionally consider the fixed-effects model benchmark $po_{FE}(\mu)$ .

Note that Jeffreys reference posterior $po_{J}$ is proper if there are at least two studies in the meta-analysis data set. It is based on the improper Jeffreys reference prior, which is minimally informative given the data. The computation of the informativeness values is described in Ott et al. (2021, Section 3.6).

The absolute value of the signed informativeness quantifies how close the actual posterior and the reference posterior $po_{J}$ are. If the signed informativeness is negative, then the actual prior is anti-conservative with respect to Jeffreys reference prior J (that is puts more weight on smaller values for $\tau$ than J). If the signed informativeness is positive, then the actual prior is conservative with respect to Jeffreys reference prior J (that is puts more weight on larger values for $\tau$ than J).

If integral-based computation (H.dist.method = "integral") of Hellinger distances is selected (the default), numerical integration is applied to obtain the Hellinger distance between the two marginal posterior densities (by using the function H). If moment-based computation (H.dist.method = "moment") is selected, the marginal densities are first approximated by normal densities with the same means and standard deviations and then the Hellinger distance between these normal densities can be obtained by an analytical formula (implemented in the function H_normal).

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

Value

A matrix with 6 columns and a number of columns depending on the number of actual heterogeneity priors specified and the parameters of interests in the NNHM (if show.re = FALSE, then there are 3 parameters of interest ( $\mu, \tau, \theta_{new}$ ) and the matrix has $3*(n+2)+1$ rows, where where $n$ =length(tau.prior) is the number of actual heterogeneity priors specified; if show.re = TRUE, then the matrix has $(k+3)*(n+2)+1$ rows, where $k$ is the number of studies in the meta-analysis data set (so that there are $k+3$ parameters of interest).)

The row names specify the parameter in the NNHM for which the marginal posterior is considered, followed by the heterogeneity prior used to compute that posterior. HN0, J and FE denote the three benchmark priors introduced in Ott et al. (2021). pri_act_i denotes the i-th prior in the tau.prior list.

The 6 columns provide the following estimates:

estimate:: posterior point estimate (median or mean)
CrI_low:: lower limit of the 95% credible interval
CrI_up:: upper limit of the 95% credible interval
length_CrI:: length of the 95% credible interval
H(po_HN0, po_act):: Hellinger distance between the posterior benchmark $po_{HN0}(\Psi)$ and the marginal posterior induced by the heterogeneity prior listed on the left, for the parameter $\Psi$ listed on the left
signed_inf:: Signed informativeness, i.e. $sign(H(po_{HN0}, po_{act}) - H(po_{HN0}, po_{J})) H(po_{act}, po_{J})$ , for the marginal posterior induced by the heterogeneity prior listed on the left, for the parameter $\Psi$ listed on the left

Warning

If the integral-based method is used to compute Hellinger distances (H.dist.method = "integral"), numerical problems may occur in some cases, which may lead to implausible outputs. Therefore, we generally recommend to double-check the results of the integral-based method using the moment-based method (H.dist.method = "moment") - especially if the former results are implausibe. If large differences between the two methods are observed, we recommend to rely on the moment-based method unless a normal approximation of the involved densities is inappropriate.

References

Examples

# for aurigular acupuncture (AA) data set with two
# actual half-normal heterogeneity priors
data(aa)
# it takes a few seconds to run this function
post_RA(df=aa, tau.prior=list(function(t)dhalfnormal(t, scale=0.5),
                              function(t)dhalfnormal(t, scale=1)))
                              
# for aurigular acupuncture (AA) data set with two
# actual half-normal heterogeneity priors
data(aa)
# it takes a few seconds to run this function
post_RA(df=aa, tau.prior=list(function(t)dhalfnormal(t, scale=0.5),
                              function(t)dhalfnormal(t, scale=1)))

Posterior reference analysis based on a data frame using 3 benchmarks

Description

Computes a table of Hellinger distances between marginal posterior distributions for different parameters in the NNHM induced by the actual heterogeneity priors specified in tau.prior and posterior benchmarks proposed in the Supplementary Material of Ott et al. (2021).

Usage

post_RA_3bm(df, tau.prior=list(function(x) dhalfnormal(x, scale=1)),
            H.dist.method = "integral",
            m_inf=NA, M_inf=NA, rlmc0=0.0001, rlmc1=0.9999,
            mu.mean=0, mu.sd=4)
post_RA_3bm(df, tau.prior=list(function(x) dhalfnormal(x, scale=1)),
            H.dist.method = "integral",
            m_inf=NA, M_inf=NA, rlmc0=0.0001, rlmc1=0.9999,
            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 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.
`H.dist.method`	method for computation of Hellinger distances between marginal posterior densities. Either `"integral"` for integral-based computation or `"moment"` for approximate moment-based calculation using a normal approximation. Defaults to `"integral"`.
`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`.
`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 three posterior benchmarks used are introduced in the Supplementary Material of Ott et al. (2021, Sections 2.2.1 and 2.5, see also Section 3.4 in Ott at al. (2021) for Jeffreys reference prior), where they are denoted by $po_{m_{inf}}(\Psi)$ , $po_{J}(\Psi)$ and $po_{M_{inf}}(\Psi)$ . Here, $\Psi \in \{ \mu, \tau, \theta_1, ..., \theta_k, \theta_{new} \}$ denotes the parameter of interest in the NNHM, where $\theta_{i}$ is the random effect in the $i$ th study and $\theta_{new}$ the predicted effect for a new study.

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

Value

A list with two elements: The first element named "table" is a matrix containing the Hellinger distance estimates and the second element called "par" is a named vector giving the parameter values of the benchmark priors. The vector "par" has the following three components: m_inf, M_inf and C.

The matrix "table" contains the Hellinger distance estimates between marginal posteriors and has $3$ columns and $n*(k+3)$ rows, where $n$ =length(tau.prior) is the number of actual heterogeneity priors specified and $k$ is the number of studies in the meta-analysis data set (so that there are $k+3$ parameters of interest).

The columns of the matrix give the following Hellinger distance estimates between two marginal posteriors (for the parameter of interest $\Psi$ varying with rows) induced by the following two heterogeneity priors (from left to right):

H(po_{m_inf}, po_act):: benchmark prior SGC(m_inf) and actual prior
H(po_J, po_act):: Jeffreys reference prior $\pi_J$ and actual prior
H(po_{M_inf}, po_act):: benchmark prior SIGC(M_inf) and actual prior

The actual heterogenity prior and the parameter of interest $\Psi$ vary with the rows in the following order:

mu, pri_act_1:: $\Psi=\mu$ and first actual prior in tau.prior
mu, pri_act_2:: $\Psi=\mu$ and second actual prior in tau.prior
...
mu, pri_act_n:: $\Psi=\mu$ and nth actual prior in tau.prior
tau, pri_act_1:: $\Psi=\tau$ and first actual prior in tau.prior
...
tau, pri_act_n:: $\Psi=\tau$ and nth actual prior
theta_1, pri_act_1:: $\Psi=\theta_1$ and first actual prior
...
theta_k, pri_act_n:: $\Psi=\theta_k$ and nth actual prior
theta_new, pri_act_1:: $\Psi=\theta_{new}$ and first actual prior
...
theta_new, pri_act_n:: $\Psi=\theta_{new}$ and nth actual prior

Warnings

A warning message will be displayed if one of the parameters m_inf 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

Examples

# for aurigular acupuncture (AA) data set with two
# actual half-normal heterogeneity priors
data(aa)
# it takes several seconds to run this function
post_RA_3bm(df=aa, tau.prior=list(function(t)dhalfnormal(t, scale=0.5),
                                  function(t)dhalfnormal(t, scale=1)))

# for aurigular acupuncture (AA) data set with two
# actual half-normal heterogeneity priors
data(aa)
# it takes several seconds to run this function
post_RA_3bm(df=aa, tau.prior=list(function(t)dhalfnormal(t, scale=0.5),
                                  function(t)dhalfnormal(t, scale=1)))

Posterior reference analysis based on bayesmeta fits

Description

Computes a table of Hellinger distances between marginal posterior distributions for different parameters in the NNHM between the actual model fits in fits.actual and the benchmark fits in fits.bm. All fits should be based on the same data set.

Usage

post_RA_fits(fits.actual, fits.bm,
             H.dist.method = "integral")
post_RA_fits(fits.actual, fits.bm,
             H.dist.method = "integral")

Arguments

`fits.actual`	a list of model fits of class bayesmeta, computed with the `bayesmeta` function in the package bayesmeta.
`fits.bm`	a list of model fits of class bayesmeta, computed with the `bayesmeta` function in the package bayesmeta. To be used as benchmarks.
`H.dist.method`	method for computation of Hellinger distances between marginal posterior densities. Either `"integral"` for integral-based computation or `"moment"` for approximate moment-based calculation using a normal approximation. Defaults to `"integral"`.

Details

Value

A matrix of Hellinger distance estimates between marginal posteriors with $n.bm$ columns and $n.act*(k+3)$ rows, where $n.bm$ =length(fits.bm) is the number of benchmark fits specified, $n.act$ =length(fits.actual) the number of actual fits specified and $k$ the number of studies in the meta-analysis data set (so that there are $k+3$ parameters $\Psi \in \{ \mu, \tau, \theta_1, ..., \theta_k, \theta_{new} \}$ of potential interest in the NNHM).

H(po_{bm_1}, po_act):: first benchmark prior bm_1 inducing the fit fits.bm[[1]] and actual prior
H(po_{bm_2}, po_act):: second benchmark prior bm_2 inducing the fit fits.bm[[2]] and actual prior
...: ...
H(po_{bm_{n.bm}}, po_act):: last benchmark prior bm_n.bm inducing the fit fits.bm[[n.bm]] and actual prior

The actual heterogenity prior and the parameter of interest $\Psi$ vary with the rows in the following order:

mu, pri_act_1:: $\Psi=\mu$ and first actual prior in tau.prior
mu, pri_act_2:: $\Psi=\mu$ and second actual prior in tau.prior
...: ...
mu, pri_act_n:: $\Psi=\mu$ and nth actual prior in tau.prior
tau, pri_act_1:: $\Psi=\tau$ and first actual prior in tau.prior
...: ...
tau, pri_act_n:: $\Psi=\tau$ and nth actual prior
theta_1, pri_act_1:: $\Psi=\theta_1$ and first actual prior
...: ...
theta_k, pri_act_n:: $\Psi=\theta_k$ and nth actual prior
theta_new, pri_act_1:: $\Psi=\theta_{new}$ and first actual prior
...: ...
theta_new, pri_act_n:: $\Psi=\theta_{new}$ and nth actual prior

Warning

References

Examples

# for aurigular acupuncture (AA) data set
data(aa)
 # compute the model fits  % this example takes > 5 sec. to run
# actual standard half-normal and half-Cauchy heterogeneity priors
fits <- fit_models_RA(df=aa, tau.prior=
                             list(function(t)dhalfnormal(t, scale=1),
                                  function(t)dhalfcauchy(t, scale=1)))
# benchmark fits under HN0 and J (Jeffreys) priors
fits.bm.post <- fits[c(1,2)]
fits.actual <- fits[c(3,4)]
post_RA_fits(fits.actual=fits.actual, fits.bm=fits.bm.post)

# for aurigular acupuncture (AA) data set
data(aa)
 # compute the model fits  % this example takes > 5 sec. to run
# actual standard half-normal and half-Cauchy heterogeneity priors
fits <- fit_models_RA(df=aa, tau.prior=
                             list(function(t)dhalfnormal(t, scale=1),
                                  function(t)dhalfcauchy(t, scale=1)))
# benchmark fits under HN0 and J (Jeffreys) priors
fits.bm.post <- fits[c(1,2)]
fits.actual <- fits[c(3,4)]
post_RA_fits(fits.actual=fits.actual, fits.bm=fits.bm.post)

Prior reference analysis based on a data frame using 5 benchmarks

Description

Computes a table of Hellinger distance estimates between the actual heterogeneity prior(s) specified and four benchmark heterogeneity priors proposed in the Supplementary Material of Ott et al. (2021).

Usage

pri_RA_5bm(df, tau.prior=list(function(x) dhalfnormal(x, scale=1)),
           m_J=NA, M_J=NA, upper.J=3, digits.J=2,
           m_inf=NA, M_inf=NA, rlmc0=0.0001, rlmc1=0.9999,
           mu.mean=0, mu.sd=4)
pri_RA_5bm(df, tau.prior=list(function(x) dhalfnormal(x, scale=1)),
           m_J=NA, M_J=NA, upper.J=3, digits.J=2,
           m_inf=NA, M_inf=NA, rlmc0=0.0001, rlmc1=0.9999,
           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 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.
`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`.
`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 methodology for a prior reference analysis and the four proper heterogeneity benchmark priors used are introduced in the Supplementary Material of Ott et al. (2021, Sections 2.5 and 2.6). There, these four benchmark priors are denoted by SGC( $m_J$ ), SIGC( $M_J$ ), SGC( $m_{inf}$ ) and SIGC( $M_{inf}$ ).

Value

The matrix "table" contains the Hellinger distance estimates between actual and benchmark heterogeneity priors and has $4$ columns and $n$ rows, where $n$ is the number of actual heterogeneity priors specified, i.e. the length of the list tau.prior.

The columns of the matrix give the following Hellinger distance estimates between two heterogeneity priors (from left to right):

H(SGC(m_inf), pri_act):: benchmark prior SGC(m_inf) and actual prior
H(SIGC(M_J), pri_act):: benchmark prior SIGC(M_J) and actual prior
H(SGC(m_J), pri_act):: benchmark prior SGC(m_J) and actual prior
H(SIGC(M_inf), pri_act):: benchmark prior SIGC(M_inf) and actual prior

Each row corresponds to one actual heterogeneity prior specified in the list tau.prior, in the same order as in that list. Thus, the row names are:

pri_act_1:: first actual prior in tau.prior
pri_act_2:: second actual prior in tau.prior
...
pri_act_n:: nth (last) actual prior in tau.prior

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.

References

Examples

# for aurigular acupuncture (AA) data set with one
# actual half-normal and the "DuMouchel" heterogeneity prior
data(aa)
# warning: it takes ca. 7 min. to run this function
pri_RA_5bm(df=aa, tau.prior=list(function(t)dhalfnormal(t, scale=1),
                                 "DuMouchel"))
                                 
# computation is much faster if m_J and M_J are specified
pri_RA_5bm(df=aa, tau.prior=list(function(t)dhalfnormal(t, scale=1),
                                 "DuMouchel"),
           m_J = 1.35, M_J = 1.3)
# for aurigular acupuncture (AA) data set with one
# actual half-normal and the "DuMouchel" heterogeneity prior
data(aa)
# warning: it takes ca. 7 min. to run this function
pri_RA_5bm(df=aa, tau.prior=list(function(t)dhalfnormal(t, scale=1),
                                 "DuMouchel"))
                                 
# computation is much faster if m_J and M_J are specified
pri_RA_5bm(df=aa, tau.prior=list(function(t)dhalfnormal(t, scale=1),
                                 "DuMouchel"),
           m_J = 1.35, M_J = 1.3)

Prior reference analysis based on bayesmeta fits

Description

Computes a table of Hellinger distance estimates between the benchmark heterogeneity priors inducing the specified model fits in fits.bm and the actual heterogenity priors inducing the specified actual model fits in fits.actual. All fits should be based on the same data set.

Usage

pri_RA_fits(fits.actual, fits.bm)
pri_RA_fits(fits.actual, fits.bm)

Arguments

`fits.actual`	a list of model fits of class bayesmeta, computed with the `bayesmeta` function in the package bayesmeta.
`fits.bm`	a list of model fits of class bayesmeta, computed with the `bayesmeta` function in the package bayesmeta. To be used as benchmarks.

Details

Two alternative suggestions for benchmark priors are provided in Ott et al. (2021, Section 3.4) and its Supplementary Material (Sections 2.5 and 2.6). These benchmark priors and the corresponding fits can be computed using the functions fit_models_RA and fit_models_RA_5bm, respectively.

Value

A matrix of Hellinger distance estimates between actual and benchmark heterogeneity priors with $n.bm$ columns and $n.act$ rows, where $n.bm$ =length(fit.bms) is the number of benchmark fits specified and $n.act$ =length(fit.actual) the number of actual fits specified.

The columns of the matrix give the following Hellinger distance estimates between two heterogeneity priors (from left to right):

H(pri_bm_1, pri_act):: first benchmark prior bm_1 inducing the fit fits.bm[[1]] and actual prior
H(pri_bm_2, pri_act):: second benchmark prior bm_2 inducing the fit fits.bm[[2]] and actual prior
...: ...
H(pri_bm_n.bm, pri_act):: last benchmark prior bm_n.bm inducing the fit fits.bm[[n.bm]] and actual prior

Each row correspond to one actual heterogeneity prior inducing one of the fits in fits.actual, in the same order as in that list. Thus, the row names are:

pri_act_1:: first actual prior in tau.prior
pri_act_2:: second actual prior in tau.prior
...: ...
pri_act_n:: nth (last) actual prior in tau.prior

References

Examples

# for aurigular acupuncture (AA) data set
data(aa)
# compute the model fits  % function with long running time
# two actual half-normal heterogeneity priors
# warning: it takes ca. 7 min. to run this function
fits <- fit_models_RA_5bm(df=aa, tau.prior=
                                 list(function(t)dhalfnormal(t, scale=0.5),
                                      function(t)dhalfnormal(t, scale=1)))[[1]]
# benchmark fits under SGC(m_inf), SIGC(M_J), SGC(m_J) and SIGC(M_inf) priors
fits.bm.pri <- fits[1:4]
# actual fits under HN priors
fits.actual <- fits[c(6,7)]
# prior reference analysis
pri_RA_fits(fits.actual=fits.actual, fits.bm=fits.bm.pri)

# for aurigular acupuncture (AA) data set
data(aa)
# compute the model fits  % function with long running time
# two actual half-normal heterogeneity priors
# warning: it takes ca. 7 min. to run this function
fits <- fit_models_RA_5bm(df=aa, tau.prior=
                                 list(function(t)dhalfnormal(t, scale=0.5),
                                      function(t)dhalfnormal(t, scale=1)))[[1]]
# benchmark fits under SGC(m_inf), SIGC(M_J), SGC(m_J) and SIGC(M_inf) priors
fits.bm.pri <- fits[1:4]
# actual fits under HN priors
fits.actual <- fits[c(6,7)]
# prior reference analysis
pri_RA_fits(fits.actual=fits.actual, fits.bm=fits.bm.pri)

Respiratory tract infections data

Description

Meta-analysis data set including 22 randomized, controlled clinical trials on the prevention of respiratory tract infections by selective decontamination of the digestive tract in intensive care unit patients. The patients in the treated group received oral antibiotics, and those in the control groups received no prophylaxis.

Usage

data(rti)data(rti)

Format

A data frame with 22 observations on the following 7 variables:

study: character string, label of the study
f.t: integer, number of patients who became cases of respiratory tract infections among those receiving antibiotics
n.t: integer, number of patients receiving antibiotics
f.c: integer, number of patients who became cases of respiratory tract infections among those receiving no prophylaxis
n.c: integer, number of patients receiving no prophylaxis (control group)
y: numeric, log odds ratio estimates for the individual trials
sigma: numeric, standard error of the log odds ratio estimate for the individual trials

Details

The data set was originally analyzed by the Selective Decontamination of the Digestive Tract Trialists' Collaborative Group (1993) and reanalyzed by Bodnar et al. (2017). Overall, 3836 patients are included in these 22 trials.

The log odds ratio estimates and standard errors were computed using the escalc function in the package metafor using the option of adding 0.5 to all cells in tables including zeros (argument to="only0") as described in Bodnar et al. (2017).

Source

Bodnar, O., Link, A., Arendacka, B., Possolo, A., Elster, C. (2017). Bayesian estimation in random effects meta-analysis using a non-informative prior. Statistics in Medicine 36, 378–399.

References

Selective Decontamination of the Digestive Tract Trialists' Collaborative Group (1993). Meta-analysis of randomised controlled trials of selective decontamination of the digestive tract. British Medical Journal 307(6903), 525–532.

Examples

data(rti)
str(rti)
# forest plot
forest(x=rti$y, sei=rti$sigma, xlab="log odds ratio")
data(rti)
str(rti)
# forest plot
forest(x=rti$y, sei=rti$sigma, xlab="log odds ratio")

Reference standard deviation

Description

Computes the reference standard deviation of the given meta-analysis data set. The reference standard deviation is defined as the geometric mean of the standard deviations of the individual studies (Sorbye & Rue 2014, equation (7)).

Usage

sigma_ref(df)
sigma_ref(df)

Arguments

`df`	data frame with one column "sigma" containing the standard errors of the estimates for the individual studies.

Value

The reference standard deviation of the data set. Non-negative real number.

References

Sorbye, S., Rue, H. (2014). Scaling intrinsic Gaussian Markov random field priors in spatial modelling. Spatial Statistics 8, 39–51. doi:10.1016/j.spasta.2013.06.004

Examples

# reference sd for resporiratory tract infections (RTI) data
data(rti)
sigma_ref(df=rti)
# reference sd for resporiratory tract infections (RTI) data
data(rti)
sigma_ref(df=rti)

Package 'ra4bayesmeta'

Help Index

Reference Analysis for Bayesian Meta-Analysis

Description

Details

Author(s)

References

Examples

Auricular acupuncture data

Description

Usage

Format

Details

Source

References

Examples

Acute otitis media data

Description

Usage

Format

Details

Source

References

Examples

Calibration of the Hellinger distance

Description

Usage

Arguments

Details

Value

References

Examples

Density function of the square-root generalized conventional (SGC) benchmark prior

Description

Usage

Arguments

Details

Value

References

See Also

Examples

Density function of the square-root inverse generalized conventional (SIGC) benchmark prior

Description

Usage

Arguments

Details

Value

References

See Also

Examples

Model fitting for reference analysis using 2 benchmarks: Posterior inference for benchmark and actual heterogeneity priors

Description

Usage

Arguments

Details

Value

Warning

References

See Also

Examples

Model fitting for reference analysis using 5 benchmarks: Posterior inference for benchmark and actual heterogeneity priors

Description

Usage

Arguments

Details

Value

Warning

References

See Also

Examples

Hellinger distance between two probability densities

Description

Usage

Arguments

Details

Value

References

See Also

Examples

Hellinger distance between marignal posterior densities of two bayesmeta fits