% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sim_lvm.R
\name{sim_lvm}
\alias{sim_lvm}
\title{Simulate data from a latent variable model}
\usage{
sim_lvm(
  N = 1000,
  mla = NULL,
  K = 3,
  J = 18,
  cpf = 0,
  lam = 0.7,
  lac = 0.3,
  phi = 0.3,
  ph12 = -1,
  phx = NULL,
  ecr = 0,
  P = 0,
  b = 0.3,
  K1 = 0,
  ph1 = 0.2,
  b1 = 0.3,
  phd = 0,
  ilvl = NULL,
  cati = NULL,
  noc = c(4),
  misp = 0,
  ome_out = FALSE,
  necw = K,
  necb = K,
  add_ind = c(),
  add_la = 0.5,
  add_phi = 0,
  zero_it = 0,
  rseed = 333,
  digits = 4
)
}
\arguments{
\item{N}{Sample size.}

\item{mla}{Population loading matrix. If supplied, \code{K}, \code{J} and \code{cpf} are
taken from it.}

\item{K}{Number of factors (used when \code{mla = NULL}). Must divide \code{J}.}

\item{J}{Number of items (used when \code{mla = NULL}).}

\item{cpf}{Number of cross-loadings per factor (used when \code{mla = NULL}).}

\item{lam}{Value of the primary loadings.}

\item{lac}{Value of the cross-loadings.}

\item{phi}{Homogeneous correlation between any two factors.}

\item{ph12}{Correlation between factors 1 and 2, when it differs from \code{phi};
\code{-1} (default) to use \code{phi}.}

\item{phx}{Correlation among the observed covariates. Defaults to \code{phi},
which is LAWBL's behaviour; set \code{phx = 0} for uncorrelated covariates.}

\item{ecr}{Residual correlation (local dependence).}

\item{P}{Number of observed predictors (MIMIC model); \code{0} for none.}

\item{b}{Coefficients of the observed predictors: a scalar, or a
\verb{(K - K1) x P} matrix.}

\item{K1}{Number of latent predictors (MIMIC / structural model).}

\item{ph1}{Correlation among the latent predictors.}

\item{b1}{Coefficients of the latent predictors: a scalar, or a
\verb{(K - K1) x K1} matrix.}

\item{phd}{Correlation among the structural disturbances (the residuals of
the regression of factors on predictors). \code{0} (default) gives independent
disturbances, which is LAWBL's behaviour; a positive value reproduces
designs with a freely correlated factor residual covariance. Ignored when
\code{P = 0} and \code{K1 = 0}.}

\item{ilvl}{Levels of every item, length \code{J + P}; values below 2 mean
continuous. \code{NULL} to use \code{cati}/\code{noc} instead.}

\item{cati}{Polytomous items by index; \code{NULL} for none, \code{-1} for all. Used
only when \code{ilvl = NULL}.}

\item{noc}{Number of categories for the polytomous items.}

\item{misp}{Proportion of missingness, applied to the \code{J} items only (never
to the covariate block).}

\item{ome_out}{Return the factor scores.}

\item{necw}{Number of within-factor local dependencies.}

\item{necb}{Number of between-factor local dependencies.}

\item{add_ind}{Indices of items loading on an additional minor factor.}

\item{add_la}{Loading value on the additional minor factor.}

\item{add_phi}{Correlation between the additional minor factor and the
others.}

\item{zero_it}{Number of surplus items with zero loadings.}

\item{rseed}{Random seed.}

\item{digits}{Significant digits used while the function is running.}
}
\value{
A list with the data (\code{dat}; items first, then any covariates),
the loading matrix (\code{MLA}), factor correlations (\code{PHI}), residual
covariance (\code{PSX}), the indices of the local-dependence pairs
(\code{ofd_ind}), and, when predictors are present, the coefficient matrices
(\code{mb}, \code{mb1}) and covariate correlation (\code{PHX}).
}
\description{
Generates factor-analytic or item-response data with optional observed and
latent predictors (MIMIC / structural models), cross-loadings, local
dependence, categorical or mixed response formats, and missingness.
}
\details{
\code{sim_lvm()} and \code{\link[=sim_fa]{sim_fa()}} are complementary rather than interchangeable.
Both accept a population loading matrix directly (\code{mla}, identical
semantics in either function); where they differ is what drives the
pattern-based path when \code{mla = NULL}, and what else each one models:

\describe{
\item{\code{sim_lvm()}}{is the \emph{model-side} generator. Use it when the design
involves \strong{predictors} -- observed covariates (\code{P}, \code{b}) or latent
predictors (\code{K1}, \code{ph1}, \code{b1}) -- or \strong{mixed response formats} per
item (\code{ilvl}). This is the generator for \code{\link[=vbmimic]{vbmimic()}}.}
\item{\code{\link[=sim_fa]{sim_fa()}}}{is the \emph{structure-side} generator. Use it when the
question is about the loading pattern itself: items per factor (\code{ipf}),
alternating-sign cross-loadings (\code{alt_sign}), or minor factors
(\code{minor}, definition-based per Auerswald & Moshagen, 2019). This is the
generator for \code{\link[=vbfa]{vbfa()}}.}
}

The two generators share \code{ph12} for the factor 1-2 correlation. \code{ph1}
exists only in \code{sim_lvm()}, where it means something different: the
correlation \strong{among latent predictors} (\code{K1}), not the factor 1-2
correlation.
}
\examples{
## MIMIC data: 18 items on 3 factors, 9 covariates in disjoint blocks of 3.
## Supply `b` as a matrix for a sparse structural design; a scalar `b` makes
## every covariate predict every factor, which quickly leaves no disturbance
## variance (the function stops if it does).
B <- matrix(0, 3, 9)
for (k in 1:3) B[k, ((k - 1) * 3 + 1):(k * 3)] <- .3

s <- sim_lvm(N = 500, K = 3, J = 18, P = 9, b = B, phx = 0, rseed = 1)
dim(s$dat)      # 500 x 27 -- items first, covariates last
s$mb            # the generating structural coefficients

## correlated disturbances (unrestricted factor residual covariance)
s2 <- sim_lvm(N = 500, K = 3, J = 18, P = 9, b = B, phx = 0, phd = .3,
              rseed = 1)
round(s2$PHI, 2)

## matrix-driven: supply the population loading matrix directly
mla <- matrix(0, 12, 2)
mla[1:6, 1] <- .7; mla[7:12, 2] <- c(.8, .7, .6, .7, .8, .6)
s3 <- sim_lvm(N = 300, mla = mla, phi = .3, rseed = 4)
s3$MLA                     # the generating matrix, as supplied

}
\references{
Chen, J. (2022). \emph{LAWBL: Latent (variable) analysis with Bayesian
learning} (R package version 1.5.0).

Jin, Y., & Chen, J. (2025). Regularized variational Bayesian approximations
for variable selection in extended multiple-indicators multiple-causes
models. \emph{Multivariate Behavioral Research}.
\doi{10.1080/00273171.2025.2483253}
}
\seealso{
\code{\link[=sim_fa]{sim_fa()}} for the structure-side generator, \code{\link[=vbmimic]{vbmimic()}} and
\code{\link[=vbfa]{vbfa()}} for the estimators.
}
