Draw Samples from the Generative Model

Sample model parameters, latent variables, or observed variables from the generative model underlying a fitted INLAvaan model. By default, parameters are drawn from the posterior distribution; set prior = TRUE to draw from the prior instead (useful for prior predictive checks).

Usage

sampling(object, ...)

# S4 method for class 'INLAvaan'
sampling(
  object,
  type = c("lavaan", "theta", "latent", "observed", "implied", "all"),
  nsamp = 1000L,
  samp_copula = TRUE,
  prior = FALSE,
  silent = FALSE,
  ...
)

Arguments

object

An object of class INLAvaan (or inlavaan_internal).

...

Additional arguments (currently unused).

type

Character string specifying what to sample:

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

nsamp

Number of samples to draw.

samp_copula

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

prior

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

silent

Logical. When TRUE, suppresses the informational message about rejected non-PD draws during prior rejection sampling. Default FALSE.

Value

A matrix or named list, depending on type.

Details

Each row of the output corresponds to a fresh parameter draw: a new $\boldsymbol\theta^{(s)}$ is sampled and then propagated through the generative chain to produce one latent vector and one observed vector. This makes sampling() ideal for prior and posterior predictive checks (e.g., density overlays, test statistic distributions).

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

If you need complete replicate datasets (many observations from a single parameter draw) — for example, for simulation-based calibration (SBC) — use simulate() instead.

This is distinct from predict(), which computes individual-specific factor scores $\boldsymbol\eta \mid \mathbf{y},\boldsymbol\theta$ conditional on observed data.

Examples

utils::data("HolzingerSwineford1939", package = "lavaan")
fit <- acfa("visual =~ x1 + x2 + x3", HolzingerSwineford1939)
#> ℹ Finding posterior mode.
#> ✔ Finding posterior mode. [20ms]
#> 
#> ℹ Computing the Hessian.
#> ✔ Computing the Hessian. [22ms]
#> 
#> ℹ Performing VB correction.
#> ✔ VB correction; mean |δ| = 0.246σ. [53ms]
#> 
#> ⠙ Fitting 0/6 skew-normal marginals.
#> ⠹ Fitting 2/6 skew-normal marginals.
#> ✔ Fitting 6/6 skew-normal marginals. [76ms]
#> 
#> ℹ Adjusting copula correlations (NORTA).
#> ✔ Adjusting copula correlations (NORTA). [20ms]
#> 
#> ⠙ Posterior sampling and summarising.
#> ✔ Posterior sampling and summarising. [405ms]
#> 

# Posterior samples of lavaan-side parameters
samps <- sampling(fit, nsamp = 500)
head(samps)
#>      visual=~x2 visual=~x3    x1~~x1    x2~~x2    x3~~x3 visual~~visual
#> [1,]  0.7537805  0.8935477 0.7449751 1.0608426 0.7990191      0.5787902
#> [2,]  0.9422014  1.4805455 0.9188254 0.9455022 0.5311365      0.3138488
#> [3,]  0.8447581  1.0890487 0.8035399 1.0817900 0.6379797      0.5077081
#> [4,]  0.8089361  1.1685147 0.8635664 1.3605692 0.5690487      0.4243235
#> [5,]  0.7961315  1.1204401 0.8234872 1.1495866 0.6530604      0.5262784
#> [6,]  0.6701568  0.8722089 1.0238411 1.1570314 0.7509603      0.6064207

# 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)