Plot timeseries of simulation

Visualize simulation results of a stock-and-flow model. Plot the evolution of stocks over time, with the option of also showing other model variables.

Usage

# S3 method for class 'simulate_stockflow'
plot(
  x,
  show_constants = FALSE,
  vars = NULL,
  order = vars,
  palette = "Dark 2",
  colors = NULL,
  line_width = 2,
  line_type = list(stock = "solid", flow = "solid", aux = "solid", constant = "dash",
    lookup = "dash"),
  vars_display = c("vstack", "hstack", "joint"),
  fill_flows = TRUE,
  font_family = getOption("sdbuildR.font_family", default = "stix-two-text"),
  font_size = 16,
  wrap_width = 25,
  show_legend = TRUE,
  format_label = TRUE,
  animation = c("none", "time"),
  control_options = list(),
  webgl = getOption("sdbuildR.webgl", default = TRUE),
  ...
)

Arguments

x

Output of simulate().

show_constants

If TRUE, include constants in plot. Defaults to FALSE.

vars

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

order

Character vector of model variable names giving the trace and legend order. Listed variables appear first; any plotted variables not listed keep their default relative order. Defaults to vars, so the order in which variables are listed in vars is followed unless order is set explicitly.

palette

Colour palette. Must be one of hcl.pals().

colors

Colours for the plotted variables. A named vector (names are variable names) sets the colours of those variables and the palette fills the rest, so you can recolour only a few variables. An unnamed vector assigns colours in plot order. NULL uses palette. Defaults to NULL.

line_width

Line width of the plotted trajectories. Either a single value applied to all variables, a named per-variable vector (names are variable names), or an unnamed vector with one value per variable in plot order. Defaults to 2.

line_type

Dash style of the plotted lines. Each value is one of "solid", "dot", "dash", "longdash", "dashdot", "longdashdot", or a pixel pattern such as "5px,10px". Supply a single style for every variable (line_type = "dash"), a named vector to style variables individually (line_type = c(S = "solid", I = "dot")), an unnamed vector in plot order, or a list keyed by variable type to style each type at once (line_type = list(stock = "solid", flow = "dash"); the types are stock, flow, aux, constant, and lookup). By default stocks, flows, and auxiliaries are solid and constants and lookups are dashed.

vars_display

How to arrange saved variables. Use "vstack" to stack stocks above flows, auxiliaries, constants, and lookups; "hstack" to put stocks beside non-stock variables; or "joint" to draw all variables in one panel. If only one variable group is available, a single panel is drawn. Defaults to "vstack".

fill_flows

If TRUE, flow traces are filled down to zero. Auxiliaries, constants, and lookups are never filled. Defaults to TRUE. Filled flows always render with SVG scatter, as WebGL does not support fills (see webgl).

font_family

Font family. 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.

font_size

Font size. Defaults to 16.

wrap_width

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

show_legend

Whether to show legend. Must be TRUE or FALSE. Defaults to TRUE.

format_label

If TRUE, apply default formatting (replacing periods and underscores with spaces) to variable labels that are the same as the variable name. Applies to the legend and any condition controls. Defaults to TRUE.

animation

Animation mode. Use "none" for a static plot or "time" to cumulatively reveal trajectories over time. Defaults to "none".

control_options

Named list fine-tuning the speed and smoothness of the animation = "time" animation. Supports frame_ms: the duration of each frame in milliseconds (default 100); duration: the total animation length in seconds, as an alternative to frame_ms (supplying both is an error); transition_ms: the transition time between frames in milliseconds (default 0); and max_frames: the maximum number of animation frames (default 50; lower it for a chunkier reveal that also shortens the animation at a fixed frame_ms). Defaults to list(), i.e. all defaults.

webgl

If TRUE, render trajectories with WebGL (plotly scattergl) for performance with many lines; if FALSE, use SVG (scatter). Defaults to getOption("sdbuildR.webgl", default = TRUE). Set options(sdbuildR.webgl = FALSE) (e.g. in vignettes or dashboards, or when a plot renders blank) to disable WebGL globally. WebGL is not supported for filled flow traces (fill_flows = TRUE) or time animations; these always render with SVG scatter regardless of webgl.

...

Optional parameters

Value

Plotly object

Styling variables

Names in colors, line_width, and line_type refer to the model variable names, not the labels shown in the legend.

Use one value to style every trajectory: plot(sim, line_width = 3).

Use a named vector to style selected variables and leave the rest at their defaults or palette colours: plot(sim, colors = c(susceptible = "#377EB8"), line_width = c(infected = 4)).

See also

simulate(), as.data.frame.simulate_stockflow(), plot.simulate_stockflow()

Examples

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


# When all variables are saved in the output, the stocks are plotted 
# separately from the other variables by default:
sim_all <- simulate(sfm, only_stocks = FALSE)
plot(sim_all)


# Plot all variables in one panel:
plot(sim_all, vars_display = "joint")


# Animate the simulation over time:
plot(sim_all, animation = "time")


# Slow the animation down to ~10 seconds in total, or speed up the
# individual frames
plot(sim, animation = "time", control_options = list(duration = 10))

plot(sim, animation = "time", control_options = list(frame_ms = 40))


## Styling options
# The default plot title and axis labels can be changed like so:
plot(sim, main = "Simulated trajectory", xlab = "Time", ylab = "Value")


# Add constants to the plot
plot(sim, show_constants = TRUE)


# Plot selected variables:
plot(sim, vars = c("susceptible", "infected"))