Editing and saving path diagrams with lvmPlot

What the diagram includes

Here is a static rendering of the model. Shiny is not launched when this vignette is built.

plot_lvm(fit, diagram = "all", label = "std", stars = FALSE)

The three-factor CFA with standardized coefficients and factor covariances.

Ellipses represent latent variables and rectangles represent observed variables. Loading arrows run from a factor to its indicators. A covariance has arrowheads at both ends. In a regression such as speed ~ textual, the arrow runs from textual to speed.

The call uses diagram = "all" to retain the factor covariances. The default, diagram = "auto", simplifies some diagrams, including the covariance mesh in a pure CFA. It can also summarize very wide item batteries and dense models. If an expected path is missing, try diagram = "all" before changing the model.

diagram = "all" retains the graph edges supplied by the adapter. It does not turn every row of a statistical output table into a path. Variances require residuals = TRUE; intercepts, thresholds, constraints, and defined effects such as indirect := a*b are not drawn as separate nodes.

lvmPlot(fit, mode = "edit", diagram = "all", residuals = TRUE,
        label = "std", stars = FALSE)

Check the model itself with summary(fit, fit.measures = TRUE) and the diagnostics appropriate to the analysis. Editing the diagram does not change the fitted model, assess identification, or establish a causal interpretation.

Checking the exported appearance

Open Export preview and click Refresh export preview. Look for the moved visual node, its new name, and the coefficient you placed beside the arrow. Return to Edit if they need more space, then refresh the preview again.

The editing canvas and exported files use different renderers. The canvas responds quickly to mouse movements; R graphics determines the fonts, node sizes, and routing in the files. The export preview uses that R renderer, which is why it is worth checking before downloading, particularly with long labels. The preview itself is a raster image, while PDF and SVG downloads remain vector files.

The grid, selection highlights, and lock indicators are absent from the exported figure. Background and Grid affect the editing canvas; standard exports have a white background.

Returning to the editor

State JSON is the useful file when you expect to keep adjusting the diagram. A PDF alone cannot restore the editing session. Rerun the model, or load a saved fit, then open the editor with the same diagram settings and select the JSON file under Load state JSON:

saveRDS(fit, "cfa-fit.rds")

# In a later R session:
library(lvmPlot)
fit <- readRDS("cfa-fit.rds")
lvmPlot(fit, mode = "edit", label = "std", stars = FALSE,
        diagram = "all", export_name = "three-factor-cfa")
# In the editor, use Load state JSON.

State JSON contains the editing state, not the observations or a fitted lavaan object. The editor checks node names and the path information stored in current state files. For example, state saved from a structural summary may not match an editor opened with the full measurement model. A mismatched or invalid file produces a notification without closing the current session.

If you refit the model without changing its nodes or paths, loading compatible state reuses the arrangement with the new coefficients. Figure R behaves differently: it keeps the estimates recorded when the script was downloaded.

Reproducing a saved figure in R

The Figure R download starts with library(lvmPlot) and reconstructs the graph from saved node and edge tables. It can run in a fresh R session without the original fit. It draws the figure and writes PDF, SVG, and PNG files in the working directory:

# Run in the directory where you want the figure files to be written.
source("three-factor-cfa-figure.R")

The script creates an object called object containing the selected graph and its manual positions. After sourcing it, you can open that graph in the editor to continue adjusting the layout:

lvmPlot(object, mode = "edit", layout = layout, label = label,
        theme = theme, digits = digits, stars = stars, style = style)

Keep style = style in this call so that the editor uses the font sizes and colours saved with the figure. The downloaded script defines style as NULL when the figure has no global style overrides.

Keep the analysis script as well. If the data or model changes, refit the model and apply the layout to the new fit. Editing an estimate inside a saved graph only changes the number in the figure.

Coefficient labels

If standardized values are missing, label = "std" leaves the labels blank; it does not substitute raw estimates. std.lv and std.all describe different standardizations, so a column called std.lv is not treated as std.all.

