make_sem_structure: Define Structural Equation Model (SEM) Matrices

In EMC2: Bayesian Hierarchical Analysis of Cognitive Models of Choice

Define Structural Equation Model (SEM) Matrices

Description

This function helps create the specification matrices (Lambda, B, K, G) for an SEM. It takes a design object, data, factor names, covariate column names, and list-based specifications for the paths to be estimated. The subject-level parameter names for Lambda_mat and K_mat rows are derived from sampled_pars(design). It validates that covariates are consistent per subject (subject column in data must be named "subjects") and includes an aggregated subject-level covariate data frame named covariates in the output list. For identifiability, the first parameter listed in lambda_specs for each factor is fixed to 1.

Usage

make_sem_structure(
  data = NULL,
  design,
  covariate_cols = NULL,
  lambda_specs = NULL,
  b_specs = NULL,
  k_specs = NULL,
  g_specs = NULL,
  fixed_value = 0
)

Arguments

data	A data frame containing a column named "subjects" and any covariate columns specified in covariate_cols.
design	An emc.design object, as created by the design() function. The parameter names for the SEM are derived from names(sampled_pars(design)).
covariate_cols	Character vector or NULL. Column names in data to be used as covariates for K_mat and G_mat. If NULL, no covariates are processed.
lambda_specs	A list defining factor loadings. The list names should be factor names and each element should be a character vector of parameter names (from names(sampled_pars(design))) that load onto that factor. The first parameter listed for each factor will be fixed to 1 for identifiability. Example: list(Factor1 = c("v_Sleft", "a_Eneutral"), Factor2 = "t0") Here, Lambda_mat["v_Sleft", "Factor1"] would be 1.
b_specs	A list defining regressions among factors. List names are outcome factors, elements are character vectors of predictor factors. Example: list(Factor2 = "Factor1", Factor3 = c("Factor1", "Factor2"))
k_specs	A list defining covariate effects on subject-level parameters. List names are parameter names (from names(sampled_pars(design))), elements are character vectors of covariate names (must be present in covariate_cols and thus in the processed covariates data frame). Example: list(v_Sleft = "cov1", a_Eneutral = c("cov1", "cov2"))
g_specs	A list defining covariate effects on factors. List names are factor names, elements are character vectors of covariate names. Example: list(Factor1 = "cov1", Factor2 = c("cov1", "cov2"))
fixed_value	Numeric. The value used for fixed paths in the matrices that are not set to 1 for identifiability or Inf for estimation. Default is 0.

Value

A list containing:

• Lambda_mat: The factor loading matrix.

• B_mat: The matrix of regressions among factors.

• K_mat: The matrix of covariate effects on subject-level parameters.

• G_mat: The matrix of covariate effects on factors.

• par_names: The subject-level parameter names derived from sampled_pars(design).

• factor_names: The provided SEM factor names.

• covariates: A data frame with one row per unique subject and columns for each covariate, containing the unique subject-level values. Column names are the covariate names.

Examples

# Create a design object (simplified from design.R example)
ADmat <- matrix(c(-1/2,1/2),ncol=1,dimnames=list(NULL,"diff"))
matchfun_example <- function(d) d$S==d$lR # Example match function

example_design_obj <- design(
  data = forstmann,
  model= LBA,
  matchfun=matchfun_example,
  formula=list(v~lM,sv~lM,B~E+lR,A~1,t0~1),
  contrasts=list(v=list(lM=ADmat)),
  constants=c(sv=log(1)),
)

# SEM Factor names

# Make a copy of forstmann for example modification
forstmann_mod <- forstmann
set.seed(123) # for reproducibility
subj_trait_values <- stats::setNames(rnorm(length(levels(forstmann_mod$subjects))),
                                    levels(forstmann_mod$subjects))
forstmann_mod$SubjTrait <- subj_trait_values[forstmann_mod$subjects]

my_cov_cols <- c("SubjTrait")

lambda_example_specs <- list(
  Speed = c("v", "v_lMdiff"), # "v" will be fixed to 1
  Caution = c("B", "B_Eneutral", "B_Eaccuracy", "B_lRright", "A") # "B" fixed to 1
)
b_example_specs <- list(Caution = "Speed")
k_example_specs <- list(t0 = "SubjTrait") # "SubjTrait" must be in my_cov_cols
g_example_specs <- list(Speed = "SubjTrait")

sem_settings_definition <- make_sem_structure(
  data = forstmann_mod,
  design = example_design_obj,
  covariate_cols = my_cov_cols,
  lambda_specs = lambda_example_specs,
  b_specs = b_example_specs,
  k_specs = k_example_specs,
  g_specs = g_example_specs
)

print(sem_settings_definition$Lambda_mat)
print(sem_settings_definition$B_mat)
print(sem_settings_definition$K_mat)
print(sem_settings_definition$G_mat)
print(head(sem_settings_definition$covariates))

EMC2 documentation built on Dec. 2, 2025, 9:06 a.m.