% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/method-simulate.R
\name{simulate}
\alias{simulate}
\alias{simulate,INLAvaan-method}
\title{Simulate Datasets from the Generative Model}
\usage{
\S4method{simulate}{INLAvaan}(
  object,
  nsim = 1L,
  seed = NULL,
  sample.nobs = NULL,
  prior = FALSE,
  samp_copula = TRUE,
  silent = FALSE,
  ...
)
}
\arguments{
\item{object}{An object of class \link{INLAvaan}.}

\item{nsim}{Number of replicate datasets to generate (default 1).}

\item{seed}{Optional random seed (passed to \code{\link[=set.seed]{set.seed()}}).}

\item{sample.nobs}{Number of observations per dataset. Defaults to the
sample size of the original data.}

\item{prior}{Logical. When \code{TRUE}, parameters are drawn from the prior;
when \code{FALSE} (default), from the posterior.}

\item{samp_copula}{Logical. When \code{TRUE} (default) and \code{prior = FALSE},
posterior parameter draws use the copula method. Ignored when
\code{prior = TRUE}.}

\item{silent}{Logical. When \code{TRUE}, suppresses the informational message
about rejected non-PD draws. Default \code{FALSE}.}

\item{...}{Additional arguments (currently unused).}
}
\value{
A list of length \code{nsim}. Each element is a data frame with
\code{sample.nobs} rows and two attributes:
\itemize{
\item \code{"truth"} — named numeric vector of lavaan-side (x-space, constrained)
parameter values used to generate the dataset.
\item \code{"truth_theta"} — named numeric vector of the corresponding unconstrained
(theta-space) parameter values.
}
}
\description{
Generate complete synthetic datasets from a fitted INLAvaan model. For each
simulation, a single parameter vector is drawn (from the posterior or prior),
and then \code{sample.nobs} observations are generated from the model-implied
distribution at that parameter value.
}
\details{
This function is designed for tasks that require \strong{full replicate datasets}
from a single parameter draw, such as simulation-based calibration (SBC) and
posterior predictive p-values. It differs from \code{\link[=sampling]{sampling()}} which generates
one observation per parameter draw (useful for prior/posterior predictive
density overlays).

For each simulation \eqn{s = 1, \ldots, S}:
\enumerate{
\item Draw \eqn{\boldsymbol\theta^{(s)}} from the posterior (or prior).
\item Compute the model-implied covariance
\eqn{\boldsymbol\Sigma(\boldsymbol\theta^{(s)})}.
If it is not positive-definite, reject and redraw.
\item Generate a dataset of \code{sample.nobs} rows from
\eqn{N(\boldsymbol\mu(\boldsymbol\theta^{(s)}),\,
   \boldsymbol\Sigma(\boldsymbol\theta^{(s)}))}.
}

Parameter draws reuse the same internal machinery as \code{\link[=sampling]{sampling()}}
(\code{sample_params_prior} / \code{sample_params_posterior}), so the prior
specification is consistent.
}
\examples{
utils::data("HolzingerSwineford1939", package = "lavaan")
fit <- acfa("visual =~ x1 + x2 + x3", HolzingerSwineford1939)

# Simulate one replicate dataset from the posterior
sims <- simulate(fit, nsim = 1)
head(sims[[1]])                    # data frame
attr(sims[[1]], "truth")           # true lavaan-side (x-space) parameters
attr(sims[[1]], "truth_theta")     # corresponding unconstrained (theta-space) parameters

# Simulate from the prior (e.g., for SBC)
sims_prior <- simulate(fit, nsim = 5, prior = TRUE)
lapply(sims_prior, nrow)
}
\seealso{
\code{\link[=sampling]{sampling()}} for single-observation draws from the predictive
distribution (prior/posterior predictive checks).
}
