% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/PM_final.R
\name{plot.PM_final}
\alias{plot.PM_final}
\title{Plot Pmetrics Final Cycle Parameter Value Distributions}
\usage{
\method{plot}{PM_final}(
  x,
  formula = NULL,
  line,
  marker = TRUE,
  standardize,
  legend,
  log,
  grid = TRUE,
  xlab,
  ylab,
  zlab,
  title,
  xlim,
  ylim,
  print = TRUE,
  ...
)
}
\arguments{
\item{x}{The name of an \link{PM_final} data object as a field in a \link{PM_result} R6
object, e.g \code{PM_result$final}.}

\item{formula}{An optional formula of the form \code{y ~ x}, where \code{y} and \code{x}
are two model parameters to plot in a 3-dimensional bivariate plot.  See details.}

\item{line}{Controls characteristics of lines. This argument maps to plotly line attributes. \code{TRUE} will plot default lines. \code{FALSE} will suppress lines. If a list, can control many line characteristics, including overriding defaults. Use the plotly \code{plotly::schema()} command in the console and navigate to traces > scatter > attributes > line to see all the ways the line can be formatted. Most common will be:  \itemize{ \item{\code{color}} Line color. \item{\code{dash}} Plotting character. See \code{plotly::schema()}, traces > scatter >  attributes > line > dash > values. \item{\code{width}} Thickness in points. }

Example: \code{line = list(color = "red", dash = "longdash", width = 2)}
The \code{line} argument is used to format:
\itemize{
\item the density line drawn over an NPAG \link{PM_final} object. Default is \code{FALSE},
which means no density line will be drawn. Use \code{TRUE} to draw the default line,
which is black, solid, and of width 1, or specify as a list to control these
elements, e.g. \code{line = list(color = "red", width = 2, dash = "dash")}
\item the drop lines from point to lower surface when a \code{formula} is specified
to generate a bivariate plot from an NPAG \link{PM_final} object.
In this case, default is \code{line = TRUE}. The default
format is black, dashed, and of width 1.
\item the lines drawing the normal distribution of parameter values from an IT2B \link[=PM_final]{PM_Final} object.
Again, here the default is \code{line = TRUE}, and the format is black, solid, of width 1.
See \link{density}.  Ignored for IT2B output.
}}

\item{marker}{See details for which objects the \code{marker} argument controls.
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} Fill color for NPAG bars, marker color for bivariate NPAG plots.
Ignored for IT2B plots.
\item \code{symbol} Plotting character. See \code{plotly::schema()}, traces > scatter >
attributes > marker > symbol > values. Only relevant for bivariate NPAG plots.
\item \code{size} Character size in points. Only relevant for bivariate NPAG plots.
\item \code{opacity} Bar fill color for univariate NPAG plots or marker opacity for
bivariate NPAG plots. Ignored for IT2B plots.
Ranges between 0 (fully transparent) to 1 (fully opaque).
\item \code{line} A list of  additional attributes governing the outline for bars in
univariate NPAG plots or markers in bivariate NPAG plots. Ignored for IT2B plots.
\itemize{
\item \code{color} Outline color. Default is "black".
\item \code{width} Outline width. Default is 1.
Example: \code{marker = list(color = "red", symbol = "triangle", opacity = 0.8, line = list(color = "black", width = 2))}
}
}}

\item{standardize}{Standardize the normal parameter distribution plots from IT2B to the same
scale x-axis.  Ignored for NPAG output.}

\item{legend}{Ignored 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 the name of the plotted x-variable.
Formatting can be controlled, but the text is recommended to not be changed.}

\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 "Probability" for univariate plots,
and the name of the plotted y-variable for bivariate plots.
Formatting can be controlled, but the text is recommended to not be changed.}

\item{zlab}{Only for bivariate plots. Default is "Probability". Can be a list
to control formatting or default text, as for \code{xlab} and \code{zlab}.}

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

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

Plot R6 \link{PM_final} objects loaded as a field in the
\link{PM_result} object, e.g. \code{PM_result$final}.
}
\details{
This is a function usually called by the \verb{$plot()} method for \link{PM_final} objects
within a \link{PM_result} to generate a plot the parameter value probability densities
after completion of a model fitting.
The function can be called directly on a \link{PM_final} object.

If \code{formula} is omitted, this will generate a marginal plot for each parameter.
For NPAG data, this will be a histogram of marginal values for each parameter and the associated probability
of that value.  For IT2B, this will be a series of normal distributions with mean and standard deviation
equal to the mean and standard deviation of each parameter marginal distribution.

On the other hand, if \code{formula} is specified as two parameters, e.g. CL~V, this will generate a bivariate plot.
For NPAG data, it will be support point with size proportional to the probability
of each point.  For IT2B, it will be an elliptical distribution of a bivariate normal distribution centered at the mean
of each plotted variable and surrounding quantiles of the bivariate distribution plotted in decreasing shades of grey.
Mulitvariate normal density code is borrowed from the mvtnorm package.
}
\examples{
\dontrun{
# NPAG
NPex$final$plot()
NPex$final$plot(line = TRUE)
NPex$final$plot(Ke ~ V)
# IT2B
ITex$final$plot()
ITex$final$plot(Ke ~ V)
}
}
\seealso{
\link{PM_final}, \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_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}
