nonmem2R VPC plot functions

Magnus Åstrand

February 2020

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/RtmpP9tI9Q/Rinst5c1e791f4fb6/nonmem2R/extdata/vpctab004.dat 
## and
##    /tmp/RtmpP9tI9Q/Rinst5c1e791f4fb6/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/RtmpP9tI9Q/Rinst5c1e791f4fb6/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/RtmpP9tI9Q/Rinst5c1e791f4fb6/nonmem2R/extdata//vpctab004.dat 
## and
##    /tmp/RtmpP9tI9Q/Rinst5c1e791f4fb6/nonmem2R/extdata//vpc_results.csv 
## Facetting was set using:
##  facet_wrap(~strata)
## Warning in self$trans$transform(x): NaNs produced
## Warning: Transformation introduced infinite values in continuous y-axis

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/RtmpP9tI9Q/Rinst5c1e791f4fb6/nonmem2R/extdata//vpctab004.dat 
## and
##    /tmp/RtmpP9tI9Q/Rinst5c1e791f4fb6/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.

vpcfig2(path1,strata.subset=2:1,strata.names=c("Cohort 1","Cohort 2"))
## VPC based on files:
##    /tmp/RtmpP9tI9Q/Rinst5c1e791f4fb6/nonmem2R/extdata//vpctab004.dat 
## and
##    /tmp/RtmpP9tI9Q/Rinst5c1e791f4fb6/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/RtmpP9tI9Q/Rinst5c1e791f4fb6/nonmem2R/extdata/vpc001/vpctab001.dat 
## and
##    /tmp/RtmpP9tI9Q/Rinst5c1e791f4fb6/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.