---
title: "Binary aggregate outcomes"
author: "metaGLMM authors"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Binary aggregate outcomes}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>",
                      fig.width = 6, fig.height = 4)
set.seed(20260821)
library(metaGLMM)
```

## Data contract

For a binomial analysis, `y` is the observed proportion and `ni` is the
number of trials.  With two treatment arms per study, use `re_group` to
identify the study and `trt` to identify the 0/1 treatment loading.  This
shares one random treatment effect within each study.

```{r data}
binary_dat <- data.frame(
  study = factor(rep(paste0("Study ", 1:6), each = 2)),
  treatment = rep(c(0, 1), 6),
  events = c(20, 60, 25, 20, 30, 25, 15, 55, 35, 15, 25, 70),
  ni = rep(c(100, 90, 110, 95, 105, 120), each = 2)
)
binary_dat$y <- binary_dat$events / binary_dat$ni
binary_dat$vi <- 1 / (binary_dat$ni * binary_dat$y * (1 - binary_dat$y))
binary_dat
```

The finite `vi` values above are useful for displaying the arm-level
contrasts later.  The binomial likelihood uses `ni` to represent the number
of trials.

## Fit the grouped model

```{r fit}
binary_fit <- metaGLMM(
  y ~ treatment,
  data = binary_dat,
  vi = binary_dat$vi,
  ni = binary_dat$ni,
  tau2 = NA,
  family = binomial(link = "logit"),
  tau2_var = TRUE,
  re_group = binary_dat$study,
  trt = "treatment",
  fast = TRUE,
  ghq_Q = 40L
)

summary(binary_fit)
coef(binary_fit)
confint(binary_fit, parm = "treatment", method = "wald")
stopifnot(is.finite(binary_fit$tau), binary_fit$tau > 0)
```

The treatment effects vary deliberately across studies (including effects in
both directions), making the grouped random slope and its prediction interval
visible in this small example.

The treatment coefficient is on the log-odds-ratio scale.  A two-level factor
can be used in place of the numeric `treatment` column; the second factor
level is normalized to one.  Logical treatment indicators are also accepted.

## Study-level contrasts and a forest plot

The paired two-arm structure identifies one treatment contrast per study.
`forest()` obtains these study estimates and variances through
`as_metafor_data()` and selects the fixed treatment coefficient automatically:

```{r forest}
binary_contrasts <- as_metafor_data(binary_fit)
binary_contrasts

forest(binary_fit,
       xlab = "Log odds ratio",
       ci_methods = c("Wald", "profile", "SBC"))
```

Here `yi` is the within-study treated-minus-control log-odds contrast and `vi`
is its sampling variance.  The treatment-arm rows are therefore combined into
one comparable effect estimate per study before plotting.

Explicit `estimate`, `vi`, `labels`, and `parm` arguments remain available for
custom displays.  If a study has a zero cell, its automatically derived
display variance may be infinite; supply a finite, pre-specified correction
before requesting a forest plot.