Package {lvmPlot}

lvmPlot: publication-quality diagrams for latent variable models

Description

Converts latent variable model output into publication-ready path diagrams and model schematics. lavaan fit objects and parameter tables are supported as a primary workflow, with adapters for blavaan, lavaan.mi, semPlot, mirt, eRm, OpenMx, psych, poLCA, mclust, flexmix, lcmm, tidyLPA, and MplusAutomation workflows when those packages are available. The package supports structural equation and confirmatory factor analysis diagrams, multilevel structural equation models, growth models, higher-order factor models, latent class and profile schematics, item response theory models, OpenMx RAM models, and Mplus-style parameter output through a shared lvm_graph grammar with model-aware defaults, geometry diagnostics, customizable publication styles, RStudio preview, SVG/PDF/PNG export, and TikZ output.

See Also

plot_lvm, as_lvm_graph, lvm_graph, lvm_tikz, plot_sem, sem_tikz

Convert lavaan output to a graph object

Description

as_sem_graph() reads a lavaan fit object or a lavaan-style parameter table and returns the node, edge, and layout data used by sem_tikz().

Usage

as_sem_graph(object, standardized = TRUE, layout = NULL,
  residuals = FALSE, covariances = TRUE)

Arguments

Value

A list with nodes, edges, and parameters, with class "sem_graph".

Check layout quality against publication gates

Description

check_lvm_layout() is the assertion-style companion to layout_quality(). It prepares a supported model object as an lvm_graph, computes geometry and optional label diagnostics, and checks the result against explicit publication-readiness gates. This is useful in R Markdown, CI, and manuscript-generation scripts where a diagram should fail early if nodes, paths, or labels collide.

Usage

check_lvm_layout(object, min_score = 92,
  minimum_status = c("ready", "review", "repair"),
  max_node_overlaps = 0, max_edge_node_overlaps = 0,
  max_edge_crossings = NULL, max_label_overlaps = 0,
  max_label_node_overlaps = 0, max_label_edge_overlaps = 0,
  label = c("auto", "none", "std", "est", "both"), digits = 2,
  stars = "auto", respect_curves = TRUE,
  action = c("error", "warning", "message", "none"),
  layout = NULL,
  layout_family = c("auto", "sem", "bifactor", "irt", "mixture", "growth",
    "multilevel", "circle"),
  orientation = c("top-down", "bottom-up", "left-right", "right-left"),
  diagram = c("auto", "all", "measurement", "structural", "loadings",
    "paths", "covariances", "compact"),
  show = NULL, min_abs = NULL, significant = NULL, alpha = 0.05,
  routing = c("straight", "smart", "none"),
  node_style = NULL, edge_style = NULL, ...)

Arguments

Value

A lvmPlot_layout_quality object with additional passed, requirements, violations, graph, and label fields.

Examples

params <- data.frame(
  lhs = c("f", "f", "f"),
  op = "=~",
  rhs = c("x1", "x2", "x3"),
  std.all = c(.7, .8, .75)
)
quality <- check_lvm_layout(params, label = "std", action = "none")
quality$passed

Export a publication bundle

Description

export_lvm_bundle() writes a complete manuscript-ready diagram bundle: vector/raster graphics, standalone TikZ, graph tables, diagnostics, quality report, and reproducibility metadata. It is intended to make the diagram a reproducible research artifact rather than a one-off image.

Usage

export_lvm_bundle(object, dir, name = "lvmPlot-diagram",
  formats = c("pdf", "png", "svg", "tex"), width = "auto",
  height = "auto", res = 300, layout = NULL,
  layout_family = c("auto", "sem", "bifactor", "irt", "mixture", "growth",
    "multilevel", "circle"),
  orientation = c("top-down", "bottom-up", "left-right", "right-left"),
  diagram = c("auto", "all", "measurement", "structural", "loadings",
    "paths", "covariances", "compact"),
  show = NULL, min_abs = NULL, significant = NULL, alpha = 0.05,
  label = c("auto", "std", "est", "both", "none"), digits = 2,
  stars = "auto", node_labels = NULL, theme = lvm_theme_names(),
  style = NULL, node_style = NULL, edge_style = NULL,
  routing = c("straight", "smart", "none"),
  aspect = c("balanced", "preserve", "fill"), margin = 0.08,
  optimize = FALSE, optimize_layout_family = "auto",
  optimize_orientation = c("top-down", "left-right", "bottom-up",
    "right-left"),
  optimize_diagram = "auto", optimize_routing = "straight",
  tables = TRUE, diagnostics = TRUE, check = FALSE, check_min_score = 92,
  check_status = c("ready", "review", "repair"),
  check_max_edge_crossings = NULL,
  check_action = c("error", "warning", "message", "none"),
  metadata = TRUE, report = TRUE,
  compile_tex = FALSE,
  engine = c("pdflatex", "xelatex", "lualatex", "tectonic"), ...)

