% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plot.R
\name{plot.simulate_stockflow}
\alias{plot.simulate_stockflow}
\title{Plot timeseries of simulation}
\usage{
\method{plot}{simulate_stockflow}(
  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{
\item{x}{Output of \code{\link[=simulate.stockflow]{simulate()}}.}

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

\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{palette}{Colour palette. Must be one of hcl.pals().}

\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 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 \code{2}.}

\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{vars_display}{How to arrange saved variables. Use \code{"vstack"} to stack
stocks above flows, auxiliaries, constants, and lookups; \code{"hstack"} to put
stocks beside non-stock variables; or \code{"joint"} to draw all variables in
one panel. If only one variable group is available, a single panel is
drawn. Defaults to \code{"vstack"}.}

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

\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 \code{TRUE} or \code{FALSE}. Defaults to \code{TRUE}.}

\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{animation}{Animation mode. Use \code{"none"} for a static plot or \code{"time"}
to cumulatively reveal trajectories over time. Defaults to \code{"none"}.}

\item{control_options}{Named list fine-tuning the speed and smoothness of
the \code{animation = "time"} animation. 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}; lower it for a chunkier reveal that also
shortens the animation at a fixed \code{frame_ms}). Defaults to \code{list()}, i.e.
all defaults.}

\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 simulation results of a stock-and-flow model. Plot the evolution of stocks over time, with the option of also showing other model variables.
}
\section{Styling variables}{

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

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

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

\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)

\dontshow{if (Sys.getenv("NOT_CRAN") == "true") withAutoprint(\{ # examplesIf}
# 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"))
\dontshow{\}) # examplesIf}
}
\seealso{
\code{\link[=simulate.stockflow]{simulate()}}, \code{\link[=as.data.frame.simulate_stockflow]{as.data.frame.simulate_stockflow()}}, \code{\link[=plot.simulate_stockflow]{plot.simulate_stockflow()}}
}
\concept{simulate}
