% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sim_fa.R
\name{sim_fa}
\alias{sim_fa}
\title{Simulating data with Latent Variable Modeling}
\usage{
sim_fa(
  N = 1000,
  mla = NULL,
  K = 3,
  ipf = 8,
  cpf = 2,
  lam = 0.7,
  lac = 0.3,
  alt_sign = TRUE,
  phi = 0.5,
  ph12 = -1,
  gamma = NULL,
  ecr = 0,
  ome_out = FALSE,
  cati = NULL,
  noc = c(4),
  misp = 0,
  rseed = 333,
  necw = K,
  necb = K,
  add_ind = c(),
  add_la = 0,
  add_phi = 0,
  add1_ind = c(),
  add1_la = 0,
  add1_phi = 0,
  zero_it = 0,
  minor = NULL,
  digits = 4
)
}
\arguments{
\item{N}{Sample size.}

\item{mla}{Population loading matrix (J x K). If supplied, the pattern
arguments (\code{ipf}, \code{cpf}, \code{lam}, \code{lac}, \code{alt_sign},
\code{add_*}, \code{minor}, \code{zero_it}) are ignored and \code{K},
\code{J} are taken from it -- the same convention as \code{\link[=sim_lvm]{sim_lvm()}}.}

\item{K}{Number of factors.}

\item{ipf}{Items per factor.}

\item{cpf}{Cross-loadings per factor.}

\item{lam}{Number of formal iterations for posterior sampling.}

\item{lac}{Number of iterations to update the sampling information.}

\item{alt_sign}{Logical; alternate the sign of the cross-loadings across the
cross-loading items (default \code{TRUE}).}

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

\item{ph12}{Correlation between factor 1 and 2 (if it's different from
\code{phi}). Shared with \code{\link[=sim_lvm]{sim_lvm()}}, which uses \code{ph1} for a
different purpose (correlation among latent predictors); see \code{\link[=sim_lvm]{sim_lvm()}}
for that distinction.}

\item{gamma}{Optional second-order loadings for direct \strong{higher-order}
generation: a scalar or length-\code{K} vector in \eqn{(0, 1)}. When
supplied, each group factor \eqn{\eta_k} is driven by a general factor
\eqn{\xi} through \eqn{\eta_k = \gamma_k \xi + \zeta_k}, and the data are
generated from the equivalent Schmid-Leiman orthogonal bifactor matrix:
general loadings \eqn{\lambda_j \gamma_k} and group loadings
\eqn{\lambda_j \sqrt{1 - \gamma_k^2}} (a testlet model is the same model).
The returned \code{MLA} is this \eqn{J \times (K+1)} bifactor matrix
(general factor first), \code{PHI} is the identity, and the first-order
matrix and \code{gamma} are returned as \code{MLA1} and \code{gamma}.
Incompatible with \code{mla}, \code{cpf > 0}, \code{add_ind},
\code{add1_ind}, \code{minor}, and \code{zero_it}; \code{phi}/\code{ph12}
are ignored (the SL solution is orthogonal by construction).}

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

\item{ome_out}{Output factor score or not.}

\item{cati}{The set of categorical (polytomous) items in sequence number (i.e., 1 to \eqn{J});
\code{NULL} for no and -1 for all (default is \code{NULL}).}

\item{noc}{Number of categories for categorical items}

\item{misp}{Proportion of missingness.}

\item{rseed}{An integer for the random seed.}

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

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

\item{add_ind}{(Additional) minor factor with cross-loadings.}

\item{add_la}{Value of cross-loadings on (Additional) minor factor.}

\item{add_phi}{Correlations between (Additional) minor factor and other factors.}

\item{add1_ind}{A second (additional) minor factor with cross-loadings,
given as item indices; \code{c()} for none.}

\item{add1_la}{Value of the cross-loadings on the second minor factor.}

\item{add1_phi}{Correlations between the second minor factor and other
factors.}

\item{zero_it}{Surplus items with zero loading.}

\item{minor}{Optional character vector requesting orthogonal minor factors
loading on every indicator, each \code{"weak"} or \code{"moderate"}
(Auerswald & Moshagen, 2019); \code{NULL} for none.}

\item{digits}{Number of significant digits to print when printing numeric values.}
}
\value{
An object of class \code{list} containing the data, loading, and factorial correlation matrix.
}
\description{
\code{sim_fa} can simulate data based on factor analysis or
item response models with different response formats (continuous or categorical),
loading patterns and residual covariance (local dependence) structures.

\code{sim_fa()} and \code{\link[=sim_lvm]{sim_lvm()}} are complementary rather than
interchangeable: \code{sim_fa()} is the \emph{structure-side} generator, driven
by 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) -- and is the generator for \code{\link[=vbfa]{vbfa()}}.
\code{\link[=sim_lvm]{sim_lvm()}} is the \emph{model-side} generator, adding observed/latent
predictors (\code{P}/\code{b}, \code{K1}/\code{ph1}/\code{b1}) and mixed response formats (\code{ilvl}),
and is the generator for \code{\link[=vbmimic]{vbmimic()}}. Both generators also accept a
population loading matrix directly (\code{mla}) with identical semantics.
}
\examples{

# for continuous data with cross-loadings and local dependence effect .3
out <- sim_fa(N=1000,K=3,ipf=6,lam = .7, lac=.3,ecr=.3)
summary(out$dat)
out$MLA
out$ofd_ind

# for categorical data with cross-loadings .4 and 10\% missingness
out <- sim_fa(N=1000,K=3,ipf=6,lam = .7, lac=.4,cati=-1,noc=4,misp=.1)
summary(out$dat)
out$MLA
out$ofd_ind

## 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)
s <- sim_fa(N = 300, mla = mla, phi = .3, rseed = 4)
s$MLA                      # the generating matrix, as supplied

## higher-order (testlet) data, generated directly: 3 group factors driven
## by one general factor with second-order loadings .8, .7, .6
s <- sim_fa(N = 500, K = 3, ipf = 6, lam = .7, gamma = c(.8, .7, .6))
round(s$MLA, 2)            # J x 4 Schmid-Leiman bifactor matrix (general first)
s$gamma                    # the second-order loadings

}
