Simulate with modified parameter values

Built 2025-05-30 using NMsim 0.2.3.903.

Other relevant material

Please note the following ACOP2024 poster which is more recent and more comprehensive than this document:
Simulate modified Nonmem models using NMsim (Poster T19)
Authors: Simone Cassani, Jahidur Rashid, Christopher Banker, Philip Delff

Objectives

This vignettes aims at enabling you to use NMsim for the following purposes

• Simulation with parameters modified from the estimated values

Vary parameter values

Sometimes we want to simulate with some modification to the estimated model. NMsim can make such user-specified modifications to the model before simulating through the modify.model argument.

The SAD study was run with a fast solution formulation. We want to see how a slower absorption rate would affect the PK prediction for the multiple dose regimen. In the model estimate, TVKA=2.17. We now try with a four times slower absorption:

Notice, until NMsim 0.1.0, the modify.model argument was called list.sections. The helper functions add and overwrite were introduced with NMsim 0.1.3. Until then, custom modification functions had to be provided like described in the section “Edit control stream using customized functions”.

file.mod <- system.file("examples/nonmem/xgxr021.mod",package="NMsim")
dat.sim <- read.csv(system.file("examples/derived/dat_sim1.csv",package="NMsim"))

simres <- NMsim(file.mod=file.mod
               ,data=dat.sim
               ,dir.sims="~/NMsim_vignette" ## where to store simulation files
               ,name.sim="original"
               ,seed.R=12345
                )

simres.slowabs <- NMsim(file.mod=file.mod,
                        data=dat.sim
                       ,dir.sims="~/NMsim_vignette" ## where to store simulation files
                       ,name.sim="slower_abs"
                       ,seed.R=12345
                       ##,modfiy.model=list(PK=function(x)c(x,"TVKA=TVKA/4","KA=KA/4"))
                       ,modify.model=list(PK=add("TVKA=TVKA/4","KA=KA/4"))
                        )

rbind(simres,simres.slowabs) |>
    ggplot(aes(TIME,PRED,colour=model))+
    geom_line()

We used modify.model to modify the $PK section. We used it to append two lines. We could use it to modify any section in the model, and we could essentially do any modification. However, appending to $PK or $PRED is simple and often both robust and flexible enough.

That was a very spcific analysis of one specific KA value. It is often more convenient to control the numeric changes to the model using the simulation input data set rather than hard-coding numerical values into modify.model. The following tries a number of fold changes to KA.

setDT(dat.sim)
## this repeats dat.sim for each of the values in KASCAL - effectively
## an outer join
dat.sim.varka <- dat.sim[,data.table(KASCALE=c(1,4,10)),by=dat.sim]
dat.sim.varka[,ID:=.GRP,by=.(KASCALE,ID)]
setorder(dat.sim.varka,ID,TIME,EVID)

simres.varka <- NMsim(file.mod=file.mod,
                      data=dat.sim.varka
                     ,dir.sims="~/NMsim_vignette" ## where to store simulation files
                     ,name.sim="varka"
                     ,seed=12345
                     ## ,modify.model=list(PK=function(x)c(x,"TVKA=TVKA/KASCALE","KA=KA/KASCALE"))
                     ,modify.model=list(PK=add(c("TVKA=TVKA/KASCALE","KA=KA/KASCALE")))
                      )

ggplot(simres.varka[simres.varka$EVID==2,],aes(TIME,PRED,colour=factor(KASCALE)))+
geom_line()+
labs(colour="Fold absorption prolongation")

Edit control stream using customized functions

The modify.model argument can be used to apply customized functions to control stream sections. In the example above, we used

modify.model=list(PK=add(c("TVKA=TVKA/KASCALE","KA=KA/KASCALE")))

This is exactly the same as creating a custom function that adds those two lines (text strings to a vector of text strings each representing a line in the control stream)

modify.model=list(PK=function(x)c(x,"TVKA=TVKA/KASCALE","KA=KA/KASCALE"))

We can use a difference custom function to modify TVKA when it is first defined in the control stream. The following uses a regular expression to substitute

simres.varka2 <- NMsim(file.mod=file.mod,
                      data=dat.sim.varka
                     ,dir.sims="~/NMsim_vignette" ## where to store simulation files
                     ,name.sim="varka2"
                     ,seed.R=12345
                     ,modify.model=list(PK=function(x) {
                         ## identify line number if first definition of TVKA
                         idx.line1.TVKA <- min(grep(" *TVKA *=",x))
                         ## add /KASCALE after dropping potential comments
                         x[idx.line1.TVKA] <- paste(sub(";.*","",x[idx.line1.TVKA]),"/KASCALE")
                         x})
                      )

simres.both <- rbind(simres.varka[,method:="add()"],
                     simres.varka2[,method:="custom/sub()"]
                     )

ggplot(simres.both[EVID==2],aes(TIME,PRED,colour=factor(KASCALE)))+
geom_line()+
    labs(colour="Fold absorption prolongation")+
    facet_wrap(~method)