PMXForest

The goal of PMXForest is to make it easy to create Forest plots for pharmacometric models, in particular NONMEM models. The user only have to specify information about the covariate values to visualize, how the covariates relates to the parameters of interest and where the uncertainty information is. The latter can be a NONMEM .cov file, a PsN bootstrap or SIR raw_results file. The Forest plots will include the crucial information needed for an accurate interpretation of the plot and the user have full control of the formatting and annotations.

Installation

You can install the development version of PMXForest from GitHub with:

# install.packages("devtools")
devtools::install_github("pharmetheus/PMXForest")

The vignette sources are in vignettes/. Open the .Rmd files in RStudio and click Knit to compile, or run browseVignettes("PMXForest") to read the versions built at install time. Note that some of the vignettes take a fair bit of time to compile.

To get the latest stable release (including vignettes), please click the appropriate link on the right side of the page. Download the file with a name that starts with PMXForest. Install PMXForest with the install.packages command, e.g.:

install.packages("path_to_release.tar.gz")

Example of using PMXForest

This is a basic example which shows you how to create a Forest plot for a NONMEM model.

First attach the PMXForest library:

library(PMXForest)

and set the ggplot theme

ggplot2::theme_set(ggplot2::theme_bw())

Point at the model and the data

Everything below uses the run7 example bundled with the package, so it runs anywhere PMXForest is installed.

modFile <- system.file("extdata", "SimVal/run7.mod", package = "PMXForest")
dataFile <- system.file("extdata", "SimVal/DAT-1-MI-PMX-2.csv", package = "PMXForest")
covFile <- system.file("extdata", "SimVal/run7.cov", package = "PMXForest")
extFile <- system.file("extdata", "SimVal/run7.ext", package = "PMXForest")

filterByModel() applies the model’s own IGNORE/ACCEPT statements, so the covariate summaries below describe the subjects the model was actually fitted to.

dfData <- filterByModel(read.csv(dataFile), modFile)
#> Applying IGNORE: (TYPE == 2) | (BLQ == 1) | (ID == 895)
#> Removed 35131 of 69016 record(s) and 210 subject(s).

Specify the covariate information

setupDfCovs() turns the data into one row per Forest plot row: the 5th and 95th percentiles of a continuous covariate, one row per level of a categorical one. catRef = list(GENO = 2) makes 2D6 EM the reference and sep = "" names the one-hot columns the way the control stream does.

dfCovs <- setupDfCovs(
  data = dfData,
  covariates = c("FOOD", "GENO", "WT", "SEX"),
  catRef = list(GENO = 2),
  sep = "",
  idVar = "ID"
)

The labels are given once per covariate, not once per row: a display name, a unit for the continuous covariates and a label for each categorical level. generateCovNames() applies them below, so the weight rows show whatever percentiles the data give.

name_map <- c(FOOD = "Food status", GENO = "2D6 Genotype", WT = "Weight", SEX = "Sex")
unit_map <- c(WT = "kg")
level_map <- list(
  FOOD = c("0" = "Fasted", "1" = "Fed"),
  GENO = c("1" = "2D6 UM", "2" = "2D6 EM", "3" = "2D6 IM", "4" = "2D6 PM"),
  SEX  = c("1" = "Male", "2" = "Female")
)

Describe how the parameters are related to the covariates

The parameter function turns the estimates and one row of covariate values into the quantities to plot. createParamFunction() writes it by translating the model’s $PK block, so the relationship is not retyped in R and cannot drift away from the model. secondary adds AUC after an 80 mg dose, which is not in $PK because the dose is not.

gen <- createParamFunction(
  modFile,
  parameters = "CL",
  covRef = list(GENO1 = 0, GENO3 = 0),
  secondary = list(AUC = "80 / (CL / FREL)"),
  quiet = TRUE
)

The result is source text. Read it against the control stream, then evaluate it:

paramFunction <- eval(parse(text = paste(gen$code, collapse = "\n")))
functionListName <- c("CL (L/h)", "AUC (mgh/L)")

Generate the data for the plot

PMXForest takes care of the simulations and predictions needed for the plot, including the uncertainty. Here it is taken from the NONMEM $COV step: getSamples() draws the parameter vectors and getForestDFSCM() does the calculations, in parallel if asked. gen$noBaseThetas is the THETA count read from the model, so it does not have to be typed in and kept up to date.

# Seeded so that rebuilding the README reproduces the figure below rather than
# redrawing 175 new samples and shifting every confidence interval.
set.seed(20240101)
dfSamples <- getSamples(covFile, extFile, n = 175)

dfres <- getForestDFSCM(
  dfCovs = dfCovs,
  functionList = list(paramFunction),
  functionListName = functionListName,
  noBaseThetas = gen$noBaseThetas,
  dfParameters = dfSamples
)

dfres <- generateCovNames(dfCovs, dfres,
  name_map = name_map, unit_map = unit_map, level_map = level_map
)

Create the Forest plot

With the above information is an easy task to generate the Forest plot.

forestPlot(dfres, size = 10)

Further information

The above is a simple use case of PMXForest for a straight forward PK model. However, PMXForest is quite capable of handling most problems and complexities. Both the “standard” use for NONMEM based problems as well as more tailored solutions to other types of problems are described in the package vignettes.

Once the package is installed you can issue the command: browseVignettes("PMXForest")