Skip to contents

Plot PM_pop Prediction Data

Source: R/PM_pop.R
plot.PM_pop.Rd

[Stable]

Plots PM_pop objects

Usage

# S3 method for class 'PM_pop'
plot(
  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 = "",
  xlim,
  ylim,
  print = TRUE,
  ...
)

Arguments

x

The name of a PM_pop object, e.g. NPex$pop. in a PM_result object

include

A vector of subject IDs to include in the plot, e.g. c(1:3,5,15)

exclude

A vector of subject IDs to exclude in the plot, e.g. c(4,6:14,16:20)

line

Controls characteristics of lines as for all plotly plots. It can either be a boolean or a list. If set to TRUE or a list of plotly line attributes, it will generate line segments joining observations. If set to 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: - width Width of the segments, default 1. - dash See plotly::schema(), traces > scatter > attributes > line > dash > values. Default is "solid". - join Set to TRUE (default) to join markers with lines, or FALSE for markers only. Example: line = list(width = 2, dash = "longdash", join = FALSE)

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. TRUE will plot the marker with default characteristics. FALSE will suppress marker plotting. If a list, can control many marker characteristics, including overriding defaults. Use the plotly 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:

  • color Marker color.

  • symbol Plotting character. See plotly::schema(), traces > scatter > attributes > marker > symbol > values.

  • size Character size in points.

  • opacity Ranging between 0 (fully transparent) to 1 (fully opaque).

  • line A list of additional attributes governing the outline for filled shapes, most commonly color and width.

Example: 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 outeq), marker$color can be a palette name from RColorBrewer::brewer.pal.info or a vector of colors. Line colors are automatically matched to marker colors.

out_names

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

mult

Multiplication factor for y axis, e.g. to convert mg/L to ng/mL

icen

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

outeq

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

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 outeq.

overlay

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

legend

Not used for this plot.

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 plotly::schema() command in the console and navigate to layout > layoutAttributes > yaxis > type.

Example: log = T

grid

Controls grid display. This argument maps to the xaxis and yaxis layout objects in plotly. Use the plotly plotly::schema() command in the console and navigate to layout > layoutAttributes > xaxis or yaxis > gridcolor or gridwidth. It is a Boolean operator. If FALSE, no grid is plotted. If TRUE, the default color grey and width 1 will be plotted at major tick marks. If a list, color and width can be customized.

Examples:

  • grid = F

  • grid = list(gridcolor = "black", gridwidth = 2)

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 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 bold may be included as a list element, either on its own or within the font list. The default for bold is TRUE.

Examples:

  • xlab = "Time (h)"

  • xlab = list(text = "Time", bold = F, font = list(color = "red", family = "Arial", size = 10))

  • xlab = list(text = "Time", font = list(bold = T))

Default is "Time".

ylab

Value for y axis label. This argument maps to the the yaxis title element of the layout object in plotly. See xlab for details. If xlab is specified as a list with formatting, and ylab is simply a character label, then the formatting for the xlab will be applied to the ylab. To format ylab independently, specify a formatting list as for xlab.

Default is "Output".

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 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 bold may be included as a list element. The default for bold is TRUE.

Examples:

  • title = "Observed vs. Predicted"

  • title = list(text = "Raw Data", font = list(color = "red", family = "Arial", size = 10, bold = T))

Default is to have no title.

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 plotly::schema() command in the console and navigate to layout > layoutAttributes > xaxis > range.

Example: xlim = c(0,1)

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 plotly::schema() command in the console and navigate to layout > layoutAttributes > yaxis > range.

Example: ylim = c(0,100)

print

If TRUE, will print the plotly object and return it. If FALSE, will only return the plotly object.

...

Other attributes which can be passed to the layout > xaxis/yaxis in a plotly plot to further control formatting. Note that log, xlab, ylab, xlim, and 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 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:

  • NPex$data$plot(xaxis = list(tickcolor = "black", tickfont = list(family = "Arial", size = 14, color = "black"))) #applies to x axis only

  • NPex$data$plot(linecolor = "red", ticks = "inside") #applies to both axes

.

Value

Plots the object.

Details

This is a function usually called by the $plot() method for PM_pop objects within a PM_result to generate the plot. However, the function can be called directly on a PM_pop object. This function will plot time and population predictions with a variety of options. By default markers are included and have the following plotly properties: list(symbol = "circle", color = "red", size = 10, opacity = 0.5, line = list(color = "black", width = 1)). Markers are omitted by default. If enabled, markers can be joined by lines, default is line = list(join = TRUE). If joined, the joining lines will have the following properties: list(color = "dodgerblue", width = 1, dash = "solid". The grid and legend are omitted by default.

See also

PM_pop, PM_result

Other PMplots: plot.PM_cov(), plot.PM_cycle(), plot.PM_data(), plot.PM_final(), plot.PM_model(), plot.PM_op(), plot.PM_opt(), plot.PM_post(), plot.PM_pta(), plot.PM_sim(), plot.PM_valid()

Author

Michael Neely

Examples

if (FALSE) { # \dontrun{
# basic spaghetti plot
NPex$pop$plot()
# format line and marker
NPex$pop$plot(
  marker = list(color = "blue", symbol = "square", size = 12, opacity = 0.4),
  line = list(color = "orange")
)
} # }