xpose4 (version 4.5.0)

xpose.VPC: 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=FALSE,
          type="p",
          by=NULL,
          PI=NULL,
          PI.ci="area",
          PI.real=T,
          PI.ci.med.arcol="red",
          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,
          ...)

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

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

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

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 prediction interval of the simulated data's percentiles for each bin. Values can be "both", "area" or "lines" This can be thought of as a prediction interval about the PI.real or a confidence interval abo

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

PI.ci.med.arcol

The color of the median PI.ci.

force.x.continuous

Logical value indicating whether x-values should be taken as continuous, even if categorical.

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

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.

verbose

Text messages passed to screen or not.

...

Other arguments passed to xpose.panel.default, xpose.plot.default and others. Please see these functions for more descri

Value

• A plot or a list of plots.

See Also

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

Examples

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)