Package {metaGLMM}

metaGLMM: Aggregate-Data Generalized Linear Mixed-Effects Meta-Analysis

Description

Fits likelihood-based random-effects meta-analysis models directly to aggregate Gaussian, binomial, Poisson, and Gamma outcomes. The package also provides profile and simple Bartlett-corrected inference, plug-in prediction intervals, forest plots, and a documented custom-family interface.

Author(s)

Maintainer: Keisuke Hanada keisuke.hanada.87@gmail.com

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.

See Also

Useful links:

• https://github.com/keisuke-hanada/metaGLMM

• Report bugs at https://github.com/keisuke-hanada/metaGLMM/issues

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

Value

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

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

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.

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

Value

A 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

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.

Wald Confidence Intervals

Description

Wald Confidence Intervals

Usage

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

Arguments

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

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

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

Value

A two-column confidence-interval matrix.

Forest Plots for metaGLMM Fits

Description

Forest Plots for metaGLMM Fits

Usage

forest(x, ...)

Arguments

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

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

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

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

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

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

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

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

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

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

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

Value

An object of class summary.metaGLMM.