Arguments

Value

A list with exported files, quality summary, graph, and device size, with class "lvmPlot_bundle".

Examples

params <- data.frame(
  lhs = c("f", "f", "f"),
  op = "=~",
  rhs = c("x1", "x2", "x3"),
  std.all = c(.7, .8, .75)
)
out <- tempfile("lvmPlot-bundle-")
export_lvm_bundle(
  params,
  out,
  name = "cfa",
  formats = c("pdf", "tex"),
  check = TRUE,
  optimize = TRUE,
  optimize_orientation = c("top-down", "left-right")
)

Diagnose a diagram layout

Description

layout_diagnostics() scores the current node coordinates before drawing. It is useful for checking whether a complex SEM/LVM layout still has node overlaps, straight-edge crossings, edge/node collisions, or estimated parameter label collisions before export.

Usage

layout_diagnostics(
  object,
  respect_curves = TRUE,
  label = c("none", "auto", "std", "est", "both"),
  digits = 2,
  stars = "auto"
)

Arguments

Value

A list with node overlap counts, edge crossing counts, edge/node overlap counts, optional edge-label collision counts, edge length summaries, and detail data frames, with class "lvmPlot_layout_diagnostics".

Examples

nodes <- data.frame(
  name = c("a", "b", "middle"),
  type = "observed",
  x = c(0, 2, 1),
  y = c(0, 0, 0)
)
edges <- data.frame(from = "a", to = "b", type = "path")
graph <- lvm_graph(nodes, edges)
layout_diagnostics(graph, respect_curves = FALSE)
layout_diagnostics(graph, respect_curves = FALSE, label = "est")

Create a diagram layout from a matrix

Description

layout_matrix() converts a familiar SEM plotting matrix into explicit node coordinates. Rows are interpreted from top to bottom and columns from left to right.

Usage

layout_matrix(x, x_spacing = 1.8, y_spacing = 1.7)

Arguments

Value

A data frame with name, x, and y columns.

Examples

layout <- layout_matrix(matrix(
  c(NA, "f", NA,
    "x1", ".", "x2"),
  nrow = 2,
  byrow = TRUE
))
layout

Score layout quality

Description

layout_quality() turns layout_diagnostics() into a compact quality score and issue table. It is designed for publication workflows where a diagram should be checked before being exported or submitted.

Usage

layout_quality(object, label = c("none", "auto", "std", "est", "both"),
  digits = 2, stars = "auto", respect_curves = TRUE)

Arguments

Value

A list with score, grade, status, issues, and diagnostics, with class "lvmPlot_layout_quality".

Examples

params <- data.frame(
  lhs = c("f", "f", "f"),
  op = "=~",
  rhs = c("x1", "x2", "x3"),
  std.all = c(.7, .8, .75)
)
quality <- layout_quality(as_lvm_graph(params), label = "std")
quality

Open a latent variable model diagram

Description

lvmPlot() is the high-level entry point for the package. In an interactive R session it asks whether to open the browser editor or draw a static plot, with the editor offered first because it is the recommended path for final manuscript figures. In non-interactive sessions it falls back to a static plot so scripts, examples, and package checks never wait for input. Use mode = "edit" to open the editor directly or mode = "plot" for a static diagram.

edit_lvm() is a short alias for opening the interactive editor directly.

Usage

lvmPlot(
  object,
  ...,
  mode = c("ask", "edit", "plot"),
  label = c("auto", "std", "est", "both", "none"),
  digits = 2,
  stars = "auto",
  theme = lvm_theme_names(),
  style = NULL,
  export_name = "lvmPlot-diagram",
  launch = interactive()
)

