generate_posterior_correlation: Generate Posterior Samples Propagating Correlation Parameter...

In lgspline: Lagrangian Multiplier Smoothing Splines for Smooth Function Estimation

Generate Posterior Samples Propagating Correlation Parameter Uncertainty

Description

Called internally by generate_posterior when draw_correlation = TRUE, but can be used directly for finer control. For each draw, samples the correlation parameter vector from its approximate normal posterior, rebuilds the posterior covariance under that drawn correlation structure without re-solving for a new coefficient mode, then draws coefficients from the updated posterior.

Usage

generate_posterior_correlation(
  object,
  new_sigmasq_tilde = object$sigmasq_tilde,
  new_predictors = NULL,
  theta_1 = 0,
  theta_2 = 0,
  posterior_predictive_draw = function(N, mean, sqrt_dispersion, ...) {
     rnorm(N,
    mean, sqrt_dispersion)
 },
  draw_dispersion = TRUE,
  include_posterior_predictive = FALSE,
  num_draws = 1,
  enforce_qp_constraints = TRUE,
  correlation_param_mean = NULL,
  correlation_param_vcov_sc = NULL,
  correlation_VhalfInv_fxn = NULL,
  correlation_Vhalf_fxn = NULL,
  include_warnings = TRUE,
  ...
)

Arguments

object	A fitted lgspline object with a correlation structure (i.e., VhalfInv_fxn and VhalfInv_params_estimates present, or supplied via override arguments).
new_sigmasq_tilde	Numeric; dispersion starting value when draw_dispersion = FALSE. Default object$sigmasq_tilde.
new_predictors	Matrix or NULL; predictor matrix for posterior predictive sampling. Default uses in-sample predictors.
theta_1	Numeric; shape increment for the inverse-gamma prior. Default 0.
theta_2	Numeric; rate increment for the inverse-gamma prior. Default 0.
posterior_predictive_draw	Function; sampler for posterior predictive realisations. Default rnorm.
draw_dispersion	Logical; sample \sigma^2 within each draw. Default TRUE.
include_posterior_predictive	Logical; generate posterior predictive draws. Default FALSE.
num_draws	Positive integer; number of draws (each requires one correlation parameter sample and one covariance rebuild). Default 1.
enforce_qp_constraints	Logical; if TRUE, enforce active QP inequality constraints during each coefficient draw via the stored elliptical-slice constrained sampler. Default TRUE.
correlation_param_mean	Numeric vector or NULL; mean of the approximate normal posterior on the working scale. Default: object$VhalfInv_params_estimates. Supplying this allows correlation draws for models fit with a fixed (non-optimised) correlation structure.
correlation_param_vcov_sc	Matrix or NULL; variance-covariance on the working scale. Default: object$VhalfInv_params_vcov. No further scaling is applied within this function.
correlation_VhalfInv_fxn	Function or NULL; maps parameter vector to \mathbf{V}^{-1/2}. Default object$VhalfInv_fxn.
correlation_Vhalf_fxn	Function or NULL; maps to \mathbf{V}^{1/2}. Not consumed in the current method body but resolved for interface consistency and potential future use.
include_warnings	Logical; emit warnings. Default TRUE.
...	Additional arguments forwarded to the GLM weight function, dispersion function, and posterior_predictive_draw.

Details

Each draw proceeds in three steps:

1. Draw correlation parameters. \boldsymbol{\rho}^{(m)} \sim \mathcal{N}(\hat{\boldsymbol{\rho}}_{\mathrm{REML}}, \mathbf{H}^{-1}_{\mathrm{BFGS}}) on the unbounded working scale. Draws producing a non-PD correlation matrix are rejected and redrawn (up to 50 attempts); if all fail, the point estimate is used with a warning.

2. Rebuild posterior covariance. Using the already-expanded \mathbf{X}_k, \mathbf{A}, and \boldsymbol{\Lambda} from the original fit, recompute only the covariance-side quantities implied by the drawn correlation structure:

   \mathbf{G}_{\mathrm{correct}}^{(m)} = \left(\mathbf{X}^{\top} \mathbf{W}\mathbf{D} \mathbf{V}^{-1}(\boldsymbol{\rho}^{(m)}) \mathbf{X} + \boldsymbol{\Lambda}\right)^{-1},

   and from this the updated constraint projection \mathbf{U}^{(m)} and effective degrees of freedom \mathrm{trace}(\mathbf{H}^{(m)}).

   The coefficient mode \hat{\boldsymbol{\beta}}_{\mathrm{raw}} and fitted mean \tilde{\mathbf{y}} are held fixed at the original fit values. Knot placement, partitioning, polynomial expansion, penalty tuning, and coefficient re-estimation are all skipped entirely.

3. Draw coefficients. Updated quantities (U, Ghalf_correct, VhalfInv, sigmasq_tilde, trace_XUGX) are passed to the stored closure via override_* arguments so that the draw is centred at the original mode but uses the covariance implied by the drawn correlation structure. The stored mode object$B_raw is passed as override_B_raw so it is not recomputed.

Why the mode is held fixed. Re-solving for a new MAP estimate under each drawn correlation structure is expensive, requires iterative solvers, and risks convergence failures on draws far from the REML estimate. The posterior draw is centred at the original mode, which remains a reasonable approximation when the REML surface is not sharply peaked. The covariance update captures the primary effect of correlation uncertainty on posterior width and shape.

BFGS inverse Hessian caveat. The BFGS inverse Hessian approximation for the correlation parameter covariance is asymptotically valid but may be poor for small samples, near-boundary estimates, or multimodal REML surfaces. It is not guaranteed to converge to the observed information matrix. Users should inspect object$VhalfInv_params_vcov before relying on these draws.

Value

When num_draws = 1, a named list:

post_draw_coefficients

List of length K+1; per-partition coefficient vectors on the original scale.

post_draw_sigmasq

Drawn dispersion.

post_pred_draw

Posterior predictive vector (only when include_posterior_predictive = TRUE).

post_draw_correlation_params

Drawn correlation parameters on the working scale.

When num_draws > 1:

post_draw_coefficients

List of num_draws lists of K+1 coefficient vectors.

post_draw_sigmasq

List of num_draws scalars.

post_pred_draw

N_{\mathrm{new}} \times M matrix, where M = \mathrm{num\_draws} (only when include_posterior_predictive = TRUE).

post_draw_correlation_params

List of num_draws vectors.

See Also

generate_posterior, lgspline, lgspline.fit

Examples

## See ?generate_posterior for a complete worked example.

lgspline documentation built on May 8, 2026, 5:07 p.m.