Explicit edge_label values take precedence over numeric labels unless you choose label = "none". This is useful for a model schematic with labels such as a and b, but check custom labels when refitting a model: they are text, not automatically updated estimates.

plot_lvm(fit, label = "est", digits = 3, stars = FALSE)
plot_lvm(fit, label = "both", digits = 2, stars = FALSE)
plot_lvm(fit, label = "none")

stars = FALSE is convenient when a separate results table reports inferential statistics. With stars = TRUE, significance symbols use the available p-values; fixed parameters may not have a p-value. stars = "auto" may suppress stars on crowded diagrams. Geometric label rules may also omit a coefficient that cannot fit on a very short edge. Increase spacing rather than inferring that a blank label means a zero coefficient.

Node positions

For several figures that need the same arrangement, it can be convenient to specify a layout in R. Matrix rows run from top to bottom and columns from left to right; "", NA, and "." leave a cell empty.

positions <- layout_matrix(rbind(
  c("", "visual", "", "", "textual", "", "", "speed", ""),
  paste0("x", 1:9)
))

positions
#>       name    x     y
#> 1   visual -5.4  0.85
#> 2  textual  0.0  0.85
#> 3    speed  5.4  0.85
#> 4       x1 -7.2 -0.85
#> 5       x2 -5.4 -0.85
#> 6       x3 -3.6 -0.85
#> 7       x4 -1.8 -0.85
#> 8       x5  0.0 -0.85
#> 9       x6  1.8 -0.85
#> 10      x7  3.6 -0.85
#> 11      x8  5.4 -0.85
#> 12      x9  7.2 -0.85

Use model variable names in the layout, even if you have changed their display labels. Every displayed node must have a coordinate. Extra rows are useful when reusing a full-model layout for a smaller diagram.

node_labels <- c(
  visual = "Visual ability",
  textual = "Textual ability",
  speed = "Processing speed"
)

A coordinate data frame is equally valid:

positions <- data.frame(
  name = c("factor", "item1", "item2", "item3"),
  x = c(0, -2, 0, 2),
  y = c(2, 0, 0, 0)
)

Increasing x moves right; increasing y moves up. Duplicate names, missing coordinates, and infinite coordinates are rejected with an error. Row-named x/y data frames and matrices are also supported. Keep spacing comparable across figures; extreme coordinate ranges can make a block appear very small.

Fonts and other styling

This example uses black lines, white nodes, and Times text. The longer factor names come from the node_labels vector above:

manuscript_style <- lvm_style(
  font_family = "Times",
  node_font_size = 11,
  edge_font_size = 9,
  latent_fill = "#FFFFFF",
  observed_fill = "#FFFFFF",
  node_color = "#000000",
  node_text_color = "#000000",
  edge_color = "#000000",
  label_color = "#000000",
  label_fill = "#FFFFFF"
)

plot_lvm(
  fit, layout = positions, diagram = "measurement",
  node_labels = node_labels, label = "std", stars = FALSE,
  theme = "classic", style = manuscript_style
)

This measurement-only figure omits factor covariances deliberately. Use diagram = "all" when they belong in the final figure. List the available themes with lvm_themes(); a theme supplies defaults, and explicit style fields override them.

The font must be available to the graphics device. Standard families such as Times, Helvetica, and Courier work with base PDF. Text widths can differ between browser, SVG, and PDF fonts, so inspect the file at the size at which it will appear in the manuscript.

For long node labels, insert \n in a named label vector to choose line breaks. Automatic wrapping is useful for variable names, but an explicit display label is more predictable for a manuscript. Increase observed_width or reduce node_font_size modestly if necessary.

Coefficient positions

When you drag a coefficient in the editor, Figure R records its position in edge_style. You can also supply the coordinates directly. For example, this places the loading label for visual to x2 beside the factor’s x-coordinate:

edge_positions <- data.frame(
  from = "visual", to = "x2", type = "loading",
  label_x = positions$x[positions$name == "visual"] + 0.45,
  label_y = mean(positions$y)
)

