### Prerequisite

The examples below require the package campismod.

library(campsismod)

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]
## TVKA=THETA_KA
## TVVC=THETA_VC
## TVVP=THETA_VP
## TVQ=THETA_Q
## TVCL=THETA_CL
## TVPROP_RUV=THETA_PROP_RUV
##
## 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)
## PROP_RUV=TVPROP_RUV
##
## [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
##
## [ERROR]
## CONC=A_CENTRAL/VC
## if (CONC <= 0.001) CONC=0.001
## IPRED=log(CONC)
## W=PROP_RUV
## Y=IPRED + W*EPS_RUV_FIX
##
##
## THETA's:
##       name index value   fix
## 1       KA     1   1.0 FALSE
## 2       VC     2  60.0 FALSE
## 3       VP     3  10.0 FALSE
## 4        Q     4   2.0 FALSE
## 5       CL     5   3.0 FALSE
## 6 PROP_RUV     6   0.1 FALSE
## OMEGA's:
##   name index index2 value   fix type same
## 1   KA     1      1    25 FALSE  cv%   NA
## 2   VC     2      2    25 FALSE  cv%   NA
## 3   VP     3      3    25 FALSE  cv%   NA
## 4    Q     4      4    25 FALSE  cv%   NA
## 5   CL     5      5    25 FALSE  cv%   NA
## SIGMA's:
##      name index index2 value  fix type
## 1 RUV_FIX     1      1     1 TRUE  var
## 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
## 1   CL     5     3 FALSE
model %>% find(Omega("KA"))
##   name index index2 value   fix type same
## 1   KA     1      1    25 FALSE  cv%   NA
model %>% find(Sigma("RUV_FIX"))
##      name index index2 value  fix type
## 1 RUV_FIX     1      1     1 TRUE  var

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
## 1   CL     5     3 FALSE
model@parameters %>% getByIndex(Omega(index=1, index2=1))
##   name index index2 value   fix type same
## 1   KA     1      1    25 FALSE  cv%   NA
model@parameters %>% getByIndex(Sigma(index=1, index2=1))
##      name index index2 value  fix type
## 1 RUV_FIX     1      1     1 TRUE  var

### 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
## 1 TEST     1      1 0.02225061 FALSE  var   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]
## TVKA=THETA_KA
## TVVC=THETA_VC
## TVVP=THETA_VP
## TVQ=THETA_Q
## TVCL=THETA_CL
## TVPROP_RUV=THETA_PROP_RUV
##
## 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)
## PROP_RUV=TVPROP_RUV
##
## [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
##
## [ERROR]
## CONC=A_CENTRAL/VC
## if (CONC <= 0.001) CONC=0.001
## IPRED=log(CONC)
## W=PROP_RUV
## Y=IPRED + W*EPS_RUV_FIX
##
##
## THETA's:
##       name index value   fix
## 1       KA     1   2.0 FALSE
## 2       VC     2  60.0 FALSE
## 3       VP     3  10.0 FALSE
## 4        Q     4   2.0 FALSE
## 5       CL     5   3.0 FALSE
## 6 PROP_RUV     6   0.1 FALSE
## OMEGA's:
##   name index index2 value   fix type same
## 1   KA     1      1    25 FALSE  cv%   NA
## 2   VC     2      2    25 FALSE  cv%   NA
## 3   VP     3      3    25 FALSE  cv%   NA
## 4    Q     4      4    25 FALSE  cv%   NA
## 5   CL     5      5    20 FALSE  cv%   NA
## SIGMA's:
##      name index index2 value  fix type
## 1 RUV_FIX     1      1     1 TRUE  var
## 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]
## TVKA=THETA_KA
## TVVC=THETA_VC
## TVVP=THETA_VP
## TVQ=THETA_Q
## TVCL=THETA_CL
## TVPROP_RUV=THETA_PROP_RUV
##
## 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)
## PROP_RUV=TVPROP_RUV
##
## [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
##
## [ERROR]
## CONC=A_CENTRAL/VC
## if (CONC <= 0.001) CONC=0.001
## IPRED=log(CONC)
## W=PROP_RUV
## Y=IPRED + W*EPS_RUV_FIX
##
##
## THETA's:
##       name index value   fix
## 1       VC     2  60.0 FALSE
## 2       VP     3  10.0 FALSE
## 3        Q     4   2.0 FALSE
## 4       CL     5   3.0 FALSE
## 5 PROP_RUV     6   0.1 FALSE
## OMEGA's:
##   name index index2 value   fix type same
## 1   KA     1      1    25 FALSE  cv%   NA
## 2   VC     2      2    25 FALSE  cv%   NA
## 3   VP     3      3    25 FALSE  cv%   NA
## 4    Q     4      4    25 FALSE  cv%   NA
## SIGMA's:
##      name index index2 value  fix type
## 1 RUV_FIX     1      1     1 TRUE  var
## 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): objet de classe "campsis_model" incorrect: In slot "parameters" of class "parameters": First THETA index is different than 1>