Overview

Description

buildVar is designed to build the best variance model for the random effects by selecting which individual parameters vary and which ones are fixed.

Penalization criterion can be either a custom penalization of the form \(\gamma\)*(number of parameters), AIC (\(\gamma=2\)), BIC (\(\gamma=\log(N)\)) or BICc.

Usage 

buildVar <- function(project=NULL,final.project=NULL, prior=NULL, weight=NULL, cv.min=0.001, 
                     fix.param1=NULL, fix.param0=NULL, criterion="BICc", linearization=F, remove=T, add=T,
                     delta=c(30,10,5), omega.set=NULL, pop.set1=NULL, pop.set2=NULL, print=TRUE)

Arguments

project
a string: the initial Monolix project
final.project
the final Monolix project (default is the original project)a string: the final Monolix project (default adds “_var” to the original project)
prior
named vector of prior probabilities (default=NULL)
weight
named vector of weights (default=NULL)
cv.min
value of the coefficient of variation below which an individual parameter is considered fixed (default=0.001)
fix.param1
parameters with variability that cannot be removed (default=NULL)
fix.param0
parameters without variability that cannot be added (default=NULL)
criterion
penalization criterion to optimize c(“AIC”, “BIC”, {“BICc”}, gamma)
linearization
TRUE/{FALSE} whether the computation of the likelihood is based on a linearization of the model (default=FALSE)
remove
{TRUE}/FALSE try to remove random effects (default=TRUE)
add
{TRUE}/FALSE try to add random effects (default=TRUE)
delta
maximum difference in criteria for testing a new model (default=c(30,10,5))
omega.set
settings to define how a variance varies during iterations of SAEM
pop.set1
Monolix settings 1
pop.set2
Monolix settings 2
print
{TRUE}/FALSE display the results (default=TRUE)


Example

library(Rsmlx)

We select a Monolix project

project <- "projects/simulatedPK1.mlxtran"

The model has 5 parameters: ka, Cl, V1, Q, V2. We will use buildVar to distinguish the parameters with and without IIV.

buildVar.res1 <- buildVar(project)
## 
## --------------------------------------------------
## 
## Building the variance model
## 
## __________________________________________________
## 
## Estimating the population parameters
## 
## __________________________________________________
## Iteration  1 
## 
## removing variability...
## 
## -----------------------
## Step  1 
## Parameters without variability:  
## Parameters with variability   : ka Cl V1 Q V2 
## 
## Criterion (linearization):  3843 
## trying to remove omega_V2 : 3839.2 
## trying to remove omega_Q  : 3839.3 
## trying to remove omega_V1 : 3887.7 
## trying to remove omega_Cl : 5481.4 
## trying to remove omega_ka : 4011.8 
## 
## Criterion:  3860.8
## fitting the model with no variability on  V2 : 3852.6
## variability on V2 removed
## 
## -----------------------
## Step  2 
## Parameters without variability: V2 
## Parameters with variability   : ka Cl V1 Q 
## 
## Criterion (linearization):  3837.8 
## trying to remove omega_Q  : 3834.0 
## 
## Criterion:  3852.6
## fitting the model with no variability on  V2 Q : 3849.2
## variability on Q removed
## 
## no more variability can be removed
## _______________________
## 
## adding variability...
## 
## -----------------------
## Step  1 
## Parameters without variability: Q V2 
## Parameters with variability   : ka Cl V1 
## 
## Criterion (linearization):  3833.9 
## trying to add omega_V2 : 3844.9 
## 
## no more variability can be added
## 
## __________________________________________________
## 
## Final variance model: 
## 
## Parameters without variability: Q V2 
## Parameters with variability   : ka Cl V1 
## 
## Fitting the final model using the original settings... 
## 
## Estimated criteria (importanceSampling):
##     AIC     BIC    BICc    s.e. 
## 3795.10 3831.57 3848.96    0.21 
## 
## total time: 263.4s
print(buildVar.res1)
## $project
## [1] "projects/simulatedPK1_var.mlxtran"
## 
## $niter
## [1] 1
## 
## $change
## [1] TRUE
## 
## $variability.model
##    ka    Cl    V1     Q    V2 
##  TRUE  TRUE  TRUE FALSE FALSE 
## 
## $time
## elapsed 
##  263.44

It is possible to fix the type of variability of some parameters of the model. In this example, we force Q to have no IIV while ka and Cl vary:

buildVar.res2 <- buildVar(project, final.project="projects/buildVar2.mlxtran", 
                          fix.param0="Q", fix.param1=c("ka", "Cl"))
print(buildVar.res2$variability.model)
##    ka    Cl    V1     Q    V2 
##  TRUE  TRUE  TRUE FALSE FALSE

Rather than forcing certain parameters to vary or to be fixed, one can introduce a priori information to favor the presence or absence of variability.

We can either define a prior probability or introduce a weighting for the penalty term. For instance, weight=2 means that, for each parameter, we penalize twice as much the presence of a variance, while weight=0.5 means that the penalty is twice less than when the chosen criterion is used by default (i.e. weight=1). By default, BICc is used. Then, the criteria to minimize is -2 LL + weight x log(N) x (number of variances)

In this example, add=F means that the algorithm starts with a full variance model and only tries to remove variances.

buildVar.res3 <- buildVar(project, final.project="projects/buildVar3.mlxtran", weight=3, add=F)
print(buildVar.res3$variability.model)
##    ka    Cl    V1     Q    V2 
##  TRUE  TRUE FALSE FALSE FALSE

Different weights can be used for the different parameters. In this example, the variability of Q is privileged while that of V1 is strongly penalized

buildVar.res4 <- buildVar(project, final.project="projects/buildVar4.mlxtran", weight=c(Q=0.05, V1=20))
print(buildVar.res4$variability.model)
##    ka    Cl    V1     Q    V2 
##  TRUE  TRUE FALSE  TRUE FALSE