---
title: "metaBMA: Bayesian Model Averaging for Random- and Fixed-Effects Meta-Analysis"
author: "Daniel W. Heck"
date: "`r Sys.Date()`"
number_section: true
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{metaBMA: Meta-Analysis with Bayesian Model Averaging}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---
  
  
## Overview
  
Fixed-effects meta-analyses assume that the effect size $d$ is identical in all
studies. In contrast, random-effects meta-analyses assume that effects vary
according to a normal distribution with mean $d$ and standard deviation $\tau$.
Both models can be compared in a Bayesian framework by assuming specific prior
distribution for $d$ and $\tau$. Given the posterior model probabilities, the
evidence for or against an effect (i.e., whether $d = 0$) and the evidence for
or against random effects can be evaluated (i.e., whether $\tau = 0$). By using
Bayesian model averaging (i.e., inclusion Bayes factors), both types of tests
can be performed by marginalizing over the other question. Most importantly,
this allows to test whether an effect exists while accounting for uncertainty
whether study heterogeneity exists or not.


## Defining and Plotting Priors

To fit a meta-analysis model, prior distributions on the average effect $d$ and
the heterogeneity $\tau$ are required. The package `metaBMA` leaves the user the
freedom to choose from several predefined distributions or even define an owen
prior density function. The function `prior` facilitates the construction and
visual inspection of prior distributions to check whether they meet the prior
knowledge about the field of interest.

```{r, fig.height=3.5, fig.width=5}
# load package
library("metaBMA")
# load data set
data(towels)

# Half-normal (truncated to > 0)
p1 <- prior("norm", c(mean=0, sd=.3), lower = 0)
p1
p1(1:3)
plot(p1)

# custom prior
p1 <- prior("custom", function(x) x^3-2*x+3, lower = 0, upper = 1)
plot(p1, -.5, 1.5)
```


## Bayesian Meta-Analysis

The functions `meta_fixed()` and `meta_random()` fit Bayesian meta-analysis
models. The model-specific posteriors for $d$ can then be averaged by `bma()`
and inclusion Bayes factors be computed by `inclusion()`.

The fixed-effects meta-analysis assumes that the effect size is identical across
studies. This model requires only one prior distribution for the overall effect
$d$:

```{r, fig.height=3.5, fig.width=5}
# Fixed-effects
progres <- capture.output(  # suppress Stan progress for vignette
  mf <- meta_fixed(logOR, SE, study, towels, 
                   d = prior("norm", c(mean=0, sd=.3), lower=0))
)
mf

# plot posterior distribution
plot_posterior(mf)
```

In contrast, the random-effects meta-analysis assumes that the effect size
varies across studies. Specifically, it is assumed that study effect sizes
follow a normal distribution with mean $d$ and standard deviation $\tau$. This
model requires two prior distributions for both parameters:

```{r, fig.height=3.5, fig.width=5}
# Random-effects
progres <- capture.output(  # suppress Stan progress for vignette
  mr <- meta_random(logOR, SE, study, towels,
                    d = prior("norm", c(mean=0, sd=.3), lower=0),
                    tau = prior("t", c(location=0, scale=.3, nu=1), lower=0),
                    iter = 1500, logml_iter = 2000, rel.tol = .1)
)
mr  

# plot posterior distribution
plot_posterior(mr, main = "Average effect size d")
plot_posterior(mr, "tau", main = "Heterogeneity tau")
```

## Model-Averaging for Meta-Analysis

The most general functions in `metaBMA` are `meta_bma()` and `meta_default()`,
which fit random- and fixed-effects models, compute the inclusion Bayes factor
for the presence of an effect and the averaged posterior distribution of the
mean effect $d$ (which accounts for uncertainty regarding study heterogeneity).


```{r, fig.height=4.5, fig.width=6}
mb <- meta_bma(logOR, SE, study, towels,
               d = prior("norm", c(mean=0, sd=.3), lower=0),
               tau = prior("t", c(location=0, scale=.3, nu=1), lower=0),
                    iter = 1500, logml_iter = 2000, rel.tol = .1)
mb
plot_posterior(mb, "d", -.1, 1.4)
plot_forest(mb)
```



## Predicted Bayes Factor for New Study

Often, it is of interest to judge how much additional evidence future studies can contribute to the present knowledge. Conditional on the outcome of the model averaging for meta-analysis, the function `predicted_bf()` samples new data sets from the posterior and performs model selection for each replication. Thereby, a distribution of predicted Bayes factors is obtain that represents the expected evidence one expects when running a new study. The following example is not executed since it requires time-intensive computations:

```{r, eval = FALSE, fig.height=4.5, fig.width=6}
mp <- predicted_bf(mb, SE = .2, sample = 30)
plot(mp)
```