% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plot.R
\name{plot.ensemble_stockflow}
\alias{plot.ensemble_stockflow}
\title{Plot timeseries of ensemble simulation}
\usage{
\method{plot}{ensemble_stockflow}(
  x,
  which = c("summary", "sims")[1],
  sim = seq(1, min(c(x[["n"]], 100))),
  condition = seq(1, min(c(x[["n_conditions"]], 9))),
  vars = NULL,
  order = vars,
  show_constants = FALSE,
  nrows = ceiling(sqrt(max(condition))),
  margin = 0.05,
  shareX = TRUE,
  shareY = TRUE,
  palette = "Dark 2",
  alpha = list(central = 1, spread = 0.3, sims = 0.3),
  colors = NULL,
  line_width = list(central = 3, spread = 0, sims = 1),
  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,
  central = c("mean", "median", "none"),
  spread = c("quantile", "sd", "range"),
  format_label = TRUE,
  condition_display = c("subplots", "slider", "dropdown"),
  control_options = list(),
  animation = c("none", "time"),
  webgl = getOption("sdbuildR.webgl", default = TRUE),
  ...
)
}
\arguments{
\item{x}{Output of \code{\link[=ensemble]{ensemble()}}.}

\item{which}{Type of plot. Either \code{"summary"} for a summary plot with mean or median lines and confidence intervals, or \code{"sims"} for individual simulation trajectories with mean or median lines. Defaults to \code{"summary"}.}

\item{sim}{Indices of the individual trajectories to plot if which = \code{"sims"}. Defaults to the first \code{min(n, 100)} trajectories. Including a high number of trajectories will slow down plotting considerably.}

\item{condition}{Indices of the condition(s) to plot. Defaults to 1:9.}

\item{vars}{Variables to plot. Defaults to \code{NULL} to plot all variables.}

\item{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 \code{vars}, so the order
in which variables are listed in \code{vars} is followed unless \code{order} is set
explicitly.}

\item{show_constants}{If \code{TRUE}, include constants in plot. Defaults to \code{FALSE}.}

\item{nrows}{Number of rows in the plot grid. Defaults to \code{ceiling(sqrt(max(condition)))}.}

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

\item{shareX}{If \code{TRUE}, share the x-axis across subplots. Defaults to \code{TRUE}.}

\item{shareY}{If \code{TRUE}, share the y-axis across subplots. Defaults to \code{TRUE}.}

\item{palette}{Colour palette. Must be one of hcl.pals().}

\item{alpha}{Opacity, with the same grammar as \code{line_width}: a single value, a
named per-variable vector, or a list keyed by layer (\code{central}/\code{spread}/
\code{sims}). Defaults to \code{list(central = 1, spread = 0.3, sims = 0.3)}.}

\item{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. \code{NULL} uses \code{palette}. Defaults to \code{NULL}.}

\item{line_width}{Line width(s). The plot draws three layers: the central
tendency line (\code{central}), the uncertainty band's border (\code{spread}), and the
individual trajectories (\code{sims}). Supply a single value (used for every
layer and variable), a named per-variable vector (names are variable names;
unnamed values fill in plot order), or a list keyed by layer
(\code{list(central = , spread = , sims = )}) whose elements are themselves a
single value or per-variable vector. Unspecified layers/variables fall back
to the defaults. Defaults to \code{list(central = 3, spread = 0, sims = 1)}
(a \code{spread} width of \code{0} draws no band border).}

\item{line_type}{Dash style of the plotted lines. Each value is one of
\code{"solid"}, \code{"dot"}, \code{"dash"}, \code{"longdash"}, \code{"dashdot"}, \code{"longdashdot"}, or
a pixel pattern such as \code{"5px,10px"}. Supply a single style for every
variable (\code{line_type = "dash"}), a named vector to style variables
individually (\code{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
(\code{line_type = list(stock = "solid", flow = "dash")}; the types are \code{stock},
\code{flow}, \code{aux}, \code{constant}, and \code{lookup}). By default stocks, flows, and
auxiliaries are solid and constants and lookups are dashed.}

\item{font_family}{Font family. Kebab-case names (e.g. \code{"eb-garamond"})
are Fontsource ids (browse them at \url{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 \code{sdbuildR.font_family} option, or
the \code{"stix-two-text"} webfont when the option is unset; use
\code{options(sdbuildR.font_family = )} to change the default for all plots,
e.g. in your .Rprofile.}

\item{font_size}{Font size. Defaults to 16.}

\item{wrap_width}{Width of text wrapping for labels. Must be an integer. Defaults to 25.}

\item{show_legend}{Whether to show legend. Must be TRUE or FALSE. Defaults to TRUE.}

\item{label_subplots}{Whether to plot labels indicating the condition of the subplot.}

\item{central}{Which central-tendency line to draw, given as preferences in
order: the first one that \code{\link[=ensemble]{ensemble()}} computed is used. For example,
\code{c("mean", "median")} draws the mean if it is available, otherwise the
median, and \code{"none"} draws no line. Defaults to \code{c("mean", "median", "none")}.}

\item{spread}{Which uncertainty band to draw, again as ordered preferences:
\code{"quantile"} (between the lowest and highest quantile), \code{"sd"} (the central
line plus/minus one standard deviation), \code{"range"} (between \code{min} and
\code{max}), or \code{"none"}. The first band the computed statistics can support is
used; \code{"sd"} also needs a central line. Defaults to \code{c("quantile", "sd", "range")}.}

\item{format_label}{If \code{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
\code{TRUE}.}

\item{condition_display}{How to display multiple conditions. Use \code{"subplots"}
to show conditions as panels, \code{"slider"} to select one condition with a
slider, or \code{"dropdown"} to select one condition with a dropdown. Defaults
to \code{"subplots"}. If only a single condition is available (e.g. no
conditions were varied), \code{"slider"} and \code{"dropdown"} fall back to
\code{"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.}

\item{control_options}{Named list fine-tuning the \code{"slider"}/\code{"dropdown"}
condition control and the \code{animation = "time"} animation. For the
condition control it supports \code{max_labels}: the maximum number of
slider tick labels to keep visible when many conditions are varied (the
slider always keeps one step per condition; intermediate labels are thinned
above this count); and \code{spacing}: the vertical gap (in pixels) between the
tops of stacked controls when several condition parameters are varied. By
default the spacing and the reserved bottom margin are sized automatically
so the controls never overlap each other or the x-axis title; pass a number
to widen or tighten the gap. For the animation it supports \code{frame_ms}:
the duration of each frame in milliseconds (default \code{100}); \code{duration}:
the total animation length in seconds, as an alternative to \code{frame_ms}
(supplying both is an error); \code{transition_ms}: the transition time between
frames in milliseconds (default \code{0}); and \code{max_frames}: the maximum number
of animation frames (default \code{50}). Defaults to \code{list()}, i.e. all
defaults.}

\item{animation}{Animation mode. Use \code{"none"} for a static plot or \code{"time"}
to cumulatively reveal trajectories over time. Defaults to \code{"none"}.
Time animation requires \code{which = "sims"} (confidence ribbons cannot be
animated) and a single condition (one panel); combining it with
\code{condition_display} controls or multiple conditions is not supported.}

\item{webgl}{If \code{TRUE}, render trajectories with WebGL (plotly \code{scattergl}) for
performance with many lines; if \code{FALSE}, use SVG (\code{scatter}). Defaults to
\code{getOption("sdbuildR.webgl", default = TRUE)}. Set
\code{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 (\code{fill_flows = TRUE}) or time animations; these always
render with SVG \code{scatter} regardless of \code{webgl}.}

\item{...}{Optional parameters}
}
\value{
Plotly object
}
\description{
Visualize ensemble simulation results of a stock-and-flow model. Either summary statistics or individual trajectories can be plotted. When multiple conditions j are specified, a grid of subplots is plotted. See \code{\link[=ensemble]{ensemble()}} for examples.
}
\section{Styling variables and layers}{

Names in \code{colors}, \code{alpha}, and \code{line_width} refer to the model variable
names, not the labels shown in the legend. For example, use \code{infected}, not
\code{Infected}, even when \code{format_label = TRUE} changes the legend text.

A single value applies everywhere:
\code{plot(sims, line_width = 3, alpha = 0.7)}.

A named vector styles selected variables and leaves the rest at their
defaults:
\code{plot(sims, colors = c(infected = "firebrick"), line_width = c(infected = 4))}.

Ensemble plots also have layers. Use a list to style the central tendency
line, the uncertainty band border, and individual trajectories separately:
\code{plot(sims, which = "sims", line_width = list(central = 3, sims = 1, spread = 0))}.

List elements can be named vectors too, which is useful when only one layer
needs variable-specific styling:
\code{plot(sims, alpha = list(central = 1, sims = c(infected = 0.15), spread = 0.25))}.

The \code{spread} line width controls the border of the uncertainty band. The
default is \code{0}, so the band is filled but not outlined.
}

\seealso{
\code{\link[=ensemble]{ensemble()}}
}
\concept{ensemble}
