% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/input-priors.R
\name{RoBMA_prior_specification}
\alias{RoBMA_prior_specification}
\title{Prior specification for model-averaging}
\arguments{
\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_bias}{prior distribution(s) for alternative publication-bias
component(s), such as weight functions, PET, or PEESE.

Alternative prior arguments can be:
\itemize{
\item A single prior distribution object (creates a mixture with one alternative)
\item A list of prior distributions (creates a mixture with multiple alternatives)
\item \code{NULL} or \code{FALSE} (omits the alternative hypothesis component)
}
See \code{\link{publication_bias_prior_specification}} for details on
specifying publication-bias priors and \code{\link{prior_specification}} for
details on specifying meta-analytic parameter priors.}

\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{prior_bias_null}{prior distribution(s) for null publication-bias
component(s), usually \code{prior_none()}. See
\code{\link{publication_bias_prior_specification}}.

Null prior arguments can be:
\itemize{
\item A single prior distribution object (creates a mixture with one null)
\item A list of prior distributions (creates a mixture with multiple nulls)
\item \code{NULL} or \code{FALSE} (omits the null hypothesis component)
}
Defaults to a point mass (spike) at zero for effect and heterogeneity parameters.}

\item{model_type}{character string specifying predefined publication-bias model
ensembles. One of:
\itemize{
\item \code{"PSMA"} (default): Full RoBMA-PSMA ensemble with 6 weight functions + PET + PEESE
\item \code{"6w"}: Six weight function models
\item \code{"2w"}: Two weight function models
\item \code{"PP"}: PET-PEESE models only
}
Custom \code{prior_bias} replaces the preset alternative bias components. If
\code{prior_bias} is omitted, \code{model_type} determines the default alternatives even
when \code{prior_bias_null} is customized or omitted.}
}
\description{
The \code{\link{RoBMA}} function extends the prior specification described in
\code{\link{prior_specification}} by allowing mixture priors that define competing
hypotheses for Bayesian model-averaging. This enables multimodel inference via the
product space method \insertCite{carlin1995bayesian,lodewyckx2011tutorial}{RoBMA},
where a single MCMC chain explores a joint model space containing all competing models.
}
\details{
\subsection{The product space method for model-averaging}{

RoBMA implements Bayesian model-averaging using the product space method
\insertCite{carlin1995bayesian,lodewyckx2011tutorial}{RoBMA}. Rather than fitting
each model separately and combining results after the fitting is complete,
this approach embeds all competing models within a single joint model space.
A discrete model indicator variable selects which model component is "active"
at each MCMC iteration, and the posterior probability of each model is estimated
from the proportion of iterations spent in that model's subspace.

This is achieved by specifying \strong{mixture priors} that combine:
\itemize{
\item \strong{Null hypothesis component(s)}: Typically point masses (spikes) representing
the absence of an effect, heterogeneity, or publication bias
\item \strong{Alternative hypothesis component(s)}: Continuous distributions representing
the presence of the parameter
}

The mixture structure enables direct computation of:
\itemize{
\item \strong{Inclusion Bayes factors}: Evidence for the presence vs. absence of each
parameter (e.g., effect, heterogeneity, bias)
\item \strong{Model-averaged estimates}: Posterior estimates that account for model
uncertainty by weighting across all models
\item \strong{Conditional estimates}: Posterior estimates given that a particular
hypothesis is true
}
}

\subsection{Default mixture prior structure}{

By default, \code{\link{RoBMA}} creates the following mixture priors:

\tabular{lll}{
\strong{Parameter}      \tab \strong{Null component}         \tab \strong{Alternative component}   \cr
Effect (\eqn{\mu})        \tab Spike(0)                   \tab Normal(0, UISD-scaled)      \cr
Heterogeneity (\eqn{\tau}) \tab Spike(0)                   \tab Normal+(0, UISD-scaled)     \cr
Publication bias   \tab No bias (prior_none)       \tab Weight functions + PET + PEESE \cr
Allocation (\eqn{\rho})   \tab (none by default)          \tab Beta(1, 1)
}

See \code{\link{prior_specification}} for details on how the UISD scaling is determined.
}

\subsection{Specifying custom mixture priors}{
\subsection{Single prior vs. list of priors}{

Each \verb{prior_*} and \verb{prior_*_null} argument accepts either a single prior or a list:
\itemize{
\item \strong{Single prior}: Creates one component in the mixture
\item \strong{List of priors}: Creates multiple components, enabling model-averaging
across different prior specifications (e.g., different effect size scales)
}

When multiple priors are specified in a list, they are all treated as alternative
(or null) hypothesis components for the main inclusion Bayes factor. The inclusion
Bayes factor tests the combined evidence for all alternative components against all
null components. The detailed summary output shows posterior probabilities and
inclusion Bayes factors for each individual component separately, allowing finer-grained
inference about which specific prior specification is most supported by the data.
}

\subsection{Omitting hypothesis components}{

For top-level mixture components, setting a prior argument to \code{NULL} or \code{FALSE}
removes that hypothesis component:
\itemize{
\item \code{prior_effect_null = NULL}: No null hypothesis for effect (assumes effect exists)
\item \code{prior_effect = NULL}: No alternative hypothesis (assumes no effect)
\item \code{prior_bias_null = NULL} or \code{FALSE}: No "no bias" model (assumes some bias mechanism)
\item \code{prior_bias = NULL} or \code{FALSE}: No bias model (assumes no bias mechanism)
}
For moderator and scale regression terms, an omitted or whole-argument \code{NULL}
\code{prior_mods} / \code{prior_scale} means "use defaults". To omit a component for a
specific term, use a named list entry such as \code{prior_mods_null = list(x1 = NULL)}.
}

\subsection{Parameter-specific customization for moderators}{

For moderator priors (\code{prior_mods}, \code{prior_mods_null}), you can specify different
priors for different predictors using named lists. A single prior object applies
to all moderator terms:
\preformatted{
RoBMA(...,
  mods = ~ x1 + x2,
  prior_mods_null = list(x1 = NULL)  # No null for x1, default null for x2
)
}
This allows testing whether specific moderators have effects while assuming others
are always included or excluded.
}

}

\subsection{Mixture priors for different parameter types}{
\subsection{Effect size (\eqn{\mu}) and heterogeneity (\eqn{\tau})}{

Effect and heterogeneity priors combine spike-and-slab components:
\preformatted{
# Default: spike(0) null + normal alternative
# Custom: multiple alternatives with different scales
RoBMA(...,
  prior_effect = list(
    prior("normal", list(mean = 0, sd = 0.5)),
    prior("normal", list(mean = 0, sd = 1.0))
  )
)
}
}

\subsection{Publication bias}{

Bias priors combine different publication bias adjustment mechanisms:
\itemize{
\item No publication bias (null hypothesis)
\item Weight functions: Selection models with different step functions
\item PET/PEESE: Regression-based bias adjustment
}

The \code{model_type} argument provides convenient presets:
\preformatted{
RoBMA(..., model_type = "PSMA")  # Full ensemble (default)
RoBMA(..., model_type = "PP")    # Only PET-PEESE models
}
See \code{\link{publication_bias_prior_specification}} for the bias-prior
constructors and preset model spaces.
}

\subsection{Heterogeneity allocation (\eqn{\rho}) for multilevel models}{

When \code{cluster} is specified, \eqn{\rho} controls the cluster-level variance
allocation. The decomposition is
\eqn{\tau_{between} = \tau\sqrt{\rho}} and
\eqn{\tau_{within} = \tau\sqrt{1 - \rho}}. By default, only an alternative
(Beta(1,1)) is specified, but null hypotheses can be added:
\preformatted{
RoBMA(...,
  cluster = study,
  prior_heterogeneity_allocation_null = prior("spike", list(location = 0.5))
)
}
}

\subsection{Moderator and scale regression terms}{

When \code{mods} is specified, the effect prior becomes the intercept prior, and each
moderator receives a mixture prior. The \strong{intercept} inherits the effect mixture
structure, while \strong{regression coefficients} get separate spike-and-slab mixtures.

Similarly, when \code{scale = ~ ...} is specified for location-scale models, the
heterogeneity prior becomes the scale intercept prior, and each scale predictor
receives a mixture prior following the same pattern as moderator terms.
Note that the scale intercept (i.e., baseline heterogeneity) is always positive and
the multiplicative scale coefficients require non-zero prior distribution on the
intercept.
}

}

\subsection{Model weights and prior odds}{

Each component in a mixture prior has an associated prior weight (prior model
probability). User-specified components receive equal weights unless their
prior objects set \code{prior_weights}. Publication-bias presets use fixed weights:
\code{"2w"} and \code{"6w"} split the alternative bias mass equally across their
weight functions, \code{"PP"} splits it equally across PET and PEESE, and \code{"PSMA"}
assigns half of the alternative bias mass to the six weight functions
combined and one quarter each to PET and PEESE. Custom weights can be
specified via the \code{prior_weights} argument in individual prior objects.

The prior odds between null and alternative hypotheses affect the Bayes factor
interpretation. With equal prior weights on null and alternative, the posterior
odds equal the Bayes factor.
}
}
\examples{
\dontrun{
if (requireNamespace("metadat", quietly = TRUE)) {
  data(dat.lehmann2018, package = "metadat")

  # Default mixture priors (spike-and-slab for effect and heterogeneity)
  fit1 <- RoBMA(
    yi      = yi,
    vi      = vi,
    data    = dat.lehmann2018,
    measure = "SMD",
    seed    = 1,
    silent  = TRUE
  )

  # Custom alternative priors (two effect size scales)
  fit2 <- RoBMA(
    yi           = yi,
    vi           = vi,
    data         = dat.lehmann2018,
    measure      = "SMD",
    prior_effect = list(
      prior("normal", list(mean = 0, sd = 0.35)),
      prior("normal", list(mean = 0, sd = 0.70))
    ),
    seed         = 1,
    silent       = TRUE
  )

  # No null hypothesis for effect (assume effect exists)
  fit3 <- RoBMA(
    yi                = yi,
    vi                = vi,
    data              = dat.lehmann2018,
    measure           = "SMD",
    prior_effect_null = NULL,
    seed              = 1,
    silent            = TRUE
  )

  # Only selection model bias adjustment (no PET-PEESE)
  fit4 <- RoBMA(
    yi         = yi,
    vi         = vi,
    data       = dat.lehmann2018,
    measure    = "SMD",
    model_type = "6w",
    seed       = 1,
    silent     = TRUE
  )

  # Meta-regression with different null specifications per moderator
  fit5 <- RoBMA(
    yi              = yi,
    vi              = vi,
    mods            = ~ Preregistered,
    data            = dat.lehmann2018,
    measure         = "SMD",
    prior_mods_null = list(Preregistered = NULL),
    seed            = 1,
    silent          = TRUE
  )
}
}

}
\references{
\insertAllCited{}
}
\seealso{
\code{\link{prior_specification}} for base prior specification options,
\code{\link{publication_bias_prior_specification}} for publication-bias priors,
\code{\link{RoBMA}} for the main model-averaging function,
\code{\link[BayesTools]{prior}} for creating prior distribution objects
}
