model_diagram: Hierarchical model diagramming

In modeldiagramR: Generate Model Diagrams for Linear Mixed Effect Models

Hierarchical model diagramming

Description

model_diagram() takes a hierarchical nested model and returns a DiagrammeR object visualizing the fixed and random effects structure.

Usage

model_diagram(
  modelObject,
  filePath = NULL,
  fileType = "PNG",
  width = 800,
  height = 1600,
  includeSizes = TRUE,
  includeLabels = TRUE,
  orientation = "vertical",
  scaleFontSize = 1,
  shiftFixed = 0,
  shiftRandom = 0,
  nodeColors = md_color(diagram = "gray25", random = "gray25", fixed = "gray25"),
  nodeFillColors = md_fill(diagram = "aliceblue", random = "aliceblue", fixed =
    "darkseagreen1"),
  nodeFontColors = md_fontColor(diagram = "black", random = "black", fixed = "black"),
  exportObject = 1
)

Arguments

modelObject	Input model. Either a lme or merMod (including glmerMod) object with a nested random effects structure.
filePath	Optional. Path to a location to export the diagram. Default is NULL.
fileType	Optional. File type to export the diagram. Default is "PNG".
width	Optional. Width of diagram in pixels. Default is 800.
height	Optional. Height of diagram in pixels. Default is 1600.
includeSizes	Optional. Include group sizes in random effect labels. Default is TRUE.
includeLabels	Optional. Include labels for the model diagram components. Default is TRUE.
orientation	Optional. Orientation of the diagram, either vertically or horizontally. Options are "vertical", "horizontal". Default is "vertical".
scaleFontSize	Optional. Proportional font size adjustment for model diagram component, fixed effect, and random effect labels. Multiplies these label font sizes by the specified amount. Default is 1.
shiftFixed	Optional. Additive x-axis adjustment for fixed effect labels, only used when orientation == "horizontal". Default is 0.
shiftRandom	Optional. Additive x-axis adjustment for random effect labels, only used when orientation == "horizontal". Default is 0.
nodeColors	Optional. Function specifying the colors (md_color()) for the outline of the nodes. Components can be specified individually (diagram, random, and fixed).
nodeFillColors	Optional. Function specifying the colors (md_fill()) for the fill color of the nodes. Components can be specified individually (diagram, random, and fixed).
nodeFontColors	Optional. Function specifying the colors (md_fontColor()) for the font color of text in the nodes. Components can be specified individually (diagram, random, and fixed).
exportObject	Optional. Object(s) to return, 1 for a rendered DiagrammeR graph as an SVG document, 2 for a dgr_graph object, and 3 returns a list containing both objects. Default is 1.

Details

NOTE: When including this function in an RMD document and knitting to PDF, the graphic size variables width and height do not currently work. It is recommended that instead the image is exported to a file such as a PDF and then reimported to the document. See the examples below.

Value

A rendered DiagrammeR graph as an SVG document (default), or a dgr_graph object, or a list containing both (dgr_graph_obj, rendered_graph_obj).

References

Greta M. Linse, Mark C. Greenwood, Ronald K. June, Data-Driven Model Structure Diagrams for Hierarchical Linear Mixed Models, J. data sci.(2026), 1-21, DOI 10.6339/26-JDS1222

Examples

# merMod object example
library(lme4)

sleepstudy_lmer <- lmer(Reaction ~ Days + (Days | Subject), sleepstudy)
summary(sleepstudy_lmer)
model_diagram(sleepstudy_lmer)

# lme object example
library(nlme)

sleepstudy_lme <- lme(Reaction ~ Days, random=~Days|Subject, data=sleepstudy)
summary(sleepstudy_lme)
model_diagram(sleepstudy_lme)


library(rsvg) # required to produce a PDF file
temp_path <- tempfile("sleepstudy_lmer_modeldiagram", fileext=".pdf")
# Knitting to PDF example
model_diagram(sleepstudy_lmer,
               filePath= temp_path,
               fileType="PDF")

modeldiagramR documentation built on April 15, 2026, 5:07 p.m.