simulate_factors: Simulate a common-factor model

In simulab: Simulates a Wide Variety of Data Shapes, Sizes and Distributions

Simulate a common-factor model

Description

Draws factor scores from a multivariate normal with unit variances and correlation factor_correlation, then forms each indicator as intercept + loadings %*% scores + error, where the error standard deviation is sqrt(uniqueness). The implied population covariance is loadings %*% factor_correlation %*% t(loadings) + diag(uniquenesses). Because the factors have unit variance, the loadings are on the standardized-factor metric.

Usage

simulate_factors(
  n,
  loadings,
  uniquenesses = NULL,
  factor_correlation = NULL,
  intercepts = 0,
  include_scores = FALSE,
  seed = NULL,
  batch = NULL
)

Arguments

n	Number of observations. A single whole number of at least 2.
loadings	Variable-by-factor loading matrix (one row per indicator, one column per factor, at least 2 rows), or a tidy data frame with columns item, factor and loading. Row and column names, when present, name the indicators and the factors.
uniquenesses	Residual variances (not standard deviations), a scalar recycled across indicators or one non-negative value per indicator. NULL (the default) uses 1 - rowSums(loadings^2), which gives every indicator unit total variance, so the loadings are then fully standardized. Loadings whose squared row sum exceeds one therefore raise an error rather than producing a Heywood case.
factor_correlation	Optional factor correlation matrix, or a tidy data frame with columns row, column and correlation. NULL (the default) makes the factors orthogonal.
intercepts	Variable intercepts, a scalar recycled across indicators (the default, 0) or one value per indicator.
include_scores	Single flag; when TRUE the true factor scores are appended to the primary data as one column per factor. Defaults to FALSE.
seed	Optional random seed.
batch	Optional single positive whole number. When given, the simulator runs batch times and returns a plain list of batch results, each exactly what the same call without batch returns. With a seed, every dataset gets its own seed drawn from seed, so the whole batch is reproducible; without one the datasets are consecutive draws from the session's random-number stream. The default NULL returns a single result.

Value

A simulab_sim base data.frame with one row per observation and columns id and one per indicator, plus one column per factor when include_scores = TRUE. A parameters component holds one row per variable-by-factor combination with columns variable, factor, loading, uniqueness and intercept; a covariance component holds the implied population covariance in tidy form, one row per variable pair, with columns row, column and covariance.

Examples

# `loadings` is one row per item and one column per factor.
loadings <- matrix(
  c(0.8, 0.7, 0.6, 0, 0, 0,
    0, 0, 0, 0.8, 0.7, 0.6),
  ncol = 2
)
result <- simulate_factors(n = 300, loadings = loadings, seed = 1)
head(result)
as.data.frame(result, what = "parameters")

simulab documentation built on Oct. 15, 2026, 5:08 p.m.