Package {diy.sem.plot}

Manually plot path diagrams for structural equation models

Description

Plot fully customisable path diagrams for structural equation models fitted with lavaan, rendered using ggplot2.

To render the ggplot object of the diagram, the function only requires users to supply a fitted lavaan model, specify node positions using x-y coordinates, and detail where on the perimeter of each node (top, bottom, left, or right) each path should begin and end. The render automatically inserts estimates centred on the midpoint and adjusts each node's shape to match its variable type. A range of optional fine-tuning arguments are included, facilitating the creation of a path diagram exactly as you envision it, entirely within R.

Usage

diyPaths(
  fit,
  node_positions,
  path_positions,
  standardised = FALSE,
  digits = 3,
  est_stars = FALSE,
  est_p = FALSE,
  est_ci = FALSE,
  variance_stars = FALSE,
  variance_p = FALSE,
  variance_ci = FALSE,
  sig_linetype = FALSE,
  p_threshold = 0.05,
  show_variances = FALSE,
  show_grid = FALSE,
  grid_axis_scale = 1,
  non_transparent_text = TRUE,
  latent_node_text_size = 4,
  observed_node_text_size = 4,
  path_text_size = 3.5,
  line_thickness = 0.6,
  arrow_size = 0.2,
  node_width = 1.5,
  node_height = 1,
  latent_node_size_adjust = 1,
  observed_node_size_adjust = 1,
  show_group_labels = FALSE,
  panel_titles = NULL,
  panel_cols = NULL,
  margin_x = 0.5,
  margin_y = 0.5,
  look_up_table = FALSE,
  panel_notes = NULL,
  note_text_size = NULL,
  title_text_size = NULL,
  font_family = "",
  title_note_font_family = NULL
)

Arguments

Details

The easiest way to start is with template(), which prints ready-to-run code for your fitted model. Edit the node positions and path sides it generates, render with diyPaths(), then fine-tune and re-render until the layout looks right. See vignette("diy.sem.plot") for worked examples.

Value

A ggplot (or patchwork, for multi-group models) object representing the SEM path diagram(s). If look_up_table = TRUE, a list containing the diagram(s) (⁠$plot⁠) and a look-up data.frame of node width/height and text sizes for latent, observed, and path labels (⁠$look_up_table⁠).

See Also

template() to generate starting code for node_positions, path_positions, panel_titles and panel_notes; node(), path(), panel_title(), and panel_note() for the helper functions used within them.

Examples

#full SEM example, this model may not make theoretical sense.

library(lavaan)
library(ggplot2)

data(HolzingerSwineford1939, package = "lavaan")

#specify the model

sem_model <- '
  visual  =~ x1 + x2 + x3
  textual =~ x4 + x5 + x6
  speed   =~ x7 + x8 + x9

  speed ~ visual + textual
  visual ~~ textual
'

#fit the model

fit <- sem(sem_model, data = HolzingerSwineford1939)

#generate a starting template

temp <- template(fit = fit, diyPaths_arguments = "max", quiet = TRUE)

#### edited template ####

node_list <- list(
  node(name = "visual", x = 1, y = 1, label = "Visual"),
  node(name = "textual", x = 1, y = 2, label = "Textual"),
  node(name = "speed", x = 4, y = 1.5, label = "Speed"),
  node(name = "x1", x = -0.06, y = -0.5, label = "Visual\nPerception"),
  node(name = "x2", x = 1, y = -0.5, label = "Cubes"),
  node(name = "x3", x = 2.06, y = -0.5, label = "Lozenges"),
  node(name = "x4", x = -0.06, y = 3.5, label = "Paragraph\nComprehension"),
  node(name = "x5", x = 1, y = 3.5, label = "Sentence\nCompletion"),
  node(name = "x6", x = 2.06, y = 3.5, label = "Word\nMeaning"),
  node(name = "x7", x = 6, y = 0.5, label = "Speeded\nAddition"),
  node(name = "x8", x = 6, y = 1.5, label = "Speeded\nCounting"),
  node(name = "x9", x = 6, y = 2.5, label = "Speeded\nDiscrimination")
)

