Package 'metaGLMM'

Create Study-Level Data for metafor Workflows

Description

Create Study-Level Data for metafor Workflows

Usage

as_metafor_data(object, estimate = NULL, vi = NULL, labels = NULL)

Arguments

object	A fitted metaGLMM object.
estimate	Optional study-level estimates on the link scale.
vi	Optional study-level sampling variances on the link scale.
labels	Optional study labels.

Details

forest.metaGLMM() uses this conversion for its study rows. Automatic conversion is conservative; supply display estimates explicitly when the arm-level data do not identify one unambiguous study effect.

Value

A plain data frame with columns yi, vi, and slab. No metafor model class is assigned.

---

Convert a metaGLMM Fit to Aggregate-Row Data

Description

Convert a metaGLMM Fit to Aggregate-Row Data

Usage

## S3 method for class 'metaGLMM'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

x	A fitted metaGLMM object.
row.names	Optional row names.
optional	Unused.
...	Unused.

Value

A data frame containing the model frame and standardized diagnostic columns prefixed with a dot.

---

dataset of Chu et al. (2020)

Description

dataset of Chu et al. (2020)

Usage

chu2020

Format

A data.frame for binary distributed outcome with 7 studies:

Study

Study ID

x1

COVID-19 events in the longer-distance group

n1

Number of participants in the longer-distance group

x0

COVID-19 events in the shorter-distance group

n0

Number of participants in the shorter-distance group

Source

Chu, D. K., Akl, E. A., Duda, S., Solo, K., Yaacoub, S., Schuenemann, H. J., et al. (2020). Physical distancing, face masks, and eye protection to prevent person-to-person transmission of SARS-CoV-2 and COVID-19: a systematic review and meta-analysis. The Lancet, 395(10242), 1973-1987. Data used under the terms of the Creative Commons Attribution IGO 3.0 License (CC BY 3.0 IGO): https://creativecommons.org/licenses/by/3.0/igo/

---

Legacy Confidence-Interval Dispatcher

Description

Legacy Confidence-Interval Dispatcher

Usage

ci_metaGLMM(
  object,
  parm = .default_ci_parm(object),
  method = "PLSBC",
  level = 0.95,
  renge.c = 30,
  correction = c("corrected", "noma"),
  ...
)

Arguments

object	A fitted metaGLMM or legacy mle2 object.
parm	Parameter names.
method	One of "AN", "PL", "SBC", or the legacy alias "PLSBC".
level	Confidence level.
renge.c	Maximum profile bracket expansions.
correction	SBC correction option.
...	Additional low-level arguments.

Value

A confidence-interval matrix.

---

Wald Confidence Intervals

Description

Wald Confidence Intervals

Usage

confint_AN(object, parm = .default_ci_parm(object), level = 0.95, ...)

Arguments

object	A fitted metaGLMM or legacy mle2 object.
parm	Parameter names.
level	Confidence level.
...	Unused.

Value

A two-column confidence-interval matrix.

---

Experimental Godambe-Calibrated Bartlett Intervals

Description

This low-level method is retained for compatibility and remains experimental. It is intentionally not available through confint.metaGLMM().

Usage

confint_GSBC(
  object,
  parm = .default_ci_parm(object),
  level = 0.95,
  renge.c = 30,
  silent = FALSE,
  ...
)

Arguments

object	A fitted metaGLMM or legacy mle2 object.
parm	Parameter names.
level	Confidence level.
renge.c	Maximum number of geometric bracket expansions.
silent	Logical; return infinite endpoints instead of warning when a profile root cannot be bracketed.
...	Unused.

Value

A two-column confidence-interval matrix.

---

Profile-Likelihood Confidence Intervals

Description

Profile-Likelihood Confidence Intervals

Usage

confint_PL(
  object,
  parm = .default_ci_parm(object),
  level = 0.95,
  renge.c = 30,
  silent = FALSE,
  ...
)

Arguments

object	A fitted metaGLMM or legacy mle2 object.
parm	Parameter names.
level	Confidence level.
renge.c	Maximum number of geometric bracket expansions.
silent	Logical; return infinite endpoints instead of warning when a profile root cannot be bracketed.
...	Unused.

