Visual Predictive Check (VPC) using XPOSE

This Function is used to create a VPC in xpose using the output from the vpc command in Pearl Speaks NONMEM (PsN). The function reads in the output files created by PsN and creates a plot from the data. The dependent variable, independent variable and conditioning variable are automatically determined from the PsN files.

Usage

xpose.VPC(
  vpc.info = "vpc_results.csv",
  vpctab = dir(pattern = "^vpctab")[1],
  object = NULL,
  ids = FALSE,
  type = "p",
  by = NULL,
  PI = NULL,
  PI.ci = "area",
  PI.ci.area.smooth = FALSE,
  PI.real = TRUE,
  subset = NULL,
  main = "Default",
  main.sub = NULL,
  main.sub.cex = 0.85,
  inclZeroWRES = FALSE,
  force.x.continuous = FALSE,
  funy = NULL,
  logy = FALSE,
  ylb = "Default",
  verbose = FALSE,
  PI.x.median = TRUE,
  PI.rug = "Default",
  PI.identify.outliers = TRUE,
  ...
)

Arguments

vpc.info: The results file from the vpc command in PsN. for example vpc_results.csv, or if the file is in a separate directory ./vpc_dir1/vpc_results.csv.
vpctab: The vpctab from the vpc command in PsN. For example vpctab5, or if the file is in a separate directory ./vpc_dir1/vpctab5. Can be NULL. The default looks in the current working directory and takes the first file that starts with vpctab that it finds. Note that this default can result in the wrong files being read if there are multiple vpctab files in the directory. One of object or vpctab is required. If both are present then the information from the vpctab will over-ride the xpose data object object (i.e. the values from the vpctab will replace any matching values in the object\@Data portion of the xpose data object).
object: An xpose data object. Created from xpose.data. One of object or vpctab is required. If both are present then the information from the vpctab will over-ride the xpose data object object (i.e. the values from the vpctab will replace any matching values in the object\@Data portion of the xpose data object).
ids: A logical value indicating whether text ID labels should be used as plotting symbols (the variable used for these symbols indicated by the idlab xpose data variable). Can be FALSE or TRUE.
type: Character string describing the way the points in the plot will be displayed. For more details, see plot. Use type="n" if you don't want observations in the plot.
by: A string or a vector of strings with the name(s) of the conditioning variables. For example by = c("SEX","WT"). Because the function automatically determines the conditioning variable from the PsN input file specified in vpc.info, the by command can control if separate plots are created for each condition (by=NULL), or if a conditioning plot should be created (by="WT" for example). If the vpc.info file has a conditioning variable then by must match that variable. If there is no conditioning variable in vpc.info then the PI for each conditioned plot will be the PI for the entire data set (not only for the conditioning subset).
PI: Either "lines", "area" or "both" specifying whether prediction intervals (as lines, a shaded area or both) should be added to the plot. NULL means no prediction interval.
PI.ci: Plot the confidence interval for the simulated data's percentiles for each bin (for each simulated data set compute the percentiles for each bin, then, from all of the percentiles from all of the simulated datasets compute the 95% CI of these percentiles). Values can be "both", "area" or "lines". These CIs can be used to asses the PI.real values for model misspecification. Note that with few observations per bin the CIs will be approximate because the percentiles in each bin will be approximate. For example, the 95th percentile of 4 data points will always be the largest of the 4 data points.
PI.ci.area.smooth: Should the "area" for PI.ci be smoothed to match the "lines" argument? Allowed values are TRUE/FALSE. The "area" is set by default to show the bins used in the PI.ci computation. By smoothing, information is lost and, in general, the confidence intervals will be smaller than they are in reality.
PI.real: Plot the percentiles of the real data in the various bins. values can be NULL or TRUE. Note that for a bin with few actual observations the percentiles will be approximate. For example, the 95th percentile of 4 data points will always be the largest of the 4 data points.
subset: A string giving the subset expression to be applied to the data before plotting. See xsubset.
main: A string giving the plot title or NULL if none. "Default" creates a default title.
main.sub: Used for names above each plot when using multiple plots. Should be a vector c("Group 1","Group 2")
main.sub.cex: The size of the main.sub titles.
inclZeroWRES: Logical value indicating whether rows with WRES=0 is included in the plot.
force.x.continuous: Logical value indicating whether x-values should be converted to continuous variables, even if they are defined as factors.
funy: String of function to apply to Y data. For example "abs"
logy: Logical value indicating whether the y-axis should be logarithmic, base 10.
ylb: Label for the y-axis
verbose: Should warning messages and other diagnostic information be passed to screen? (TRUE or FALSE)
PI.x.median: Should the x-location of percentile lines in a bin be marked at the median of the x-values? (TRUE or FALSE)
PI.rug: Should there be markings on the plot showing where the binning intervals for the VPC are (or the locations of the independent variable used for each VPC calculation if binning is not used)?
PI.identify.outliers: Should outlying percentiles of the real data be highlighted? (TRUE of FALSE)
...: Other arguments passed to xpose.panel.default, xpose.plot.default and others. Please see these functions for more descriptions of what you can do.

