% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/methods.R
\name{generate_posterior}
\alias{generate_posterior}
\title{Generate Posterior Samples from a Fitted lgspline}
\usage{
generate_posterior(
  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,
  draw_correlation = FALSE,
  correlation_param_mean = NULL,
  correlation_param_vcov = NULL,
  correlation_VhalfInv_fxn = NULL,
  correlation_Vhalf_fxn = NULL,
  correlation_param_vcov_scale = NULL,
  include_warnings = TRUE,
  ...
)
}
\arguments{
\item{object}{A fitted \code{lgspline} model object.}

\item{new_sigmasq_tilde}{Numeric; dispersion \eqn{\tilde{\sigma}^2} used
as the point estimate when \code{draw_dispersion = FALSE}.
Default \code{object$sigmasq_tilde}.}

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

\item{theta_1}{Numeric; shape increment for the inverse-gamma prior on
\eqn{\sigma^2}. 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. Must accept \code{N}, \code{mean},
\code{sqrt_dispersion}, \code{...}. Default \code{rnorm}.}

\item{draw_dispersion}{Logical; sample \eqn{\sigma^2} from its posterior.
Default TRUE.}

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

\item{num_draws}{Positive integer; number of draws. Default 1.}

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

\item{draw_correlation}{Logical; propagate correlation parameter
uncertainty. Requires \code{VhalfInv_fxn} and
\code{VhalfInv_params_estimates} in the fitted object.
Default FALSE.}

\item{correlation_param_mean}{Numeric vector; mean of the approximate
normal posterior for correlation parameters on the unbounded
(working) scale. Default: \code{object$VhalfInv_params_estimates}.}

\item{correlation_param_vcov}{Matrix; variance-covariance for correlation
parameter draws. Default: inverse Hessian from BFGS
(\code{object$VhalfInv_params_vcov}).}

\item{correlation_VhalfInv_fxn}{Function; maps correlation 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}}. Passed through to
\code{\link{generate_posterior_correlation}}; the current correlation-aware posterior path only requires \code{correlation_VhalfInv_fxn}.}

\item{correlation_param_vcov_scale}{NULL or numeric; if supplied,
divides a user-supplied \code{correlation_param_vcov} by this
value before passing it to
\code{\link{generate_posterior_correlation}}. When NULL,
no additional scaling is applied.}

\item{include_warnings}{Logical; emit warnings for degenerate draws,
constraint violations, etc. 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 (or fixed) 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 (only when \code{draw_correlation = TRUE}).}
}
When \code{num_draws > 1}, each element becomes a list of length
\code{num_draws}, and \code{post_pred_draw} (if requested) is an
\eqn{N_{\mathrm{new}} \times M} matrix, where \eqn{M = \mathrm{num\_draws}}.
}
\description{
Draws from the posterior distribution of model coefficients, with optional
dispersion sampling, posterior predictive draws, and propagation of
uncertainty in estimated correlation parameters.
}
\details{
Uses a Laplace approximation centred at the MAP estimate for non-Gaussian
responses.


\strong{Dispersion posterior.}
When \code{draw_dispersion = TRUE}, \eqn{\sigma^2} is drawn from
\deqn{
  \sigma^2 \mid \mathbf{y} \sim
  \mathrm{InvGamma}(\alpha_1, \alpha_2),
}
where
\deqn{
  \alpha_1 = \theta_1 + \tfrac{1}{2}(N - s \cdot \mathrm{tr}(\mathbf{H})),
  \quad
  \alpha_2 = \theta_2 + \tfrac{1}{2}(N - s \cdot \mathrm{tr}(\mathbf{H}))
             \tilde{\sigma}^2,
}
\eqn{\mathbf{H} = \mathbf{XUGX}^\top} is the hat matrix, \eqn{s = 1}
when \code{unbias_dispersion = TRUE} (else \eqn{s = 0}), and
\eqn{\theta_1 = \theta_2 = 0} recovers an improper uniform prior.

\strong{Correlation parameter posterior.}
When \code{draw_correlation = TRUE} and the fitted model contains an
estimated correlation structure, each draw first samples
\eqn{\boldsymbol{\rho}} from
\deqn{
  \boldsymbol{\rho}^{(m)} \sim
  \mathcal{N}(\hat{\boldsymbol{\rho}}_{\mathrm{REML}},
              \mathbf{H}^{-1}_{\mathrm{BFGS}}),
}
rebuilds the posterior covariance under the drawn correlation
structure (reusing all pre-computed design matrices, constraints, and
penalty matrices) and then draws coefficients from the updated
posterior. Knot placement, partitioning, coefficient re-estimation,
and GCV tuning are skipped entirely.
Draws producing non-positive-definite correlation matrices are
rejected and redrawn (up to 50 attempts).

When \code{draw_correlation = FALSE} (default), correlation parameters
are fixed at their estimated values.

\strong{Inequality constraints.}
Active QP inequalities can be enforced during posterior sampling via
elliptical slice sampling, producing draws from the corresponding
truncated multivariate normal posterior on the coefficient scale.
The public \code{enforce_qp_constraints} argument is forwarded to the
stored sampler for both the standard and correlation-aware posterior
paths.
}
\examples{

\donttest{
set.seed(1234)
n_blocks <- 100; block_size <- 5; N <- n_blocks * block_size
rho_true <- 0.3
t <- seq(-5, 5, length.out = N)
true_mean <- sin(t)
errors <- Reduce("rbind",
  lapply(1:n_blocks, function(i) {
    sigma <- diag(block_size) + rho_true *
      (matrix(1, block_size, block_size) - diag(block_size))
    matsqrt(sigma) \%*\% rnorm(block_size)
  })
)
y <- true_mean + errors * 0.5

model_fit <- lgspline(t, y,
  K = 3,
  correlation_id = rep(1:n_blocks, each = block_size),
  correlation_structure = "exchangeable",
  include_warnings = FALSE
)

## Propagate correlation uncertainty across 50 draws
post <- generate_posterior(model_fit,
  draw_correlation = TRUE, num_draws = 50,
  include_warnings = FALSE
)

## Fixed correlation parameters for comparison
post_fixed <- generate_posterior(model_fit, num_draws = 50)

corr_draws <- unlist(post$post_draw_correlation_params)
rho_draws <- exp(-exp(corr_draws))
print(summary(rho_draws))
}

}
\seealso{
\code{\link{lgspline}},
\code{\link{generate_posterior_correlation}},
\code{\link{wald_univariate}}
}
