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.
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 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 about the PI.
However, note that with increasing number of simulations the CI
will not go towards zero because the interval is also
dependent on the size of the data set.
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.
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 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.
## 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)