--- title: "Model specifications" vignette: > %\VignetteIndexEntry{Model specifications} %\VignetteEngine{quarto::html} %\VignetteEncoding{UTF-8} knitr: opts_chunk: collapse: true comment: '#>' --- ```{r} #| label: setup #| eval: false #| message: false #| warning: false #| include: false library(mapbayr) ``` mapbayr contains a library of example model files (.cpp), accessible with `exmodel()`. You are invited to perform MAP-Bayesian estimation with your own models. These model files should be follow some specifications in order to be "read" by mapbayr. ### 1. `$PARAM` block From mapbayr version 1.0.0, it is not needed to define ETAs in `$PARAM` anymore. If ETA1, ETA2 etc... are found in `$PARAM`, an error will be returned. ```{c, eval = F} // Don't do this anymore $PARAM ETA1 = 0, ETA2 = 0 ``` #### Covariates * Mandatory: + Use a `@covariates` tag to record covariates in the `$PARAM` block. Otherwise, you will not be allowed to pass a dataset with covariates columns. + Set the reference value. * Strongly recommended + Provide a description as a plain text + Provide units in parentheses (or a description of 0/1 coding for categorical covariates) ```{c, eval = F} // Do this $PARAM @covariates BW = 70, SEX = 0 // Better $PARAM @annotated @covariates BW : 70 : Body weight (kg) SEX : 0 : Sex (0=Male, 1=Female) // Don't do this $PARAM BW = 70, SEX = 0 ``` ### 2. `$CMT` block * Strongly recommended... ... and **mandatory** if you have multiple types of DV, i.e. parent drug + metabolite: + A `@annotated` tag must be used to record compartments. + Write OBS in brackets to define the observation compartment(s). Also used by `obs_rows()` to fill the 'cmt' column in your dataset. + Write ADM in brackets to define "default" administration compartment(s). This information is not used for optimization process and the `mapbayest()` function. The information is mandatory if you use `adm_rows()` to build your dataset in order to automatically set the value of the 'cmt' column. Especially useful if you use a model with an absorption from several depot compartment requiring to duplicate administrations lines in the data set. ```{c, eval = F} //example: model with dual zero and first order absorption in compartment 1 & 2, respectively, and observation of parent drug + metabolite $CMT @annotated DEPOT: Depot [ADM] CENT_PAR: examplinib central [ADM, OBS] PERIPH : examplinib peripheral CENT_MET : methylexamplinib central [OBS] ``` ### 3. `$OMEGA` block Define at least one `$OMEGA` block. ```{c, eval = F} $OMEGA 0.123 0.456 0.789 ``` Multiple blocks and all the options (e.g. `correlation`, `block` etc) are allowed. ```{c, eval = F} $OMEGA @annotated ECL : 0.123 : Clearance ETA2 : 0.456 : Volume of distribution FOO : 0.789 : Absorption rate constant // reminder: Each ETA can be described with (`@annotated`) // The labels (on the left-hand side) are not considered by mapbayr ``` ### 4. `$SIGMA` block The definition of the `$SIGMA` block may not be as straightforward as other blocks, but we tried to keep it as simple as possible. Keep in mind that mapbayr always expect a **pair of sigma values** for each type of dependent variable: the **first** value for proportional error, the **second** for additive. Two situations can be distinguished: 1. You only have one type of concentration to fit, and you did not use the [OBS] assignment in `$CMT`. Simply write **one pair** of sigma values to describe proportional and additive error on your concentrations. This error model will be automatically applied to the compartment where observations were recorded in your dataset (i.e. value of CMT when MDV = 0). ```{c, eval = F} $SIGMA 0.111 0 // proportional error ``` ```{c, eval = F} $SIGMA 0 0.222 // (log) additive error ``` ```{c, eval = F} $SIGMA 0.333 0.444 // mixed error ``` 2. You have multiple types of DV (parent and metabolite), and/or you used the [OBS] assignment in `$CMT`. Write as many **pairs of sigma values** as there are compartments assigned with [OBS] in `$CMT`. The order of the pair must respect the order in which compartments were assigned. To put it more clearly, the sigma matrix will be interpreted as such whatever the model : | N° in the SIGMA matrix diagonal | Associated error | |:-------------------------------:|:----------------:| | 1 | Proportional on concentrations in the 1st cmt with [OBS] | | 2 | Additive on concentrations in the 1st cmt with [OBS] | | 3 | Proportional on concentrations in the 2nd cmt with [OBS] | | 4 | Additive on concentrations in the 2nd cmt with [OBS] | ```{c, eval = F} //example: correlated proportional error between parent and metabolite $SIGMA @block 0.050 // proportional error on parent drug 0.000 0.000 // additive error on parent drug 0.100 0.000 0.200 // proportional error on metabolite 0.000 0.000 0.000 0.000 // additive error on metabolite // reminder: sigma values can be recorded in multiple $SIGMA blocks ``` ### 6. `$TABLE` block or `$ERROR` block * Mandatory: + Refer the concentration variable to fit as `DV`. Mind the code, especially if concentrations are observed in multiple compartments. + Express log-additive error models as exponential. This way, concentrations will automatically be log-transformed during the optimization process, with no necessity to prior log-transform your concentration. ```{c, eval = F} $TABLE double DV = (CENTRAL / VC) * exp(EPS(2)) ; ``` + For fitting parent drug and metabolite simultaneously, refer to them as PAR and MET, and define DV accordingly (only DV will be used during the optimization process, but PAR and MET variables are mandatory for post-processing internal functions) ```{c, eval = F} $TABLE double PAR = (CENT_PAR / V) * (1 + EPS(1)) ; double MET = (CENT_MET / V) * (1 + EPS(3)) ; double DV = PAR ; if(self.cmt == 4) DV = MET ; // reminder: use "self.cmt" to internaly refer to a compartment in a mrgsolve model code. ``` Note that mapbayr does not strictly rely on this `$ERROR` block to define the residual error internally and compute the objective function value, but on information passed in the `$SIGMA` block. However, we strongly advise you to properly code your `$ERROR` block with `EPS(1)`, `EPS(2)` etc..., if only to use your code as a regular mrgsolve model code and simulate random effects. ### 7. `$MAIN` block From mapbayr version 1.0.0, it is not needed to duplicate expressions with ETAs in `$MAIN` anymore. ```{c, eval = F} // Do this (as usual) $MAIN double CL = TVCL * exp(ETA(1)) ; // Don't do this anymore MAIN double CL = TVCL * exp(ETA1 + ETA(1)) ; ``` ### 8. `$CAPTURE` block * Mandatory: + DV must be captured + For models with parent + metabolite, PAR and MET must be captured too. + Do not capture variables called IPRED and PRED (they will be returned by `mapbayest()` anyway) + Do not capture any ETAn (ETA1, ETA2 etc...) (they will be returned by `mapbayest()` anyway) * Strongly recommended: + Capture a posteriori values of parameters you are interested in (e.g. CL) ```{c, eval = F} $CAPTURE DV PAR MET CL ```