cSEM (version 0.5.0)

parseModel: Parse lavaan model

Description

Turns a model written in lavaan model syntax into a cSEMModel list.

Usage

parseModel(
  .model        = NULL, 
  .instruments  = NULL, 
  .check_errors = TRUE
  )

Value

An object of class cSEMModel is a standardized list containing the following components. J stands for the number of constructs and K for the number of indicators.

$structural

A matrix mimicking the structural relationship between constructs. If constructs are only linearly related, structural is of dimension (J x J) with row- and column names equal to the construct names. If the structural model contains nonlinear relationships structural is (J x (J + J*)) where J* is the number of nonlinear terms. Rows are ordered such that exogenous constructs are always first, followed by constructs that only depend on exogenous constructs and/or previously ordered constructs.

$measurement

A (J x K) matrix mimicking the measurement/composite relationship between constructs and their related indicators. Rows are in the same order as the matrix $structural with row names equal to the construct names. The order of the columns is such that $measurement forms a block diagonal matrix.

$error_cor

A (K x K) matrix mimicking the measurement error correlation relationship. The row and column order is identical to the column order of $measurement.

$cor_specified

A matrix indicating the correlation relationships between any variables of the model as specified by the user. Mainly for internal purposes. Note that $cor_specified may also contain inadmissible correlations such as a correlation between measurement errors indicators and constructs.

$construct_type

A named vector containing the names of each construct and their respective type ("Common factor" or "Composite").

$construct_order

A named vector containing the names of each construct and their respective order ("First order" or "Second order").

$model_type

The type of model ("Linear" or "Nonlinear").

$instruments

Only if instruments are supplied: a list of structural equations relating endogenous RHS variables to instruments.

$indicators

The names of the indicators (i.e., observed variables and/or first-order constructs)

$cons_exo

The names of the exogenous constructs of the structural model (i.e., variables that do not appear on the LHS of any structural equation)

$cons_endo

The names of the endogenous constructs of the structural model (i.e., variables that appear on the LHS of at least one structural equation)

$vars_2nd

The names of the constructs modeled as second orders.

$vars_attached_to_2nd

The names of the constructs forming or building a second order construct.

$vars_not_attached_to_2nd

The names of the constructs not forming or building a second order construct.

It is possible to supply an incomplete list to parseModel(), resulting in an incomplete cSEMModel list which can be passed to all functions that require .csem_model as a mandatory argument. Currently, only the structural and the measurement matrix are required. However, specifying an incomplete cSEMModel list may lead to unexpected behavior and errors. Use with care.

Arguments

.model

A model in lavaan model syntax or a cSEMModel list.

.instruments

A named list of vectors of instruments. The names of the list elements are the names of the dependent (LHS) constructs of the structural equation whose explanatory variables are endogenous. The vectors contain the names of the instruments corresponding to each equation. Note that exogenous variables of a given equation must be supplied as instruments for themselves. Defaults to NULL.

.check_errors

Logical. Should the model to parse be checked for correctness in a sense that all necessary components to estimate the model are given? Defaults to TRUE.

Details

Instruments must be supplied separately as a named list of vectors of instruments. The names of the list elements are the names of the dependent constructs of the structural equation whose explanatory variables are endogenous. The vectors contain the names of the instruments corresponding to each equation. Note that exogenous variables of a given equation must be supplied as instruments for themselves.

By default parseModel() attempts to check if the model provided is correct in a sense that all necessary components required to estimate the model are specified (e.g., a construct of the structural model has at least 1 item). To prevent checking for errors use .check_errors = FALSE.

Examples

# ===========================================================================
# Providing a model in lavaan syntax 
# ===========================================================================
model <- "
# Structural model
y1 ~ y2 + y3

# Measurement model
y1 =~ x1 + x2 + x3
y2 =~ x4 + x5
y3 =~ x6 + x7

# Error correlation
x1 ~~ x2
"

m <- parseModel(model)
m

# ===========================================================================
# Providing a complete model in cSEM format (class cSEMModel)
# ===========================================================================
# If the model is already a cSEMModel object, the model is returned as is:

identical(m, parseModel(m)) # TRUE

# ===========================================================================
# Providing a list 
# ===========================================================================
# It is possible to provide a list that contains at least the
# elements "structural" and "measurement". This is generally discouraged
# as this may cause unexpected errors.

m_incomplete <- m[c("structural", "measurement", "construct_type")]
parseModel(m_incomplete)

# Providing a list containing list names that are not part of a `cSEMModel`
# causes an error:

if (FALSE) {
m_incomplete[c("name_a", "name_b")] <- c("hello world", "hello universe")
parseModel(m_incomplete)
}

# Failing to provide "structural" or "measurement" also causes an error:

if (FALSE) {
m_incomplete <- m[c("structural", "construct_type")]
parseModel(m_incomplete)
}