% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/brma.norm.R
\name{brma}
\alias{brma}
\alias{brma.norm}
\title{Bayesian Meta-Analysis}
\usage{
brma(
  yi,
  vi,
  sei,
  weights,
  ni,
  mods,
  scale,
  cluster,
  data,
  slab,
  subset,
  measure,
  prior_effect,
  prior_heterogeneity,
  prior_mods,
  prior_scale,
  prior_heterogeneity_allocation,
  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,
  ...
)
}
\arguments{
\item{yi}{a vector of effect sizes, or a formula with the effect size on the
left-hand side and location moderators on the right-hand side (for example
\code{yi ~ x1 + x2}). If a formula is supplied, \code{mods} must not be specified.}

\item{vi}{a vector of sampling variances. Either \code{vi} or \code{sei} must be
supplied for normal models.}

\item{sei}{a vector of standard errors. Either \code{vi} or \code{sei} must be
supplied for normal models.}

\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{ni}{an optional vector of sample sizes. Used for \code{measure = "GEN"}
or when estimating \code{"UISD"}).}

\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 for the effect size (\eqn{\mu}) parameter
(the intercept). If omitted, a default prior is constructed. In single-model
functions, explicit \code{NULL} or \code{FALSE} sets a spike at zero.}

\item{prior_heterogeneity}{prior distribution for the heterogeneity (\eqn{\tau})
parameter. If omitted, a default prior is constructed. In single-model
functions, explicit \code{NULL} or \code{FALSE} sets a spike at zero.}

\item{prior_mods}{prior distribution for the moderators (\eqn{\beta}) parameters.
A single prior applies to all terms; a named list can specify term-specific
priors. If omitted or \code{NULL}, default priors are used.}

\item{prior_scale}{prior distribution for the scale (\eqn{\delta}) parameters.
A single prior applies to all terms; a named list can specify term-specific
priors. If omitted or \code{NULL}, default priors are used.}

\item{prior_heterogeneity_allocation}{prior distribution for the fraction of
heterogeneity allocated to the cluster-level component in multilevel models
(\eqn{\rho}). If omitted or \code{NULL}, defaults to \code{Beta(1, 1)}.}

