% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/input-priors.R
\name{prior_specification}
\alias{prior_specification}
\title{Prior specification}
\arguments{
\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{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_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{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_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.}
}
\description{
Prior distributions can be supplied for all model parameters. When omitted,
the fitting functions construct defaults from the effect-size measure, sample
sizes, or informed-prior settings when available.

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.
}
\details{
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. For publication-bias
prior distributions, see \code{\link{publication_bias_prior_specification}}.
}
}
\references{
\insertAllCited{}
}
\seealso{
\code{\link{publication_bias_prior_specification}},
\code{\link[BayesTools]{prior}}, \code{\link{RoBMA.options}},
\code{\link{brma}}
}