plot_lvm(fit, layout = positions, diagram = "measurement",
         label = "std", stars = FALSE, edge_style = edge_positions)

label_x and label_y use the same graph coordinates as the nodes, not pixels or millimetres. These positions override automatic placement and contribute to the exported plot bounds, even when they lie beyond the nodes. Automatic placement will not move a manually positioned label away from an overlap.

For graphs with parallel edges, an explicit unique edge_id can identify the edge unambiguously. Downloaded Figure R scripts retain those IDs along with the node-pair information. The same manual-position support applies to SVG, PDF, and PNG. Do not assume a TikZ export preserves all interactive label positioning; check that output separately.

Structural paths

To illustrate structural paths, add regressions among the three factors. These regressions are chosen for the plotting example, not as a substantive explanation of the relationships in the test-score data.

sem_model <- paste(cfa_model, '
  textual ~ visual
  speed ~ visual + textual
')
sem_fit <- sem(sem_model, data = HolzingerSwineford1939)

plot_lvm(sem_fit, diagram = "structural", label = "std", stars = FALSE,
         theme = "classic", style = manuscript_style)

A structural view of the fitted example, with the measurement paths omitted.

lvmPlot(sem_fit, mode = "edit", diagram = "all", label = "std",
        stars = FALSE, export_name = "structural-model")

diagram = "structural" is useful when the measurement model is described elsewhere. orientation = "left-right" can help emphasize a predictor-to-outcome sequence. A custom coordinate layout is applied after the automatic arrangement in the editor, so it remains your final placement instruction.

A parameter table

If the model was estimated elsewhere, you can supply a lavaan-style parameter table. It needs lhs, op, and rhs columns. Add est, std.all, and pvalue for the numerical labels you want to show.

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

These numbers are illustrative. In the last row, achieve ~ engage becomes an arrow from engage to achieve. Defined parameters and constraints are omitted from the graph rather than being mistaken for variables.

lvmPlot(params, mode = "edit", label = "std", stars = FALSE)

A graph without a fitted model

You can construct the graph directly when drawing a model schematic. This item-response diagram uses a1, a2, and a3 as labels rather than estimates:

irt_graph <- lvm_graph(
  nodes = data.frame(
    name = c("theta", "item1", "item2", "item3"),
    label = c("Ability", "Item 1", "Item 2", "Item 3"),
    type = c("latent", rep("observed", 3)),
    role = c("trait", rep("item", 3))
  ),
  edges = data.frame(
    from = "theta", to = paste0("item", 1:3), type = "loading",
    edge_label = c("a1", "a2", "a3")
  ),
  model_type = "irt", layout_family = "irt"
)
plot_lvm(irt_graph, label = "auto", theme = "classic")

Adapters for other fitted-model classes depend on the information available in those objects. With an unfamiliar class, inspect the $nodes and $edges returned by as_lvm_graph(your_object) to see which paths and estimates it supplies. The worked examples here use lavaan and directly constructed graphs.

Separate group diagrams

For paths shared across fitted groups, lvmPlot shows the common structure without pooling their coefficients, and issues a warning. An average of the group estimates would not be an estimate from a pooled model. To show the numbers, extract the parameter table and draw each group separately:

fit_groups <- cfa(cfa_model, data = HolzingerSwineford1939, group = "school")
pe <- parameterEstimates(fit_groups, standardized = TRUE)
group_names <- lavInspect(fit_groups, "group.label")
data.frame(group = seq_along(group_names), name = group_names)

first_group <- pe[pe$group == 1, , drop = FALSE]
second_group <- pe[pe$group == 2, , drop = FALSE]

plot_lvm(first_group, layout = positions, diagram = "all",
         label = "std", stars = FALSE)
plot_lvm(second_group, layout = positions, diagram = "all",
         label = "std", stars = FALSE)

Reuse positions so that a layout change does not distract from the coefficient differences. Put the group names in the captions or filenames, and keep each group’s significance annotations with its own estimates.