specify_model: Specify an ESEM Model Structure

In bifactory: (Bifactor) ESEM with Continuous (MLR) or Ordinal (WLSMV) Data

Specify an ESEM Model Structure

Description

Creates a model specification object that flows automatically through all subsequent steps – CFA, ESEM, B-ESEM, alignment check, Mplus syntax, and comparison tables. Define your factor structure once at the top; everything else is derived automatically.

Usage

specify_model(
  ...,
  data,
  label = "ESEM Model",
  ordered = FALSE,
  group = NULL,
  estimator = NULL,
  missing = NULL
)

Arguments

...	Named character vectors, one per factor. The name becomes the factor name and the vector contains the indicator names. Example: EX = c("y1","y2","y3"), MD = c("y4","y5","y6").
data	A data.frame containing the indicators.
label	Optional character string labelling the model (used in output headers and Mplus titles). Default "ESEM Model".
ordered	Logical or character vector. If TRUE, all indicators are treated as ordinal and the estimator is automatically switched to "WLSMV" (both R and Mplus). If a character vector of item names is supplied, only those items are treated as ordered. Default FALSE (continuous).
group	Character. Name of a grouping variable in data for multi-group models. When supplied, a configural model is fitted by default. Use group_equal in run_comparison() to test metric or scalar invariance.
estimator	Character. Override the auto-selected lavaan estimator. If NULL (default), uses "WLSMV" when ordered is supplied and "MLR" otherwise.
missing	Character. Missing-data handling. If NULL (default), "pairwise" for ordered data and "listwise" for continuous. Ordered accepts "pairwise" or "listwise". Continuous accepts "listwise" or any FIML alias ("fiml", "ml", "direct"). The chosen method is applied uniformly to CFA, ESEM, and B-ESEM so that fit statistics are computed on the same sample (fair comparison). Note that the FIML + GPArotation::targetT path used for B-ESEM with 4+ specific factors can settle into a local optimum (G absorbs specific-factor variance); a warning is emitted when that combination is detected.

Value

An object of class "esem_spec" containing:

factors

Named list of factor -> indicator assignments.

factor_names

Character vector of factor names.

all_items

Character vector of all indicators in order.

nfactors

Number of specific factors.

data

The supplied data frame.

label

Model label.

cfa_syntax

Ready-to-use lavaan CFA model string.

target

Target matrix for ESEM target rotation.

bifactor_target

Target matrix for B-ESEM.

Examples

data("HolzingerSwineford1939", package = "lavaan")

# Continuous indicators (MLR estimator by default)
spec <- specify_model(
  Visual  = c("x1", "x2", "x3"),
  Textual = c("x4", "x5", "x6"),
  Speed   = c("x7", "x8", "x9"),
  data    = HolzingerSwineford1939,
  label   = "Holzinger-Swineford 3-factor"
)
print(spec)

# Multi-group spec (for invariance testing)
spec_mg <- specify_model(
  Visual  = c("x1", "x2", "x3"),
  Textual = c("x4", "x5", "x6"),
  Speed   = c("x7", "x8", "x9"),
  data    = HolzingerSwineford1939,
  group   = "sex",
  label   = "HS 3-factor (multi-group)"
)


# Run the CFA/ESEM/B-ESEM comparison from a spec
results <- run_comparison(spec)
print(results)

bifactory documentation built on Oct. 28, 2026, 1:06 a.m.