Value

A two-column confidence-interval matrix.

---

Simple Bartlett-Corrected Confidence Intervals

Description

Simple Bartlett-Corrected Confidence Intervals

Usage

confint_SBC(
  object,
  parm = .default_ci_parm(object),
  level = 0.95,
  renge.c = 30,
  silent = FALSE,
  correction = c("corrected", "noma"),
  ...
)

Arguments

object	A fitted metaGLMM or legacy mle2 object.
parm	Parameter names.
level	Confidence level.
renge.c	Maximum number of geometric bracket expansions.
silent	Logical; return infinite endpoints instead of warning when a profile root cannot be bracketed.
correction	Either "corrected" or the legacy value "noma".
...	Unused.

Value

A two-column confidence-interval matrix.

---

Confidence Intervals for a metaGLMM Fit

Description

Confidence Intervals for a metaGLMM Fit

Usage

## S3 method for class 'metaGLMM'
confint(
  object,
  parm = names(stats::coef(object)),
  level = 0.95,
  method = "wald",
  ...
)

Arguments

object	A fitted metaGLMM object.
parm	Fixed-effect parameter names. The default is all fixed effects.
level	Confidence level.
method	One of "wald", "profile", or "SBC", matched without regard to case. SBC denotes the simple Bartlett-corrected profile method.
...	Additional arguments passed to the low-level interval method.

Details

SBC is available for built-in and custom families with estimated heterogeneity. The correction uses the supplied study-level variances and the heterogeneity estimate under the profile constraint, so vi must represent an appropriate sampling variance on the link scale. Profile and SBC intervals can be substantially more computationally expensive than Wald intervals.

Value

A matrix with lower and upper columns.

---

Forest Plots for metaGLMM Fits

Description

Forest Plots for metaGLMM Fits

Usage

forest(x, ...)

Arguments

x	A fitted metaGLMM object.
...	Arguments passed to a method.

Value

The value returned by the dispatched method. For a metaGLMM object, the function draws a forest plot as a side effect and invisibly returns the plotting data described in forest.metaGLMM().

---

Draw a Forest Plot

Description

Draw a Forest Plot

Usage

## S3 method for class 'metaGLMM'
forest(
  x,
  estimate = NULL,
  vi = NULL,
  labels = NULL,
  parm = NULL,
  contrast = NULL,
  random_scale = 1,
  level = 0.95,
  type = c("link", "exp"),
  ci_methods = NULL,
  prediction = TRUE,
  ci_args = list(),
  annotate = TRUE,
  digits = 2L,
  header = NULL,
  xlab = NULL,
  pch = 15,
  cex = 0.9,
  summary_cex = max(1.1, cex * 1.2),
  diamond_height = 0.18,
  left_margin = NULL,
  right_margin = NULL,
  ...
)

Arguments

x	A fitted metaGLMM object.
estimate	Optional study-level estimates on the link scale.
vi	Optional study-level sampling variances on the link scale.
labels	Optional study labels.
parm	Fixed-effect name for the pooled result.
contrast	Optional fixed-effect contrast; used instead of parm.
random_scale	Loading of heterogeneity for the pooled prediction interval.
level	Confidence and prediction level.
type	Either "link" or "exp".
ci_methods	One or more fixed-effect confidence-interval methods: "wald", "profile", or "SBC". Matching is case-insensitive and the displayed order follows this vector. The default uses SBC when it is available and Wald otherwise.
prediction	Logical; include a prediction interval?
ci_args	Optional list of additional arguments passed to confint.metaGLMM() for profile and SBC calculations.
annotate	Logical; show forest-plot-style column headers and formatted estimates with confidence limits in the right margin?
digits	Number of digits after the decimal point in annotations.
header	Optional two-element character vector for the left and right column headers.
xlab	Optional horizontal-axis label.
pch	Plotting symbol for studies.
cex	Expansion factor for study labels and symbols.
summary_cex	Expansion factor for pooled and prediction labels and symbols.
diamond_height	Half-height of the pooled confidence-interval diamond in plot-row units.
left_margin	Optional left margin in inches. The default measures the rendered labels and enlarges the current device margin when necessary.
right_margin	Optional right margin in inches. The default measures the formatted annotations when annotate = TRUE.
...	Additional arguments passed to graphics::plot.default().

