xpose.VPC: Visual Predictive Check (VPC) using XPOSE
In xpose4: Diagnostics for Nonlinear Mixed-Effect Models

xpose.VPC

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 = 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(s)

Andrew Hooker

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)

## 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)


## End(Not run)

xpose4 documentation built on May 29, 2024, 7:56 a.m.