\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("brma.norm", "brma")}. The object
contains checked \code{data}, checked \code{priors}, the JAGS \code{fit}, cached \code{summary},
and cached \code{coefficients}. If the corresponding package options are enabled,
it can also contain cached LOO, WAIC, or marginal likelihood results. The
advanced internal \code{only_data = TRUE} and \code{only_priors = TRUE} paths return
partially constructed objects.
}
\description{
Function for fitting normal-likelihood/effect-size
random-effects, meta-regression, multilevel, and location-scale
meta-analytic models. \code{brma.norm()} is an alias for \code{brma()}; raw-count
GLMM models use \code{brma.glmm()}.
}
\details{
\subsection{Prior distributions}{

Prior distributions must be specified for all model parameters.
This typically includes the pooled effect \eqn{\mu} and between-study heterogeneity
\eqn{\tau}. In the case of meta-regression, the pooled effect \eqn{\mu} corresponds to
the intercept, and additional prior distributions for the regression coefficients
are required. In the case of a location-scale model, the between-study heterogeneity
corresponds to the intercept of the scale regression, and additional prior
distributions for the scale regression coefficients are required.

There are several ways to specify the prior distributions: \enumerate{
\item{via a standardized effect size \code{measure} with known unit information standard deviation,}
\item{by estimating unit information standard deviation using sample sizes \code{ni},}
\item{by manually setting \code{prior_unit_information_sd},}
\item{by specifying informed empirical prior distributions via \code{prior_informed_field}
and \code{prior_informed_subfield},}
\item{or via fully custom specification using the \code{prior_effect}, \code{prior_heterogeneity},
\code{prior_mods}, \code{prior_scale}, and \code{prior_heterogeneity_allocation} arguments.}
}
In all cases, the prior behavior can be further modified by the \code{rescale_priors},
\code{standardize_continuous_predictors}, and \code{set_contrast_factor_predictors} arguments.
\subsection{(1) Specifying prior distributions via standardized effect size measures with known}{

unit information standard deviation
This is the easiest way to specify prior distributions. The width of prior
distributions is based on a fraction of the known unit information standard deviation (\code{UISD})
\insertCite{rover2021weakly}{RoBMA}. The default prior distributions for the parameters
are set as follows:\tabular{ll}{
effect size:               \tab Normal(0, \eqn{\frac{1}{2}} \code{UISD})  \cr
heterogeneity:             \tab Normal+(0, \eqn{\frac{1}{4}} \code{UISD}) \cr
effect moderation:         \tab Normal(0, \eqn{\frac{1}{4}} \code{UISD})  \cr
heterogeneity moderation:  \tab Normal(0, \eqn{\frac{1}{2}})
}
The heterogeneity moderation parameters are multiplicative, as such they are independent of \code{UISD}.

The default fraction of the \code{UISD} can be changed via \code{RoBMA.options()} using one of
the following arguments: \code{"default_UISD.effect"}, \code{"default_UISD.heterogeneity"},
\code{"default_UISD.mods"}, \code{"default_UISD.scale"}.

The known \code{UISD} for standardized effect size measures (\code{measure}) are set as follows:
\tabular{ll}{
\code{"SMD"}:   \tab \eqn{\sqrt{2}} \cr
\code{"ZCOR"}:  \tab \eqn{1}        \cr
\code{"RR"}:    \tab \eqn{\sqrt{4}} \cr
\code{"OR"}:    \tab \eqn{\sqrt{4}} \cr
\code{"HR"}:    \tab \eqn{\sqrt{4}} \cr
\code{"IRR"}:   \tab \eqn{\sqrt{4}}
}
See Chapter 2.4 in \insertCite{spiegelhalter2004bayesian;textual}{RoBMA} and
Chapter 1 in \insertCite{grieve2022hybrid;textual}{RoBMA}.
}

\subsection{(2) Estimating unit information standard deviation using sample sizes}{

When effect sizes are on a non-standardized scale (\code{measure = "GEN"}) or use a
standardized effect size without known \code{UISD}, the \code{UISD} can be estimated from
sample sizes (\code{ni}) and standard errors (\code{sei}) following Equation 6 in
\insertCite{rover2021weakly;textual}{RoBMA}. The estimated \code{UISD} is then used to
scale the default prior distributions as described in section (1).

Note that the known \code{UISD} for standardized effect size measures (section (1)) is
used if available, even when \code{ni} is provided.
}

\subsection{(3) Manually setting unit information standard deviation}{

Alternatively, the \code{UISD} can be specified directly via the \code{prior_unit_information_sd}
argument. This is useful when the appropriate scale for prior distributions is known
a priori or when multiple analyses are to be performed on subsets of the same data
(re-estimating \code{UISD} on different subsets of the data can lead to slightly different
prior distributions for different subsets; see \code{\link[=estimate_unit_information_sd]{estimate_unit_information_sd()}}).
The specified \code{prior_unit_information_sd} is then used to scale the default prior
distributions as described in section (1).

Note that the manually specified \code{prior_unit_information_sd} takes precedence over
the estimated \code{UISD} from \code{ni} (section (2)) and the known \code{UISD} from \code{measure}
(section (1)). It cannot be combined with \code{prior_informed_field}.
}

\subsection{(4) Specifying informed empirical prior distributions}{

Informed prior distributions can be specified via the \code{prior_informed_field} and
\code{prior_informed_subfield} arguments. Currently, only \code{prior_informed_field = "medicine"}
with subfields defined in \code{BayesTools::prior_informed_medicine_names} is supported,
which uses empirically derived prior distributions from medical meta-analyses as described in
\insertCite{bartos2021bayesian;textual}{RoBMA} and
\insertCite{bartos2023empirical;textual}{RoBMA}.

When \code{prior_informed_field = "medicine"}, the default \code{prior_informed_subfield} is
\code{"Cochrane"} (i.e., using the whole CDSR database as a reference). The informed
prior distributions are available for the following effect size measures:
\tabular{ll}{
\code{"SMD"}:  \tab standardized mean difference \cr
\code{"OR"}:   \tab log odds ratio               \cr
\code{"RR"}:   \tab log risk ratio               \cr
\code{"RD"}:   \tab risk difference              \cr
\code{"HR"}:   \tab log hazard ratio
}

Note that informed prior distributions are only available for the effect size (\eqn{\mu})
and heterogeneity (\eqn{\tau}) parameters. For effect moderation (\code{prior_mods}), the
informed effect prior is scaled by a factor of \code{RoBMA.get_option("default_informed_priors.mods")}.
For heterogeneity moderation (\code{prior_scale}), a normal prior with standard deviation
specified by \code{RoBMA.get_option("default_informed_priors.scale")} is used.
}

\subsection{(5) Fully custom prior distributions}{

Prior distributions can be fully customized by directly specifying the \code{prior_effect},
\code{prior_heterogeneity}, \code{prior_mods}, \code{prior_scale}, and \code{prior_heterogeneity_allocation}
arguments. These should be prior distribution objects created via \code{BayesTools::prior()}
or related functions (e.g., \code{prior_factor()}).
}

\subsection{Rescaling prior distributions}{

The \code{rescale_priors} argument allows rescaling supported prior distributions by a
multiplicative factor. For example, \code{rescale_priors = 2} doubles the standard
deviations/scales of normal, Cauchy, t, and inverse-gamma prior distributions,
making them more diffuse. Point and none priors are unchanged.
}

\subsection{Handling of continuous and factor predictors}{

When \code{standardize_continuous_predictors = TRUE}, continuous moderator and
scale predictors are internally standardized before fitting. Reported
summaries are transformed back to the original predictor scale by default;
use \code{standardized_coefficients = TRUE} in \code{summary()} or related methods to
inspect coefficients on the standardized scale.

Factor predictors use the contrast specified by
\code{set_contrast_factor_predictors}. The default \code{"treatment"} follows standard
treatment coding. Model-averaging functions default to \code{"meandif"} so
inclusion priors for factor levels are centered on deviations from the grand
mean.
}

}
}
\examples{
\dontrun{
if (requireNamespace("metadat", quietly = TRUE) &&
    requireNamespace("metafor", quietly = TRUE)) {
  data(dat.bcg, package = "metadat")
  dat <- metafor::escalc(
    measure = "RR",
    ai      = tpos,
    bi      = tneg,
    ci      = cpos,
    di      = cneg,
    data    = dat.bcg
  )

  fit <- brma(
    yi      = yi,
    vi      = vi,
    mods    = ~ ablat + year,
    data    = dat,
    measure = "RR",
    seed    = 1,
    silent  = TRUE
  )

  summary(fit)
  predict(fit, type = "terms")
}
}

}
\references{
\insertAllCited{}
}
\seealso{
\code{\link[=RoBMA]{RoBMA()}}, \code{\link[=BMA]{BMA()}}, \code{\link[=brma.glmm]{brma.glmm()}}, \code{\link[=summary.brma]{summary.brma()}},
\code{\link[=plot.brma]{plot.brma()}}, \code{\link[=predict.brma]{predict.brma()}}
}
