% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/BMA.glmm.R
\name{BMA.glmm}
\alias{BMA.glmm}
\title{Bayesian Model-Averaged Generalized Meta-Analysis}
\usage{
BMA.glmm(
  ai,
  bi,
  ci,
  di,
  n1i,
  n2i,
  x1i,
  x2i,
  t1i,
  t2i,
  weights,
  mods,
  scale,
  cluster,
  data,
  slab,
  subset,
  measure = "OR",
  prior_effect,
  prior_heterogeneity,
  prior_mods,
  prior_scale,
  prior_heterogeneity_allocation,
  prior_baserate,
  prior_lograte,
  prior_effect_null,
  prior_heterogeneity_null,
  prior_mods_null,
  prior_scale_null,
  prior_heterogeneity_allocation_null,
  standardize_continuous_predictors = TRUE,
  set_contrast_factor_predictors = "treatment",
  prior_unit_information_sd,
  rescale_priors = 1,
  prior_informed_field,
  prior_informed_subfield,
  sample = 5000,
  burnin = 2000,
  adapt = 500,
  chains = 3,
  thin = 1,
  parallel = FALSE,
  autofit = FALSE,
  autofit_control = set_autofit_control(),
  convergence_checks = set_convergence_checks(),
  seed = NULL,
  silent = TRUE,
  ...
)
}
\arguments{
\item{ai}{a vector of the number of events in the treatment or experimental
group for binomial GLMM models.}

\item{bi}{a vector of the number of non-events in the treatment or
experimental group for binomial GLMM models.}

\item{ci}{a vector of the number of events in the control group for binomial
GLMM models.}

\item{di}{a vector of the number of non-events in the control group for
binomial GLMM models.}

\item{n1i}{a vector of the sample size in the treatment or experimental
group. If omitted for binomial GLMMs, it is computed as \code{ai + bi}.}

\item{n2i}{a vector of the sample size in the control group. If omitted for
binomial GLMMs, it is computed as \code{ci + di}.}

\item{x1i}{a vector of the number of events in the treatment/experimental group
(for Poisson data).}

\item{x2i}{a vector of the number of events in the control group (for Poisson data).}

\item{t1i}{a vector of the person-time in the treatment/experimental group.}

\item{t2i}{a vector of the person-time in the control group.}

\item{weights}{an optional vector of positive likelihood weights. For
normal/effect-size models, each weight powers the estimate likelihood. For
constructors with GLMM raw-count input, each weight powers the paired
two-arm likelihood for one study.}

\item{mods}{an optional matrix, data.frame, or formula specifying
location moderators (meta-regressors). Formula input is evaluated in \code{data}.}

\item{scale}{an optional matrix, data.frame, or formula specifying
scale predictors for location-scale models. Formula input is evaluated in
\code{data}.}

\item{cluster}{an optional vector of cluster identifiers for multilevel
meta-analysis.}

\item{data}{an optional data frame containing the variables.}

\item{slab}{an optional vector of study labels.}

\item{subset}{an optional logical or numeric vector specifying a subset of
data to be used.}

\item{measure}{a character string specifying the effect size measure.
Normal/effect-size constructors require an explicit value and support
\code{"SMD"}, \code{"ZCOR"}, \code{"RR"}, \code{"OR"}, \code{"HR"}, \code{"RD"}, \code{"IRR"}, and \code{"GEN"}.
Use \code{"GEN"} only for general effect sizes without a known unit information
standard deviation. GLMM raw-count constructors support only \code{"OR"} and
\code{"IRR"} and default to \code{"OR"}.}

\item{prior_effect}{prior distribution(s) for the alternative effect
component(s).}

\item{prior_heterogeneity}{prior distribution(s) for the alternative
heterogeneity component(s).}

\item{prior_mods}{prior distribution(s) for alternative moderator
components. A single prior applies to all terms; a named list can specify
term-specific components.}

\item{prior_scale}{prior distribution(s) for alternative scale-regression
components. A single prior applies to all terms; a named list can specify
term-specific components.}

\item{prior_heterogeneity_allocation}{prior distribution(s) for the
alternative cluster-level heterogeneity allocation component(s).}

\item{prior_baserate}{prior distribution for the estimate-specific midpoint
base-rate probability in binomial GLMM models. If omitted or \code{NULL}, defaults
to independent \code{Beta(1, 1)} priors.}

\item{prior_lograte}{prior distribution for the estimate-specific midpoint
log-rate in Poisson GLMM models. If omitted or \code{NULL}, a data-based
unit-information normal prior is used independently for each estimate.}

\item{prior_effect_null}{prior distribution(s) for the null effect
component(s).}

\item{prior_heterogeneity_null}{prior distribution(s) for the null
heterogeneity component(s).}

\item{prior_mods_null}{prior distribution(s) for null moderator components.
A single prior applies to all terms; a named list can specify term-specific
components.}

\item{prior_scale_null}{prior distribution(s) for null scale-regression
components. A single prior applies to all terms; a named list can specify
term-specific components.}

\item{prior_heterogeneity_allocation_null}{prior distribution(s) for the
null cluster-level heterogeneity allocation component(s).}

\item{standardize_continuous_predictors}{logical. Whether to standardize continuous predictors.
Defaults to \code{TRUE}.}

\item{set_contrast_factor_predictors}{character. How to set contrast for factor predictors.
Defaults are constructor-specific and shown in each function usage; single-model
constructors use \code{"treatment"}, while model-averaging constructors use \code{"meandif"}.}

\item{prior_unit_information_sd}{numeric. The unit information standard deviation (\eqn{\sigma_{unit}}).
Cannot be used together with \code{prior_informed_field}.}

\item{rescale_priors}{numeric. A scaling factor for supported prior distributions.
Point and none priors are unchanged. For constructors with publication-bias
prior distributions, \code{rescale_priors} does not rescale them except for the
default PEESE prior's UISD adjustment. Defaults to 1.}

\item{prior_informed_field}{character. The field of the informed prior distributions.
Omit to use the standard default prior specification; explicit \code{NULL} is invalid.}

\item{prior_informed_subfield}{character. The subfield of the informed prior distributions.
Omit to use the field-specific default, such as \code{"Cochrane"} for
\code{prior_informed_field = "medicine"}; explicit \code{NULL} is invalid.}

\item{sample}{numeric. Number of MCMC samples to save. Defaults to \code{5000}.}

\item{burnin}{numeric. Number of burn-in iterations. Defaults to \code{2000}.}

\item{adapt}{numeric. Number of adaptation iterations. Defaults to \code{500}.}

\item{chains}{numeric. Number of MCMC chains. Defaults to \code{3}.}

\item{thin}{numeric. Thinning interval. Defaults to \code{1}.}

\item{parallel}{logical. Whether to run MCMC chains in parallel. Defaults to \code{FALSE}.}

\item{autofit}{logical. Whether to automatically extend the MCMC chains if convergence is not met.
Defaults to \code{FALSE}.}

\item{autofit_control}{list of autofit control settings. See \code{\link[=set_autofit_control]{set_autofit_control()}} for details.}

\item{convergence_checks}{list of convergence check settings. See \code{\link[=set_convergence_checks]{set_convergence_checks()}} for details.}

\item{seed}{numeric. Random seed for reproducibility. Defaults to \code{NULL}.}

\item{silent}{logical. Whether to suppress output. Constructors with no
explicit default use \code{RoBMA.get_option("silent")} when \code{silent} is omitted.
Model-averaging wrappers default to \code{TRUE} unless explicitly changed.}

\item{...}{additional advanced arguments. Fitting functions reject unused
arguments; currently recognized internal arguments include \code{only_data},
\code{only_priors}, \code{is_JASP}, and \code{is_JASP_prefix}.}
}
\value{
A fitted object of class
\code{c("BMA.glmm", "RoBMA", "brma.glmm", "brma")}. The object contains checked
\code{data}, checked mixture \code{priors}, the JAGS \code{fit}, cached \code{summary}, and
cached \code{coefficients}.
}
\description{
Function for fitting Bayesian model-averaged meta-analytic models
directly to binary or count data using a generalized linear mixed model (GLMM)
framework. Unlike \code{\link{RoBMA}}, this function does not adjust for
publication bias, as weight function and regression-based bias adjustment
methods are not available for GLMM outcomes.
}
\details{
\code{BMA.glmm} combines the data input style of \code{\link{brma.glmm}} with
the mixture prior specification of \code{\link{RoBMA}} for Bayesian model-averaging.

Model for odds ratios (\code{measure = "OR"}) uses a binomial-normal model
as described in \insertCite{jackson2018comparison;textual}{RoBMA}.

Model for incidence rate ratios (\code{measure = "IRR"}) uses a Poisson-normal
model as described in \insertCite{bagos2009mixed;textual}{RoBMA}.

When \code{weights} are supplied, they are treated as likelihood weights on
the paired two-arm study contribution.
}
\examples{
\dontrun{
if (requireNamespace("metadat", quietly = TRUE)) {
  data(dat.bcg, package = "metadat")

  fit <- BMA.glmm(
    ai      = tpos,
    bi      = tneg,
    ci      = cpos,
    di      = cneg,
    data    = dat.bcg,
    measure = "OR",
    seed    = 1,
    silent  = TRUE
  )

  summary(fit)
}
}

}
\seealso{
\code{\link[=brma.glmm]{brma.glmm()}} \code{\link[=RoBMA]{RoBMA()}} \code{\link[=summary.brma]{summary.brma()}} \code{\link[=plot.brma]{plot.brma()}}
}
