% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/method-sampling.R
\name{sampling}
\alias{sampling}
\alias{sampling,INLAvaan-method}
\title{Draw Samples from the Generative Model}
\usage{
sampling(object, ...)

\S4method{sampling}{INLAvaan}(
  object,
  type = c("lavaan", "theta", "latent", "observed", "implied", "all"),
  nsamp = 1000L,
  samp_copula = TRUE,
  prior = FALSE,
  silent = FALSE,
  ...
)
}
\arguments{
\item{object}{An object of class \link{INLAvaan} (or \code{inlavaan_internal}).}

\item{...}{Additional arguments (currently unused).}

\item{type}{Character string specifying what to sample:
\describe{
\item{\code{"lavaan"}}{(Default) The lavaan-side (constrained) model
parameters. Returns an \code{nsamp} by \code{npar} matrix.}
\item{\code{"theta"}}{The INLAvaan-side unconstrained parameters.
Returns an \code{nsamp} by \code{npar} matrix.}
\item{\code{"latent"}}{Latent variables from the model-implied
distribution. Returns an \code{nsamp} by \code{nlv} matrix (one draw per
posterior sample, not tied to any individual).}
\item{\code{"observed"}}{Observed variables generated from the full
model. Returns an \code{nsamp} by \code{nobs_vars} matrix.}
\item{\code{"implied"}}{Model-implied moments. Returns a length-\code{nsamp}
list, each element a list with \code{cov} (model-implied covariance
matrix) and, when \code{meanstructure = TRUE}, \code{mean} (model-implied
mean vector). For multi-group models each element is itself a
list of groups.}
\item{\code{"all"}}{A named list with elements \code{lavaan}, \code{theta},
\code{latent}, \code{observed}, and \code{implied}.}
}}

\item{nsamp}{Number of samples to draw.}

\item{samp_copula}{Logical. When \code{TRUE} (default), posterior parameter
samples use the copula method with the fitted marginals. When \code{FALSE},
samples are drawn from the joint Gaussian (Laplace) approximation.
Ignored when \code{prior = TRUE}.}

\item{prior}{Logical. When \code{TRUE}, parameters are drawn from the prior
distribution and then propagated through the generative model. When
\code{FALSE} (default), parameters come from the posterior.}

\item{silent}{Logical. When \code{TRUE}, suppresses the informational message
about rejected non-PD draws during prior rejection sampling. Default
\code{FALSE}.}
}
\value{
A matrix or named list, depending on \code{type}.
}
\description{
Sample model parameters, latent variables, or observed variables from the
generative model underlying a fitted INLAvaan model. By default, parameters
are drawn from the \strong{posterior} distribution; set \code{prior = TRUE} to draw
from the \strong{prior} instead (useful for prior predictive checks).
}
\details{
Each row of the output corresponds to a \strong{fresh parameter draw}: a new
\eqn{\boldsymbol\theta^{(s)}} is sampled and then propagated through the
generative chain to produce one latent vector and one observed vector. This
makes \code{sampling()} ideal for \strong{prior and posterior predictive checks}
(e.g., density overlays, test statistic distributions).

The generative chain is:
\deqn{\boldsymbol\theta^{(s)} \sim \pi(\boldsymbol\theta \mid \mathbf{y})}
\deqn{\boldsymbol\eta^{(s)} \sim N((\mathbf{I} - \mathbf{B})^{-1}\boldsymbol\alpha,\,\boldsymbol\Phi)}
\deqn{\mathbf{y}^{*(s)} \sim N(\boldsymbol\Lambda\boldsymbol\eta^{(s)} + \boldsymbol\nu,\,\boldsymbol\Theta)}

If you need \strong{complete replicate datasets} (many observations from a single
parameter draw) — for example, for simulation-based calibration (SBC) — use
\code{\link[=simulate]{simulate()}} instead.

This is distinct from \code{\link[=predict]{predict()}}, which computes individual-specific
factor scores \eqn{\boldsymbol\eta \mid \mathbf{y},\boldsymbol\theta}
conditional on observed data.
}
\examples{
utils::data("HolzingerSwineford1939", package = "lavaan")
fit <- acfa("visual =~ x1 + x2 + x3", HolzingerSwineford1939)

# Posterior samples of lavaan-side parameters
samps <- sampling(fit, nsamp = 500)
head(samps)

# Compare copula vs Gaussian sampling
s_cop <- sampling(fit, nsamp = 500, samp_copula = TRUE)
s_gaus <- sampling(fit, nsamp = 500, samp_copula = FALSE)

# Prior predictive samples
y_prior <- sampling(fit, type = "observed", nsamp = 500, prior = TRUE)
}
\seealso{
\code{\link[=simulate]{simulate()}} for generating complete replicate datasets (e.g.,
for SBC); \code{\link[=predict]{predict()}} for individual-specific factor scores;
\code{\link[=bfit_indices]{bfit_indices()}} for Bayesian fit indices.
}