Details

With omitted display vectors, study estimates and variances are obtained through as_metafor_data(). Automatic extraction is used only when the fitted data unambiguously define one estimate per independent study. Otherwise, estimate, vi, and optionally labels must be supplied. For a grouped treatment-slope model, the pooled coefficient is selected automatically when exactly one model-matrix column represents the random-effect treatment loading. Display estimates are conceptually separate from the likelihood used for fitting. Selected fixed-effect confidence intervals and the plug-in prediction interval are drawn as filled diamonds. Profile and SBC intervals require parm; arbitrary contrast values are supported only for Wald intervals. The prediction interval is the package's Wald-type plug-in interval, not a profile- or Bartlett-corrected prediction interval. Plot margins are enlarged automatically for labels, headers, and numeric annotations.

Value

Invisibly, a data frame containing the data used to draw the plot, with one row for each study, requested pooled confidence interval, and optional prediction interval. The columns are kind (the row type: "study", "pooled", or "prediction"), label (the displayed row label), estimate (the point estimate), lower and upper (the interval limits), and method (the confidence-interval method, "prediction", or NA for study rows). Estimates and limits are on the link scale when type = "link" and are exponentiated when type = "exp". The forest plot is drawn as a side effect.

---

Evaluate the aggregate-data GLMM negative log likelihood.

Description

Evaluate the aggregate-data GLMM negative log likelihood.

Usage

likelihood(
  formula,
  data,
  vi,
  ni,
  beta,
  tau2,
  family = stats::binomial(link = "logit"),
  tau2.min = 1e-06,
  re_group = NULL,
  trt = NULL,
  rstdnorm = stats::qnorm((qrng::sobol(5000, d = 1, scrambling = 1) * 4999 + 0.5)/5000)
)

Arguments

formula	Model formula.
data	Data frame or model frame containing the response and covariates.
vi	Sampling variances.
ni	Information multipliers (sample sizes for binomial/Poisson aggregate data).
beta	Fixed-effect coefficient vector.
tau2	Between-row/group variance.
family	A stats family or metaGLMM_family() object.
tau2.min	Lower numerical bound used while estimating tau2.
re_group	Optional grouping variable for a shared random slope.
trt	Optional name of a binary treatment/loading column.
rstdnorm	Standard-normal quadrature or quasi-Monte Carlo draws.

Value

A scalar negative log likelihood.

---

dataset of Long et al. (2020)

Description

dataset of Long et al. (2020)

Usage

long2020

Format

A data.frame for gamma distributed outcome with 5 studies:

Study

Study ID

mi

Mean of intensive care unit (ICU) length of stay (LoS)

sdi

Standard deviation of ICU LoS

ni

Number of subjects

trt

Treatment indicator: 1 for treatment and 0 for control

Source

Long, R., Tian, J., Wu, S., Li, Y., Yang, X., & Fei, J. (2020). Clinical efficacy of surgical versus conservative treatment for multiple rib fractures: a meta-analysis of randomized controlled trials. International Journal of Surgery, 83, 79-88. Data used under the terms of the Creative Commons Attribution 4.0 International License (CC BY 4.0): https://creativecommons.org/licenses/by/4.0/

---

Build the quasi-Monte Carlo likelihood function used by metaGLMM().

Description

The formal argument names are exactly the columns of model.matrix() (plus tau2 when it is estimated), which makes factor and interaction models safe for optimizers such as bbmle::mle2().

Usage

make_ll_fun(
  formula,
  data,
  vi,
  ni,
  tau2,
  family,
  tau2_var = FALSE,
  tau2.min = 1e-06,
  re_group = NULL,
  trt = NULL,
  rstdnorm = stats::qnorm((qrng::sobol(5000, d = 1, scrambling = 1) * 4999 + 0.5)/5000),
  ...
)

Arguments

