% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/methods.R
\name{generate_posterior_correlation}
\alias{generate_posterior_correlation}
\title{Generate Posterior Samples Propagating Correlation Parameter Uncertainty}
\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{
\item{object}{A fitted \code{lgspline} object with a correlation structure
(i.e., \code{VhalfInv_fxn} and \code{VhalfInv_params_estimates}
present, or supplied via override arguments).}

\item{new_sigmasq_tilde}{Numeric; dispersion starting value when
\code{draw_dispersion = FALSE}. Default \code{object$sigmasq_tilde}.}

\item{new_predictors}{Matrix or NULL; predictor matrix for posterior
predictive sampling. Default uses in-sample predictors.}

\item{theta_1}{Numeric; shape increment for the inverse-gamma prior.
Default 0.}

\item{theta_2}{Numeric; rate increment for the inverse-gamma prior.
Default 0.}

\item{posterior_predictive_draw}{Function; sampler for posterior predictive
realisations. Default \code{rnorm}.}

\item{draw_dispersion}{Logical; sample \eqn{\sigma^2} within each
draw. Default TRUE.}

\item{include_posterior_predictive}{Logical; generate posterior predictive
draws. Default FALSE.}

\item{num_draws}{Positive integer; number of draws (each requires one
correlation parameter sample and one covariance rebuild).
Default 1.}

\item{enforce_qp_constraints}{Logical; if TRUE, enforce active QP
inequality constraints during each coefficient draw via the
stored elliptical-slice constrained sampler. Default TRUE.}

\item{correlation_param_mean}{Numeric vector or NULL; mean of the
approximate normal posterior on the working scale. Default:
\code{object$VhalfInv_params_estimates}. Supplying this allows
correlation draws for models fit with a fixed (non-optimised)
correlation structure.}

\item{correlation_param_vcov_sc}{Matrix or NULL; variance-covariance
on the working scale. Default:
\code{object$VhalfInv_params_vcov}. No further scaling is
applied within this function.}

\item{correlation_VhalfInv_fxn}{Function or NULL; maps parameter vector
to \eqn{\mathbf{V}^{-1/2}}. Default \code{object$VhalfInv_fxn}.}

\item{correlation_Vhalf_fxn}{Function or NULL; maps to
\eqn{\mathbf{V}^{1/2}}. Not consumed in the current method body
but resolved for interface consistency and potential future use.}

\item{include_warnings}{Logical; emit warnings. Default TRUE.}

\item{...}{Additional arguments forwarded to the GLM weight function,
dispersion function, and \code{posterior_predictive_draw}.}
}
\value{
When \code{num_draws = 1}, a named list:
\describe{
  \item{post_draw_coefficients}{List of length K+1; per-partition
        coefficient vectors on the original scale.}
  \item{post_draw_sigmasq}{Drawn dispersion.}
  \item{post_pred_draw}{Posterior predictive vector (only when
        \code{include_posterior_predictive = TRUE}).}
  \item{post_draw_correlation_params}{Drawn correlation parameters
        on the working scale.}
}
When \code{num_draws > 1}:
\describe{
  \item{post_draw_coefficients}{List of \code{num_draws} lists of K+1
        coefficient vectors.}
  \item{post_draw_sigmasq}{List of \code{num_draws} scalars.}
  \item{post_pred_draw}{\eqn{N_{\mathrm{new}} \times M} matrix, where
        \eqn{M = \mathrm{num\_draws}} (only when
        \code{include_posterior_predictive = TRUE}).}
  \item{post_draw_correlation_params}{List of \code{num_draws} vectors.}
}
}
\description{
Called internally by \code{\link{generate_posterior}} when
\code{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.
}
\details{
Each draw proceeds in three steps:
\enumerate{
  \item \strong{Draw correlation parameters.}
    \eqn{\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.

  \item \strong{Rebuild posterior covariance.}
    Using the already-expanded \eqn{\mathbf{X}_k}, \eqn{\mathbf{A}}, and
    \eqn{\boldsymbol{\Lambda}} from the original fit, recompute only the
    covariance-side quantities implied by the drawn correlation structure:
    \deqn{
      \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
    \eqn{\mathbf{U}^{(m)}} and effective degrees of freedom
    \eqn{\mathrm{trace}(\mathbf{H}^{(m)})}.

    The coefficient mode \eqn{\hat{\boldsymbol{\beta}}_{\mathrm{raw}}}
    and fitted mean \eqn{\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.

  \item \strong{Draw coefficients.}
    Updated quantities (\code{U}, \code{Ghalf_correct}, \code{VhalfInv},
    \code{sigmasq_tilde}, \code{trace_XUGX}) are passed to the stored
    closure via \code{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 \code{object$B_raw} is passed
    as \code{override_B_raw} so it is not recomputed.
}

\strong{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.

\strong{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
\code{object$VhalfInv_params_vcov} before relying on these draws.
}
\examples{
## See ?generate_posterior for a complete worked example.

}
\seealso{
\code{\link{generate_posterior}},
\code{\link{lgspline}},
\code{\link{lgspline.fit}}
}
