Build structural equation modeling portfolio project (#1)

Add a reproducible R/lavaan SEM case study with CFA, measurement invariance, latent mediation, diagnostics, documentation, visuals, tests, and GitHub Actions validation.

Author: mjeans

.github/workflows/validate.yml

@@ -0,0 +1,31 @@
+name: Validate structural equation modeling project
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          r-version: "release"
+      - name: Install lavaan
+        run: Rscript -e 'install.packages("lavaan", repos = "https://cloud.r-project.org")'
+      - name: Run end-to-end SEM workflow
+        run: make all
+      - name: Check required outputs
+        run: |
+          test -s outputs/cfa_fit_indices.csv
+          test -s outputs/measurement_invariance.csv
+          test -s outputs/sem_fit_indices.csv
+          test -s outputs/structural_paths.csv
+          test -s outputs/indirect_effects.csv
+          test -s outputs/residual_variances.csv

.gitignore

@@ -0,0 +1,7 @@
+data/
+artifacts/
+.Rhistory
+.RData
+.Rproj.user/
+outputs/*.csv
+!outputs/README.md

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Jeans
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,22 @@
+.PHONY: all data measurement structural diagnostics test clean
+
+all: data measurement structural diagnostics test
+
+data:
+	Rscript scripts/01_generate_data.R
+
+measurement: data
+	Rscript scripts/02_measurement_models.R
+
+structural: measurement
+	Rscript scripts/03_structural_model.R
+
+diagnostics: structural
+	Rscript scripts/04_diagnostics.R
+
+test:
+	Rscript tests/test_pipeline.R
+
+clean:
+	rm -rf data artifacts
+	rm -f outputs/*.csv

R/data_generation.R

@@ -0,0 +1,65 @@
+clamp <- function(x, lower, upper) {
+  pmin(pmax(x, lower), upper)
+}
+
+make_indicator <- function(latent, loading, intercept = 3) {
+  residual_sd <- sqrt(1 - loading^2)
+  clamp(intercept + loading * latent + rnorm(length(latent), 0, residual_sd), 1, 5)
+}
+
+generate_sem_data <- function(n = 2400L, seed = 20260813L) {
+  stopifnot(n >= 600L, n %% 2L == 0L)
+  set.seed(seed)
+
+  grade_band <- rep(c("Middle school", "High school"), each = n / 2L)
+  high_school <- as.integer(grade_band == "High school")
+  school_id <- sprintf("SCH-%02d", sample(seq_len(24L), n, replace = TRUE))
+
+  baseline_z <- rnorm(n)
+  support <- rnorm(n, mean = -0.08 * high_school, sd = 1)
+  engagement <-
+    0.55 * support + 0.22 * baseline_z - 0.12 * high_school + rnorm(n, 0, 0.72)
+  confidence <-
+    0.48 * engagement + 0.18 * support + 0.22 * baseline_z +
+    0.05 * high_school + rnorm(n, 0, 0.70)
+  followup_score <-
+    70 + 7.0 * baseline_z + 4.0 * engagement + 4.5 * confidence +
+    1.5 * support - 1.0 * high_school + rnorm(n, 0, 5.5)
+
+  data <- data.frame(
+    student_id = sprintf("STU-%05d", seq_len(n)),
+    school_id = school_id,
+    grade_band = grade_band,
+    high_school = high_school,
+    baseline_z = round(baseline_z, 4),
+    followup_score = round(followup_score, 2),
+    support_1 = make_indicator(support, 0.82),
+    support_2 = make_indicator(support, 0.76),
+    support_3 = make_indicator(support, 0.72),
+    support_4 = make_indicator(support, 0.68),
+    engagement_1 = make_indicator(engagement, 0.84),
+    engagement_2 = make_indicator(engagement, 0.79),
+    engagement_3 = make_indicator(engagement, 0.73),
+    engagement_4 = make_indicator(engagement, 0.69),
+    confidence_1 = make_indicator(confidence, 0.86),
+    confidence_2 = make_indicator(confidence, 0.78),
+    confidence_3 = make_indicator(confidence, 0.71),
+    stringsAsFactors = FALSE
+  )
+
+  item_names <- grep("^(support|engagement|confidence)_", names(data), value = TRUE)
+  lower_baseline <- as.integer(data$baseline_z < -0.5)
+
+  for (item_index in seq_along(item_names)) {
+    item <- item_names[[item_index]]
+    missing_probability <- plogis(
+      -3.25 + 0.35 * lower_baseline + 0.12 * high_school +
+        0.05 * ((item_index - 1L) %% 3L)
+    )
+    data[[item]][runif(n) < missing_probability] <- NA_real_
+  }
+
+  numeric_items <- c(item_names, "followup_score")
+  data[numeric_items] <- lapply(data[numeric_items], function(x) round(x, 3))
+  data
+}

R/sem_helpers.R

@@ -0,0 +1,98 @@
+required_fit_measures <- c(
+  "chisq.scaled", "df.scaled", "pvalue.scaled",
+  "cfi.scaled", "tli.scaled", "rmsea.scaled",
+  "rmsea.ci.lower.scaled", "rmsea.ci.upper.scaled", "srmr"
+)
+
+fit_summary_row <- function(fit, model_name) {
+  values <- lavaan::fitMeasures(fit, required_fit_measures)
+  data.frame(
+    model = model_name,
+    chisq = unname(values[["chisq.scaled"]]),
+    df = unname(values[["df.scaled"]]),
+    p_value = unname(values[["pvalue.scaled"]]),
+    cfi = unname(values[["cfi.scaled"]]),
+    tli = unname(values[["tli.scaled"]]),
+    rmsea = unname(values[["rmsea.scaled"]]),
+    rmsea_lower = unname(values[["rmsea.ci.lower.scaled"]]),
+    rmsea_upper = unname(values[["rmsea.ci.upper.scaled"]]),
+    srmr = unname(values[["srmr"]]),
+    stringsAsFactors = FALSE
+  )
+}
+
+round_numeric <- function(data, digits = 3L) {
+  numeric_columns <- vapply(data, is.numeric, logical(1))
+  data[numeric_columns] <- lapply(data[numeric_columns], round, digits = digits)
+  data
+}
+
+standardized_loadings <- function(fit) {
+  estimates <- lavaan::parameterEstimates(fit, standardized = TRUE)
+  estimates <- estimates[estimates$op == "=~", , drop = FALSE]
+  round_numeric(estimates[c("lhs", "rhs", "est", "se", "pvalue", "std.all")])
+}
+
+composite_reliability <- function(fit) {
+  standardized <- lavaan::standardizedSolution(fit)
+  factors <- unique(standardized$lhs[standardized$op == "=~"])
+
+  rows <- lapply(factors, function(factor_name) {
+    loadings <- standardized$est.std[
+      standardized$op == "=~" & standardized$lhs == factor_name
+    ]
+    error_variance <- 1 - loadings^2
+    omega <- sum(loadings)^2 / (sum(loadings)^2 + sum(error_variance))
+    ave <- sum(loadings^2) / (sum(loadings^2) + sum(error_variance))
+    data.frame(
+      factor = factor_name,
+      indicators = length(loadings),
+      composite_reliability = omega,
+      average_variance_extracted = ave
+    )
+  })
+
+  round_numeric(do.call(rbind, rows))
+}
+
+measurement_invariance_table <- function(configural, metric, scalar) {
+  fits <- list(configural = configural, metric = metric, scalar = scalar)
+  table <- do.call(rbind, Map(fit_summary_row, fits, names(fits)))
+  table$delta_cfi <- c(NA_real_, diff(table$cfi))
+  table$delta_rmsea <- c(NA_real_, diff(table$rmsea))
+  round_numeric(table)
+}
+
+missingness_summary <- function(data, variables) {
+  data.frame(
+    variable = variables,
+    n_missing = vapply(data[variables], function(x) sum(is.na(x)), integer(1)),
+    percent_missing = vapply(
+      data[variables],
+      function(x) mean(is.na(x)) * 100,
+      numeric(1)
+    ),
+    row.names = NULL
+  ) |>
+    round_numeric()
+}
+
+model_diagnostics <- function(fit) {
+  estimates <- lavaan::parameterEstimates(fit, standardized = TRUE)
+  residual_variances <- estimates[
+    estimates$op == "~~" & estimates$lhs == estimates$rhs,
+    c("lhs", "est", "se", "pvalue", "std.all")
+  ]
+  residual_variances$negative_variance <- residual_variances$est < 0
+
+  modification_indices <- lavaan::modindices(fit, sort. = TRUE)
+  modification_indices <- modification_indices[
+    modification_indices$mi >= 10,
+    c("lhs", "op", "rhs", "mi", "epc", "sepc.all")
+  ]
+
+  list(
+    residual_variances = round_numeric(residual_variances),
+    modification_indices = round_numeric(head(modification_indices, 20L))
+  )
+}

README.md

@@ -1,3 +1,111 @@
-# Structural Equation Modeling
+# Structural Equation Modeling of Student Engagement
 
-Project build in progress.
+[![Validate structural equation modeling project](https://github.com/mjeans/structural-equation-modeling/actions/workflows/validate.yml/badge.svg)](https://github.com/mjeans/structural-equation-modeling/actions/workflows/validate.yml)
+
+An end-to-end R and `lavaan` case study connecting measurement quality to a structural model of student support, engagement, academic confidence, and later achievement. The project demonstrates confirmatory factor analysis, measurement invariance, full-information maximum likelihood, latent-variable mediation, model diagnostics, and careful interpretation.
+
+> All records are deterministic and synthetic. No student, school, district, or client data are included.
+
+![Structural equation model linking support, engagement, confidence, and achievement](assets/structural-model.svg)
+
+## Research question
+
+How are perceived support, student engagement, and academic confidence associated with later achievement after accounting for baseline performance and grade band—and is the measurement structure sufficiently comparable across middle- and high-school students to support group comparisons?
+
+The workflow separates that question into two stages:
+
+1. **Measurement:** Do 11 survey indicators represent three distinct latent constructs, and do the loadings and intercepts operate similarly across grade bands?
+2. **Structure:** Are support, engagement, confidence, and follow-up achievement connected through the prespecified direct and indirect pathways?
+
+## Verified reference results
+
+GitHub Actions regenerates the complete 2,400-record dataset and executes every model and test. The validated reference run produced:
+
+| Analysis | CFI | TLI | RMSEA | SRMR |
+|---|---:|---:|---:|---:|
+| Three-factor pooled CFA | 0.998 | 0.997 | 0.015 | 0.012 |
+| Structural equation model | 0.998 | 0.998 | 0.013 | 0.015 |
+
+The scalar-invariance step changed CFI and RMSEA by less than 0.001. The serial indirect association from support through engagement and confidence to follow-up achievement was 1.184 (`p < .001`). Diagnostics examined 17 residual variances, found no negative variances, and retained one modification index above 10 for transparent review rather than automatically respecifying the model.
+
+The excellent fit is expected because the synthetic data were generated from the prespecified structure. It demonstrates correct implementation and recovery under known conditions; it is not evidence that comparable fit should be expected in real data.
+
+## What the project demonstrates
+
+- Three-factor confirmatory factor analysis with robust maximum likelihood
+- Configural, metric, and scalar measurement-invariance testing
+- Model comparison using changes in CFI and RMSEA rather than chi-square alone
+- Full-information maximum likelihood for incomplete continuous indicators
+- Composite reliability and average variance extracted
+- A latent-variable structural model with serial and specific indirect effects
+- Baseline and grade-band covariate adjustment
+- Standardized path estimates, confidence intervals, and explained variance
+- Residual-variance and modification-index diagnostics
+- Deterministic synthetic data, automated tests, and GitHub Actions
+- Explicit separation of statistical association from causal interpretation
+
+## Measurement model
+
+![Three-factor measurement model](assets/measurement-model.svg)
+
+The prespecified model includes:
+
+- **Support:** four indicators of relational and instructional support
+- **Engagement:** four indicators of behavioral and cognitive engagement
+- **Academic confidence:** three indicators of perceived academic capability
+
+The same factor structure is evaluated in middle- and high-school groups. Configural invariance tests the shared pattern, metric invariance constrains loadings, and scalar invariance additionally constrains intercepts. The decision rules flag a step when absolute CFI deterioration exceeds 0.010 or RMSEA increases by more than 0.015.
+
+## Structural model
+
+The final model estimates:
+
+- support → engagement
+- support and engagement → academic confidence
+- support, engagement, and confidence → follow-up achievement
+- baseline performance and grade band as observed covariates
+- support’s specific and serial indirect associations with achievement
+
+The serial indirect path is `support → engagement → confidence → follow-up achievement`. Bootstrap language is intentionally avoided because the reference workflow uses robust maximum-likelihood standard errors; the project reports model-based confidence intervals and labels that distinction clearly.
+
+## Repository map
+
+```text
+R/            Synthetic data generation and reusable SEM reporting helpers
+scripts/      Data, CFA/invariance, SEM, and diagnostic entry points
+config/       Prespecified measurement and structural models
+tests/        Reproducibility, fit, invariance, mediation, and solution checks
+docs/         Analysis plan, model card, data dictionary, and decision memo
+assets/       Measurement and structural model diagrams
+outputs/      Documentation for reproducibly generated result tables
+.github/      Continuous-integration workflow
+```
+
+## Reproduce the analysis
+
+R and `lavaan` are the only requirements.
+
+```bash
+install.packages("lavaan")
+make all
+```
+
+Or run the stages separately:
+
+```bash
+Rscript scripts/01_generate_data.R
+Rscript scripts/02_measurement_models.R
+Rscript scripts/03_structural_model.R
+Rscript scripts/04_diagnostics.R
+Rscript tests/test_pipeline.R
+```
+
+Generated record-level data, fitted model objects, and result tables are ignored by Git. The scripts regenerate them deterministically, and continuous integration executes the entire workflow on every pull request.
+
+## Interpretation boundary
+
+The structural paths are conditional associations within a synthetic cross-sectional measurement design with a later observed outcome. Model fit does not prove the model is true, establish temporal ordering among the latent constructs, eliminate omitted-variable bias, or identify causal effects. A real application would require instrument validation, sampling and clustering review, preregistration where appropriate, sensitivity analyses, and replication in an independent cohort.
+
+See the [analysis plan](docs/analysis-plan.md), [model card](docs/model-card.md), [data dictionary](docs/data-dictionary.md), and [decision memo](docs/decision-memo.md).
+
+Built as a public portfolio demonstration by [Matthew Jeans, PhD](https://github.com/mjeans).