formula	Model formula.
data	Model data.
vi	Sampling variances.
ni	Information multipliers.
tau2	Fixed or starting between-study variance.
family	A stats family or metaGLMM_family() object.
tau2_var	Whether tau2 is an optimizer parameter.
tau2.min	Numerical lower bound for estimated tau2.
re_group	Optional grouping variable.
trt	Optional binary loading column name.
rstdnorm	Standard-normal quasi-Monte Carlo draws.
...	Additional compatibility arguments (including offset).

Value

A function suitable for bbmle::mle2().

---

Build the fast likelihood function using Gaussian closed form or GHQ.

Description

Custom families intentionally use the QMC path (fast = FALSE) so their callback remains the single source of truth for the likelihood.

Usage

make_ll_fun.fast(
  formula,
  data,
  vi,
  ni,
  tau2,
  family,
  tau2_var = FALSE,
  tau2.min = 1e-06,
  re_group = NULL,
  trt = NULL,
  ghq_Q = 1000L,
  ...
)

Arguments

formula	Model formula.
data	Model data.
vi	Sampling variances.
ni	Information multipliers.
tau2	Fixed or starting between-study variance.
family	A stats family or metaGLMM_family() object.
tau2_var	Whether tau2 is an optimizer parameter.
tau2.min	Numerical lower bound for estimated tau2.
re_group	Optional grouping variable.
trt	Optional binary loading column name.
ghq_Q	Number of Gauss-Hermite quadrature nodes.
...	Additional compatibility arguments (including offset).

Value

A function suitable for bbmle::mle2().

---

Fit an Aggregate-Data Generalized Linear Mixed-Effects Meta-Analysis

Description

Fits the aggregate-data generalized linear mixed model described by Hanada and Sugimoto (2026). The optimizer is provided by bbmle::mle2(), but the returned object has a stable metaGLMM S3 interface.

Usage

metaGLMM(
  formula,
  data,
  vi,
  ni,
  tau2 = NA_real_,
  family = stats::gaussian(),
  tau2_var = TRUE,
  re_group = NULL,
  trt = NULL,
  rstdnorm = NULL,
  skip.hessian = FALSE,
  fast = TRUE,
  ghq_Q = 1000L,
  method_opt = NULL,
  start_beta = NULL,
  start_tau2 = NULL,
  tau2_param = c("tau2", "log_tau2"),
  control = NULL,
  ...
)

Arguments

formula	A model formula.
data	A data frame containing the variables in formula.
vi	A numeric vector of aggregate-data variances or dispersion values.
ni	A numeric vector of sample sizes, denominators, or exposures.
tau2	A fixed between-study variance when tau2_var = FALSE. Use 0 for a model without a random effect. It is ignored when tau2_var = TRUE.
family	A supported stats::family() object or an object created by metaGLMM_family().
tau2_var	Logical; estimate the between-study variance?
re_group	Optional grouping vector. When supplied, observations in a group share the scalar random treatment effect defined by trt. Every group must contain both normalized loadings 0 and 1.
trt	Optional single column name in data containing a binary random- effect loading. It is required when re_group is supplied.
rstdnorm	Optional numeric integration points on the standard-normal scale for quasi-Monte Carlo integration.
skip.hessian	Logical; skip calculation of the Hessian?
fast	Logical; use closed-form Gaussian integration or compiled Gauss-Hermite quadrature for built-in families?
ghq_Q	Positive integer number of Gauss-Hermite quadrature points.
method_opt	Optional optimizer name passed to bbmle::mle2().
start_beta	Optional numeric vector or list of fixed-effect starts. Named values must exactly match colnames(model.matrix(formula, data)). Unnamed values are interpreted in model-matrix column order.
start_tau2	Starting value for the between-study variance.
tau2_param	Internal parameterization for estimated heterogeneity: either "tau2" or "log_tau2".
control	Optional optimizer control list.
...	Additional arguments passed to bbmle::mle2().

Details

Construction fails before optimization for empty, non-finite, or rank-deficient model designs and for invalid grouped random-effect or custom-family contracts. Non-convergence produces a warning; boundary heterogeneity and unavailable Hessian or covariance information remain available as object diagnostics.

Value

An object of class metaGLMM. Its integration component records the integration method and QMC provenance without storing the integration vector. Its convergence component records optimizer, Hessian, covariance, and boundary diagnostics.

