compute_gaussian_prior: Compute Calibrated Gaussian Normal–Gamma Prior Components

In glmbayes: Bayesian Generalized Linear Models (IID Samples)

Compute Calibrated Gaussian Normal–Gamma Prior Components

Description

Internal Gaussian calibration routine used by Prior_Setup. Given weighted Gaussian regression inputs and a dispersion–independent coefficient–scale prior covariance \Sigma_0, this function computes all Normal–Gamma quantities required by the Gaussian prior families: dispersion, shape, shape_ING, rate, rate_gamma, and the calibrated coefficient–scale covariance Sigma. The input Sigma_0 is returned unchanged.

Usage

compute_gaussian_prior(
  X,
  Y,
  weights,
  offset,
  dispersion = NULL,
  n_effective,
  bhat,
  mu,
  Sigma_0,
  Sigma = NULL,
  n_prior,
  k = 1
)

Arguments

X	Numeric model matrix with nrow(X) == length(Y).
Y	Numeric response vector.
weights	Numeric vector of case weights.
offset	Numeric offset vector.
dispersion	Optional scalar dispersion. If supplied, overrides the calibrated value.
n_effective	Effective sample size (typically sum(weights)).
bhat	Numeric coefficient vector, usually the weighted least–squares estimate.
mu	Numeric prior mean vector.
Sigma_0	Dispersion–independent prior covariance matrix [p \times p].
Sigma	Optional coefficient–scale covariance matrix. If supplied, overrides the calibrated Sigma.
n_prior	Effective prior sample size.
k	Non–negative scalar with k + p \ge 2. Controls tail behavior of the variance prior; does not affect posterior means.

Details

The computation follows a structured pipeline:

1. Validate dimensions and numeric inputs.

2. Compute the weighted residual sum of squares at bhat.

3. Form the weighted Gram matrix X^\top W X, invert it, and construct the marginal quadratic term S_{marg}.

4. Map n_prior and k to the Normal–Gamma shape and rate.

5. Calibrate the implied dispersion and coefficient covariance.

6. Return all calibrated prior components.

The function assumes the Chapter 11 convention that \Sigma_0 is dispersion–free: it encodes prior structure on the precision–weighted coefficient scale. The returned Sigma is the corresponding coefficient–scale covariance after calibration.

A common choice is the Zellner–type form

\Sigma_0 = \frac{1 - \mathrm{pwt}}{\mathrm{pwt}} (X^\top W X)^{-1},

where \mathrm{pwt} is a scalar prior weight. More generally, Sigma_0 may be any positive–definite matrix.

The function computes:

• The marginal quadratic term

  S_{marg} = RSS_w + (\hat\beta - \mu)^\top \left(\Sigma_0 + (X^\top W X)^{-1}\right)^{-1} (\hat\beta - \mu).

• Prior Gamma shape: a_0 = (n_{\mathrm{prior}} + k)/2.

• Posterior Gamma shape: a_n = (n_{\mathrm{prior}} + n_w + k)/2, where n_w = n_{\mathrm{effective}}.

• Calibrated dispersion:

  E[\sigma^2 \mid y] = \frac{S_{marg}}{n_w - p},

  the usual weighted residual–df estimator.

• Prior Gamma rate:

  b_0 = \frac{1}{2} S_{marg} \frac{n_{\mathrm{prior}} + k + p - 2}{n_w - p},

  ensuring E[\sigma^2 \mid y] = S_{marg}/(n_w - p).

• Calibrated coefficient covariance:

  \Sigma = \frac{n_w}{n_{\mathrm{prior}}} E[\sigma^2 \mid y] (X^\top W X)^{-1}.

Limiting behavior.

• As n_{\mathrm{prior}} \to \infty, the prior becomes increasingly concentrated and dominates the likelihood.

• As n_{\mathrm{prior}} \to 0^+ with n_w > p, S_{marg} \to RSS_w and E[\sigma^2 \mid y] \to RSS_w/(n_w - p), matching the classical weighted Gaussian estimator.

• Strict positivity of the prior rate requires n_{\mathrm{prior}} + k + p > 2.

• The prior mean \mu is never altered; this function calibrates only scale parameters.

Value

A list with components:

• dispersion — calibrated Gaussian dispersion.

• shape — Gamma shape for residual precision.

• shape_ING — shape for the independent Normal–Gamma prior.

• rate — Gamma rate for residual precision.

• rate_gamma — Gamma rate for the fixed–\beta path (dGamma).

• Sigma — calibrated coefficient–scale covariance.

• Sigma_0 — the input dispersion–free covariance.

References

\insertAllCited

glmbayes documentation built on Aug. 5, 2026, 1:07 a.m.