Value

A plot or a list of plots.

Additional arguments

Below are some of the additional arguments that can control the look and feel of the VPC. See xpose.panel.default for all potential options.

Additional graphical elements available in the VPC plots.

PI.mirror = NULL, TRUE or AN.INTEGER.VALUE: Plot the percentiles of one simulated data set in each bin. TRUE takes the first mirror from vpc_results.csv and AN.INTEGER.VALUE can be 1, 2, ...{} n where n is the number of mirror's output in the vpc_results.csv file.
PI.limits = c(0.025, 0.975): A vector of two values that describe the limits of the prediction interval that should be displayed. These limits should be found in the vpc_results.csv file. These limits are also used as the percentages for the PI.real, PI.mirror and PI.ci. However, the confidence interval in PI.ci is always the one defined in the vpc_results.csv file.

Additional options to control the look and feel of the PI. See See grid.polygon and plot for more details.

PI.arcol: The color of the PI area
PI.up.lty: The upper line type. can be "dotted" or "dashed", etc.
PI.up.type: The upper type used for plotting. Defaults to a line.
PI.up.col: The upper line color
PI.up.lwd: The upper line width
PI.down.lty: The lower line type. can be "dotted" or "dashed", etc.
PI.down.type: The lower type used for plotting. Defaults to a line.
PI.down.col: The lower line color
PI.down.lwd: The lower line width
PI.med.lty: The median line type. can be "dotted" or "dashed", etc.
PI.med.type: The median type used for plotting. Defaults to a line.
PI.med.col: The median line color
PI.med.lwd: The median line width

Additional options to control the look and feel of the PI.ci. See See grid.polygon and plot for more details.

PI.ci.up.arcol: The color of the upper PI.ci.
PI.ci.med.arcol: The color of the median PI.ci.
PI.ci.down.arcol: The color of the lower PI.ci.
PI.ci.up.lty: The upper line type. can be "dotted" or "dashed", etc.
PI.ci.up.type: The upper type used for plotting. Defaults to a line.
PI.ci.up.col: The upper line color
PI.ci.up.lwd: The upper line width
PI.ci.down.lty: The lower line type. can be "dotted" or "dashed", etc.
PI.ci.down.type: The lower type used for plotting. Defaults to a line.
PI.ci.down.col: The lower line color
PI.ci.down.lwd: The lower line width
PI.ci.med.lty: The median line type. can be "dotted" or "dashed", etc.
PI.ci.med.type: The median type used for plotting. Defaults to a line.
PI.ci.med.col: The median line color
PI.ci.med.lwd: The median line width
PI.ci.area.smooth: Should the "area" for PI.ci be smoothed to match the "lines" argument? Allowed values are TRUE/FALSE. The "area" is set by default to show the bins used in the PI.ci computation. By smoothing, information is lost and, in general, the confidence intervals will be smaller than they are in reality.

Additional options to control the look and feel of the PI.real. See See grid.polygon and plot for more details.

