---
title: "Multilevel Robust Bayesian Meta-Analysis"
author: "František Bartoš"
date: "17th of December 2025 (updated: 29th of April 2026)"
output:
  rmarkdown::html_vignette:
    self_contained: yes
bibliography: ../inst/REFERENCES.bib
csl: ../inst/apa.csl
link-citations: true
vignette: >
  %\VignetteIndexEntry{Multilevel Robust Bayesian Meta-Analysis}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown_notangle}
---

```{r child = "_vignette-nowrap.md", echo = FALSE, eval = TRUE}
```

```{r setup, include = FALSE}
source("vignette-cache.R", local = knitr::knit_global())

cached_fits <- vignette_cache(
  name    = "v32-robma-multilevel",
  objects = c("fit", "fit_simple")
)

knitr::opts_chunk$set(
  collapse    = TRUE,
  comment     = "#>",
  eval        = vignette_cache_eval(cached_fits),
  message     = FALSE,
  warning     = FALSE,
  fig.width   = 7,
  fig.height  = 3.5,
  dev         = "png",
  fig.retina  = 3
)
if (.Platform$OS.type == "windows") {
  knitr::opts_chunk$set(dev.args = list(type = "cairo"))
}
```

```{r load-models, include = FALSE}
library("RoBMA")

data("Johnides2025", package = "RoBMA")

vignette_cache_load(cached_fits)
```

```{r precompute-models, include = FALSE, eval = FALSE}
library("RoBMA")

data("Johnides2025", package = "RoBMA")

prior_effect_361        <- prior("normal",   list(mean = 0, sd = 1))
prior_heterogeneity_361 <- prior("invgamma", list(shape = 1, scale = 0.15))

fit <- RoBMA(
  yi = d, sei = se, measure = "SMD", cluster = study,
  prior_effect        = prior_effect_361,
  prior_heterogeneity = prior_heterogeneity_361,
  adapt = 5000, burnin = 5000, sample = 10000,
  parallel  = TRUE, seed = 1, data = Johnides2025
)

fit_simple <- RoBMA(
  yi = d, sei = se, measure = "SMD",
  prior_effect        = prior_effect_361,
  prior_heterogeneity = prior_heterogeneity_361,
  adapt = 5000, burnin = 5000, sample = 10000,
  parallel  = TRUE, seed = 1, data = Johnides2025
)

vignette_cache_save(cached_fits)
```

