Adapt your parameters • campsismod

Prerequisite

The examples below require the package campismod.

library(campsismod)

Retrieve your parameters

The examples below are illustrated based on the reference 2-compartment PK model that you find in the built-in library. This model has 5 parameters. All these parameters have inter-individual variability defined.

model <- model_suite$pk$`2cpt_fo`
model

## [MAIN]
## TVBIO=THETA_BIO
## TVKA=THETA_KA
## TVVC=THETA_VC
## TVVP=THETA_VP
## TVQ=THETA_Q
## TVCL=THETA_CL
## 
## BIO=TVBIO
## KA=TVKA * exp(ETA_KA)
## VC=TVVC * exp(ETA_VC)
## VP=TVVP * exp(ETA_VP)
## Q=TVQ * exp(ETA_Q)
## CL=TVCL * exp(ETA_CL)
## 
## [ODE]
## d/dt(A_ABS)=-KA*A_ABS
## d/dt(A_CENTRAL)=KA*A_ABS + Q/VP*A_PERIPHERAL - Q/VC*A_CENTRAL - CL/VC*A_CENTRAL
## d/dt(A_PERIPHERAL)=Q/VC*A_CENTRAL - Q/VP*A_PERIPHERAL
## 
## [F]
## A_ABS=BIO
## 
## [ERROR]
## CONC=A_CENTRAL/VC
## if (CONC <= 0.001) CONC=0.001
## CONC_ERR=CONC*(1 + EPS_PROP_RUV)
## 
## 
## THETA's:
##   name index value   fix                            label unit
## 1  BIO     1     1 FALSE                  Bioavailability <NA>
## 2   KA     2     1 FALSE                  Absorption rate  1/h
## 3   VC     3    10 FALSE    Volume of central compartment    L
## 4   VP     4    40 FALSE Volume of peripheral compartment    L
## 5    Q     5    20 FALSE           Inter-compartment flow  L/h
## 6   CL     6     3 FALSE                        Clearance  L/h
## OMEGA's:
##   name index index2 value   fix type
## 1   KA     1      1    25 FALSE  cv%
## 2   VC     2      2    25 FALSE  cv%
## 3   VP     3      3    25 FALSE  cv%
## 4    Q     4      4    25 FALSE  cv%
## 5   CL     5      5    25 FALSE  cv%
## SIGMA's:
##       name index index2 value   fix type
## 1 PROP_RUV     1      1   0.1 FALSE   sd
## No variance-covariance matrix
## 
## Compartments:
## A_ABS (CMT=1)
## A_CENTRAL (CMT=2)
## A_PERIPHERAL (CMT=3)

To retrieve a parameter by its name, just call the method find as follows:

model %>% find(Theta("CL"))

##   name index value   fix     label unit comment
## 1   CL     6     3 FALSE Clearance  L/h    <NA>

model %>% find(Omega("KA"))

##   name index index2 value   fix type same label comment
## 1   KA     1      1    25 FALSE  cv%   NA  <NA>    <NA>

model %>% find(Sigma("RUV_FIX"))

## NULL

These parameters can also alternatively be retrieved by their index(es). Use the specific method getByIndex created for that purpose:

model@parameters %>% getByIndex(Theta(index=5))

##   name index value   fix                  label unit comment
## 1    Q     5    20 FALSE Inter-compartment flow  L/h    <NA>

model@parameters %>% getByIndex(Omega(index=1, index2=1))

##   name index index2 value   fix type same label comment
## 1   KA     1      1    25 FALSE  cv%   NA  <NA>    <NA>

model@parameters %>% getByIndex(Sigma(index=1, index2=1))

##       name index index2 value   fix type label comment
## 1 PROP_RUV     1      1   0.1 FALSE   sd  <NA>    <NA>

Access parameter values

Accessing parameter values is straightforward. Parameters have a slot value that may be accessed.

thetaCL <- model %>% find(Theta("CL"))
thetaCL@value

## [1] 3

For OMEGA and SIGMA parameters, be careful; the interpretation of this value depends on the type of the parameter. It may be var (for a variance), covar (for a covariance), sd (for standard deviation), cv (value expressed as coefficient of variation), cv% (value expressed as coefficient of variation in percentage).
For a quick access to the value as variance or covariance, the method standardise can be called first on the parameter itself. This is especially useful for values expressed in CV or in standard deviation.

theta <- Omega(name="TEST", index=1, index2=1, value=15, type="cv%")
theta@value # 15 is returned

## [1] 15

theta_standardised <- theta %>% standardise() # Conversion to variance
theta_standardised

##   name index index2      value   fix type same label comment
## 1 TEST     1      1 0.02225061 FALSE  var   NA  <NA>    <NA>

theta_standardised@value

## [1] 0.02225061

Replace parameters

Parameters can be replaced easily. Here are a few examples:

model <- model %>% replace(Theta("KA", value=2)) # Previous value for KA was 1
model <- model %>% replace(Omega("CL", value=20, type="cv%")) # Previous value was a 25% CV
model

