% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/PM_cov.R
\name{plot.PM_cov}
\alias{plot.PM_cov}
\title{Plot Pmetrics Covariate objects}
\usage{
\method{plot}{PM_cov}(
  x,
  formula,
  line = list(lm = NULL, loess = NULL, ref = NULL),
  marker = TRUE,
  colors,
  icen = "median",
  include = NULL,
  exclude = NULL,
  legend,
  log = FALSE,
  grid = TRUE,
  xlab,
  ylab,
  title,
  stats = TRUE,
  xlim,
  ylim,
  print = TRUE,
  ...
)
}
\arguments{
\item{x}{The name of an \link{PM_cov} data object
and loaded with \link{PM_load} as a \link{PM_result}, e.g. \code{PM_result$cov}.}

\item{formula}{This is a mandatory formula of the form \code{y ~ x}, where \code{y} and \code{x}
are the two \code{data} parameters to plot.}

\item{line}{Controls characteristics of lines. Unlike
some other Pmetrics plots, but like \link{plot.PM_op}, \code{line} is a list of
three elements:
\itemize{
\item \code{lm}  If set to \code{TRUE} or a list of plotly line attributes,
will generate a linear regression of the form y ~ x
Line attributes will control the appearance of the regression
line and the confidence interval around the line. If set to
\code{FALSE}, no linear regression will be generated. The default
values for the elements of the \code{lm} list, all of which can be
overriden are:
\itemize{
\item \code{ci} Confidence interval around the regression, default 0.95.
\item \code{color} Color of the regression line and the confidence area around
the line, but at opacity = 0.2. Default is "dodgerblue".
\item \code{width }Width of the regression line, default 1.
\item \code{dash} See \code{plotly::schema()}, traces > scatter > attributes >
line > dash > values. Default is "solid".
Example: \code{line = list(lm = list(color = "red", dash = "longdash", width = 2))}
}
\item \code{loess} If set to \code{TRUE} or a list of plotly line attributes,
will generate a loess regression of the form y ~ x
The list elements and default values in the \code{loess} list are the
same as for \code{lm} except the default style is "dash".
Example: \code{line = list(lm = FALSE, loess = TRUE)}
\item \code{ref} If set to \code{TRUE} or a list of plotly line attributes,
will generate a reference line with slope = 1 and intercept = 0.
The default values for the elements of the \code{ref} list are:
\itemize{
\item \code{color} "grey".
\item \code{width} 1.
\item \code{dash} "dot".
Note that there is no \emph{ci} argument for the \emph{ref} list.
Example: \code{line = list(lm = FALSE, loess = TRUE, ref = list(color = "lightgrey"))}
If the \code{line} argument is missing, it will be set to
\code{line = list(lm = FALSE, loess = TRUE, ref = FALSE)}, i.e. there will be a linear
regression with reference line, but no loess regression.
If \emph{time} is chosen as the x variable in the formula, linear, loess and reference
lines will be suppressed, although formatting specified in the loess line (except color,
see below) will be applied to the lines joining the subject values.
}
}}

\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))}
Default is
\code{marker = list(color = orange, shape = "circle", size = 10, opacity = 0.5, line = list(color = black, width = 1))}.}

\item{colors}{to use for subjects when \emph{time} is set as the x parameter.
This can be a palette or a vector of colors.
For accepted palette names see \code{RColorBrewer::brewer.pal.info}. Examples include
"BrBG", or "Set2". An example vector could be \code{c("red", "green", "blue")}. It is not
necessary to specify the same number of colors as groups within \code{color}, as colors
will be interpolated to generate the correct number. The default
is the "Spectral" palette. This will override any color in the \code{marker} or \code{line}.}

\item{icen}{Can be either "median" for the predictions based on medians of\code{pred.type}  parameter value distributions, or "mean".  Default is "median".}

\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{legend}{Not used for this function.}

\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))}} }
If missing, will default to the name of the
x variable in the formula.}

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

If missing, will default to the name of the
y variable in the formula.}

\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{stats}{Add the statistics from linear regression to the plot. If
\code{FALSE}, will be suppressed. Default is \code{TRUE} which results in default format of
\code{list(x= 0.8, y = 0.1, bold = F, font = list(color = "black", family = "Arial", size = 14))}.
The coordinates are relative to the plot with lower left = (0,0), upper right = (1,1). This
argument maps to \code{plotly::add_text()}.}

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

Plot PMcov objects
}
\details{
This method will plot any two columns, specified using a formula, of a PMcov object, which contains covariate and Bayesian posterior parameter information
for each subject.  Specifiying any two variables that do not include time will result in a scatter plot with optional regression and reference lines.  If
time is included as the x variable, the y variable will be plotted vs. time, aggregated by subject.  This can be useful to see time varying parameters,
although a formula within formula approach may be required, e.g. \verb{$plot(I(cl_0*wt**0.75) ~ time)} in order to see the change in cl over time according to
the change in wt over time, even though cl_0 is constant for a given subject.
}
\examples{
#'
\dontrun{
NPex$cov$plot(V ~ wt)
NPex$cov$plot(Ke ~ wt, line = list(lm = TRUE, ref = FALSE, loess = FALSE))
NPex$cov$plot(Ke ~ wt, line = list(loess = list(ci = 0.9, color = "green")))
NPex$cov$plot(V ~ time, marker = list(color = "blue"))
NPex$cov$plot(V ~ wt,
  line = list(lm = TRUE, loess = FALSE),
  stats = list(x = 0.5, y = 0.2, font = list(size = 7, color = "blue"))
)
}
}
\seealso{
\link{PM_cov}, \link{PM_result}, \link[plotly:schema]{schema}

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