ggPMX: an open-source R package for pharmacometric model diagnostic plots
I. Baltcheva (1), C. Bartels (1), T. Dumortier (1), S. Bhattacharya (2), I. Paule (1), I. Ludwig (1), I. Demin (1), A. Gassem (3), D. Renard (1), B. Bieth (1)
(1) Pharmacometrics, Novartis, Basel, Switzerland (2) Pharmacometrics, Novartis Institute of Biomedical Research Inc, Cambridge, USA (3) AG-Sudy, 18 rue Philibert Lucot, 75013 Paris, France
Introduction:
ggPMX is an open-source R package freely available on CRAN since April 2019. It builds on the R-package ggplot2 and provides a library of reproducible diagnostic plots needed for longitudinal population model building and validation. The package aims at providing a workflow that is consistent and efficient, resulting in high quality graphics ready-to-use in submission documents and publications. Intuitive functions and options allow for optimal figure customization and graphics stratification. ggPMX enables straightforward generation of PDF, Word or PNG output files that contain all diagnostic plots for keeping track of modeling results. The package is currently compatible with Monolix versions 2016 and 2018R1.
Methods:
ggPMX implementation uses object-oriented programming, which allows having code that is modular and easy to customize. The architecture consists of the following four components:
- Reader - reads model outputs from different sources (i.e. text files containing population parameters, model predictions, individual random effects, simulations and data-related inputs like covariates) and restructures these outputs into standard formats, which can be easily processed by the Generator.
- Generator - processes outputs from Reader and produces the diagnostic plots. A set of default plots is defined in a configuration file. The configuration file can be adapted, e.g., to have different configurations for different types of modeling activities (health authority submission, publication, internal report).
- Controller - serves as user interface. The user will call Generator functions via the Controller to produce either the default plots or customized versions.
- Reporter - generates sets of graphs and tables as individual PNG files and integrates them all into one single output document (Word or PDF) with annotations pointing to the locations of the individual PNG files. The report generation is based on Rmarkdown, which enables the user to create his own report template.
The most important task for the user is the Controller creation. This is the step where the user defines which model variable and which covariates to consider for the diagnostic session. All these settings can be defined manually, or can be automatically parsed from a Monolix project file (.mlxtran). Once the Controller is created, the user can display the graphs by calling pre-defined functions. The same syntax is used independently of the model structure or of the fitting software.
Results:
Using simple syntax, the toolbox produces various model diagnostics such as residual- and empirical Bayes estimate (EBE)-based plots, distribution plots, prediction- and simulation-based diagnostics (visual predictive checks). In addition, shrinkage and summary parameters table can be also produced. By default, the output file generated by the Reporter contains essential goodness-of-fit plots. However, these can be adapted to produce different sets of diagnostics as desired by the user, and any of the plots may be customized individually. The types of supported customizations include modifications of the graphical parameters, labels, and various stratifications by covariates.
Conclusions:
The ggPMX R package generates standard diagnostic plots for mixed effect models used in pharmacometric activities. The tool is built upon ggplot2 and currently supports models developed with Monolix 2016 and 2018R1. Future plans are to enhance ggPMX to support Monolix 2019, nlmixr and NONMEM outputs. ggPMX is now ready for inputs and enhancements by the pharmacometric community.
