nonmem2R: An R-package for Visual Predictive Checks and Goodness-of-fit Plots
Magnus Åstrand
) Early Clinical Development, IMED Biotech Unit, AstraZeneca, Gothenburg, Sweden
Objectives:
nonmem2R is an open-source R-package, freely available on CRAN[1]. On top of the main functionality of the previous version, Visual Predictive Checks (VPC) plots and functions to extract parameter estimates from NONMEM[2] and PSN[3] generated output files, the functionality has been extended with Goodness-of-fit (GOF) plots.
Methods:
The plotting functionality in nonmem2R builds on the R-packages ggplot2[4] and as far as possible return ggplot-objects that can be further modified by adding ggplot formatting. The GOF functions use a default graphical setting to provide GOF’s of similar appearance with a minimum input. Each GOF plot will have a red dashed reference line and blue solid lines are smoother’s representing the actual data when applicable. The default setting can easily be modified to affect all GOF’s within a script including captions text to indicate source script for each generated graph. The GOF function assume a data-frame as input as returned by e.g. read.table when reading a NONMEM $TABLE output file.
Results:
The package has a set of tailored functions to provide basic GOF plots for NONMEM generated output files.
- Basic.GOF4 will provide a summary GOF of population and individual predictions vs observations together with conditional weighted residuals (CWRES) untransformed as well as transformed by square root of the absolute value, both plotted vs TIME by default. The square root of the absolute value CWRES is indented to explore for a trends of heteroscedasticity.
- Basic.GOF6 provide the same set of graphs as basic.GOF4 with 2 additional GOF’s for the distribution of CWRES by histogram and normal quantile plot.
- do.individual.GOF will provide GOF plots of PRED, IPRED and DV vs TIME with one panel per subject This will generate one page/plot per 20 subjects (default) and therefore this function is best used when exporting to a PDF.
- There are 4 tailored functions for doing GOF plots for ETA's: basic.eta.GOF, eta.cov.GOF, eta.cat.GOF, and eta.pairs.GOF. These functions identify all ETA’s in the input data-frame and provides different types of GOF plots for these columns. All 4 functions will by default exclude ETA's which are constant i.e. when set as FIX in your NONMEM model and each ETA is scaled to unit variance.
All GOF’s have arguments to change from the default setting, e.g. to have time after last dose (TAD), or any column in the input data-frame, on x-axis instead of TIME; exclude the loess smoother; or drop the reference line.
It is also possible to add ggplot formatting to each sub GOF before combining into one single graph, e.g. adding the ggplot function facet_wrap(~SEX) to basic.GOF4 will make each of the 4 GOF plots stratified by gender in two separate panels.
Along with the above tailored functions there are a set of GOF building blocks from simple x-y-GOF plots to histogram and normal quantile GOF plots. The GOF building block functions can be used together a set of GOF builders to define new tailored GOF’s and maintain the graphical settings.
GOF plotting functions 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.
Furthermore, all GOF functions make use of the control argument for formatting of e.g. lines, plot symbols, histogram bars, caption text. Axis labels are set according to a default dictionary for the most common NONMEM columns e.g. CWRES is by default labelled "Cond. weighted res" and TAD is by default labeled "Time since last dose(hrs)". The dictionary can be extended and or modified with e.g. "Time after first dose (days)" for the variable `TIME` in case the unit is days.
Conclusions:
With the addition of easy to use yet flexible functions for GOF plots nonmem2R now can produce the vast majority of graphics for model evaluation.
References:
[1] https://cran.r-project.org/web/packages/nonmem2R/index.html
[2] NONlinear Mixed-Effect Modeling, http://www.iconplc.com/innovation/solutions/nonmem/
[3] Perl-speaks-NONMEM, https://uupharmacometrics.github.io/PsN/
[4] https://cran.r-project.org/web/packages/ggplot2/index.html