**This vignette accompanies the manuscript [Robust Bayesian Multilevel Meta-Analysis: Adjusting for Publication Bias in the Presence of Dependent Effect Sizes](https://doi.org/10.31234/osf.io/9tgp2_v1) preprinted at *PsyArXiv* [@bartos2025robust].**

This vignette reproduces the first example from the manuscript.
For multilevel meta-regression with moderators, see the [*Multilevel Robust Bayesian Model-Averaged Meta-Regression*](v33-robma-multilevel-metaregression.html) vignette.

Multilevel Robust Bayesian Meta-Analysis (RoBMA) extends the standard RoBMA framework to datasets containing multiple effect sizes from the same studies.
We demonstrate the method using data from @johnides2025secondary, who meta-analyzed 412 effect sizes from 128 studies investigating secondary benefits of family-based treatments for childhood disorders.

## When to Use Multilevel RoBMA

Multilevel RoBMA is appropriate for datasets that contain multiple effect sizes from the same studies.
The multilevel approach explicitly models the clustering structure through the `cluster` argument, which:

 - accounts for dependencies among effect sizes from the same study,
 - partitions heterogeneity into within-study and between-study components,
 - simultaneously adjusts for publication bias at the study level (corresponding to selective reporting).

## Loading the Data

We load the package and examine the dataset structure.
```{r}
library(RoBMA)
data("Johnides2025", package = "RoBMA")
```

The dataset contains effect sizes (`d`), standard errors (`se`), and study identifiers (`study`).

```{r}
head(Johnides2025)
```

Multiple rows share the same study name, indicating that these effect sizes come from the same study. 
For example, the first five effect sizes are from "Price et al. (2012)" and might be more similar to each other than to effect sizes from other studies.

## Prior Distributions

To reproduce the RoBMA 3.6.1 version results, which used a different prior distribution formulation and scaling settings, we need to specify the prior distributions manually
(see the [*Prior Distributions*](v01-prior-distributions.html) vignette for more details on specifying prior distributions).

```{r prior-specification}
prior_effect_361        <- prior("normal",   list(mean = 0, sd = 1))
prior_heterogeneity_361 <- prior("invgamma", list(shape = 1, scale = 0.15))
```

## Fitting the Multilevel Model

We specify the effect sizes as `yi` and standard errors as `sei` argument.
Setting `measure = "SMD"` specifies that we are using standardized mean differences as the effect-size input, which is important for the prior distribution specification
(here the effect size and heterogeneity prior distributions are specified explicitly since they differ from the default specification in the 3.6.1 version; the publication-bias specification remains the same).
The `cluster` argument specifies which effect sizes belong together.

```{r, eval = FALSE}
fit <- RoBMA(
  yi = d, sei = se, measure = "SMD", cluster = study,
  prior_effect        = prior_effect_361,
  prior_heterogeneity = prior_heterogeneity_361,
  adapt = 5000, burnin = 5000, sample = 10000, 
  parallel  = TRUE, seed = 1, data = Johnides2025
)
```

*Note: This model takes 10-15 minutes with parallel processing enabled. Without parallel processing, expect over an hour.*

## Interpreting the Results

The `summary()` output contains two main sections.

```{r}
summary(fit)
```

### Components Summary

This table shows Bayes factors testing the presence of effect, heterogeneity, and publication bias. 
Each row displays the prior probability, posterior probability after observing the data, and the inclusion Bayes factor comparing models with versus without that component.

In our example, the inclusion BF for the effect is 0.927, indicating weak evidence against an effect. 
The inclusion BF for heterogeneity and publication bias are reported as `Inf`, i.e., beyond the numerical precision of the estimation algorithm (> 10⁶), indicating extreme evidence for both components.

We also notice a warning about the effective sample size (ESS) being below the set target.
The difference is, however, not substantial, and we can safely ignore it.

### Model-Averaged Estimates

This section provides meta-analytic estimates averaged across all models, weighted by their posterior probabilities.
The average effect size is `mu`, the overall heterogeneity is `tau`, and the heterogeneity allocation parameter is `rho`.
The heterogeneity allocation parameter `rho` indicates the proportion of heterogeneity allocated to the cluster-level component: `rho = 0` means all heterogeneity is within clusters, `rho = 1` means all heterogeneity is between clusters, and `rho = 0.5` means equal split.
The remaining parameters summarize the weight function and PET/PEESE regression for publication bias.

In our example, we find a small effect size (*d* = 0.050, 95% CI [0.000, 0.173]), substantial heterogeneity (τ = 0.40, 95% CI [0.348, 0.458]), and nearly balanced heterogeneity allocation (ρ = 0.461, 95% CI [0.306, 0.603]).
The large heterogeneity combined with the small pooled effect suggests substantial variation in true effects.
This distribution of true effect sizes can be obtained from the `summary_heterogeneity()` function:

```{r}
summary_heterogeneity(fit)
```

The wide prediction interval (*d* = -0.752 to 0.845) quantifies the degree of this heterogeneity: some studies may show benefits while others show harm.

## Model Types Summary

To understand which publication bias mechanisms the data support, we examine the posterior distribution across model types:

```{r}
summary_models(fit)
```

Essentially all of the posterior probability is allocated to selection models (weight functions).
The publication-bias adjustment therefore reflects selective reporting rather than small-study effects (PET/PEESE regression); specifically, one-sided selection operating on marginally significant p-values and on the direction of the effect.

## Visualizing the Weight Function

The weight function shows how publication probability varies across p-value ranges:

```{r, fig.width = 6, fig.height = 4}
plot_weightfunction(fit)
```

The plot displays one-sided p-value cutoffs (x-axis) against relative publication probability (y-axis), averaged across weight function specifications. 
A flat line at 1.0 indicates no publication bias; values below 1.0 indicate suppression. 

In our example, we notice a small drop in the relative publication probability at the cutoff corresponding to p = 0.05 (one-sided, i.e., 0.10 two-sided: selection on marginally significant p-values) and a much sharper drop corresponding to the direction of the effect (p = 0.50).


## Comparison with Single-Level RoBMA

To understand the importance of accounting for nested structure, we compare our results with a standard single-level RoBMA that ignores dependencies among effect sizes from the same study.

```{r, eval = FALSE}
fit_simple <- RoBMA(
  yi = d, sei = se, measure = "SMD", 
  prior_effect        = prior_effect_361,
  prior_heterogeneity = prior_heterogeneity_361,
  adapt = 5000, burnin = 5000, sample = 10000, 
  parallel  = TRUE, seed = 1, data = Johnides2025
)
```

```{r}
summary(fit_simple)
```

The single-level model differs by:

 - omitting `cluster`: it treats all effect sizes as independent,
 - estimating only one heterogeneity parameter: it cannot distinguish within-study from between-study variation,
 - potentially biased inference: ignoring dependencies can lead to overconfident conclusions.

For the Johnides et al. data, the single-level RoBMA finds strong evidence for the absence of an effect, while the multilevel model provides only weak evidence against it. 
Properly accounting for data structure leads to more conservative and appropriate inferences.


## References