---
title: "Getting started with metaGLMM"
author: "metaGLMM authors"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting started with metaGLMM}
  %\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)
```

## Overview

`metaGLMM` fits generalized linear mixed-effects likelihoods to aggregate
study summaries.  Each row contains a response, its sampling variance `vi`,
and a study size or exposure `ni`.  A formula supplies the fixed-effect model
matrix, so interactions, factors, and offsets use ordinary R model syntax.

The initial release provides four built-in families:

| Family | Typical response | Common links |
|:--|:--|:--|
| `gaussian()` | continuous effect estimate | `identity`, `log` |
| `binomial()` | proportion | `logit`, `probit`, `cloglog` |
| `poisson()` | rate | `log`, `identity` |
| `Gamma()` | positive mean | `log`, `inverse` |

The package uses the fast numerical path for built-in families when
`fast = TRUE`.  An R-level custom family uses QMC integration with
`fast = FALSE`; see the [custom-family vignette](custom-family.html).

## A small Gaussian analysis

The following data are deliberately small so that the example is quick to
run and easy to reproduce.

```{r gaussian-data}
dat <- data.frame(
  study = paste0("Study ", 1:6),
  estimate = c(-0.80, -0.30, 0.10, 0.70, 1.10, -0.50),
  moderator = c(0, 0, 1, 1, 0, 1),
  vi = c(0.04, 0.05, 0.03, 0.06, 0.04, 0.05),
  ni = c(100, 90, 120, 80, 110, 95)
 )
dat
```

Fit a random-effects model with an intercept and a moderator.  The study
estimates intentionally span a broad range, so the between-study component
is estimable rather than collapsing to the boundary:

```{r gaussian-fit}
library(metaGLMM)

fit <- metaGLMM(
  estimate ~ moderator,
  data = dat,
  vi = dat$vi,
  ni = dat$ni,
  tau2 = NA,
  family = gaussian(link = "identity"),
  tau2_var = TRUE,
  fast = TRUE
)

fit
summary(fit)
```

`coef()` and `vcov()` expose fixed effects only.  The estimated heterogeneity
is available separately as `tau2` and `tau`:

```{r gaussian-methods}
coef(fit)
vcov(fit)
fit$tau2
fit$tau
confint(fit, method = "wald")
stopifnot(is.finite(fit$tau), fit$tau > 0)
```

The object also retains the model frame and model matrix used for fitting.
This makes factor contrasts and coefficient names explicit:

```{r model-objects}
formula(fit)
terms(fit)
model.frame(fit)
colnames(model.matrix(fit))
```

## A positive-response example

For a Gamma likelihood, provide positive aggregate means and their sampling
variances.  Here the response is on the original positive scale and the log
link makes the treatment coefficient multiplicative.

```{r gamma-fit}
gamma_dat <- data.frame(
  study = paste0("Study ", 1:6),
  mean = c(9.6, 9.9, 13.8, 16.5, 8.2, 14.6),
  sd = c(0.7, 8.3, 4.2, 7.4, 4.3, 2.2),
  n = c(20, 25, 23, 18, 75, 20),
  treatment = c(1, 1, 1, 1, 1, 0)
)
gamma_dat$vi <- (gamma_dat$sd / gamma_dat$mean)^2

gamma_fit <- metaGLMM(
  mean ~ treatment,
  data = gamma_dat,
  vi = gamma_dat$vi,
  ni = gamma_dat$n,
  tau2 = NA,
  family = Gamma(link = "log"),
  tau2_var = TRUE,
  start_tau2 = 0.1,
  fast = TRUE
)
summary(gamma_fit)
stopifnot(is.finite(gamma_fit$tau), gamma_fit$tau > 0)
```

## Where to go next

Use the family-specific vignettes for binary and Poisson summaries, then see
the inference and prediction vignettes for intervals, new-study predictions,
and study-level displays.