Creates a prior distribution for factors

Source: R/priors.R

prior_factor creates a prior distribution for fitting models with factor predictors. (Note that results across different operating systems might vary due to differences in JAGS numerical precision.)

prior_factor(
  distribution,
  parameters,
  truncation = list(lower = -Inf, upper = Inf),
  prior_weights = 1,
  contrast = "meandif"
)

Arguments

distribution

name of the prior distribution. The possible options are

"point"

for a point density characterized by a location parameter.

"normal"

for a normal distribution characterized by a mean and sd parameters.

"lognormal"

for a lognormal distribution characterized by a meanlog and sdlog parameters.

"cauchy"

for a Cauchy distribution characterized by a location and scale parameters. Internally converted into a generalized t-distribution with df = 1.

"t"

for a generalized t-distribution characterized by a location, scale, and df parameters.

"gamma"

for a gamma distribution characterized by either shape and rate, or shape and scale parameters. The latter is internally converted to the shape and rate parametrization

"invgamma"

for an inverse-gamma distribution characterized by a shape and scale parameters. The JAGS part uses the BayesTools module distribution dbt_invgamma(shape, scale) on the natural parameter.

"beta"

for a beta distribution characterized by an alpha and beta parameters.

"exp"

for an exponential distribution characterized by either rate or scale parameter. The later is internally converted to rate.

"uniform"

for a uniform distribution defined on a range from a to b

"moment"

for a Johnson-Rossell moment prior characterized by exactly one of mode or tau, an optional order that defaults to 1, and an optional location that defaults to 0.

"invmoment"

for a Johnson-Rossell inverse-moment prior characterized by exactly one of mode or tau, a df, an optional order that defaults to 1, and an optional location that defaults to 0.

"dirichlet"

for a Dirichlet distribution over a simplex, whose finite nonnegative coordinates must have a finite total and roundoff bound and sum to one within that bound, characterized by a concentration vector alpha. Numeric entries must be finite and at least 0.01; this is a supported-input minimum, not a numerical guarantee. Positive expression-valued concentrations retain their existing JAGS-only support: expression containers, including literal elements, are not statically evaluated or validated, and R random generation refuses them. Cumulative weight functions and ordered allocations require numeric concentrations. Accepted sampling can still be unavailable; see prior_functions. Two-bin cumulative JAGS initialization near the minimum can repeatedly refuse unrepresentable interior ratios. Density and plot methods show one beta marginal per simplex coordinate.

parameters

list of appropriate parameters for a given distribution.

truncation

list with two elements, lower and upper, that define the lower and upper truncation of the distribution. Defaults to list(lower = -Inf, upper = Inf). The truncation is automatically set to the bounds of the support.

prior_weights

prior odds associated with a given distribution. The value is passed into the model fitting function, which creates models corresponding to all combinations of prior distributions for each of the model parameters and sets the model priors odds to the product of its prior distributions.

contrast

type of contrast for the prior distribution. The possible options are

"meandif"

for contrast centered around the grand mean with equal marginal distributions, making the prior distribution exchangeable across factor levels. In contrast to "orthonormal", the marginal distributions are identical regardless of the number of factor levels and the specified prior distribution corresponds to the difference from grand mean for each factor level. Only supports distribution = "mnormal" and distribution = "mt" which generates the corresponding multivariate normal/t distributions. The distribution must be centered exactly at zero.

"orthonormal"

for contrast centered around the grand mean with equal marginal distributions, making the prior distribution exchangeable across factor levels. Only supports distribution = "mnormal" and distribution = "mt" which generates the corresponding multivariate normal/t distributions. The distribution must be centered exactly at zero.

"treatment"

for contrasts using the first level as a comparison group and setting equal prior distribution on differences between the individual factor levels and the comparison level.

"independent"

for one independently regularized coefficient per factor level. With a free intercept, this coefficient design is likelihood-rank-deficient and its separation is prior-dependent. In a BayesTools formula with 0 + factor or factor - 1, the intercept is instead fixed structurally at zero, so the level coefficients are identified directly.

Value

return an object of class 'prior'.

Details

The factor prior owns the contrast family. BayesTools does not change that family merely because the formula includes or removes an intercept. In particular, ~ 0 + factor represents a point-zero intercept and the contrast selected here; it requests one coefficient per level only when contrast = "independent".

A formula interaction of two or more factors in which a factor is coded by a mean-difference or orthonormal contrast accepts only priors that do not depend on the basis of that contrast: mean-difference and orthonormal priors, and treatment or independent priors that are zero-mean untruncated normal or zero spike priors (priors symmetric about zero when every coded factor of the term has two levels). Other treatment and independent priors, and ordered priors, are refused (see the conditions of JAGS_formula()).

Examples

# create an orthonormal prior distribution
p1 <- prior_factor(distribution = "mnormal", contrast = "orthonormal",
                   parameters = list(mean = 0, sd = 1))