This example script is intended to illustrate how to use the 'ddmore' R package to perform a M&S workflow using the DDMoRe Standalone Execution Environment (SEE).
The following steps are implemented in this workflow:
To run a task, select with the cursor any code lines you wish to execute and press CTRL+R+R in your keyboard. An HTML file containing the commands in this file and associated output will be provided to allow the user to compare the results
Clear workspace and set working directory under 'models' folder
Clear workspace and set working directory under 'UsesCasesDemo' project
rm(list=ls(all=F))
mydir <- file.path(Sys.getenv("MDLIDE_WORKSPACE_HOME"),"UseCasesDemo")
setwd(mydir)
Set name of .mdl file and dataset for future tasks
uc <- "UseCase3_1"
datafile <- "warfarin_conc_pca_PKparam.csv"
mdlfile <- paste0(uc,".mdl")
Create a new folder to be used as working directory and where results will be stored
wd <- file.path(mydir,uc)
dir.create(wd)
Copy the dataset and the .mdl file available under “models” into the working directory
file.copy(file.path(mydir,"models", datafile),wd)
## [1] TRUE
file.copy(file.path(mydir,"models",mdlfile),wd)
## [1] TRUE
Set the working directory.
setwd(file.path(mydir,uc))
The working directory needs to be set differently when knitr R package is used to spin the file
library(knitr)
opts_knit$set(root.dir = file.path(mydir,uc))
cache.path <- file.path(mydir,uc, 'cache')
dir.create(cache.path)
opts_chunk$set(cache.path=cache.path)
figure.path <- file.path(mydir,uc, 'figure')
dir.create(figure.path)
opts_chunk$set(figure.path=figure.path)
List files available in working directory
list.files()
## [1] "cache" "figure"
## [3] "UseCase3_1.mdl" "warfarin_conc_pca_PKparam.csv"
Use 'ddmore' function getModelObjects() to retrieve model object(s) from an existing .mdl file. This function reads the MDL in an .mdl file and parses the MDL code for each MDL Object into an R list of objects of appropriate types with names corresponding to the MDL Object names given in the file.
myMDLObj <- getMDLObjects(mdlfile)
length(myMDLObj)
## [1] 4
names(myMDLObj)
## [1] "warfarin_PKPD_turnover_dat" "warfarin_PKPD_turnover_par"
## [3] "warfarin_PKPD_turnover_mdl" "warfarin_PKPD_turnover_task"
Use 'ddmore' function getDataObjects() to retrieve only data object(s) from an existing .mdl file. This function returns a list of Parameter Object(s) from which we select the first element. Hover over the variable name to see its structure
myDataObj <- getDataObjects(mdlfile)[[1]]
Use 'ddmore' function getParameterObjects() to retrieve only parameter object(s) from an existing .mdl file
myParObj <- getParameterObjects(mdlfile)[[1]]
Use 'ddmore' function getModelObjects() to retrieve only model object(s) from an existing .mdl file.
myModObj <- getModelObjects(mdlfile)[[1]]
Use 'ddmore' function getTaskPropertiesObjects() to retrieve only task properties object(s) from an existing .mdl file
myTaskObj <- getTaskPropertiesObjects(mdlfile)[[1]]
Recall that getDataObjects only reads the MDL code from the .mdl file. Use 'ddmore' function readDataObj() to create an R object from the MDL data object.
myData <- readDataObj(myDataObj)
Let's look at the first 6 lines of the data set
head(myData)
## ID TIME WT AGE SEX AMT DVID DV MDV CL V KA TLAG
## 1 1 0 66.7 50 male 100 0 NA 1 0.278 8.26 0.395 0.976
## 2 1 0 66.7 50 male NA 2 NA 1 0.278 8.26 0.395 0.976
## 3 1 24 66.7 50 male NA 2 44 0 0.278 8.26 0.395 0.976
## 4 1 36 66.7 50 male NA 2 27 0 0.278 8.26 0.395 0.976
## 5 1 48 66.7 50 male NA 2 28 0 0.278 8.26 0.395 0.976
## 6 1 72 66.7 50 male NA 2 31 0 0.278 8.26 0.395 0.976
Extract only observation records
myEDAData<-myData[myData$MDV==0,]
Open an R window to record and access all your plots
windows(record=TRUE)
Now plot the data using xyplot from the lattice library
plot3 <- xyplot(DV~TIME,groups=ID,data=myEDAData,subset=DVID==2,type="b",ylab="PCA",xlab="Time (h)")
print(plot3)
plot4 <- xyplot(DV~TIME|ID,data=myEDAData,subset=DVID==2,type="b",layout=c(3,4),ylab="PCA",xlab="Time (h)",scales=list(relation="free"))
print(plot4)
Export the results in a PDF file
pdf(paste0(uc,"_EGA.pdf"))
print(plot3)
print(plot4)
dev.off()
## png
## 2
The ddmore “estimate” function translates the contents of the .mdl file to a target language and then estimates parameters using the target software. After estimation, the output is converted to a Standardised Output object which is saved in a .SO.xml file.
Translated files and Monolix output will be returned in the ./Monolix subfolder. The Standardised Output object (.SO.xml) is read and parsed into an R object called “mlx” of (S4) class “StandardOutputObject”.
mlx <- estimate(mdlfile, target="MONOLIX", subfolder="Monolix")
## -- Tue Aug 16 17:48:54 2016
## New
## Submitted
## Job 19773e24-a8b9-4d6c-ae14-619e0c7d65c0 progress:
## Running [ ...... ]
## Importing Results
## Copying the result data back to the local machine for job ID 19773e24-a8b9-4d6c-ae14-619e0c7d65c0...
## From C:\Users\zparra\AppData\Local\Temp\Rtmpk5tG0t\DDMORE.job1c843c7d1eea to D:/SEE-Prod5_RC4/MDL_IDE/workspace/UseCasesDemo/UseCase3_1/Monolix
## Done.
##
##
## The following main elements were parsed successfully:
## ToolSettings
## RawResults
## Estimation::PopulationEstimates::MLE
## Estimation::PrecisionPopulationEstimates::MLE
## Estimation::IndividualEstimates::Estimates
## Estimation::IndividualEstimates::RandomEffects
## Estimation::Residuals::ResidualTable
## Estimation::Predictions
## Estimation::OFMeasures::IndividualContribToLL
## Estimation::OFMeasures::InformationCriteria
## Estimation::OFMeasures::LogLikelihood
##
## Completed
## -- Tue Aug 16 17:50:59 2016
slotNames(mlx)
## [1] "ToolSettings" "RawResults" "TaskInformation"
## [4] "Estimation" "ModelDiagnostic" "Simulation"
## [7] "OptimalDesign" ".pathToSourceXML"
The ddmore “LoadSOObj” reads and parsed existing Standardise Output Objects
mlx <- LoadSOObject(“Monolix/UseCase3_1.SO.xml”)
The ddmore function “getPopulationParameters” extracts the Population Parameter values from an R object of (S4) class “StandardOutputObject” and returns the estimates. See documentation for getPopulationParameters to see other arguments and settings for this function.
parameters_mlx <- getPopulationParameters(mlx, what="estimates")$MLE
print(parameters_mlx)
## POP_PCA0 POP_TEQ POP_C50 POP_EMAX PPV_PCA0 PPV_TEQ PPV_C50 PPV_EMAX
## 96.22244 13.09847 1.17781 1.00000 0.05236 0.10754 0.43963 0.00000
## RUV_FX
## 3.75425
print(getPopulationParameters(mlx, what="precisions"))
## $MLE
## Parameter MLE SE RSE
## 1 POP_C50 1.17781 0.09410 7.99
## 2 POP_EMAX 1.00000 0.00000 0.00
## 3 POP_PCA0 96.22244 1.08568 1.13
## 4 POP_TEQ 13.09847 0.39148 2.99
## 5 PPV_C50 0.43963 0.05787 13.16
## 6 PPV_EMAX 0.00000 0.00000 0.00
## 7 PPV_PCA0 0.05236 0.00972 18.57
## 8 PPV_TEQ 0.10754 0.03035 28.22
## 9 RUV_FX 3.75425 0.22135 5.90
print(getEstimationInfo(mlx))
## $OFMeasures
## $OFMeasures$LogLikelihood
## $OFMeasures$LogLikelihood[[1]]
## [1] -722.45
##
##
## $OFMeasures$IndividualContribToLL
## Subject ICtoLL
## 1 1 -24.98
## 2 2 -20.82
## 3 3 -31.60
## 4 4 -23.18
## 5 5 -25.86
## 6 6 -22.88
## 7 7 -24.16
## 8 8 -23.44
## 9 9 -24.56
## 10 10 -23.06
## 11 12 -22.97
## 12 13 -16.06
## 13 14 -23.37
## 14 15 -24.65
## 15 16 -22.71
## 16 17 -24.19
## 17 18 -19.90
## 18 19 -19.54
## 19 20 -21.70
## 20 21 -20.15
## 21 22 -24.54
## 22 23 -22.63
## 23 24 -18.99
## 24 25 -30.98
## 25 26 -19.10
## 26 27 -19.06
## 27 28 -23.09
## 28 29 -19.21
## 29 30 -22.19
## 30 31 -20.78
## 31 32 -20.85
## 32 33 -21.23
##
## $OFMeasures$InformationCriteria
## $OFMeasures$InformationCriteria$AIC
## [1] 1458.9
##
## $OFMeasures$InformationCriteria$BIC
## [1] 1469.16
##
##
##
## $Messages
## list()
There is currently a bug with as.xpdb and Monolix in UseCase3_1. Therefore, goodness-of-fit plots are created manually from the standardised output. Later in the script, Xpose functionality on UseCase3 is shown for NONMEM.
Use 'ddmore' function as.xpdb() to create an Xpose database object from the standardised output object, regardless of target software used for estimation. Users can then call xpose functions directly.
mlx.xpdb<-as.xpdb(mlx,datafile)
##
## Removed dose rows in rawData slot of SO to enable merge with Predictions data.
We can then call Xpose functions referencing this mlx.xpdb object as the input. Perform some basic goodness of fit (graphs are exported to PDF file)
pdf("GOF_MLX.pdf")
basic.gof(mlx.xpdb,by="DVID",subset="DVID==2")
ind.plots(mlx.xpdb,subset="DVID==2")
dev.off()
## png
## 2
myPredictions <- mlx@Estimation@Predictions@data
myPredictions <- apply(myPredictions,2,as.numeric)
myXPDB <- merge(myEDAData, myPredictions)
plot(ggplot() + ggtitle("PCA level") +
geom_abline() +
geom_point(data=myXPDB[myXPDB$DVID==2,], aes(x=PRED, y=DV)) +
xlab("Population predictions") + ylab("Observations") )
plot(ggplot() + ggtitle("PCA level") +
geom_abline() +
geom_point(data=myXPDB[myXPDB$DVID==2,], aes(x=IPRED, y=DV)) +
xlab("Individual predictions") + ylab("Observations") )
MDL Objects can be manipulated from R to change for example the estimation algorithm
myTaskProperties <- getTaskPropertiesObjects(mdlfile)[[1]]
myNewTaskProperties <- myTaskProperties
myNewTaskProperties@ESTIMATE$algo <- "focei"
Assembling the new MOG. Note that we reuse the data and model from the previous run.
myNewerMOG <- createMogObj(dataObj = getDataObjects(mdlfile)[[1]],
parObj = getParameterObjects(mdlfile)[[1]],
mdlObj = getModelObjects(mdlfile)[[1]],
taskObj = myNewTaskProperties)
We can then write the MOG back out to an .mdl file.
mdlfile.FOCEI <- paste0(uc,"_FOCEI.mdl")
writeMogObj(myNewerMOG,mdlfile.FOCEI)
Test estimation using this new MOG.
NM.FOCEI <- estimate(mdlfile.FOCEI, target="PsN", subfolder="NONMEM_FOCEI")
## -- Tue Aug 16 17:51:17 2016
## New
## Submitted
## Job a0b8c2a7-e948-4bf9-af6b-d7d1dd022b4e progress:
## Running [ ......... ]
## Importing Results
## Copying the result data back to the local machine for job ID a0b8c2a7-e948-4bf9-af6b-d7d1dd022b4e...
## From C:\Users\zparra\AppData\Local\Temp\Rtmpk5tG0t\DDMORE.job1c8477a27221 to D:/SEE-Prod5_RC4/MDL_IDE/workspace/UseCasesDemo/UseCase3_1/NONMEM_FOCEI
## Done.
##
##
## The following main elements were parsed successfully:
## RawResults
## Estimation::PopulationEstimates::MLE
## Estimation::IndividualEstimates::Estimates
## Estimation::IndividualEstimates::RandomEffects
## Estimation::Residuals::ResidualTable
## Estimation::Predictions
## Estimation::OFMeasures::Deviance
##
## The following MESSAGEs were raised during the job execution:
## estimation_successful: 1
## covariance_step_run: 0
## rounding_errors: 0
## hessian_reset: 0
## zero_gradients: 0
## final_zero_gradients: 0
## estimate_near_boundary: 0
## s_matrix_singular: 0
## significant_digits: 3.8
## nmoutput2so_version: This SOBlock was created with nmoutput2so version 4.5.27
##
## Completed
## -- Tue Aug 16 17:54:22 2016
Load previous results
NM.FOCEI <- LoadSOObject(“NONMEM_FOCEI/UseCase3_1_FOCEI.SO.xml”)
Results from NONMEM should be comparable to previous results
print(getPopulationParameters(NM.FOCEI, what="estimates"))
## $MLE
## POP_PCA0 POP_C50 POP_TEQ RUV_FX POP_EMAX PPV_PCA0
## 96.6348000 1.1755700 13.0066000 3.7638300 1.0000000 0.0532667
## PPV_EMAX PPV_C50 PPV_TEQ
## 0.0000000 0.4394390 0.1015090
Before running the VPC with PsN we must update the (initial) values in the MDL Parameter Object MLE estimates from previous step can be used
structuralPar <- getPopulationParameters(NM.FOCEI, what="estimates",block='structural')$MLE
variabilityPar <- getPopulationParameters(NM.FOCEI, what="estimates",block='variability')$MLE
Update the parameter object using the ddmore “updateParObj” function. This function updates an R object of (S4) class “parObj”. The user chooses which block to update, what items within that block, and what to replace those items with. NOTE: that updateParObj can only update attributes which ALREADY EXIST in the MDL Parameter Object for that item. This ensures that valid MDL is preserved.
myParObj <- getParameterObjects(mdlfile)[[1]]
myParObjUpdated <- updateParObj(myParObj,block="STRUCTURAL",
item=names(structuralPar),
with=list(value=structuralPar))
myParObjUpdated <- updateParObj(myParObjUpdated,block="VARIABILITY",
item=names(variabilityPar),
with=list(value=variabilityPar))
Check that the appropriate initial values have been updated to the MLE values from the previous fit.
print(myParObjUpdated@STRUCTURAL)
## $POP_PCA0
## $POP_PCA0$value
## [1] "96.6348"
##
## $POP_PCA0$lo
## [1] "0.01"
##
## $POP_PCA0$hi
## [1] "200"
##
##
## $POP_EMAX
## $POP_EMAX$value
## [1] "1"
##
## $POP_EMAX$lo
## [1] "0"
##
## $POP_EMAX$fix
## [1] "true"
##
##
## $POP_C50
## $POP_C50$value
## [1] "1.17557"
##
## $POP_C50$lo
## [1] "0.01"
##
## $POP_C50$hi
## [1] "10"
##
##
## $POP_TEQ
## $POP_TEQ$value
## [1] "13.0066"
##
## $POP_TEQ$lo
## [1] "0.01"
##
## $POP_TEQ$hi
## [1] "100"
##
##
## $RUV_FX
## $RUV_FX$value
## [1] "3.76383"
##
## $RUV_FX$lo
## [1] "0"
print(myParObjUpdated@VARIABILITY)
## $PPV_PCA0
## $PPV_PCA0$value
## [1] "0.0532667"
##
## $PPV_PCA0$type
## [1] "sd"
##
##
## $PPV_EMAX
## $PPV_EMAX$value
## [1] "0"
##
## $PPV_EMAX$type
## [1] "sd"
##
## $PPV_EMAX$fix
## [1] "true"
##
##
## $PPV_C50
## $PPV_C50$value
## [1] "0.439439"
##
## $PPV_C50$type
## [1] "sd"
##
##
## $PPV_TEQ
## $PPV_TEQ$value
## [1] "0.101509"
##
## $PPV_TEQ$type
## [1] "sd"
Assembling the new MOG. Note that we reuse the data, model and tasks from the previous run.
myVPCMOG <- createMogObj(dataObj = getDataObjects(mdlfile)[[1]],
parObj = myParObjUpdated,
mdlObj = getModelObjects(mdlfile)[[1]],
taskObj = getTaskPropertiesObjects(mdlfile)[[1]])
We can then write the MOG back out to an .mdl file.
mdlfile.VPC <- paste0(uc,"_VPC.mdl")
writeMogObj(myVPCMOG,mdlfile.VPC)
Similarly as above, ddmore “VPC.PsN” function can be used to run a VPC using PsN as target tool
vpcFiles <- VPC.PsN(mdlfile.VPC,samples=20, seed=12345,
vpcOptions ="-n_simulation=10 -auto_bin=5,8",
subfolder="VPC", plot=FALSE)
## -- Tue Aug 16 17:54:38 2016
## New
## Submitted
## Job 63de699a-a129-48d0-8874-b25a22546bcb progress:
## Running [ ..... ]
## Importing Results
## Copying the result data back to the local machine for job ID 63de699a-a129-48d0-8874-b25a22546bcb...
## From C:\Users\zparra\AppData\Local\Temp\Rtmpk5tG0t\DDMORE.job1c846d0050f3 to D:/SEE-Prod5_RC4/MDL_IDE/workspace/UseCasesDemo/UseCase3_1/VPC
## Done.
##
##
## The following main elements were parsed successfully:
## RawResults
## SimulationSimulationBlock
## SimulationSimulationBlock
##
## The following MESSAGEs were raised during the job execution:
## nmoutput2so_version: This SOBlock was created with nmoutput2so version 4.5.27
##
## Completed
## -- Tue Aug 16 17:56:24 2016
To replay the visualisation using information from the VPC SO file
pdf(paste0(uc,"_VPC.pdf"))
print(xpose.VPC(vpc.info= file.path("./VPC",vpcFiles@RawResults@DataFiles$PsN_VPC_results$path),
vpctab= file.path("./VPC",vpcFiles@RawResults@DataFiles$PsN_VPC_vpctab$path),
main="VPC warfarin PK/PD"))
dev.off()
## png
## 2
The mlxR package has been developed to visualize and explore models that are encoded in MLXTRAN or PharmML. The ddmore function as.PharmML translates an MDL file (extension .mdl) to its PharmML representation. The output file (extension .xml) is saved in the working directory.
myPharmML <- as.PharmML(mdlfile)
Use parameter values from the Monolix estimation
parValues <- getPopulationParameters(mlx, what="estimates")$MLE
Simulate for the typical weight of 70. Recall that logtWT = log(WT/70).
p <- c(parValues,WT=70,CL=0.139,V=8,KA=2.64,TLAG=0.976)
Parameter values used in simulation
print(p)
## POP_PCA0 POP_TEQ POP_C50 POP_EMAX PPV_PCA0 PPV_TEQ PPV_C50 PPV_EMAX
## 96.22244 13.09847 1.17781 1.00000 0.05236 0.10754 0.43963 0.00000
## RUV_FX WT CL V KA TLAG
## 3.75425 70.00000 0.13900 8.00000 2.64000 0.97600
Simulate for a dose of 100mg given at time 0 into the GUT (oral administration)
adm <- list( time = 0, amount = 100)
Simulate PK parameters for individuals
ind <- list(name = c('TEQ','C50','PCA0','EMAX'))
Simulate predicted (CC) and observed concentration values (CP_obs), predicted (PCA) and observed PCA (PCA_obs)
f2 <- list( name = c('PCA'), time = seq(0,to=50,by=1))
y2 <- list( name = c('PCA_obs'), time = c(0, 0.5, 1, 2, 3, 4, 6, 8, 12, 24, 36, 48))
Simulate 12 subjects
g <- list( size = 12, level = 'individual', treatment = adm)
Call simulx
res <- simulx(model = myPharmML,
parameter = p,
group = g,
output = list(ind,f2,y2))
Simulated parameter values for each individual
print(res$parameter)
## id TEQ C50 PCA0 EMAX
## 1 1 13.13711 0.5850570 88.89440 1
## 2 2 12.63256 1.3696278 91.58011 1
## 3 3 13.13277 0.9444983 95.79183 1
## 4 4 12.17334 1.1199062 90.52653 1
## 5 5 13.42784 2.0796638 102.52597 1
## 6 6 14.15351 1.4592066 97.26957 1
## 7 7 13.23981 1.1176807 98.10918 1
## 8 8 13.49183 1.6380987 96.40673 1
## 9 9 13.13777 2.2158749 100.02220 1
## 10 10 14.74174 1.6561927 107.19870 1
## 11 11 14.05558 1.5601296 100.13338 1
## 12 12 13.30317 0.7213143 93.52413 1
Plot simulated results
plot(ggplot() +
geom_line(data=res$PCA, aes(x=time, y=PCA, colour=id)) +
geom_point(data=res$PCA_obs, aes(x=time, y=PCA_obs, colour=id)) +
xlab("time (h)") + ylab("PCA") )
Simulate 1000 subjects - with simulx this is a QUICK process!
g <- list( size = 1000, level = 'individual', treatment = adm)
Call simulx
res.1000 <- simulx(model =myPharmML,
parameter = p,
group = g,
output = list(ind,f2,y2))
Plot of predicted concentrations band defines the percentile bands displayed level = range of values to examine (in %) 100 = full range of values number = number of bins within the level range. Plot of observed PCA levels (with residual error)
prctilemlx(res.1000$PCA_obs,band=list(number=9, level=90))
Table of the same information
prctilemlx(res.1000$PCA_obs,band=list(number=10, level=100), plot=F)$y
## time 0% 10% 20% 30% 40% 50% 50%
## 1 0.0 80.80782 87.71609 90.62009 93.20755 94.70615 96.82203 96.82203
## 2 0.5 81.79883 88.29684 90.62239 92.72910 94.04895 96.93432 96.93432
## 3 1.0 82.19491 88.44517 90.80083 93.84492 95.09661 96.44032 96.44032
## 4 2.0 79.92890 85.66292 87.62960 89.18685 90.64459 92.33912 92.33912
## 5 3.0 72.67165 81.46284 84.46590 85.80091 87.62213 88.75165 88.75165
## 6 4.0 72.90332 77.39289 80.18231 81.42480 82.54670 84.29300 84.29300
## 7 6.0 63.21221 69.56848 71.62519 73.77040 74.83148 76.25319 76.25319
## 8 8.0 53.12278 63.62336 65.43826 67.21999 68.72875 70.32720 70.32720
## 9 12.0 43.31475 50.51841 52.78452 54.48037 56.68720 58.93206 58.93206
## 10 24.0 24.55448 28.92819 30.10429 32.10619 34.53137 36.17932 36.17932
## 11 36.0 12.03267 17.27569 18.58139 21.60372 24.43431 25.86370 25.86370
## 12 48.0 5.01268 13.67069 15.85161 17.55724 19.21846 20.55666 20.55666
## 60% 70% 80% 90% 100%
## 1 98.01844 99.00440 101.75152 105.09070 110.92809
## 2 98.59772 99.79860 101.52452 104.13297 115.22040
## 3 97.93200 100.13965 102.57501 104.98236 111.90698
## 4 93.66400 95.40340 98.42196 99.85229 108.71710
## 5 89.73239 91.16822 93.04803 95.02154 99.61950
## 6 85.60058 86.71709 88.79145 90.63862 97.11764
## 7 77.52433 78.92731 81.28792 85.38052 89.25445
## 8 71.30379 72.59227 73.98983 76.71863 85.31144
## 9 60.45358 61.99947 64.69160 66.96287 75.06890
## 10 37.56840 38.63930 41.08998 44.06710 56.63046
## 11 27.71709 29.37971 32.69246 36.59667 44.33175
## 12 22.19428 24.72106 27.76607 31.25445 38.38310