Unified Model Graphs for Statistical Models in Psychology

Constructs, validates, lays out, and renders Unified Model Graphs (UMG), a formal graphical grammar for statistical models in psychology. Vertices are typed by observability, support, and inferential role; edges distinguish stochastic, symmetric, deterministic, and mixing dependence; plates encode replication and hierarchy. Diagrams can be themed and rendered with base 'grid' graphics, with 'ggplot2', as 'TikZ' code, or as 'Graphviz' DOT, and can be constructed either from one-line motif builders for many model families or automatically from 'lavaan', 'lme4', 'mirt', 'blavaan', 'brms', 'OpenMx', and 'qgraph' model objects. A diagram can be inspected as a data frame, summarised, and exported back to 'lavaan' model syntax, making the model-diagram correspondence operational in both directions. Each diagram also exposes identification diagnostics (scaling checks, a graphical counting rule, and a d-separation reader) and generates the exploratory display scaffolds implied by the model-data duality. The notation builds on established results for graphical and structural equation models: plate notation follows Buntine (1994) ; the counting rule and scaling checks follow Bollen (1989) ; and the independence reader implements the d-separation criterion of Geiger, Verma and Pearl (1990) through the equivalent ancestral graph criterion of Lauritzen, Dawid, Larsen and Leimer (1990) .

umg: Unified Model Graphs for Statistical Models in Psychology

umg implements the Unified Model Graph (UMG) grammar: a single, formally specified graphical notation for the statistical models psychologists fit. A UMG types every vertex on three independent dimensions (observability, support, inferential role), types every edge by the kind of dependence it asserts (stochastic, symmetric, deterministic, mixing), and uses plates to encode replication and hierarchy. A well-formed diagram corresponds to a likelihood factorisation, so the diagram is the model.

Installation

# from GitHub (the package sits in the umg/ folder of the repository)
# install.packages("remotes")
remotes::install_github("hsiutingyu/umg", subdir = "umg")

# or from a local source copy
# install.packages("path/to/umg", repos = NULL, type = "source")

The package depends only on base R packages (grid, grDevices, stats, tools, utils). Optional features are guarded behind suggested packages: ggplot2 (ggplot backend, EDA scaffolds), DiagrammeR (Graphviz rendering), and lavaan, lme4, mirt, blavaan, brms, OpenMx, qgraph (fitted-model converters).

Three ways to build a diagram

library(umg)

# 1. One-line motif builders
plot(umg_factor("F", paste0("y", 1:4)))      # reflective CFA
plot(umg_irt("graded"))                       # graded response IRT
plot(umg_riclpm(waves = 4))                   # RI-CLPM
plot(umg_mixture(umg_growth(4), c("I", "S"))) # growth mixture model

# 2. By hand, from typed primitives
m <- umg_model(
  nodes = list(
    umg_node("eta", "$\\eta_i$", observed = FALSE, dist = "N(0, psi)"),
    umg_node("y1", "$y_{1i}$", observed = TRUE),
    umg_node("y2", "$y_{2i}$", observed = TRUE)
  ),
  edges = list(
    umg_edge("eta", "y1", "dep", fixed = 1),
    umg_edge("eta", "y2", "dep", label = "$\\lambda_2$")
  ),
  plates = list(umg_plate("person", c("eta", "y1", "y2"), "i = 1, ..., N"))
)

# 3. From a fitted model object
# umg_from_lavaan(fit); umg_from_lmer(Reaction ~ Days + (Days | Subject))
# umg_from_mirt(fit); umg_from_brms(fit); umg_from_OpenMx(fit)

Rendering

Backend	Function	Output
Base `grid`	`plot(m)` / `umg_save(m, "f.pdf")`	PDF / PNG / SVG
`ggplot2`	`umg_ggplot(m)` / `autoplot(m)`	ggplot object
TikZ	`umg_to_tikz(m)` / `umg_save(m, "f.tex")`	LaTeX source
Graphviz	`umg_to_dot(m)` / `umg_render_dot(m)`	DOT / HTML widget

Appearance is controlled by umg_theme() ("journal", "slide", "cb" colour-blind-safe).

Reading a diagram

umg_validate(m)            # well-formedness rules W1-W6
umg_identify(m)            # scaling, counting rule, label switching, implied CIs
umg_dsep(m, "X", "Y", given = "M")   # d-separation reader
umg_eda_scaffold(m, data)  # exploratory displays implied by the duality

Model families covered

Reflective and bifactor measurement, second-order and exploratory (ESEM) factor models, formative and MIMIC measurement, general SEM, the 1PL/2PL/3PL and graded/PCM/GPCM item response models (uni- and multidimensional), diagnostic classification models, latent class and profile models, growth and growth-mixture models, multilevel models, the random-intercept cross-lagged panel model, Gaussian graphical (network) models, and the Bayesian closure of any of them.