% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/PM_sim.R
\name{plot.PM_sim}
\alias{plot.PM_sim}
\title{Plot Pmetrics Simulation Objects}
\usage{
\method{plot}{PM_sim}(
  x,
  include,
  exclude,
  mult = 1,
  ci = 0.95,
  binSize = 0,
  outeq = 1,
  line = TRUE,
  marker = FALSE,
  obs,
  quiet = FALSE,
  legend = FALSE,
  log = TRUE,
  grid = FALSE,
  xlab,
  ylab,
  title,
  xlim,
  ylim,
  print = TRUE,
  ...
)
}
\arguments{
\item{x}{The name of an \emph{PM_sim} data object generated by \link{PM_sim}}

\item{include}{A vector of subject IDs to include in the plot, e.g. c(1:3,5,15)
.}

\item{exclude}{A vector of subject IDs to exclude in the plot, e.g. c(4,6:14,16:20)
.}

\item{mult}{Multiplication factor for y axis, e.g. to convert mg/L to ng/mL}

\item{ci}{Width of confidence interval bands around simulated quantiles,
from 0 to 1.  If 0, or \emph{nsim}<100, will not plot.
Default is 0.95, i.e. 95th percentile with tails of 2.5 percent above and below excluded.}

\item{binSize}{Width of binning interval for simulated concentrations, in time units, e.g. hours.
A \code{binSize} of 0.5 will pull all simulated concentrations +/- 0.5 hours into
the same time.  This is useful
for plotting PMsim objects made during \link{make_valid}. The default is 0, i.e. no binning.
If an \code{obs} object is provided, it will be binned similarly.}

\item{outeq}{Which output equation to plot. Default is 1.}

\item{line}{Controls the appearance of lines. It can be specified in several ways.
\itemize{
\item Default is \code{TRUE} which results in simulated profiles summarized
as quantiles, with default values of 0.05, 0.25, 0.5, 0.75, and 0.95. The default
format will be applied, which is solid black lines of width 1.
Numerical predictive checking will be calculated if observations are also included
(see \emph{obs} below).
\item \code{FALSE} results in no lines plotted and the plot will be blank.
\item \code{NA} Quantile summaries will be suppressed, but lines joining simulated outputs
will be plotted in default format as above. In other words, all profiles will be plotted,
not just the quantiles. Numerical predictive checking will be suppressed.
\item List of quantiles and formats to plot with the following elements:
\itemize{
\item \code{probs} Vector of quantiles to include. If missing, will be set to
defaults above, i.e., \verb{c(0.05, 0.5, and 0.95)}
Example: \code{line = list(probs = c(0.25, 0.5, 0.75))}.
\item \code{color} Vector of color names whose order corresponds to \code{probs}.
If shorter than \code{probs}, will be recycled. Default is "dodgerblue", but if
median is present (\code{prob = 0.5}), that line will be "red".
Examples: \code{line = list(color = "red")} or \code{line = list(color = c("red", "blue"))}.
\item \code{fill} Fill color between quantile lines. Can be specified in several ways:
\itemize{
\item \code{FALSE} (the default) will not fill between lines.
\item \code{TRUE} will fill between lines with a default color of "dodgerblue", opacity 0.2.
\item A list with the following elements:
\itemize{
\item \code{color} Fill color name. Default is "dodgerblue", e.g., \code{fill = list(color = "red")}.
\item \code{opacity} Fill opacity. Default is 0.2 e.g., \code{fill = list(opacity = 0.3)}.
\item \code{probs} Vector of paired quantiles to fill between. Default is the minimum and maximum
quantile specified in \code{probs}, or \code{fill = list(probs = c(0.05, 0.95))} if not specified.
Including \code{probs} in fill which are not in \code{probs} above will result in an error.
}
}
\item \code{width} Vector of widths in pixels, as for \code{color}. Default is 1.
Example: \code{line = list(width = 2)}.
\item \code{dash} Vector of dash types, as for color. Default is "solid".
See \code{plotly::schema()}, traces > scatter > attributes > line > dash > values.
Example: \code{line = list(dash = "dashdot")}.
}
}}

\item{marker}{Controls the plotting symbol for observations.  This argument maps to the plotly marker object. It can be boolean or a list. \code{TRUE} will plot the marker with default characteristics. \code{FALSE} will suppress marker plotting. If a list, can control many marker characteristics, including overriding defaults. Use the plotly \code{plotly::schema()} command in the console and navigate to traces > scatter > attributes > marker to see all the ways the marker can be formatted. Most common will be: \itemize{ \item{\code{color}} Marker color. \item{\code{symbol}} Plotting character. See \code{plotly::schema()}, traces > scatter > attributes > marker > symbol > values. \item{\code{size}} Character size in points. \item{\code{opacity}} Ranging between 0 (fully transparent) to 1 (fully opaque). \item{\code{line}} A list of  additional attributes governing the outline for filled shapes, most commonly color and width. }

Example: \code{marker = list(color = "red", symbol = "triangle", opacity = 0.8, line = list(color = "black", width = 2))}
Formatting will only be applied to observations
if included via the \code{obs} argument.}

\item{obs}{The name of a \link{PM_result} data object or the PM_op field in the
PM_result object, all generated by \link{PM_load}.  For example, if
\code{run1 <- PM_load(1)} and \code{sim1} is a PM_sim object, then
\code{sim1$plot(obs = run1)} or \code{sim1$plot(obs = run1$op)}.
If specified,
the observations will be overlaid upon the simulation plot
enabling a visual predictive check.  In this case,
a list object will be returned with two items: $npc containing the quantiles
and probability that the observations
are below each quantile (binomial test); and $simsum, the times of each
observation and the
value of the simulated quantile with upper and lower confidence intervals at that time.
Additionally, the number of observations beyond the 5th and 95th percentiles will be reported
and the binomial test P-value if this number is different than the expected 10\% value.}

\item{quiet}{If \code{TRUE}, suppresses the message about simulation report generation, defaults to \code{FALSE}.}

\item{legend}{Controls display of legend. This argument maps to the plotly layout showlegend and legend arguments. It is either a boolean operator (most common) or a list of parameters to be supplied to plotly. See \code{plotly::schema()} > layout > layoutAttributes > legend and showlegend for more details on the available options for formatting.  If legend is supplied as a list,  the plotly layout > layoutAttributes > showlegend value will be set to \code{TRUE} automatically.

Examples: \itemize{ \item{\code{legend = T}} \item{\code{legend = list(orientation = "h", font = list(color = "blue"))}} }
Default is \code{FALSE}}

\item{log}{Boolean operator to plot the y axis in log base 10. This argument maps to the   yaxis type value in the layout object in plotly.  Use the plotly \code{plotly::schema()} command in the console and navigate to layout > layoutAttributes > yaxis > type.

Example: \code{log = T}
Default is \code{TRUE}.}

\item{grid}{Controls grid display. This argument maps to the xaxis and yaxis layout objects in plotly.  Use the plotly \code{plotly::schema()} command in the console and navigate to layout > layoutAttributes > xaxis or yaxis > gridcolor or gridwidth. It is a Boolean operator. If \code{FALSE}, no grid is plotted.  If \code{TRUE}, the default color \emph{grey} and width 1 will be plotted at  major tick marks. If a list, color and width can be customized.

Examples: \itemize{ \item{\code{grid = F}} \item{\code{grid = list(gridcolor = "black", gridwidth = 2)}} }
Default is \code{FALSE}}

\item{xlab}{Value for x axis label. This argument maps to the the xaxis title element of the layout object in plotly.  It can simply be a character vector of length 1 that specifies the name of  the axis, or it can be a list for greater control. Use the plotly \code{plotly::schema()} command in the console and navigate to layout > layoutAttributes > xaxis > title to see the ways to customize this axis label. In addition to the plotly attributes, a custom Pmetrics attribute \code{bold}  may be included as a list element, either on its own or within the font list. The default for \code{bold} is \code{TRUE}.

Examples: \itemize{ \item{\code{xlab = "Time (h)"}} \item{\code{xlab = list(text = "Time", bold = F, font = list(color = "red", family = "Arial", size = 10))}} \item{\code{xlab = list(text = "Time", font = list(bold = T))}} }
Default is "Time".}

\item{ylab}{Value for y axis label. This argument maps to the the yaxis title element of the layout object in plotly.  See \code{xlab} for details. If \code{xlab} is specified as a list with formatting, and \code{ylab} is simply a character label, then the formatting for the  \code{xlab} will be applied to the \code{ylab}. To format \code{ylab} independently, specify a formatting list as for \code{xlab}.

Default is "Output".}

\item{title}{Plot title. This argument maps to the the title layout object in plotly.  It can simply be a character vector of length 1 that specifies the name of  the plot title, or it can be a list for greater control. Use the plotly \code{plotly::schema()} command in the console and navigate to layout > layoutAttributes > title to see other ways to customize the title using lists as additional arguments. In addition to the plotly attributes, a custom Pmetrics attribute \code{bold}  may be included as a list element. The default for \code{bold} is \code{TRUE}.

Examples: \itemize{ \item{\code{title = "Observed vs. Predicted"}} \item{\code{title = list(text = "Raw Data", font = list(color = "red", family = "Arial", size = 10, bold = T))}} }
Default is to have no title.}

\item{xlim}{Limits of the x axis as a vector.   This argument maps to the   the xaxis range in the layout object in plotly.  Use the plotly \code{plotly::schema()} command in the console and navigate to layout > layoutAttributes > xaxis > range.

Example: \code{xlim = c(0,1)}}

\item{ylim}{Limits of the y axis as a vector.   This argument maps to the   the yaxis range in the layout object in plotly.  Use the plotly \code{plotly::schema()} command in the console and navigate to layout > layoutAttributes > yaxis > range.

Example: \code{ylim = c(0,100)}}

\item{print}{If \code{TRUE}, will print the plotly object and return it. If \code{FALSE}, will only return the plotly object.}

\item{...}{Other attributes which can be passed to the layout > xaxis/yaxis  in a plotly plot to further control formatting.  Note that \code{log}, \code{xlab}, \code{ylab}, \code{xlim}, and \code{ylim} are  all controlled by the layout object, but are provided throughout Pmetrics plotly function arguments as shortcuts that map to layout elements.  Therefore, the dots argument should be used to specify other aspects of the  x axis, y axis, or both. See \code{plotly::schema()} layout > layoutAttributes  > xaxis/yaxis for options. To add to single axis, name it as a list.  If attributes are specified without an enclosing xaxis or yaxis list,  they will be applied to both axes.

Examples:  \itemize{ \item{\code{NPex$data$plot(xaxis = list(tickcolor = "black", tickfont = list(family = "Arial", size = 14, color = "black"))) #applies to x axis only}} \item{\code{NPex$data$plot(linecolor = "red", ticks = "inside") #applies to both axes}} }  .}
}
\value{
Plots the simulation object.  If \code{obs} is included, a list will be returned with
the folowing items:
\itemize{
\item \emph{npc} A dataframe with three columns: quantile, prop_less, pval.
** \emph{quantile} are those specified by the \code{probs} argument to the plot call
** \emph{prop_less} are the proportion of simulated
observations at all times less than the quantile
** \emph{pval} is the P-value of the difference in the
prop.less and quantile by the beta-binomial test.
\item \emph{simsum} A dataframe with the quantile concentration at each simulated time,
with lower and upper confidence intervals
\item \emph{obs} A data frame similar to a the \verb{$data} field of a \link{PM_op} object
with the addition of the quantile for each observation
}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}}

Plots \emph{PM_sim} objects with the option to perform a visual and numerical predictive check
}
\details{
Simulated observations are plotted as quantiles on the y-axis vs. time on the x.axis.  If measured
observations are included, a visual and numerical predictive check will be performed.
The default plot is to omit markers, but if the marker argument is set to \code{TRUE},
the resulting marker will have the following plotly properties:
\code{list(symbol = "circle-open", color = "black", size = 8)}. By default a grid is
omitted. The legend is also omitted by default, but if included,
clicking on a quantile item in the legend will hide it in the plot,
and double clicking will hide all other quantiles.
}
\examples{
\dontrun{
simEx$plot()
simEx$plot(log = FALSE, line = list(color = "orange"))
}
}
\seealso{
\link{PM_sim}, \link[plotly:plot_ly]{plot_ly}, \link[plotly:schema]{schema}

Other PMplots:
\code{\link[=plot.PM_cov]{plot.PM_cov()}},
\code{\link[=plot.PM_cycle]{plot.PM_cycle()}},
\code{\link[=plot.PM_data]{plot.PM_data()}},
\code{\link[=plot.PM_final]{plot.PM_final()}},
\code{\link[=plot.PM_model]{plot.PM_model()}},
\code{\link[=plot.PM_op]{plot.PM_op()}},
\code{\link[=plot.PM_opt]{plot.PM_opt()}},
\code{\link[=plot.PM_pop]{plot.PM_pop()}},
\code{\link[=plot.PM_post]{plot.PM_post()}},
\code{\link[=plot.PM_pta]{plot.PM_pta()}},
\code{\link[=plot.PM_valid]{plot.PM_valid()}}
}
\author{
Michael Neely
}
\concept{PMplots}
