model_results_rsnlme.Rmd
The Certara.ModelResults
Shiny GUI and script generating
functionality can be used alongside Certara.RsNLME
for a
robust, efficient, and reproducible pharmacometric modeling workflow in
R.
Users can iterate over multiple models in R, and easily pass the
model output files to Certara.ModelResults
to generate
model diagnostic plots and tables in the Shiny GUI. Furthermore, all
plots and tables generated in the Shiny GUI include the associated R
and/or Rmd code to reproduce the model diagnostics from the command line
in R.
We’ll first need to build and execute our models using the
Certara.RsNLME
package. We will be using the example data
file pkData
from the Certara.RsNLME
package.
We’ll define a basic two-compartment population PK model with IV
bolus (through the Certara.RsNLME
built-in function
pkmodel()
) as well as its associated column mappings. Help
is available by typing ?Certara.RsNLME::pkmodel
.
Note: The corresponding R script used in this example can be
found in
RsNLME_Examples/TwoCptIVBolus_FitBaseModel_CovariateSearch_VPC_BootStrapping.R
.
RsNLME
Example Scripts
library(Certara.RsNLME)
library(magrittr)
baseModel <- pkmodel(numCompartments = 2, data = pkData,
ID = "Subject", Time = "Act_Time", A1 = "Amount", CObs = "Conc",
modelName = "TwCpt_IVBolus_FOCE_ELS")
Next, we’ll update parameters in our pkmodel
:
baseModel <- baseModel %>%
structuralParameter(paramName = "V2", hasRandomEffect = FALSE) %>%
fixedEffect(effect = c("tvV", "tvCl", "tvV2", "tvCl2"), value = c(15, 5, 40, 15)) %>%
randomEffect(effects = c("nV", "nCl", "nCl2"), values = rep(0.1, 3)) %>%
residualError(predName = "C", SD = 0.2)
Fit the model using the default host and default values for the relevant NLME engine arguments. For this example model, FOCE-ELS is the default method for estimation, and Sandwich is the default method for standard error calculations.
Note: The default values for the relevant NLME engine arguments
are chosen based on the model, type
?Certara.RsNLME::engineParams
for details.
baseFitJob <- fitmodel(baseModel)
resultsUI()
with base model
The model argument in resultsUI()
can be supplied as
either a single model object or a vector of model objects or a list of
model objects. We can now provide our model object,
baseModel
, to the model argument in
resultsUI()
and execute Model Results.
The series of screenshots below demonstrate how users can preview model diagnostic plots and tables using the tree selection in the Shiny GUI.
We will copy our baseModel
and accept parameter
estimates before adding a covariate in the next step.
covariateModel <- copyModel(baseModel,
acceptAllEffects = TRUE,
modelName = "TwCpt_IVBolus_SelectedCovariateModel_FOCE_ELS")
Next, we’ll add the continuous covariate BodyWeight
to
our model and set the covariate effect on structural parameters
V
and Cl
.
covariateModel <- covariateModel %>%
addCovariate(covariate = "BodyWeight", effect = c("V", "Cl"))
covariateFitJob <- fitmodel(covariateModel)
resultsUI()
with multiple models
Finally, we can supply a vector of model objects to the
model
argument in resultsUI()
and execute
Model Results.
Below are a few examples of advanced modeling use cases that are easily achieved with RsNLME + Model Results.
We can use different numbers of compartments to loop through multiple
model scenarios in the following code, then easily pass the models to
resultsUI()
library(Certara.RsNLME)
# Setup compartment scenarios
numCpt <- c(1, 2, 3)
namesCpt <- c("OneCpt", "TwoCpt", "ThreeCpt")
numScenarios <- length(numCpt)
# Memory allocation for model objects
models <- vector(mode = "list", length = numScenarios)
names(models) <- namesCpt
# Memory allocation for job objects
jobs <- vector(mode = "list", length = numScenarios)
names(jobs) <- namesCpt
# Define models and then run them
for (i in 1:numScenarios){
## Define a basic PK model with IV Bolus as well as the associated column mapping
models[[i]] <- pkmodel(numCompartments = numCpt[i],
ID = "Subject", Time = "Act_Time", A1 = "Amount", CObs = "Conc",
data = pkData, modelName = paste0(namesCpt[i], "_IVBolus_FOCE-ELS")) %>%
fixedEffect(effect = "tvV", value = 5) # Set initial value for theta to 5
## Fit model
jobs[[i]] <- fitmodel(models[[i]])
}
Execute resultsUI()
with our compartment scenario
models:
dataPath <- system.file("extdata","PKCategoricalData.csv",package="Certara.ModelResults")
pkCategoricalData <- read.csv(dataPath)
head(pkCategoricalData)
#> ID Time Dose CObs CategoricalObs
#> 1 1 0.0 10 NA NA
#> 2 1 0.5 NA 0.5395386 1
#> 3 1 1.0 NA 0.8087664 1
#> 4 1 2.0 NA 1.2350127 0
#> 5 1 4.0 NA 1.1687156 0
#> 6 1 8.0 NA 0.8421397 0
library(Certara.RsNLME)
library(magrittr)
mdlPath <- system.file("extdata","PKCategorical_OneCpt1stOrderAbsorp_2CategoriesLogitImax.mdl",package="Certara.ModelResults")
model <- textualmodel(modelName = "PKCategorical_OneCpt1stOrderAbsorp_LogitImax",
mdl = mdlPath,
data = pkCategoricalData)
We can see in the “Column Mappings” section of the
print(model)
output that model variable Aa
was
not automatically mapped, since the corresponding column is named
Dose
in our dataset. In such cases where the model variable
name is different from the column name in the dataset, we will have to
manually map.
model <- model %>%
colMapping(c(Aa = "Dose"))
Engine parameters setup:
engineSetup <- engineParams(model, method = "QRPEM", numRepPCWRES = 1000)
Run the model.
job <- fitmodel(model, params = engineSetup)
xpose_data
object
Import results of an NLME run into xpose database to create commonly used diagnostic plots.
library(Certara.Xpose.NLME)
xpdb <- xposeNlme(dir = model@modelInfo@workingDir, modelName = "PKCategorical_OneCpt1stOrderAbsorp_LogitImax")
We can exclude observed variables using the
xpose::filter()
command. Let’s exclude the categorical
observed variable, CategoricalObs
, from our model
diagnostic plots.