ssm_sem_syntax: Generate lavaan syntax for a fixed-angle circumplex measurement model

Description

Emit lavaan model syntax for a structural-equation-model formulation of the Structural Summary Method, with the circumplex scale angles held fixed at their theoretical values. This is the syntax-generation layer of the SEM-based SSM (see the package's design notes); it is a pure function of its arguments and does not require lavaan to be installed (only fitting the emitted model does).

Usage

ssm_sem_syntax(
  instrument = NULL,
  scales = NULL,
  angles = NULL,
  measures = NULL,
  model = c("scaled", "strict"),
  n_groups = 1,
  invariance = c("configural", "metric", "scalar", "strict_residuals"),
  include_defined = NULL
)

Value

A single character string of lavaan model syntax, with attributes angles (a circumplex_degree vector), scales, model, weights (the 3-by-p OLS projection matrix, rows e, x, y), n_groups, and (when n_groups >= 2) invariance.

Arguments

instrument: Optional. A circumplex_instrument object; its scale abbreviations and angles are used. Supply this or both scales and angles.
scales: Optional. A character vector of circumplex scale (column) names. Ignored when instrument is supplied.
angles: Optional. A numeric vector of scale angles in degrees, the same length as scales. Ignored when instrument is supplied.
measures: Optional. Either NULL or a character vector of external measure (column) names to relate to the circumplex factors.
model: Optional. The measurement-model tier: "scaled" (default) or "strict". See Details.
n_groups: Optional. A single positive whole number: the number of groups for a multi-group model. 1 (default) emits the single-group model. When n_groups >= 2 the generator emits multi-group syntax with a mean structure and the invariance constraints selected by invariance; fitting it requires lavaan::cfa() called with group = a grouping variable whose number of levels equals n_groups. Group ordering follows the factor-level order of that variable: the first level is the reference group, whose factor metric (and, from the scalar rung, whose latent means) is fixed.
invariance: Optional. The cross-group invariance rung to emit when n_groups >= 2: "configural" (default), "metric", "scalar", or "strict_residuals". Must be left at its default when n_groups == 1 (supplying it there is an error). Under the "strict" tier the "metric" rung is vacuous (all loadings are fixed) and emits the configural structure with an explanatory comment. See the package design notes (section 6.2) for the adapted fixed-angle invariance ladder.
include_defined: Optional. (Single-group models only: for n_groups >= 2 the lines are unavailable and an explicit TRUE is ignored with a warning.) Whether to append inspection-only := definitions of the covariance-metric (e, x, y) coordinates for each measure. NULL (default) emits them automatically under the "strict" tier when at least one measure is present (there they are linear), and omits them otherwise. TRUE forces emission (an error under "scaled", where they would be nonlinear); FALSE always suppresses them.

Details

Two model tiers are available. The "scaled" tier frees a general saturation and a circumplex saturation per scale while fixing each scale's angle; the circumplex plane is held isotropic and orthogonal, and the general factor is held orthogonal to the plane (freeing the general-plane covariances alongside free saturations makes the model locally unidentified exactly at zero covariance, so they cannot be estimated in this tier). The "strict" tier fixes every loading to the unit cosine pattern (1, cos(angle), sin(angle)) and frees the 3x3 factor covariance matrix -- including the general-plane covariances, making it the tier that can model a general factor leaning into the plane. The angles enter only as evaluated cosine and sine constants; no angle is ever a free parameter.

The returned string always carries a weights attribute: the ordinary-least-squares projection matrix that maps a profile vector to the structural summary coordinates (e, x, y). For equally spaced angles this equals the conventional closed-form estimator; for unequally spaced angles it is the least-squares projection and can differ. The emitted syntax never contains := definitions for amplitude or displacement: those are nonlinear functions whose confidence intervals must be constructed in-package, not by lavaan's delta method (which ignores the angular branch cut).

Examples

Run this code

# Octant instrument, default scaled tier
syn <- ssm_sem_syntax(scales = paste0("s", 1:8), angles = octants())
attr(syn, "weights")
cat(syn)