nonmem2R VPC plot functions
Introduction
Herein is a demo of functions for VPC plots in the nonmem2R
R-package. The functions creates VPC plots using output files generated
by the vpc command in Pearl Speaks NONMEM (PsN). There are 3 functions;
vpcfig, vpcfig2, and vpcfig3. The
vpcfig function use lattice graphics for plotting and have
essentially the same arguments and functionality as the newer function
vpcfig2. The vpcfig3 function is an
experimental test function loading the raw simulated data and not the by
psn aggregated summary of the simulations. The primary focus herein is
on vpcfig2 using ggplot.
vpcfig2
Similar to the GOF functions in nonmem2R vpcfig2 returns
an ggplot object that can be further modified by adding ggplot
formatting, e.g. changing axis labels by adding
+labs(x="Time after dose").
Formatting of plot symbols, lines, and model regions can be
controlled by the arguments col.data,
cex.data, pch.data, alpha.data,
col.line, lwd.line, lty.line,
col.segm, and alpha.segm.
vpcfig2 will by default add a caption in the bottom of
the graph to indicate date when figure was generated together with the
full path to the script. However, this require that the script
name has been set using set.script.name, and then the
script name will be pasted together with the date and path as derived
from getwd. If script name has not been set no caption will
be added.
Below vpcfig2 is used with default options without any
extra formating. Here the psn generated files (vpctab-file and
vpc-results file) are specified as separate arguments. Alternatively and
more convenient it’s possible to just use the path to the folder
containing these two files, see the following examples.
# Get path to the example files included in nonmem2R package
file1 <- system.file("extdata", "vpctab004.dat", package = "nonmem2R")
file2 <- system.file("extdata", "vpc_results.csv", package = "nonmem2R")
# produce VPC with default setting, here specifying both vpctab and vpcresult
vpcfig2(vpctab=file1,vpcresult=file2)## VPC based on files:
## /tmp/RtmpZse3kZ/Rinstf8c20e47a02/nonmem2R/extdata/vpctab004.dat
## and
## /tmp/RtmpZse3kZ/Rinstf8c20e47a02/nonmem2R/extdata/vpc_results.csv
## Facetting was set using:
## facet_wrap(~strata)
Adding ggplot formating
In the below example ggplot formatting have been added with modified axis lables, logarithmic y-scale, and using the ggplot black and white theme. Also, the input source is specified using the folder path containing the vpctab and vpc results file, path1 is set to /tmp/RtmpZse3kZ/Rinstf8c20e47a02/nonmem2R/extdata/.
vpcfig2(path1)+
labs(x="Time after dose (hours)",y="Plasma concentration (nmol/L)")+
scale_y_log10()+
theme_bw()## VPC based on files:
## /tmp/RtmpZse3kZ/Rinstf8c20e47a02/nonmem2R/extdata//vpctab004.dat
## and
## /tmp/RtmpZse3kZ/Rinstf8c20e47a02/nonmem2R/extdata//vpc_results.csv
## Facetting was set using:
## facet_wrap(~strata)## Warning in transformation$transform(x): NaNs produced## Warning in scale_y_log10(): log-10 transformation introduced infinite values.
Using the fy argument for logarithmic scale
An alternative way to get logarithmic scale is to use the
fy argument to vpcfig2. Below example use a
semi-logarithmic scale with an offset of 1 so that zero can be included.
To get proper y-axis labels scale_y_continuous is added
using the fy function. The example also show how the
placement of the legend can be modified using the built in ggplot
functionality.
fy<-function(y){log(y+1)}
y.ticks<-c(0,1,10,100,1000)
vpcfig2(path1,fy=fy)+
labs(x="Time after dose (hours)",y="Plasma concentration (nmol/L)")+
scale_y_continuous(breaks=fy(y.ticks),labels=y.ticks,minor_breaks=NULL)+
theme(legend.position="top")## VPC based on files:
## /tmp/RtmpZse3kZ/Rinstf8c20e47a02/nonmem2R/extdata//vpctab004.dat
## and
## /tmp/RtmpZse3kZ/Rinstf8c20e47a02/nonmem2R/extdata//vpc_results.csv
## Facetting was set using:
## facet_wrap(~strata)
Re-naming, subsetting and or re-order of strata’s
The names for strata’s are by defult those produced by psn,
TRTPN == 1 and TRTPN == 3 in the above
examples. The strata.names argument can be used to set more
informative labels by providing a character-vector with new-labels for
each of the stratas.
The strata.subset argument can be used to re-order the
stratas and or select a subset of stratas that should be included by
providing a integer-vector with indexes which of stratas should be
included and in what order. For example strata.subset=1
will show only the TRTPN == 1 strata wheares
strata.subset=2:1 will show both strata’s byt in the
oposite order.
NOTE: length of strata.names must allways be equal to
the total number of stratas in the VPC before any subsetting
using strata.subset and in the original order.
See below example using both the strata.names and the
strata.subset argument.
## VPC based on files:
## /tmp/RtmpZse3kZ/Rinstf8c20e47a02/nonmem2R/extdata//vpctab004.dat
## and
## /tmp/RtmpZse3kZ/Rinstf8c20e47a02/nonmem2R/extdata//vpc_results.csv
## Facetting was set using:
## facet_wrap(~strata)
VPC for BLQ data
Nonmem2R version 0.2.2 now also can handle VPC for data below
quatification (BLQ) when the PSN VPC command was executed with the
-lloq option. vpcfig2 will then display the
VPC for observed data and proportion of BLQ in separate panels. Below
example show a 2 strata VPC with BLQ data in both strata.
The console will display important information on the faceting y-axis breaks/labels to guide how to add/modify formatting. In particular the y-axis breaks/labels may be challenging. In order to separate the range of data from the range of proportion of BLQ, and to get the panel for BLQ data smaller than the panel for data (>LOQ), the proportions y-data are transformed.
The example below use the fy argument for log-scale of data, and the
vpcfig2 default y-axis is modified. Note how the breaks and labels for
the BLQ panel is just copied from the output in the console. Also note
that it’s highly recommended NOT to use
scale_y_log10() when plotting BLQ VPC’s. Simarly it is
recommeneded to use the ylab and
censoring.labels for setting y-axis lables.
f1<-vpcfig2(path2,fy=log,strata.names=c("710mg","1000mg"),ylab="Plasma conc (umol/L)",
censoring.labels=c("a","BLQ(%)"),xlab="Time after dose (hrs)")## VPC based on files:
## /tmp/RtmpZse3kZ/Rinstf8c20e47a02/nonmem2R/extdata/vpc001/vpctab001.dat
## and
## /tmp/RtmpZse3kZ/Rinstf8c20e47a02/nonmem2R/extdata/vpc001/vpc_results.csv
## Facetting was set using:
## facet_grid(data.type~strata,scales="free_y",space="free_y",switch="y")
## Y-scale was set using:
## scale_y_continuous(
## breaks=c(-1,0,1,2,3,4,5.55058263829153,6.2985767486289,7.04657085896627),
## labels=c(-1,0,1,2,3,4,0,50,100))##breaks for DV
bry<-c(0.1,0.2,0.4,0.6,1,2,4,6,10,20,40,60)
mbry<-c(1:10,(1:10)/10,(1:10)*10)
##breaks for BLQ, copied from the vpcfif2 console output
brb<-c(5.55058263829153,6.2985767486289,7.04657085896627)
lbb<-c(0,50,100)
## Get minor breaks for BLQ in between the main breaks
mbrb<-(brb[-1]+brb[length(brb)])/2
f1+scale_y_continuous(breaks=c(brb,log(bry)),
labels=c(lbb,bry),minor_breaks=c(mbrb,log(mbry)))## Scale for y is already present.
## Adding another scale for y, which will replace the existing scale.