Plot verify results

Visualize the simulation(s) used during verify(). Each condition is one simulation run – the model with one set of parameter overrides (from unit_test(conditions = ), possibly none) – shared by every unit test declaring those overrides. Each condition is displayed as a subplot (or a slider/dropdown step, see condition_display), labelled by its overrides and the test(s) evaluated on it: e.g. "rate = 0 (test 2)", with the unmodified run labelled "Baseline (tests 1, 3)" (or just "Tests 1, 3" when no test varies anything). Simulations are always available since verify() unconditionally retains them.

Usage

# S3 method for class 'verify_stockflow'
plot(
  x,
  test = NULL,
  vars = NULL,
  order = vars,
  show_constants = FALSE,
  label = NULL,
  ignore_case = TRUE,
  status = c("pass", "fail", "error", "skip"),
  condition = seq(1, min(c(x[["n_conditions"]], 9))),
  nrows = ceiling(sqrt(max(condition))),
  shareX = TRUE,
  shareY = TRUE,
  palette = "Dark 2",
  colors = NULL,
  line_width = 2,
  line_type = list(stock = "solid", flow = "solid", aux = "solid", constant = "dash",
    lookup = "dash"),
  font_family = getOption("sdbuildR.font_family", default = "stix-two-text"),
  font_size = 16,
  wrap_width = 25,
  show_legend = TRUE,
  label_subplots = TRUE,
  alpha = 1,
  margin = 0.05,
  format_label = TRUE,
  condition_display = c("subplots", "slider", "dropdown"),
  control_options = list(),
  animation = c("none", "time"),
  webgl = getOption("sdbuildR.webgl", default = TRUE),
  ...
)

Arguments

x

Output of verify().

test

Integer vector of test numbers to plot. Combines with label and status as AND intersection.

vars

Variable names to retain in the data frame. Only applies when which = "sims". Defaults to NULL to include 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.

show_constants

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

label

Character vector of regex patterns for partial, case-insensitive label matching. A test is included if its label matches any pattern.

ignore_case

Logical; whether label matching is case-insensitive. Default TRUE.

status

Optional character vector of statuses to include (e.g., c("fail", "error")). Defaults to all statuses.

which = "tests": filters rows by test status.
which = "sims": filters to conditions that have at least one test with a matching status.

condition

Integer vector of condition numbers to plot. Defaults to 1:9. If only one condition is specified, the plot will not be a grid of subplots.

nrows

Number of subplot rows. Defaults to ceiling(sqrt(max(condition))).

shareX

Share the x-axis across subplots. Defaults to TRUE.

shareY

Share the y-axis across subplots. Defaults to TRUE.

palette

Colour palette (see hcl.pals()). Defaults to "Dark 2".

colors

Colours for the plotted variables. A named vector (names are variable names) recolours only those variables, the palette fills the rest; an unnamed vector assigns colours in plot order. Defaults to NULL.

line_width

Line width of the trajectories. Either a single value, 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.

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

Label wrap width. Defaults to 25.

show_legend

Whether to show the legend. Defaults to TRUE.

label_subplots

Whether to title each subplot with its condition's parameter overrides (or "Baseline") and test number(s), e.g. "rate = 0 (test 2)". Defaults to TRUE.

alpha

Trajectory opacity, between 0 and 1. A single value or a named per-variable vector. Defaults to 1.

margin

Margin between subplots. Either a single numeric or a vector of length four(left, right, top, bottom). See ?plotly::subplot() for more details. Defaults to 0.05.

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.

condition_display

How to display multiple conditions. Use "subplots" to show conditions as panels, "slider" to select one condition with a slider, or "dropdown" to select one condition with a dropdown. Defaults to "subplots". If only a single condition is available (e.g. no conditions were varied), "slider" and "dropdown" fall back to "subplots" with a message. To guarantee the control geometry, plots with a slider/dropdown have a fixed height (sized to the number of controls) instead of a responsive one.

control_options

Named list fine-tuning the "slider"/"dropdown" condition control and the animation = "time" animation; see plot.ensemble_stockflow() for the supported options (max_labels, spacing, frame_ms, duration, transition_ms, max_frames). Defaults to list(), i.e. all defaults.

animation

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

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.

...

Additional arguments passed to plot.simulate_stockflow().

Value

A plotly object.

Styling variables

Names in colors, line_width, and alpha refer to the model variable names, not the labels shown in the legend. This keeps the styling stable if labels are formatted or wrapped for display.

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

Use named vectors to style selected variables: plot(res, colors = c(susceptible = "#377EB8"), alpha = c(infected = 0.4)).

Unnamed vectors are applied in plot order. Named vectors are usually clearer, especially when vars, test, label, or status filters change what is drawn.

Examples

sfm <- stockflow("sir") |>
  unit_test(expr = all(susceptible >= 0)) |>
  unit_test(expr = all(infected >= 0), conditions = list(infected = 100))
res <- verify(sfm)
plot(res)


# Select one condition at a time with a slider or dropdown
plot(res, condition_display = "slider")

plot(res, condition_display = "dropdown")


# Animate the simulation over time (one condition at a time)
plot(res, animation = "time", condition = 1)

Usage

Arguments

Value

Styling variables

See also

Examples