Plot stock-and-flow diagram

Visualize a stock-and-flow diagram using the R package DiagrammeR. Stocks are represented as boxes. Flows are represented as arrows between stocks and/or double circles, where the latter represent what it outside of the model boundary. Thin grey edges indicate dependencies between variables. By default, constants (indicated by italic labels) are not shown. Hover over the variables to see their equations.

Usage

# S3 method for class 'stockflow'
plot(
  x,
  vars = NULL,
  format_label = TRUE,
  wrap_width = 20,
  font_size = 18,
  font_family = default_font_family(),
  colors = NULL,
  color_dependency = "#999999",
  font_color = "black",
  show_eqn = TRUE,
  show_tooltip = TRUE,
  show_dependencies = TRUE,
  show_constants = FALSE,
  show_aux = TRUE,
  flow_length = 1,
  margin = 0.1,
  spacing = 0.5,
  direction = "LR",
  align = NULL,
  order = NULL,
  arrowhead_dependency = "open",
  ...
)

Arguments

x

A stock-and-flow model object of class stockflow.

vars

Variables to plot. Defaults to NULL to plot all variables.

format_label

If TRUE, apply default formatting (removing periods and underscores) to labels if labels are the same as variable names.

wrap_width

Width of text wrapping for labels. Must be an integer. Defaults to 20.

font_size

Font size. Defaults to 18.

font_family

Font name. Kebab-case names (e.g. "eb-garamond") are Fontsource ids (browse them at https://fontsource.org/), loaded as webfonts: no installation is needed, but internet access is required to display them. Other fonts must be installed on the system viewing the plot. Defaults to the sdbuildR.font_family option, or the "stix-two-text" webfont when the option is unset; use options(sdbuildR.font_family = ) to change the default for all plots, e.g. in your .Rprofile.

colors

Colours of the diagram variables, by variable type or variable name. A single colour applies to every variable. A named list keyed by type (list(stock = , flow = , constant = , aux = )), each entry a single colour, overrides the colour of those types and keeps the defaults for the rest (as with utils::modifyList()); the defaults are list(stock = "#83d3d4", flow = "#f48153", constant = "grey90", aux = "grey90"). A named vector (names are variable names, as in the other plot methods) recolours only those variables and leaves the rest at their type default. Stocks, constants, and auxiliaries are coloured by their node fill; flows by the coloured band of their flow arrows. Defaults to NULL (the default type colours).

color_dependency

Colour of dependency arrows. Defaults to "#999999".

font_color

Colour of variable labels (and of the equation text when show_eqn = TRUE). Defaults to "black".

show_eqn

If TRUE, show each variable's equation on a new line beneath its label, in a smaller font and the same colour as the label (font_color). The equation is prefixed by what it defines for that variable type: Initial value = for stocks, Rate = for flows, Value = for constants, and Equation = for auxiliaries. Defaults to TRUE.

show_tooltip

If TRUE, show each variable's equation as a tooltip when hovering over it. Defaults to TRUE.

show_dependencies

If TRUE, show dependencies between variables. Defaults to TRUE.

show_constants

If TRUE, show constants. Defaults to FALSE.

show_aux

If TRUE, show auxiliary variables. Defaults to TRUE.

flow_length

Minimum length of flow arrows; controls how far apart connected variables sit along the flow direction. Must be an integer. Defaults to 1.

margin

Padding around the diagram. Defaults to 0.1.

spacing

Minimum space between adjacent variables placed side by side (across the flow direction). Defaults to 0.5.

direction

Overall flow direction of the layout, passed to Graphviz's rankdir. One of "LR" (left-to-right, the default), "TB" (top-to-bottom), "RL" (right-to-left), or "BT" (bottom-to-top).

align

Optional alignment of variables across the flow direction. A character vector of variable names, or a list of such vectors. Each group is placed on the same Graphviz rank ({rank=same; ...}), so its members line up (vertically when direction = "LR", horizontally when direction = "TB"). Works for any variable (stocks, flows, auxiliaries, constants), not only stocks. Names that are not currently drawn (hidden by vars, show_constants, or show_aux) are ignored with a warning; unknown names raise an error. Defaults to NULL.

order

Optional ordering of variables along the flow direction. A character vector of variable names, or a list of such vectors, giving the desired sequence. Implemented as invisible edges between consecutive names, so it acts as a soft hint that Graphviz balances against the real flows rather than a hard constraint. On its own it sequences variables into successive ranks (e.g. separate columns when direction = "LR"); to instead line variables up in a single rank and control their order within it, combine order with align (the align group sets the rank, order sets the position within it). Same validation as align. Defaults to NULL.

arrowhead_dependency

Shape of the arrowhead on dependency arrows, passed to Graphviz's arrowhead. One of "open" (the default, an open V-shape), "normal", "vee", "diamond", "dot", "box", "crow", "curve", "inv", "tee", or "none". See https://graphviz.org/docs/attr-types/arrowType/ for illustrations.

...

Optional arguments

Value

Stock-and-flow diagram

See also

import_insightmaker(), stockflow(), plot.simulate_stockflow()

Examples

sfm <- stockflow("sir")
plot(sfm)


# Don't show constants or auxiliaries
plot(sfm, show_constants = FALSE, show_aux = FALSE)


# Only show specific variables
plot(sfm, vars = "susceptible")


# Hide the equations shown beneath each label
plot(sfm, show_eqn = FALSE)


# Hide the equation tooltips shown on hover
plot(sfm, show_tooltip = FALSE)


# Custom label colour
plot(sfm, font_color = "#333333")


# Colour every variable the same
plot(sfm, colors = "lightblue")


# Change only the stock colour; other types keep their defaults
plot(sfm, colors = list(stock = "gold"))


# Recolour a single variable
plot(sfm, colors = c(susceptible = "gold"))


# Lay the model out top-to-bottom instead of left-to-right
plot(sfm, direction = "TB")


# Align variables across the flow direction (same Graphviz rank)
plot(sfm, align = c("susceptible", "recovered"))


# Order variables along the flow direction (soft hint via invisible edges)
plot(sfm, order = c("susceptible", "infected", "recovered"))