% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/PM_valid.R
\name{plot.PM_valid}
\alias{plot.PM_valid}
\title{Plot Pmetrics Validation Objects}
\usage{
\method{plot}{PM_valid}(
  x,
  type = "vpc",
  tad = FALSE,
  outeq = 1,
  line = TRUE,
  marker = TRUE,
  legend = FALSE,
  log = FALSE,
  grid = TRUE,
  xlab,
  ylab,
  title,
  xlim,
  ylim,
  print = TRUE,
  ...
)
}
\arguments{
\item{x}{The name of an \emph{PM_valid} data object, which is usually called by
the \verb{$validate} method for \link{PM_result}
objects.}

\item{type}{Default is "vpc" for a visual predictive check, but could be
"pcvpc" for a prediction-corrected visual predictive check, or
"npde" for a normalized prediction distribution error analysis/plot.
Choosing npde will call \link[npde:plot.NpdeObject]{npde::plot.NpdeObject}. To modify this plot,
supply argmuents as a named list: \code{npde = (...)}. Available arguments
are in the user manual for the \href{https://github.com/ecomets/npde30}{npde package}.}

\item{tad}{Boolean operator to use time after dose rather than time after start.  Default is \code{FALSE}.}

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

\item{line}{A list of three elements \verb{$upper}, \verb{$mid}, and \verb{$lower},
each of which controls characteristics of corresponding quantiles.
The arguments to each of these list elements map to several plotly attributes.
Each can be a boolean value or a list.
\code{TRUE} will plot default characteristics. \code{FALSE} will suppress quantile plots.
The elements of the list for each argument are as follows:
\itemize{
\item \code{value} The quantile value. Default for lower is 0.025, mid is 0.5,
and upper is 0.975.
\item \code{color} The color for both the 95\%CI region around simulated quantile vs. time,
and the color of the line for the observation quantile vs. time.
Default for lower and upper is "dodgerblue" and for mid it is "red".
\item \code{dash} The style of the obervation quantile line.
See \code{plotly::schema()}, traces > scatter > attributes > line > dash > values.
Default for lower and upper is "dash" and for mid it is "solid".
\item \code{width} Default is 1 for lower, mid, and upper.
\item \code{opacity} The opacity of the 95\%CI region around simulated quantile vs. time.
Default is 0.4 for lower, mid and upper,
but can range between 0 (fully transparent) to 1 (fully opaque).
Example: \code{line = list(upper = list(value = 0.9, color = "red", dash = "longdash", opacity = 0.5, width = 2))}
}}

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

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

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

\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" or "Time after dose" if \code{tad = TRUE}.}

\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{\dots}{If \code{type} is not "npde", the following apply. 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}} }  .
.
However, if \code{type} is "npde", to modify the appearance of the plot,
supply a list of options, \code{npde = list(...)}. See the documentation
for the \code{type} argument above.}
}
\value{
Plots and returns the plotly object
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}}
Usually called by the \verb{$plot} method for \link{PM_valid} objects, which are in turn typically added
to a \link{PM_result} object by the \verb{$validate} method. For example:

\if{html}{\out{<div class="sourceCode">}}\preformatted{   NPex$validate(limits = c(0, 3)) # creates a PM_valid object and adds it to the $valid field of NPex
   NPex$valid$plot(type = "vpc", tad = TRUE, log = TRUE) # now we can plot it
}\if{html}{\out{</div>}}

Plot \link{PM_valid} objects.
}
\details{
Generates a plot of outputs (typically concentrations) on the y axis and time
on the x axis. If \code{tad} was set to \code{TRUE}
when \link{make_valid} was called, then time may be either absolute (default) or time
after dose, controlled by the \code{tad} argument to this plot function.
The following items are included in the plot:
\itemize{
\item Observed outputs. These may be either as measured for \code{type = "vpc"} or
prediction corrected for \code{type = "pcvpc"}. Format of the observations is
controlled by the \code{marker} argument. The default is
\code{list(color = "black", symbol = "circle-open", size = 8)}.
\item Quantiles vs. time for observations. These are plotted by default as dashed
blue lines for the 2.5th and 97.5th percentiles and a solid red line for the
median. Formatting and the value for each quantile can be controlled
with the \code{upper}, \code{mid}, and \code{lower} arguments.
\item 95\% CI around the same quantiles of combined simulations from each subject.
The values and formatting for these quantile CIs are the same as for the observations,
and also controlled with the \code{upper}, \code{mid}, and \code{lower} arguments.
}

Good vpc/pcvpc plots are considered to be those where the quantile lines for
the oberservations lie within the 95\%CI quantile regions for simulations,
indicated that the model is "centered" on the data and faithfully captures the
variability in the data. For an npde plot, one expects to see approximately
normally distributed normalized prediction errors.
}
\examples{
\dontrun{
# VPC
NPex$valid$plot()

# pcVPC
NPex$valid$plot(type = "pcvpc")

# modify median line and marker
NPex$valid$plot(
  line = list(mid = list(color = "orange", dash = "dashdot")),
  marker = list(
    color = "blue", size = 12, symbol = "diamond",
    line = list(color = "navy")
  )
)
}
}
\seealso{
\link{make_valid}

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_sim]{plot.PM_sim()}}
}
\author{
Michael Neely
}
\concept{PMplots}
