xpose.VPC(xpose4generic)R Documentation

Visual Predictive Check (VPC) using XPOSE

Description

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=NULL,
          type="p",
          by=NULL,
          PI="area",
          subset=NULL,
          main="Default",
          inclZeroWRES=FALSE,
          ...)

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 NULL 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.
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.
inclZeroWRES Logical value indicating whether rows with WRES=0 is included in the plot.
... 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

Additional graphical elements available in the VPC plots

PI.real = NULL or TRUE
Plot the percentiles of the real data in the various bins. 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.
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.ci = "both", "area" or "lines"
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). These CIs can be used to asses the PI.real values for model misspecification. Again, as with the PI.real, 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.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(s)

Andrew Hooker

See Also

read.vpctab read.npc.vpc.results xpose.panel.default xpose.plot.default

Examples

## Not run: 
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)

## End(Not run)
[Package xpose4generic version 4.0.3 Index]