## [MAIN]
## TVBIO=THETA_BIO
## TVKA=THETA_KA
## TVVC=THETA_VC
## TVVP=THETA_VP
## TVQ=THETA_Q
## TVCL=THETA_CL
## 
## BIO=TVBIO
## KA=TVKA * exp(ETA_KA)
## VC=TVVC * exp(ETA_VC)
## VP=TVVP * exp(ETA_VP)
## Q=TVQ * exp(ETA_Q)
## CL=TVCL * exp(ETA_CL)
## 
## [ODE]
## d/dt(A_ABS)=-KA*A_ABS
## d/dt(A_CENTRAL)=KA*A_ABS + Q/VP*A_PERIPHERAL - Q/VC*A_CENTRAL - CL/VC*A_CENTRAL
## d/dt(A_PERIPHERAL)=Q/VC*A_CENTRAL - Q/VP*A_PERIPHERAL
## 
## [F]
## A_ABS=BIO
## 
## [ERROR]
## CONC=A_CENTRAL/VC
## if (CONC <= 0.001) CONC=0.001
## CONC_ERR=CONC*(1 + EPS_PROP_RUV)
## 
## 
## THETA's:
##   name index value   fix                            label unit
## 1  BIO     1     1 FALSE                  Bioavailability <NA>
## 2   KA     2     2 FALSE                             <NA> <NA>
## 3   VC     3    10 FALSE    Volume of central compartment    L
## 4   VP     4    40 FALSE Volume of peripheral compartment    L
## 5    Q     5    20 FALSE           Inter-compartment flow  L/h
## 6   CL     6     3 FALSE                        Clearance  L/h
## OMEGA's:
##   name index index2 value   fix type
## 1   KA     1      1    25 FALSE  cv%
## 2   VC     2      2    25 FALSE  cv%
## 3   VP     3      3    25 FALSE  cv%
## 4    Q     4      4    25 FALSE  cv%
## 5   CL     5      5    20 FALSE  cv%
## SIGMA's:
##       name index index2 value   fix type
## 1 PROP_RUV     1      1   0.1 FALSE   sd
## No variance-covariance matrix
## 
## Compartments:
## A_ABS (CMT=1)
## A_CENTRAL (CMT=2)
## A_PERIPHERAL (CMT=3)

Delete parameters

Parameters can be deleted. Please note that it does not do anything to the equations. Also, the indexes won’t be re-adjusted. Here are a few examples:

model <- model %>% delete(Theta("KA"))
model <- model %>% delete(Omega("CL"))
model

## [MAIN]
## TVBIO=THETA_BIO
## TVKA=THETA_KA
## TVVC=THETA_VC
## TVVP=THETA_VP
## TVQ=THETA_Q
## TVCL=THETA_CL
## 
## BIO=TVBIO
## KA=TVKA * exp(ETA_KA)
## VC=TVVC * exp(ETA_VC)
## VP=TVVP * exp(ETA_VP)
## Q=TVQ * exp(ETA_Q)
## CL=TVCL * exp(ETA_CL)
## 
## [ODE]
## d/dt(A_ABS)=-KA*A_ABS
## d/dt(A_CENTRAL)=KA*A_ABS + Q/VP*A_PERIPHERAL - Q/VC*A_CENTRAL - CL/VC*A_CENTRAL
## d/dt(A_PERIPHERAL)=Q/VC*A_CENTRAL - Q/VP*A_PERIPHERAL
## 
## [F]
## A_ABS=BIO
## 
## [ERROR]
## CONC=A_CENTRAL/VC
## if (CONC <= 0.001) CONC=0.001
## CONC_ERR=CONC*(1 + EPS_PROP_RUV)
## 
## 
## THETA's:
##   name index value   fix                            label unit
## 1  BIO     1     1 FALSE                  Bioavailability <NA>
## 2   VC     3    10 FALSE    Volume of central compartment    L
## 3   VP     4    40 FALSE Volume of peripheral compartment    L
## 4    Q     5    20 FALSE           Inter-compartment flow  L/h
## 5   CL     6     3 FALSE                        Clearance  L/h
## OMEGA's:
##   name index index2 value   fix type
## 1   KA     1      1    25 FALSE  cv%
## 2   VC     2      2    25 FALSE  cv%
## 3   VP     3      3    25 FALSE  cv%
## 4    Q     4      4    25 FALSE  cv%
## SIGMA's:
##       name index index2 value   fix type
## 1 PROP_RUV     1      1   0.1 FALSE   sd
## No variance-covariance matrix
## 
## Compartments:
## A_ABS (CMT=1)
## A_CENTRAL (CMT=2)
## A_PERIPHERAL (CMT=3)

As expected, this model will not be valid anymore:

tryCatch({validObject(model, complete=TRUE)}, error=function(msg) {
  print(msg)
})

## <simpleError in validObject(model, complete = TRUE): invalid class "campsis_model" object: In slot "parameters" of class "parameters": No THETA with index 2>