path_list <- list(
  # regression paths
  path(from = "visual", to = "speed", side_from = "right", side_to = "left"),
  path(from = "textual", to = "speed", side_from = "right", side_to = "left"),

  # loading paths
  path(from = "visual", to = "x1", side_from = "bottom", side_to = "top", nudge_text_x = -0.1),
  path(from = "visual", to = "x2", side_from = "bottom", side_to = "top"),
  path(from = "visual", to = "x3", side_from = "bottom", side_to = "top", nudge_text_x = 0.1),
  path(from = "textual", to = "x4", side_from = "top", side_to = "bottom", nudge_text_x = -0.1),
  path(from = "textual", to = "x5", side_from = "top", side_to = "bottom"),
  path(from = "textual", to = "x6", side_from = "top", side_to = "bottom", nudge_text_x = 0.1),
  path(from = "speed", to = "x7", side_from = "right", side_to = "left"),
  path(from = "speed", to = "x8", side_from = "right", side_to = "left"),
  path(from = "speed", to = "x9", side_from = "right", side_to = "left"),

  # covariance/correlation paths
  path(from = "visual", to = "textual", side_from = "left", side_to = "left", cov_curve = -0.6)
)

title_list <- list(
  panel_title(panel_num = 1, title = "My SEM Plot")
)

note_list <- list(
  panel_note(panel_num = 1, note_text = "Standardised estimates shown.")
)

p <- diyPaths(fit = fit, node_positions = node_list, path_positions = path_list,
              standardised = TRUE,
              digits = 3,
              est_stars = TRUE,
              est_p = FALSE,
              est_ci = FALSE,
              show_variances = FALSE,
              variance_stars = FALSE,
              variance_p = FALSE,
              variance_ci = FALSE,
              sig_linetype = FALSE,
              p_threshold = 0.05,
              panel_titles = title_list,
              panel_notes = note_list,
              show_grid = TRUE,
              grid_axis_scale = 0.5,
              non_transparent_text = TRUE,
              latent_node_text_size = 4,
              observed_node_text_size = 3,
              path_text_size = 3.5,
              line_thickness = 0.6,
              arrow_size = 0.2,
              node_width = 1.5, node_height = 1,
              latent_node_size_adjust = 0.8,
              observed_node_size_adjust = 0.55,
              show_group_labels = FALSE,
              panel_cols = NULL,
              font_family = "sans",
              title_note_font_family = "serif",
              margin_x = 0.5,
              margin_y = 0.5,
              look_up_table = TRUE)

print(p)

Create a node position list

Description

Helper function that creates a list of arguments which specify a given node's position and its label in the diagram, designed for use within the node_positions argument of diyPaths().

Usage

node(name, x = 0, y = 0, label = NULL)

Arguments

Value

A list containing arguments that specify a node's position and label, for use within the node_positions argument of diyPaths().

See Also

path() to specify the paths between nodes; diyPaths() to render the diagram; template() to generate a starting node_positions list.

Examples

#a list that specifies a node positioned on x = 1, y = 2,
#and relabelled from its `lavaan` model name.

node(name = "bpm", x = 1, y = 2,  label = "Beats per Minute")

Create a note for a diyPaths panel

Description

Helper function that creates a list of arguments which specify a custom note, displayed as a caption beneath its target panel, designed for use within the panel_notes argument of diyPaths(). Use the show_group_labels argument in diyPaths() to view each panel's number and which group it refers to.

Usage

panel_note(panel_num, note_text = NULL)

Arguments

Value

A list containing arguments that specify a panel's note text, for use within the panel_notes argument of diyPaths().

See Also

diyPaths(), where the list of notes is passed to panel_notes; panel_title() for adding titles to panels; template(), whose output includes a starting note list.