References

Hanada, K. and Sugimoto, T. (2026). Random-effects meta-analysis via generalized linear mixed models: A Bartlett-corrected approach for few studies. Biometrics. doi:10.1093/biomtc/ujag148.

---

Create a custom aggregate-data family specification.

Description

Create a custom aggregate-data family specification.

Usage

metaGLMM_family(
  name,
  link = "identity",
  loglik,
  validate = NULL,
  initialize = NULL
)

Arguments

name	Family name used in printed output.
link	A link name accepted by stats::make.link() or a compatible link object.
loglik	A function with arguments y, eta, vi, and ni. It must return one aggregate log-likelihood contribution for every value of eta.
validate	Optional function used to validate response and design inputs.
initialize	Optional family-specific initialization function.

Details

The link callbacks and loglik must be vectorized and free of side effects. metaGLMM() probes the callbacks at its deterministic starting linear predictor before optimization and rejects non-numeric, incorrectly sized, or non-finite results.

Value

An object inheriting from metaGLMM_family and family.

---

Extract the Internal mle2 Fit

Description

Extract the Internal mle2 Fit

Usage

mle2_fit(object)

Arguments

object

A fitted metaGLMM object.

Value

The internal bbmle::mle2() object.

---

Predict from a metaGLMM Fit

Description

Predict from a metaGLMM Fit

Usage

## S3 method for class 'metaGLMM'
predict(
  object,
  newdata = NULL,
  type = c("link", "response", "exp"),
  interval = c("none", "confidence", "prediction"),
  level = 0.95,
  contrast = NULL,
  random_scale = NULL,
  ...
)

Arguments

object	A fitted metaGLMM object.
newdata	Optional data frame of covariate patterns.
type	Output scale: "link", "response", or "exp". The last exponentiates a log- or logit-scale result.
interval	One of "none", "confidence", or "prediction".
level	Confidence or prediction level.
contrast	Optional numeric contrast vector or matrix against the fixed effects. It cannot be combined with newdata or type = "response".
random_scale	Optional loading of the future scalar random effect.
...	Unused.

Details

A prediction interval targets a future underlying study-specific true effect. It combines fixed-effect uncertainty with tau2; it does not add the sampling variance of a future observed estimator.

Value

A numeric vector when interval = "none"; otherwise a data frame with fit, lower, and upper columns.

---

Evaluate a Profile-Likelihood Ratio

Description

Evaluate a Profile-Likelihood Ratio

Usage

profile_ll(value, object, parm)

Arguments

value	Numeric parameter values.
object	A fitted metaGLMM or legacy mle2 object.
parm	One fixed-effect parameter name.

Value

Profile likelihood-ratio statistics.

---

Evaluate a Simple Bartlett-Corrected Profile Ratio

Description

Evaluate a Simple Bartlett-Corrected Profile Ratio

Usage

profile_ll_sbc(value, object, parm, correction = c("corrected", "noma"))

Arguments

value	Numeric parameter values.
object	A fitted metaGLMM or legacy mle2 object.
parm	One fixed-effect parameter name.
correction	Either "corrected" or "noma".

Value

Corrected profile likelihood-ratio statistics.

---

dataset of Rutter et al. (2021)

Description

dataset of Rutter et al. (2021)

Usage

rutter2021

Format

A data.frame for Poisson distributed outcome with 11 studies:

Study

Study ID

Year

Publishing year

Sex

Sex (Female or Male)

Events

Number of events

Time

Total observation time

Source

Rutter, M., Bowley, J., Lanyon, P. C., Grainge, M. J., & Pearce, F. A. (2021). A systematic review and meta-analysis of the incidence rate of Takayasu arteritis. Rheumatology, 60(11), 4982-4990. Data used under the terms of the Creative Commons Attribution 4.0 International License (CC BY 4.0): https://creativecommons.org/licenses/by/4.0/

---

Summarize a metaGLMM Fit

Description

Summarize a metaGLMM Fit

Usage

## S3 method for class 'metaGLMM'
summary(object, ...)

Arguments

object	A fitted metaGLMM object.
...	Unused.

Value

An object of class summary.metaGLMM.

---