% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/PM_post.R
\name{plot.PM_post}
\alias{plot.PM_post}
\title{Plot PM_post Prediction Data}
\usage{
\method{plot}{PM_post}(
  x,
  include = NULL,
  exclude = NULL,
  line = list(join = TRUE),
  marker = FALSE,
  out_names = NULL,
  mult = 1,
  icen = "median",
  outeq = 1,
  block = 1,
  overlay = TRUE,
  legend = FALSE,
  log = FALSE,
  grid = FALSE,
  xlab = "Time",
  ylab = "Output",
  title = "",
  print = TRUE,
  xlim,
  ylim,
  ...
)
}
\arguments{
\item{x}{The name of a \link{PM_post}  object, e.g. \code{NPex$post}.
in a \link{PM_result} object}

\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{line}{Controls characteristics of lines as for all plotly plots.
It can either be a boolean or a list. If set to \code{TRUE} or
a list of plotly line attributes, it
will generate line segments joining observations. If set to
\code{FALSE}, no segments will be generated.
Line colors are fixed to match marker colors for group displays and cannot be overridden.
Other customizable line properties are:
- \code{width} Width of the segments, default 1.
- \code{dash} See \code{plotly::schema()}, traces > scatter > attributes >
line > dash > values. Default is "solid".
- \code{join} Set to \code{TRUE} (default) to join markers with lines, or \code{FALSE} for markers only.
Example: \code{line = list(width = 2, dash = "longdash", join = FALSE)}}

\item{marker}{Formats the symbols plotting observations. 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))}

Marker colors control group display colors. When multiple output equations are displayed
(via \code{outeq}), \code{marker$color} can be a palette name from \code{RColorBrewer::brewer.pal.info} or
a vector of colors. Line colors are automatically matched to marker colors.}

\item{out_names}{A character vector of names to label the output equations if \code{legend = TRUE}.
Must be at least as long as the maximum value in \code{outeq}.
Example: \code{c("Conc A", "Conc B")} if \code{outeq = c(1, 2)}.}

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

\item{icen}{Can be \code{"median"} for predictions based on the median of the parameter
value distributions, or \code{"mean"}. Default is \code{"median"}.
Only a single value is accepted; \code{outeq} is the sole grouping dimension.}

\item{outeq}{Which output equation to plot. Default is 1.
Default is 1, but can be multiple if present in the data, e.g. \code{1:2} or \code{c(1, 3)}.}

\item{block}{Which block to plot, where blocks are defined by dose reset events (EVID = 4) in the data.
Default is 1, but can be multiple if present in the data, as for \code{outeq}.}

\item{overlay}{Operator to overlay all time prediction profiles in a single plot.
The default is \code{TRUE}. If \code{FALSE}, will trellisplot subjects one at a time. Can also be
specified as a vector with number of rows and columns, e.g. \code{c(3, 2)} for 3 rows and
2 columns of subject splots to include in each trellis.}

\item{legend}{Not used for this plot.}

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

\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{print}{If \code{TRUE}, will print the plotly object and return it. If \code{FALSE}, will only return the plotly object.}

\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{...}{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 object.
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}}

Plots \link{PM_post} objects
}
\details{
This is a function usually called by the \verb{$plot()} method for \link{PM_post} objects
within a \link{PM_result} to generate the plot.
However, the function can be called directly on a \link{PM_post} object.
This function will plot time and posterior predictions with a variety of options.
Markers are omitted by default. When enabled, markers have default plotly properties:
\code{list(symbol = "circle", color = "red", size = 10, opacity = 0.5, line = list(color = "black", width = 1))}.
Markers can be joined by lines, with default \code{line = list(join = TRUE)}.
When joined, line colors are automatically matched to marker colors.
The joining lines have the following default properties:
\code{list(color = "dodgerblue", width = 1, dash = "solid")}.
The grid and legend are omitted by default.
}
\examples{
\dontrun{
# basic spaghetti plot
NPex$post$plot()
# format line and marker
NPex$post$plot(
  marker = list(color = "blue", symbol = "square", size = 12, opacity = 0.4),
  line = list(color = "orange")
)
}
}
\seealso{
\link{PM_post}, \link{PM_result}

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_pta]{plot.PM_pta()}},
\code{\link[=plot.PM_sim]{plot.PM_sim()}},
\code{\link[=plot.PM_valid]{plot.PM_valid()}}
}
\author{
Michael Neely
}
\concept{PMplots}
