Overview

Description

Automatic search of the best covariate model. Two methods for covariate model building are proposed

Usage

r <- covariateSearch(project, final.project=NULL, method = NULL, covToTest = NULL, covToTransform=NULL, paramToUse = NULL, testRelations = NULL, settings = NULL) 

Arguments

project
a Monolix project.
final.project
[optional] string corresponding to the final Monolix project (default: ‘runFinal.mlxtran’ in covariate search output folder).
method
[optional] string correspondig to the method. It can be ‘COSSAC’ or ‘SCM’. By default, ‘COSSAC’ is used.
covToTest
[optional] vector of covariates to test. Cannot be used if testRelations is defined. By default, all covariates are tested.
covToTransform
[optional] vector of covariates to transform. The transformation consists in a log transform of the covariate with centering by the mean value (ex: WT is transformed into log(WT/mean) with mean the mean WT value over the individuals of the data set). Both the transformed and untransformed covariate are tested by the algorithm. By default, no covariate is transformed. Note: - adding a non-transformed covariate on a lognormally distributed parameter results in an exponential relationship: log(V) = log(Vpop) + betaWT + eta <=> V = Vpop exp(betaWT) exp(eta) - adding a log-transformed covariate on a lognormally distributed parameter results in a power law relationship: log(V) = log(Vpop) + betalog(WT/70) + eta <=> V = Vpop (WT/70)^beta * exp(eta)
paramToUse
vector of parameters which may be function of covariates. Cannot be used if testRelations is defined. By default, all parameters are tested.
testRelations
[optional] list of parameter-covariate relationships to test, ex: list(V=c(“WT”,“SEX”),Cl=c(“CRCL”)). Cannot be used if covToTest or paramToUse is defined. By default, all parameter-covariate relationships are tested.
settings
a list of optional settings. The settings are: - pInclusion [positive double] threshold on the LRT p-value to accept the model with the added parameter-covariate relationship during forward selection (default = .1). Only used if criteria=“LRT”. - pElimination [positive double] threshold on the LRT p-value to accept the model without the removed parameter-covariate relationship during the backward elimination (default = .05). Only used if criteria=“LRT”. - criteriaThreshold [positive double] the threshold on the AIC or BIC difference to accept the model with added/removed parameter-covariate relationship (default = 0). Only used if criteria=“BIC” or “AIC. - linearization [boolean] whether the computation of the likelihood is based on a linearization of the model (default = FALSE). - criteria [string] criteria to optimize. It can be the”BIC“,”AIC“, or”LRT" (default=“LRT”). - direction [string] method for covariate search. It can be “backward”, “forward”, or “both” (default = “both”). - updateInit [boolean] whether to update or not the initial parameters using the estimates of the parent model (default = FALSE) - saveRun [boolean] whether to save or not each run (default = TRUE)


Example

Using the default settings

To run COSSAC on a project, you just have to run

project <- "projects/remifentanil.mlxtran"
covariateSearch(project)

If you want to use the SCM method,

project <- "projects/remifentanil.mlxtran"
covariateSearch(project, method = 'SCM')

Constraining the research

Choosing the parameters to use

The remifentanil project contains 6 parameters (3-cpt PK model with infusion). If you want to constrain the selection to only some parameters, for example, V1 and Cl, you can do it using the argument paramToUse

project <- "projects/remifentanil.mlxtran"
covariateSearch(project, paramToUse = c("V1", "Cl"))

Choosing the covariates to test

By the same way, the remifentanil project contains 4 covariates (AGE, SEX, LBM, and TINFCAT). If you want to constrain the selection to only some covariate, for example, AGE, SEX, and LBM, as TINFCAT is mainly used for display purpose, you can do it using the argument paramToUse

project <- "projects/remifentanil.mlxtran"
covariateSearch(project, covToTest = c("AGE", "SEX", "LBM"))

Choosing the parameter-covariate relationships to test

If you have a deeper knowledge on what relationships make sense, you can do it using the argument testRelations. If for example, you want to only test - AGE and LBM on V1, - AGE and SEX on Cl you can do it as the following

project <- "projects/remifentanil.mlxtran"
covariateSearch(project, testRelations = list(V1 = c("AGE", "LBM"), Cl=c("AGE","SEX"))

Notice that it cannot be used if covToTest or paramToUse is defined.

Changing the settings of the algorithm

Using BIC instead of LRT

project <- "projects/warfarinPK3.mlxtran"
covariateSearch(project, settings = list(criteria = "BIC")

Using only forwarding apporach

By default, a stepwise approach is used, i.e. both forward and backward. You can choose a different option using the setting direction

project <- "projects/warfarinPK3.mlxtran"
covariateSearch(project, settings = list(direction = "forward")

Using different p-values

On the LRT test the accepatance and rejection of a new model is based on the p-value associated to the LRT (loglikelihood ratio test). By default, these values are .1 during the forward phase and .05 during the backward phase. If you want to be more selective, you can play with these p-values. For example, you can be more restrictive.

project <- "projects/warfarinPK3.mlxtran"
covariateSearch(project, settings = list(pElimination = .025, pInclusion = .05)