Prior specifications for fixed effects and random-effect SDs

Specify independent normal priors or ridge penalties on fixed-effect coefficients. Coefficient names refer to the final design matrix, so their meaning depends on contrasts and predictor units. No automatic scaling is applied. For coef = "all", state whether the intercept is included.

Usage

drm_priors(...)

drm_prior_sd_gamma(dpar = "mu", group, coef = "(Intercept)", shape, rate)

drm_prior_normal(dpar, coef, mean = 0, sd, intercept = NULL)

drm_prior_ridge(dpar, coef, lambda, intercept = NULL)

Arguments

...

Prior specifications returned by drm_prior_normal(), drm_prior_ridge(), or drm_prior_sd_gamma().

dpar

For fixed-effect priors, "mu" or "sigma". The SD prior currently supports "mu" only.

group

Exact random-effect grouping variable name.

coef

For fixed-effect priors, one exact design-matrix column name or "all". The SD prior currently supports "(Intercept)" only.

shape

Gamma shape, finite and greater than one.

rate

Gamma rate, positive and finite.

mean

Normal prior mean, a finite scalar.

sd

Normal prior standard deviation, a positive finite scalar.

intercept

For coef = "all", either "include" or "exclude".

lambda

Nonnegative finite ridge precision. The penalty is 0.5 * lambda * sum(beta^2); zero contributes no penalty.

Value

drm_priors() returns a collection of prior specifications; the other constructors return one specification.

Details

Gaussian identity models may include one independent random intercept in the mean. drm_prior_sd_gamma() targets its named group standard deviation on the natural SD scale, with density relative to SD and no log-scale Jacobian. Shape must exceed one and rate must be positive. It may be combined with fixed-effect priors. The objective is the marginal data negative log-likelihood plus the prior or penalty. A normal prior includes its density constant, whereas a ridge penalty has no normalizing constant. logLik() reports the data likelihood at the penalized estimates. Confidence intervals and information criteria are not provided for active prior fits; local penalized-Hessian curvature is not a calibrated confidence interval. The Julia bridge currently refuses factor predictors in Gaussian mean formulas with ordinary random effects; the native TMB route supports them.

Examples

drm_priors(drm_prior_normal("mu", "x", sd = 2))
#> [[1]]
#> $dpar
#> [1] "mu"
#> 
#> $coef
#> [1] "x"
#> 
#> $intercept
#> NULL
#> 
#> $kind
#> [1] "normal"
#> 
#> $mean
#> [1] 0
#> 
#> $sd
#> [1] 2
#> 
#> $precision
#> [1] 0.25
#> 
#> attr(,"class")
#> [1] "drm_fixed_prior"
#> 
#> attr(,"class")
#> [1] "drm_priors"
drm_priors(drm_prior_sd_gamma(group = "site", shape = 2, rate = 3))
#> [[1]]
#> $dpar
#> [1] "mu"
#> 
#> $group
#> [1] "site"
#> 
#> $coef
#> [1] "(Intercept)"
#> 
#> $shape
#> [1] 2
#> 
#> $rate
#> [1] 3
#> 
#> attr(,"class")
#> [1] "drm_sd_prior"
#> 
#> attr(,"class")
#> [1] "drm_priors"
# \donttest{
d <- data.frame(x = rep(c(-1, 0, 1), 6), group = factor(rep(1:6, each = 3)))
d$y <- 0.5 + 0.6 * d$x + rep(c(-0.5, 0.2, 0.7, -0.3, 0.4, -0.4), each = 3) +
  rep(c(0.1, -0.2, 0.1), 6)
p <- drm_priors(drm_prior_normal("mu", "x", mean = 0.2, sd = 0.8))
fit <- drmTMB(bf(y ~ x + (1 | group), sigma ~ 1), data = d, priors = p)
coef(fit, dpar = "mu")
#> (Intercept)           x 
#>   0.5166667   0.5984435 
logLik(fit)  # data likelihood at the penalized estimates
#> 'log Lik.' -2.940245 (df=4)
sd_prior <- drm_priors(drm_prior_sd_gamma(group = "group", shape = 2, rate = 3))
formula <- bf(mu = y ~ x + (1 | group), sigma = ~ 1)
drm_resolve_priors(formula, gaussian(), d, sd_prior)  # inspect the target
#>      class dpar group       block coefficient scale shape rate
#> 1 sd_gamma   mu group (1 | group) (Intercept)    SD     2    3
sd_fit <- drmTMB(formula, data = d, priors = sd_prior)
logLik(sd_fit)  # data likelihood at the penalized estimates
#> 'log Lik.' -2.943036 (df=4)
# }