edit_lvm(
  object,
  ...,
  label = c("auto", "std", "est", "both", "none"),
  digits = 2,
  stars = "auto",
  theme = lvm_theme_names(),
  style = NULL,
  export_name = "lvmPlot-diagram",
  launch = interactive()
)

Arguments

Value

For mode = "plot", invisibly returns the plotted "lvm_graph". For mode = "edit", returns the Shiny app object invisibly when launched or visibly when launch = FALSE.

Examples

params <- data.frame(
  lhs = c("engage", "engage", "engage", "achieve"),
  op = c("=~", "=~", "=~", "~"),
  rhs = c("item1", "item2", "item3", "engage"),
  std.all = c(.78, .72, .69, .46),
  pvalue = c(.001, .001, .002, .004)
)

graph <- lvmPlot(params, mode = "plot", label = "std")
class(graph)

if (requireNamespace("shiny", quietly = TRUE) &&
    requireNamespace("jsonlite", quietly = TRUE)) {
  app <- lvmPlot(params, mode = "edit", label = "std", launch = FALSE)
  class(app)
}

if (interactive() && requireNamespace("shiny", quietly = TRUE) &&
    requireNamespace("jsonlite", quietly = TRUE)) {
  lvmPlot(params, mode = "edit", label = "std")
}

Interactively edit and export a lvmPlot diagram

Description

lvmPlot_editor() opens a small Shiny application for final manual adjustment of an automatically prepared LVM diagram. Nodes can be selected, dragged, nudged with the keyboard, snapped to a grid, locked, aligned, distributed, relabeled, repaired, undone/redone, and polished in the browser preview. Coefficient labels can also be dragged for final manual placement, or double-clicked to return them to automatic placement. Edge-label, theme, preset, color, size, line-width, and font changes update the preview before export; the edited coordinates, coefficient-label positions, node labels, and style can then be exported as SVG/PDF/PNG, reusable R code, or a JSON editor state that can be loaded later to continue editing.

Usage

lvmPlot_editor(
  object,
  ...,
  label = c("auto", "std", "est", "both", "none"),
  digits = 2,
  stars = "auto",
  theme = lvm_theme_names(),
  style = NULL,
  export_name = "lvmPlot-diagram",
  launch = interactive()
)

Arguments

Value

A Shiny app object invisibly when launched, or visibly when launch = FALSE.

See Also

plot_lvm, save_lvm_svg

Examples

if (interactive() && requireNamespace("shiny", quietly = TRUE) &&
    requireNamespace("jsonlite", quietly = TRUE)) {
  lvmPlot_editor(
    data.frame(
      lhs = c("f", "f", "y"),
      op = c("=~", "=~", "~"),
      rhs = c("x1", "x2", "f"),
      std.all = c(.7, .8, .4)
    )
  )
}

Preview a lvmPlot diagram from the RStudio editor selection

Description

These helpers are intended for RStudio Addins. Select an object name or an R expression that evaluates to a supported model, then run the addin to draw the diagram in the Plots pane or export TikZ code.

Usage

lvmPlot_rstudio_preview(object = NULL, ...)

lvmPlot_rstudio_export_tikz(object = NULL, file = "lvmPlot-diagram.tex", ...)

Arguments

Value

Invisibly returns the plotted graph or output file.

Suggest a canvas size for an LVM diagram

Description

lvm_canvas_size() inspects the prepared graph coordinates and returns a recommended device size. It helps dense MIRT/LCA diagrams get wider canvases and multilevel diagrams get taller canvases without manually guessing export dimensions.

Usage

lvm_canvas_size(object, ..., min_width = 6, max_width = 14,
  min_height = 4, max_height = 9.5)

Arguments

Value

A named numeric vector with width and height, in inches.

Examples

params <- data.frame(
  lhs = c("visual", "visual", "visual", "textual", "textual", "textual"),
  op = "=~",
  rhs = paste0("x", 1:6),
  est = .7
)
lvm_canvas_size(params)

Latent variable model graph grammar

Description

lvm_graph() is the common diagram grammar used by SEM, LCA/LPA, multilevel SEM, IRT/MIRT, growth, mixture, and adapter-based model diagrams. Model-specific adapters convert fitted model objects to this graph structure before drawing.

Usage

lvm_graph(nodes, edges = data.frame(), model_type = "lvm",
  layout_family = NULL, title = NULL, meta = list())

as_lvm_graph(object, ...)

Arguments

Value

An object of class "lvm_graph".

