vignettes/_v00-introduction-body.md
In RoBMA: Robust Bayesian Meta-Analyses

The RoBMA R package fits a comprehensive collection of Bayesian meta-analytic models [@RoBMA]. It provides single-model fits, meta-regression, location-scale models, multilevel models, fully Bayesian model-averaged ensembles, and built-in publication-bias adjustment using selection models, PET-PEESE, and Robust Bayesian Meta-Analysis (RoBMA). Posterior sampling is performed by JAGS through a custom C++ module that implements the weighted distributions used in selection models. Prior handling, plotting, and Bayesian diagnostics are delegated to the companion BayesTools package.

This introduction maps the package at a high level and points to the more detailed vignettes that follow.

The RoBMA R package requires JAGS 4.3.1 or newer [@plummer2003jags]. Install JAGS from https://mcmc-jags.sourceforge.io/ before installing the R package.

install.packages("RoBMA")

Note on backwards compatibility. The 4.0 release is not backwards compatible with earlier versions of the package. The Manuscript Companions section accompanies the methodological papers in which the RoBMA R package was originally developed and illustrated; the vignettes there have been updated to the 4.0 version of the package, and the numerical results differ from the published values because the underlying algorithms have changed. To reproduce the published analyses exactly, install RoBMA version 3.6.1 together with BayesTools version 0.2.23:

remotes::install_version("BayesTools", version = "0.2.23")
remotes::install_version("RoBMA",      version = "3.6.1")

The package exposes a small set of high-level fitting functions.

| Function | What it fits | |:----------------------|:---------------------------------------------------------------------------| | brma(), brma.norm() | Bayesian random-effects meta-analysis | | brma.glmm() | Bayesian GLMM meta-analysis (binomial / log OR or Poisson / log IRR) | | bselmodel() | Bayesian weight-function selection model | | bPET(), bPEESE() | Bayesian PET / PEESE publication-bias adjustment | | BMA(), BMA.norm() | Bayesian model-averaging across presence / absence of effect and heterogeneity (no bias adjustment) | | BMA.glmm() | Bayesian model-averaging for GLMM meta-analysis | | RoBMA() | Robust Bayesian model-averaging including publication-bias models |

brma() and RoBMA() are the main workhorses. brma() fits a single model in the same spirit as metafor::rma(); RoBMA() averages across an ensemble that includes publication-bias adjustment. BMA() is RoBMA() without the bias-adjustment models.

All fitting functions

share an effect-size interface (yi, sei / vi, measure arguments; apart from glmm),
can be extended into a meta-regression (mods argument),
can be extended into a location-scale model (scale argument),
can be extended into a multilevel model (cluster argument),
and all produce objects that work with the same set of inference helpers (summary(), plot(), predict(), loo(), funnel(), regplot(), residuals and influence diagnostics, ...).

The vignettes are organized into four sections.

| Vignette | Topic | |:--------------------------|:----------------------------------------------------------------------| | Introduction to RoBMA | Package overview, fitting functions, and vignette map | | Prior Distributions | Default, informed, and custom prior distributions; rescaling guidance | | Bayesian Meta-Analysis | Random-effects meta-analysis with brma(), compared with metafor::rma() | | Feature Coverage | Overview of available functionality across model families |

The foundations section gives the package overview, prior specification, a baseline brma() workflow, and current feature coverage. The Bayesian Meta-Analysis vignette walks through the BCG-vaccine example from the metafor package in brma(), covering summaries, meta-regression, marginal means, residuals, influence, LOO, and the standard meta-analytic plots.

Correspondence with `metafor`

| Vignette | Topic | |:--------------------------------------------------|:-----------------------------------------------------| | Multilevel Meta-Analysis | brma() with cluster and metafor::rma.mv() for 3-level data | | Publication-Bias Adjustment | bselmodel() / bPET() / bPEESE() and metafor::selmodel() | | Location-Scale Models | brma() with scale and metafor::rma.ls() | | Generalized Linear Mixed-Effects Meta-Analysis | brma.glmm() and metafor::rma.glmm() for binomial and Poisson outcomes |

Each vignette starts from a metafor package analysis and shows the matching RoBMA R package syntax, output, and diagnostics.

| Vignette | Topic | |:-------------------------------|:-----------------------------------------------------------------------| | Bayesian Model Averaging | Accounting for model uncertainty across presence and absence of effect and heterogeneity, with posterior model probabilities and inclusion Bayes factors | | Robust Bayesian Meta-Analysis | Extending the ensemble to publication-bias models used in RoBMA(), with PSMA, PP, and bespoke ensemble specifications |

The first vignette introduces model averaging on an ensemble of models with and without effect and heterogeneity. The second extends the ensemble to publication-bias models used in RoBMA().

| Vignette | Companion paper / dataset | |:------------------------------------------|:-------------------------------------------------------------------| | Adjusting for Publication Bias Tutorial | @bartos2020adjusting, JASP / R tutorial on Lui2015 | | Robust Bayesian Meta-Regression | @bartos2023robust, RoBMA-reg on Andrews2021 | | Multilevel Robust Bayesian Meta-Analysis | @bartos2025robust, Multilevel RoBMA on Johnides2025 | | Multilevel Robust Bayesian Meta-Regression | Multilevel RoBMA-reg on Kroupova2021 | | Informed Bayesian Meta-Analysis in Medicine | @bartos2021bayesian, informed prior distributions for medical meta-analysis (continuous outcomes) | | Informed Bayesian Meta-Analysis with Binary Outcomes | @bartos2023empirical, informed prior distributions for medical meta-analysis (binary and time-to-event outcomes) | | Zplot Publication-Bias Diagnostics | @bartos2025zcurve, zplot diagnostics on Hoppen2025 |

These vignettes reproduce or update analyses from published papers and serve as references when citing the corresponding methodological work.

For readers familiar with the metafor package: read Bayesian Meta-Analysis, then the Correspondence with metafor vignettes for the model family they use most.
For readers new to Bayesian meta-analysis: read Prior Distributions and then Bayesian Meta-Analysis.
For publication-bias adjustment: read Robust Bayesian Meta-Analysis, with Adjusting for Publication Bias Tutorial as a worked example.