% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/PM_pta.R
\name{plot.PM_pta}
\alias{plot.PM_pta}
\title{Plot PM_pta Percent Target Attainment objects}
\usage{
\method{plot}{PM_pta}(
  x,
  at = "intersect",
  include,
  exclude,
  type = "pta",
  mult = 1,
  outeq = 1,
  line = TRUE,
  marker = TRUE,
  ci = 0.9,
  legend = TRUE,
  log = FALSE,
  grid = TRUE,
  xlab,
  ylab,
  title,
  xlim,
  ylim,
  print = TRUE,
  ...
)
}
\arguments{
\item{x}{The name of an \emph{PM_pta} data object}

\item{at}{Which object in the \emph{PM_pta} result list to plot. By default "intersect" if
an intersection is present due to creation of the object with multiple target types, or
1 if no intersection is present, which means only 1 target type was selected. If
"intersect" is present in the object, the default can be overridden with a number to
plot one of the individual PTAs, e.g. \code{at = 2} to plot the second PTA rather than the
intersection of all the PTAs.}

\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{type}{Character vector controlling type of plot.
Default is "pta", which plots proportion with success on the y-axis and target on the x-axis.
The other choice is "pdi", which plots the median pdi (pharmacodynamic index), e.g. AUC/MIC, on the
y-axis, and target on the x-axis.}

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

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

\item{line}{Controls characteristics of lines.
This argument maps to the plotly line object.
It can be boolean or a list.
\code{TRUE} will plot the line with default characteristics for each simulated regimen.
\code{FALSE} will suppress line plotting.
If a list, it functions a little differently than other Pmetrics plotly functions.
Rather than controlling individual line characteristics, for this plot,
the \code{line} argument should be a list of the options for group based plotting,
where each group corresponds to a simulated regimen. The possible elements of the
\code{line} list should be exactly named:
\itemize{
\item color Maps to the \link[plotly:plot_ly]{plot_ly} \code{colors} argument to override default colors
applied to the lines for each regimen. This can be a named palette, which
can be obtained with \code{RColorBrewer::display.brewer.all()} or a vector of hexadecimal
color names. One way to ensure reliable color palettes is to use the
\href{https://colorbrewer2.org/#type=qualitative&scheme=Accent&n=6}{ColorBrewer} site.
Choosing the number of data classes to correspond to regimens, and qualitative data
results in a distinct palette. Easiest importing into R is to copy/paste the Export
of JavaScript on the ColorBrewer website. The default is "Set1". Palettes
with fewer colors than regimens will be recycled. A color can also be a character
vector of color names, recycled as needed. For example, a print-friendly choice
is \code{line = list(color = "black")}.
\item width Maps to the \link[plotly:plot_ly]{plot_ly} \code{width} argument to override default widths
applied to the lines for each regimen. All lines will have the same width.
The default value is 2.
\item dash Maps to the \link[plotly:plot_ly]{plot_ly} \code{linetypes} argument to override default styles
applied to the lines for each regimen. If numeric, will map to \code{lty} \link{par} values.
It can also be a character vector of dash names as listed in \link[plotly:plot_ly]{plot_ly}.
Example: \code{line = list(color = "Blues", width = 1, dash = 2)}, which will result
in dotted lines (dash  = 2) all with width 1 but in different shades of blue.
}}

\item{marker}{Controls the plotting symbol.
This argument maps to the plotly marker object.
It can be boolean or a list.
\code{TRUE} will plot the profiles with default characteristics for each simulated regimen.
\code{FALSE} will suppress line plotting.
If a list, it functions a little differently than other Pmetrics plotly functions.
Rather than controlling individual marker characteristics, for this plot,
the \code{marker} argument should be a list of the options for group based plotting,
where each group corresponds to a simulated regimen. The possible elements of the
\code{marker} list should be exactly named:
\itemize{
\item color Default marker color is the same as the line color. If line color is specified,
marker color does not need to also be specified. Even if line plotting is suppressed
with \code{line = F}, the default color value of "Set1" will be applied to markers,
unless specified, e.g. \code{marker = list(color = "Blues")}.
\item symbol Maps to the \link[plotly:plot_ly]{plot_ly} \code{symbols} argument to override default symbols
applied to the markers for each regimen. If only one value is supplied for this,
it will be recycled for each regimen, i.e. all will have the same symbol.
See \code{plotly::schema()}, traces > scatter > attributes > marker > symbol > values
for options.
\item size Maps to the \link[plotly:plot_ly]{plot_ly} \code{size} argument to override default size
applied to the markers for each regimen. All markers will have the same size.
The default value is 12.
}}

\item{ci}{Confidence interval around curves on \code{type = "pdi"} plot, on scale of 0 to 1. Default is 0.9.}

\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 will be the labeled regimen names as an argument
when creating a \link{PM_pta} object,
or if missing, "Regimen 1, Regimen 2,...Regimen n", where \emph{n} is the number of
regimens in the PM_pta object.}

\item{log}{Boolean operator to plot the x axis in log base 10. This argument maps to
the xaxis type value in the layout object in plotly. Many other Pmetrics plots map this
argument to the y axis, but for PTA plots, the x axis is the more common axis to log transform.
Use the plotly \code{plotly::schema()} command in the console and navigate to layout > layoutAttributes > xaxis > 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 "Target" when targets are discrete,
and "Regimen" when targets are sampled.}

\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 "Proportion with success" for
plot \code{type = "pta"} and "Pharmacodynamic Index" for plot \code{type = "pdi"}.}

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

This function will plot the percent target attainment for associated with
simulations.
}
\details{
\link{PM_pta} objects are made with the \verb{$pta} method for \link{PM_sim}  or
with \code{PM_pta$new()}.
}
\examples{
\dontrun{
pta1 <- simEx$pta(
  simlabels <- c("600 mg daily", "1200 mg daily", "300 mg bid", "600 mg bid"),
  targets = c(0.25, 0.5, 1, 2, 4, 8, 16, 32), target.type = "time",
  success = 0.6, start = 120, end = 144
)
pta1$summary()
pta1$plot()
}
}
\seealso{
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_sim]{plot.PM_sim()}},
\code{\link[=plot.PM_valid]{plot.PM_valid()}}
}
\author{
Michael Neely
}
\concept{PMplots}