Examples

# a note on the first panel noting sample size was 100.
panel_note(panel_num = 1, note_text = "n = 100")

# a note on the second panel of a multi-group model noting sample size for Group 2 was 50
panel_note(panel_num = 2, note_text = "Group 2: n = 50")

Create a title for a diyPaths panel

Description

Helper function that creates a list of arguments which specify a custom title and its target panel, designed for use within the panel_titles argument of diyPaths(). Use the show_group_labels argument in diyPaths() to view each panel's number and which group it refers to.

Usage

panel_title(panel_num = 1, title = NULL)

Arguments

Value

A list containing arguments that specify a panel's number and title, for use within the panel_titles argument of diyPaths().

See Also

diyPaths(), where the list of titles is passed to panel_titles; panel_note() for adding notes to panels; template(), whose output includes a starting title list.

Examples

# titling a single, non-grouped model
panel_title(title = "My SEM Model")

# titling the second panel of a multi-group model
panel_title(panel_num = 2, title = "Female Participants")

Create a path position list

Description

Helper function that creates a list of arguments which specify a given path's position and fine-tuning adjustments, designed for use within the path_positions argument of diyPaths().

Usage

path(
  from,
  to,
  side_from = "right",
  side_to = "left",
  cov_curve = NULL,
  nudge_text_x = 0,
  nudge_text_y = 0,
  variance_position = "top"
)

Arguments

Details

from/to in path() must exactly match the variable name used in the lavaan model syntax. Furthermore, the order must also be correct for regression or loading paths. A misspelled or mismatched path() entry will not raise an error, instead, it will use default attachment points and values, not applying specific customisations. This can be completely avoided using template().

cov_curve controls the curvature of covariance/correlation paths: its size sets how strongly the path bends, and its sign sets which way. If a path bends the wrong way, flip the sign. Best results typically range from -1 to 1.

Value

A list containing arguments that specify a path's position and fine-tuning adjustments, for use within the path_positions argument of diyPaths().

See Also

node() to specify node positions; diyPaths() to render the diagram; template() to generate a starting path_positions list.

Examples

#a list that specifies a regression path of node "anxiety" predicting node "depression".

path(from = "anx", to = "dep", side_from = "right", side_to = "left")

#a list that specifies a covariance/correlation path of node "anxiety" and node "depression".
#Order of "from" and "to" does not matter for covariance/correlation.


path(from = "dep", to = "anx", side_from = "left", side_to = "left", cov_curve = -0.6)

Create a template for use in diyPaths

Description

Takes your fitted model and prints a ready-to-run starting template (node list, path list, title list, note list, and diyPaths() call) to the console. Copy the output into your script, then fine-tune the diagram by adjusting values in the lines marked ⁠#EDIT ME!⁠

The template is also returned invisibly as a character string, so it can be stored as an object then viewed with writeLines() (see examples).

Usage

template(
  fit,
  include_variance_paths = TRUE,
  diyPaths_arguments = c("max", "min"),
  quiet = FALSE
)

Arguments

Value

Invisibly returns the template as a single character string. Unless quiet = TRUE, it is also printed to the console.

See Also

diyPaths() to render the diagram from the template; node(), path(), panel_title(), and panel_note() for the helper functions the template uses.

Examples

library(lavaan)

data(HolzingerSwineford1939, package = "lavaan")


#specify the model

sem_model <- '
  visual  =~ x1 + x2 + x3
  textual =~ x4 + x5 + x6
  speed   =~ x7 + x8 + x9

  speed ~ visual + textual
  visual ~~ textual
'

#fit the model

fit <- sem(sem_model, data = HolzingerSwineford1939)

#print the maximal template to the console

# template(fit = fit, include_variance_paths = TRUE, diyPaths_arguments = "max", quiet = FALSE)

#store the template without printing it, then view it

tmpl <- template(fit = fit, diyPaths_arguments = "min", quiet = TRUE)
writeLines(tmpl)