Prior constructors for stLMM

Constructors for prior and fixed-parameter objects used by stLMM.

Usage

flat()

normal(mean = 0, sd = 1)

ig(shape, scale)

uniform(lower, upper)

log_normal(meanlog, sdlog, support = NULL)

gamma_dist(shape, rate, support = NULL)

half_normal(scale)

half_t(df, scale)

beta_dist(shape1, shape2)

fixed(value)

Arguments

mean, sd: Mean and standard deviation for independent normal fixed-effect priors created by normal(). Scalars are recycled across fixed effects; vectors must match the number of fixed effects.
shape, scale: For ig(), positive inverse-gamma shape and scale parameters. For half_normal(), positive standard-deviation scale.
lower, upper: Finite support limits for uniform().
meanlog, sdlog: Mean and standard deviation on the log scale for log_normal(); sdlog must be positive.
support: Optional finite support c(lower, upper). This is required when log_normal() or gamma_dist() is used for a covariance theta parameter.
rate: Positive gamma rate parameter.
df: Positive degrees of freedom for half_t().
shape1, shape2: Positive beta shape parameters.
value: Finite numeric scalar value at which a covariance or variance parameter should be fixed.

Details

Raw numeric vectors such as c(2, 1) are not accepted as priors. Use an explicit constructor so the prior family and parameter support are clear.

fixed(value) marks a covariance or variance parameter as fixed at value. It is used in starting, not priors. Internally this sets the starting value and sets the corresponding Metropolis tuning value to zero. Fixed parameters are omitted from Metropolis proposal blocks and do not require priors. Their values still define the likelihood and latent-process precision. If a fixed parameter also has an explicitly positive tuning value, stLMM() errors.

flat() and normal(mean, sd) are fixed-effect priors and are currently accepted only as priors = list(beta = ...). A flat beta prior is the improper prior used by earlier versions of the sampler. A normal beta prior is an independent Gaussian prior on the fixed-effect coefficients. The Gaussian likelihood defaults to flat(); Polya-Gamma likelihoods default to normal(mean = 0, sd = 10).

The _dist suffix is used only where the natural constructor name would conflict with an existing R function or a common model parameter name, as in gamma_dist() and beta_dist().

The inverse-gamma constructor uses the shape/scale parameterization $$ p(x \mid a, b) = \frac{b^a}{\Gamma(a)} x^{-(a+1)} \exp\{-b/x\}, \quad x > 0, $$ where shape = a and scale = b. Thus the second argument to ig() is a scale parameter for the inverse-gamma distribution, not a rate.

Other positive variance priors use the following parameterizations. The log_normal(meanlog, sdlog) prior is the usual log-normal density with meanlog and sdlog on $\log(x)$. The gamma_dist(shape, rate) prior uses the gamma shape/rate density $p(x) \propto x^{a-1}\exp\{-r x\}$. The half_normal(scale) and half_t(df, scale) priors are specified on the standard deviation $s = \sqrt{x}$ and transformed internally to the variance scale by the Jacobian $1/(2\sqrt{x})$. Up to normalizing constants, this gives $p(x) \propto x^{-1/2}\exp\{-x/(2A^2)\}$ for the half-normal and $p(x) \propto x^{-1/2}\{1 + x/(\nu A^2)\}^{-(\nu+1)/2}$ for the half-t.

beta_dist(shape1, shape2) uses the standard beta density $p(x) \propto x^{a-1}(1-x)^{b-1}$ on $0 < x < 1$.

Variance parameters, including tau_sq and process sigma_sq, are strictly positive. Sampled residual and process variances may use ig(), log_normal(), gamma_dist(), half_normal(), or half_t(). The half-normal and half-t priors are defined on the standard deviation scale and transformed internally to the variance scale. IID grouped random-effect variances currently use conjugate Gibbs updates and must use ig().

When resid(model = "group", group = group) is used, the grouped residual variance priors are supplied through priors$resid. A single prior can be recycled over groups, for example priors = list(resid = list(tau_sq = half_t(df = 3, scale = 1))). Alternatively, priors$resid may be a named list with one prior for each observed residual group.

Covariance theta parameters use a bounded-logit proposal transform. Therefore, all theta priors must have finite support. Positive theta parameters such as phi, lambda, nu, a, c, and Gneiting delta when free may use uniform(), log_normal(..., support = c(lower, upper)), or gamma_dist(..., support = c(lower, upper)). Unit-interval theta parameters such as mixture alpha and Gneiting alpha, beta, and gamma may use uniform() or beta_dist(). Bounded AR1 parameters currently use uniform().

For exponential covariance $\exp(-\phi h)$, the distance where correlation equals 0.05 is approximately $-\log(0.05) / \phi$. This is often a useful way to choose finite support for phi after coordinates have been scaled or projected into meaningful units. For binomial and other weak-information settings, spatial decay parameters can be weakly identified and may be sensitive to the chosen support, neighbor size, and coordinate scale; inspect trace plots and posterior mass near prior boundaries.

Value

Prior constructors return objects of class stLMM_prior describing the prior family, parameters, support, and scale used by stLMM. fixed() returns an object of class stLMM_fixed_parameter marking a covariance or variance parameter as fixed at the supplied numeric value.

Examples

priors <- list(
  beta = normal(mean = 0, sd = 10),
  resid = list(tau_sq = ig(2, 0.1)),
  nngp_1 = list(
    sigma_sq = half_t(df = 4, scale = 1),
    phi = log_normal(log(5), 0.75, support = c(0.5, 20)),
    nu = uniform(0.1, 2)
  )
)

starting <- list(
  resid = list(tau_sq = fixed(0.5)),
  nngp_1 = list(sigma_sq = fixed(1), phi = fixed(3))
)

Usage

Arguments

Details

Value

See also

Examples