Plot PMmatrix Time-Output Data

Plots PMmatrix objects. It is largely now a legacy plotting function, replaced by plot.PM_data.

Usage

# S3 method for PMmatrix
plot(
  x,
  include,
  exclude,
  pred = NULL,
  icen = "median",
  mult = 1,
  outeq,
  group,
  block = 1,
  layout = c(3, 3),
  log = F,
  pch = NA,
  errbar = F,
  doses = F,
  tad = F,
  join = T,
  grid,
  ident = F,
  overlay = T,
  main,
  xlim,
  ylim,
  xlab = "Time (h)",
  ylab = "Observation",
  col,
  col.pred,
  cex = 1,
  legend,
  out = NA,
  ...
)

Arguments

x: The name of an PMmatrix data object read by PMreadMatrix
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)
pred: The name of a population or posterior prediction object read by makePop or makePost, respectively
icen: Only relevant for PMpost or PMpop objects which have predictions based on median or mean of each subject's Bayesian posterior parameter distribution. Default is "median", but could be "mean".
mult: Multiplication factor for y axis, e.g. to convert mg/L to ng/mL
outeq: A vector of output equation(s) to plot; if missing, plot all. E.g. outeq=1, outeq=2, outeq=c(1,3).
group: Quoted name of a covariate in data by which to distinguish groups with color in the plot. Note that if covariates do not have values on observation rows, those observations will be unable to be grouped. Grouping is only applicable if outeq is specified; otherwise there would be a confusing mix of colors for groups and output equations.
block: Which block to plot, where a new block is defined by dose resets (evid=4); default is 1.
layout: If overlay is False, this parameter specifies the number of plots per page.
log: Boolean operator to plot in log-log space; the default is False
pch: Controls the plotting symbol for observations; default is NA which results in no symbol. Use 0 for open square, 1 for open circle, 2 for open triangle, 3 for cross, 4 for X, or 5 for a diamond. Other alternatives are “*” for asterisks, “.” for tiny dots, or “+” for a smaller, bolder cross. These plotting symbols are standard for R (see par).
errbar: Either boolean (true/false) or a list. If assay error coefficients are included in the data file, setting this to True will plot error bars around each observation according to the standard deviation calculated from C0, C1, C2 and C3 in the data file. If C0, C1, C2, and C3 are missing in the data file, you can specify errbar to be a named list, i.e. list(c0=,c1=,c2=,c3=), where each value is a vector of length equal to the number of output equations. For example, with two output equations having coefficients of 0.1, 0.15, 0, 0 and 0.2, 0.1, -0.001, and 0, specify as errbar=list(c0=c(0.1,0.2), c1=c(0.15,0.1),c2=c(0,-0.001),c3=c(0,0)).
doses: Boolean operator to include doses as small lines at the bottom of the plot. Infusions are correctly represented according to their duration. The default is False. This parameter is ignored if overlay is True.
tad: Boolean operator to use time after dose rather than time after start. Default is False.
join: Boolean operator to join observations by a straight line; the default is True.
grid: Either a boolean operator to plot a reference grid, or a list with elements x and y, each of which is a vector specifying the native coordinates to plot grid lines; the default is False. For example, grid=list(x=seq(0,24,2),y=1:10). Defaults for missing x or y will be calculated by axTicks.
ident: Boolean operator to plot points as ID numbers in overlay plots; the default is False. Ignored if overlay is false. This option is useful to identify outliers.
overlay: Boolean operator to overlay all time concentration profiles in a single plot. The default is True.
main: An optional parameter to specify the title for plot(s). If overlay is False, the default will be the subject identification. If overlay is True, the default is blank. To omit a title from a non-overlaid plot, use the syntax main=“”.
xlim: Optional to specify the limits for the x axis.
ylim: Optional to specify the limits for the y axis.
xlab: Label for the x axis. Default is “Time (h)”
ylab: Label for the y axis. Default is “Observation”
col: A vector of color names to be used for output equation or group coloring. If the length of col is too short, values will be recycled.
col.pred: A vector of color names to be used for prediction (post or pop) coloring. Default is the same as col.
cex: Size of the plot symbols.
legend: Either a boolean operator or a list of parameters to be supplied to the legend function (see its documentation). If False or missing, a legend will not be plotted. If True, the default legend parameters will be used, as documented in that function, with exceptions as noted in Details.
out: Direct output to a PDF, EPS or image file. Format is a named list whose first argument, type is one of the following character vectors: “pdf”, “eps” (maps to postscript), “png”, “tiff”, “jpeg”, or “bmp”. Other named items in the list are the arguments to each graphic device. PDF and EPS are vector images acceptable to most journals in a very small file size, with scalable (i.e. infinite) resolution. The others are raster images which may be very large files at publication quality dots per inch (DPI), e.g. 800 or 1200. Default value is NA which means the output will go to the current graphic device (usually the monitor). For example, to output an eps file, out=list(“eps”) will generate a 7x7 inch (default) graphic.
...: Other parameters as found in plot.default.

Value

Plots the object.

Details

This function will plot raw and fitted time and concentration data, which can be accessed as the $data object within the $data field of a PM_data object, e.g. PM_data$data$data. For the legend, defaults that are different that the standard are:

x Default “topright”
legend Default will be factor label names if group is specified and valid; otherwise “Output 1, Output 2,...Output n”, where n is the number of output equations. This default can be overridden by a supplied character vector of output names.
fill The color of each group/output as specified by the default color scheme or col
bg Default “white”

Author

Michael Neely

Examples

library(PmetricsData)
plot(NPex$data$data)