[COVARIATE]: describing covariates

Description

The section [COVARIATE] is used to list the covariates and define transformations. Note that transformations can also be defined [INDIVIDUAL] or in the [LONGITUDINAL] section if this is more convenient. In both cases, listing the covariates in the [COVARIATE] section is important to make them appear in the covariate elements of Simulx.

In the mlxR package in combination with MonolixSuite 2019 and before, the covariate block can also be used to define distributions of covariates. This is not possible in the 2020 version and later, where covariates are considered as inputs.

Scope

The [COVARIATE] section is used in Mlxtran models for simulation with Simulx. It is only needed for models that have parameters that depend on covariates. Mlxtran models for Monolix do not need this section because the covariate model is defined via the graphical user interface.

Inputs

Inputs to the [COVARIATE] section are provided through the list input = { }. The inputs are typically the untransformed covariates. In addition, for categorical covariates, the type and the categories must be listed using the syntax below. The categories can be strings or integers.

CODE

covName = {type=categorical, categories = {..., ..., ...}}

We recommend using only letters, numbers and underscore as covariate name and covariate categories. For covariate categories, it is possible to use spaces and symbols but the string must then be surrounded by single quotes.

The inputs of the [COVARIATE] section will be recognized as covariates and will appear in the covariate element definition of Simulx. Covariates for which no categories are specified will be considered as continuous covariates for which we can give any double value. Covariates with listed categories are considered as categorical covariates and only the categories listed in the model can be provided as value in the GUI.

Example:

The continuous covariate Age is just listed in the input. The categorical covariates DOSE and SEX have their categories defined just below. As the categories for DOSE have a space, they are surrounded by single quotes.

CODE

[COVARIATE] 
input = {AGE, DOSE, SEX} 
DOSE = {type=categorical, categories={'50 mg', '100 mg'}} 
SEX  = {type=categorical, categories={Female, Male}}

Outputs

All variables that have been defined in the [COVARIATE] section are considered as an output of this section. Outputs from the [COVARIATE] section can be an input for the [INDIVIDUAL] section. [COVARIATE] output to [INDIVIDUAL] input matching is made by matching parameter names in the [COVARIATE] section with parameters in the inputs = { } list of the [INDIVIDUAL] section.

Usage

Transformations of continuous covariates is done in the EQUATION: block via mathematical expressions including if/else statements. Transformations of categorical covariates (such as grouping of categories) is done in the DEFINITION: block. Transformation of categorical covariates is important in Monolix, but has only little interest in Simulx as the same beta can be reused several times for different categories in the [INDIVIDUAL] section. The syntax is the following to transform a categorical covariates called CovName with categories cat1, cat2 and cat3 into a new covariate called transCovName with a first category newcat12 grouping cat1 and cat2 and a second category newcat3 grouping cat3:

CODE

transCovName = {transform = CovName, categories = {newcat12={cat,cat2}, newcat3=cat3}, reference = newcat12}

Examples

In this example, three covariates are defined as input and will appear in the Simulx covariate elements: AGE, SEX and RACE. The categories of the categorical covariates SEX and RACE are defined just below the input list, using strings. In the EQUATION: block, a new covariate logtAGE is defined based on AGE, using an if/else statement to introduce a saturation. In the DEFINITION: block, a new categorical covariate tRACE is defined by grouping the categories Black and White together.

CODE

[COVARIATE]
input = {AGE, RACE, SEX}
RACE = {type=categorical, categories={Asian, Black, White}}
SEX = {type=categorical, categories={F, M}}

EQUATION:
if AGE < 56
logtAGE = log(AGE/35)
else
logtAGE = log(56/35)
end

DEFINITION:
tRACE =
{
transform = RACE, 
categories = {
G_Asian = Asian,
G_Black_White = {Black, White} }, 
reference = G_Black_White
}