Create diagram style overrides

Description

Creates style overrides for plot_lvm(), plot_sem(), lvm_tikz(), and sem_tikz().

Usage

lvm_style(scale = NULL, node_scale = NULL, edge_scale = NULL,
  font_scale = NULL, node_font_size = NULL, edge_font_size = NULL,
  font_family = NULL, latent_size = NULL, observed_width = NULL,
  observed_height = NULL, node_line_width = NULL,
  edge_line_width = NULL, path_line_width = NULL,
  loading_line_width = NULL, covariance_line_width = NULL,
  residual_line_width = NULL, node_color = NULL,
  latent_color = NULL, observed_color = NULL, node_fill = NULL,
  latent_fill = NULL, observed_fill = NULL, edge_color = NULL,
  path_color = NULL, loading_color = NULL, covariance_color = NULL,
  residual_color = NULL, node_text_color = NULL, label_color = NULL,
  label_fill = NULL)

Arguments

Value

A named list with class "lvm_style".

Examples

style <- lvm_style(
  scale = 1.08,
  font_scale = 0.95,
  node_font_size = 12,
  edge_font_size = 9,
  latent_size = 16,
  observed_width = 20,
  node_fill = "#F8FAFC",
  edge_line_width = 1.1
)

List built-in diagram themes

Description

lvm_themes() returns the built-in theme presets accepted by plot_lvm(), plot_sem(), lvm_tikz(), and sem_tikz(). The default theme is "journal".

Usage

lvm_themes()

Value

A data frame with theme names and short descriptions.

Examples

lvm_themes()

TikZ output for latent variable model diagrams

Description

Creates editable TikZ output from the unified LVM graph grammar.

Usage

lvm_tikz(object, layout = NULL,
  layout_family = c("auto", "sem", "bifactor", "irt", "mixture", "growth",
  "multilevel", "circle"), orientation = c("top-down", "bottom-up",
  "left-right", "right-left"), diagram = c("auto", "all", "measurement",
  "structural", "loadings", "paths", "covariances", "compact"),
  show = NULL, min_abs = NULL, significant = NULL, alpha = 0.05,
  label = c("auto", "std", "est", "both", "none"), digits = 2,
  stars = "auto",
  node_labels = NULL, standalone = FALSE, theme = lvm_theme_names(),
  style = NULL, node_style = NULL, edge_style = NULL,
  routing = c("straight", "smart", "none"),
  escape = TRUE, file = NULL, ...)

write_lvm_tikz(object, file, standalone = TRUE, compile = FALSE,
  engine = c("pdflatex", "xelatex", "lualatex", "tectonic"), clean = TRUE,
  ...)

Arguments

Value

lvm_tikz() returns a character scalar. write_lvm_tikz() invisibly returns the normalized output path.

Draw and save latent variable model diagrams

Description

Draws latent variable model diagrams in the RStudio Plots pane and exports the same graph as SVG, PDF, or PNG.

Usage

plot_lvm(object, layout = NULL,
  layout_family = c("auto", "sem", "bifactor", "irt", "mixture", "growth",
  "multilevel", "circle"), orientation = c("top-down", "bottom-up",
  "left-right", "right-left"), diagram = c("auto", "all", "measurement",
  "structural", "loadings", "paths", "covariances", "compact"),
  show = NULL, min_abs = NULL, significant = NULL, alpha = 0.05,
  label = c("auto", "std", "est", "both", "none"), digits = 2,
  stars = "auto",
  node_labels = NULL, theme = lvm_theme_names(), style = NULL,
  node_style = NULL, edge_style = NULL,
  routing = c("straight", "smart", "none"),
  aspect = c("balanced", "preserve", "fill"), margin = 0.08, ...)

## S3 method for class 'lvm_graph'
plot(x, ...)

save_lvm_svg(object, file, width = "auto", height = "auto", ...)

save_lvm_pdf(object, file, width = "auto", height = "auto", ...)

save_lvm_png(object, file, width = "auto", height = "auto", res = 240, ...)

Arguments

Value

plot_lvm() invisibly returns the graph. Save helpers invisibly return the normalized output path.

Examples