PI.real.up.lty: The upper line type. can be "dotted" or "dashed", etc.
PI.real.up.type: The upper type used for plotting. Defaults to a line.
PI.real.up.col: The upper line color
PI.real.up.lwd: The upper line width
PI.real.down.lty: The lower line type. can be "dotted" or "dashed", etc.
PI.real.down.type: The lower type used for plotting. Defaults to a line.
PI.real.down.col: The lower line color
PI.real.down.lwd: The lower line width
PI.real.med.lty: The median line type. can be "dotted" or "dashed", etc.
PI.real.med.type: The median type used for plotting. Defaults to a line.
PI.real.med.col: The median line color
PI.real.med.lwd: The median line width

Additional options to control the look and feel of the PI.mirror. See See plot for more details.

PI.mirror.up.lty: The upper line type. can be "dotted" or "dashed", etc.
PI.mirror.up.type: The upper type used for plotting. Defaults to a line.
PI.mirror.up.col: The upper line color
PI.mirror.up.lwd: The upper line width
PI.mirror.down.lty: The lower line type. can be "dotted" or "dashed", etc.
PI.mirror.down.type: The lower type used for plotting. Defaults to a line.
PI.mirror.down.col: The lower line color
PI.mirror.down.lwd: The lower line width
PI.mirror.med.lty: The median line type. can be "dotted" or "dashed", etc.
PI.mirror.med.type: The median type used for plotting. Defaults to a line.
PI.mirror.med.col: The median line color
PI.mirror.med.lwd: The median line width

Author

Andrew Hooker

Examples


if (FALSE) {
library(xpose4)

xpose.VPC()

## to be more clear about which files should be read in
vpc.file <- "vpc_results.csv"
vpctab <- "vpctab5"
xpose.VPC(vpc.info=vpc.file,vpctab=vpctab)

## with lines and a shaded area for the prediction intervals
xpose.VPC(vpc.file,vpctab=vpctab,PI="both")

## with the percentages of the real data
xpose.VPC(vpc.file,vpctab=vpctab,PI.real=T)

## with mirrors (if supplied in 'vpc.file')
xpose.VPC(vpc.file,vpctab=vpctab,PI.real=T,PI.mirror=5)

## with CIs
xpose.VPC(vpc.file,vpctab=vpctab,PI.real=T,PI.ci="area")
xpose.VPC(vpc.file,vpctab=vpctab,PI.real=T,PI.ci="area",PI=NULL)

## stratification (if 'vpc.file' is stratified)
cond.var <- "WT"
xpose.VPC(vpc.file,vpctab=vpctab)
xpose.VPC(vpc.file,vpctab=vpctab,by=cond.var)
xpose.VPC(vpctab=vpctab,vpc.info=vpc.file,PI="both",by=cond.var,type="n")

## with no data points in the plot
xpose.VPC(vpc.file,vpctab=vpctab,by=cond.var,PI.real=T,PI.ci="area",PI=NULL,type="n")

## with different DV and IDV, just read in new files and plot
vpc.file <- "vpc_results.csv"
vpctab <- "vpctab5"
cond.var <- "WT"
xpose.VPC(vpctab=vpctab,vpc.info=vpc.file,PI="both",by=cond.var)
xpose.VPC(vpctab=vpctab,vpc.info=vpc.file,PI="both")

## to use an xpose data object instead of vpctab
##
## In this example
## we expect to find the required NONMEM run and table files for run
## 5 in the current working directory
runnumber <- 5
xpdb <- xpose.data(runnumber)
xpose.VPC(vpc.file,object=xpdb)

## to read files in a directory different than the current working directory 
vpc.file <- "./vpc_strat_WT_4_mirror_5/vpc_results.csv"
vpctab <- "./vpc_strat_WT_4_mirror_5/vpctab5"
xpose.VPC(vpc.info=vpc.file,vpctab=vpctab)

## to rearrange order of factors in VPC plot
xpdb@Data$SEX <- factor(xpdb@Data$SEX,levels=c("2","1"))
xpose.VPC(by="SEX",object=xpdb)

}