% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/priors.R
\name{prior_normal}
\alias{prior_normal}
\title{Specify a normal prior}
\usage{
prior_normal(mean = 0, sd = 10, autoscale = FALSE)
}
\arguments{
\item{mean}{Prior mean (default 0).}

\item{sd}{Prior standard deviation (default 10). The default matches
the historical "very weak" scale; explicit tighter values are
recommended for regression coefficients (see Details).}

\item{autoscale}{If \code{TRUE} and this prior is passed as \code{prior_beta},
the scale is divided by each covariate's empirical SD so the prior
is weakly-informative regardless of predictor scaling. Default
\code{FALSE} to preserve backward-compatible behavior; set to \code{TRUE}
explicitly when passing unstandardized predictors. Ignored for
\code{prior_intercept} and \code{prior_sigma}.}
}
\value{
A list with components \code{distribution}, \code{mean}, \code{sd}, \code{df},
\code{autoscale}.
}
\description{
Construct a normal prior for passing to \code{\link[=mlumr]{mlumr()}} via \code{prior_intercept},
\code{prior_beta}, or \code{prior_sigma}. The resulting list is consumed by the
Stan models.
}
\section{Choosing a scale}{


The Stan community's prior-choice wiki (Vehtari et al., 2025) describes
five broad categories, from least to most informative:

\enumerate{
\item Flat prior — not recommended.
\item Super-vague proper prior, e.g., \code{normal(0, 1e6)} — not
recommended.
\item Weakly informative, \strong{very weak}, e.g., \code{normal(0, 10)}.
\item Generic weakly informative, e.g., \code{normal(0, 1)}.
\item Specific informative, e.g., \code{normal(0.4, 0.2)}.
}

Those scales assume parameters are on roughly unit scale. In ML-UMR
models the natural scales are:

\describe{
\item{Treatment intercepts}{On the linear-predictor (link) scale. For
a binary outcome with logit link, the intercept is a baseline log
odds; \code{normal(0, 10)} spans ±20 log-odds at 95 percent and is
"very weak". It is the default because the data usually constrain
the intercept strongly. Tightening to \code{normal(0, 5)} is reasonable
when the expected event rate is far from the extremes.}
\item{Regression coefficients (\code{beta})}{On the link scale, per unit
of covariate. For logistic regression with predictors on unit
scale, Gelman et al. (2008) and the Stan wiki recommend
\code{student_t(df, 0, 2.5)} with \code{df} in \code{3:7}, or — as a practical
approximation — \code{normal(0, 2.5)}. That is the default used by
\code{\link[=mlumr]{mlumr()}}. Use \code{normal(0, 1)} if you expect small effects (e.g.,
standardized predictors in a normal-outcome model). If predictors
are on very different scales, set \code{autoscale = TRUE} so the scale
is divided by each covariate's SD.}
\item{Residual SD (\code{sigma}, normal family only)}{\code{prior_sigma} is
interpreted as a half-normal via the Stan \verb{<lower=0>} constraint.
The default \code{normal(0, 2.5)} (i.e., \code{half-normal(0, 2.5)}) is
weakly informative for residual SDs on the scale of the outcome.
Scale to the outcome if it is far from unit scale, or use
\code{\link[=prior_exponential]{prior_exponential()}}.}
}

Prior sensitivity is especially important for the relaxed model,
where \code{beta_comparator} is identified only by the AgD likelihood.
Run \code{\link[=prior_sensitivity]{prior_sensitivity()}} to quantify how much conclusions move under
alternative scales; see \code{vignette("mlumr-models")}.
}

\examples{
# Default weakly-very-weak intercept prior
prior_normal(mean = 0, sd = 10)

# Gelman 2008 default for logistic-regression coefficients
prior_normal(mean = 0, sd = 2.5)

# Autoscaled coefficient prior (dividing 2.5 by each covariate's SD)
prior_normal(mean = 0, sd = 2.5, autoscale = TRUE)
}
\references{
Gelman, A., Jakulin, A., Pittau, M. G., & Su, Y.-S. (2008). A weakly
informative default prior distribution for logistic and other
regression models. \emph{Annals of Applied Statistics}, 2(4), 1360–1383.

Vehtari, A. et al. Prior Choice Recommendations (Stan wiki):
\url{https://github.com/stan-dev/stan/wiki/Prior-Choice-Recommendations}.
}