params <- data.frame(
  lhs = c("f", "f", "y"),
  op = c("=~", "=~", "~"),
  rhs = c("x1", "x2", "f"),
  est = c(1, .8, .4)
)
plot_lvm(
  params,
  layout = matrix(c(NA, "y", NA, NA, "f", NA, "x1", ".", "x2"),
                  nrow = 3, byrow = TRUE),
  node_style = data.frame(name = "f", shape = "diamond", fill = "#EEF2FF"),
  edge_style = data.frame(from = "f", to = "y", label = "beta",
                          linetype = "dashed", curvature = -.18)
)

Draw and save SEM path diagrams in R

Description

plot_sem() uses base R grid graphics, so a fitted lavaan model can be previewed directly in the RStudio Plots pane. The save helpers write the same diagram as SVG, PDF, or PNG.

Usage

plot_sem(object, layout = NULL, label = c("auto", "std", "est", "both", "none"),
  digits = 2, stars = "auto", residuals = FALSE, covariances = TRUE,
  node_labels = NULL, theme = lvm_theme_names(), style = NULL,
  node_style = NULL, edge_style = NULL,
  routing = c("straight", "smart", "none"),
  aspect = c("balanced", "preserve", "fill"), margin = 0.08, ...)

## S3 method for class 'sem_graph'
plot(x, ...)

save_sem_svg(object, file, width = 8, height = 4.8, ...)

save_sem_pdf(object, file, width = 8, height = 4.8, ...)

save_sem_png(object, file, width = 8, height = 4.8, res = 240, ...)

Arguments

Value

plot_sem() invisibly returns the "sem_graph" object used for drawing. The save helpers invisibly return the normalized output path.

Examples

params <- data.frame(
  lhs = c("f", "f", "y"),
  op = c("=~", "=~", "~"),
  rhs = c("x1", "x2", "f"),
  est = c(1, .8, .4),
  std.all = c(.7, .6, .35),
  pvalue = c(NA, .001, .01)
)
plot_sem(params)

Select the best layout automatically

Description

select_lvm_layout() evaluates a grid of candidate layout settings and chooses the candidate with the best layout_quality() score. It lets users ask lvmPlot to try common orientation and routing alternatives before exporting a figure.

Usage

select_lvm_layout(object, layout_family = "auto",
  orientation = c("top-down", "left-right", "bottom-up", "right-left"),
  diagram = "auto", routing = "straight", show = NULL, min_abs = NULL,
  significant = NULL, alpha = 0.05,
  label = c("auto", "std", "est", "both", "none"), digits = 2,
  stars = "auto", node_labels = NULL, node_style = NULL,
  edge_style = NULL, ...)

Arguments

Value

A list with the selected graph, quality object, best candidate row, and candidate table, with class "lvmPlot_layout_selection".

Examples

params <- data.frame(
  lhs = c("f", "f", "f"),
  op = "=~",
  rhs = c("x1", "x2", "x3"),
  std.all = c(.7, .8, .75)
)
selection <- select_lvm_layout(
  params,
  orientation = c("top-down", "left-right"),
  label = "std"
)
selection
plot_lvm(selection$graph, label = "std")

Render a SEM path diagram as TikZ

Description

sem_tikz() renders measurement paths, structural regressions, and covariances from lavaan output as editable TikZ code.

Usage

sem_tikz(object, layout = NULL, label = c("auto", "std", "est", "both", "none"),
  digits = 2, stars = "auto", residuals = FALSE, covariances = TRUE,
  node_labels = NULL, standalone = FALSE, theme = lvm_theme_names(),
  style = NULL, node_style = NULL, edge_style = NULL,
  routing = c("straight", "smart", "none"), escape = TRUE, file = NULL, ...)

Arguments

Value

A character scalar with class "sem_tikz".

Examples

params <- data.frame(
  lhs = c("f", "f", "y"),
  op = c("=~", "=~", "~"),
  rhs = c("x1", "x2", "f"),
  est = c(1, .8, .4),
  std.all = c(.7, .6, .35),
  pvalue = c(NA, .001, .01)
)
sem_tikz(params)

Write a TikZ SEM diagram to disk

Description

write_sem_tikz() writes a TikZ path diagram to a .tex file and can optionally compile it when a local TeX engine is available.

Usage

write_sem_tikz(object, file, standalone = TRUE, compile = FALSE,
  engine = c("pdflatex", "xelatex", "lualatex", "tectonic"), clean = TRUE,
  ...)

Arguments

Value

Invisibly returns the normalized output path.