Creating a Parameter Key

Parameter descriptions for PK model parameter tables.

yaml

1 Introduction

When formatting the NONMEM® model output to make report-ready Parameter Tables using the pmparams package, we also need to tell R how to interpret the parameter values.

Here we outline the information expected in the parameter key and the options currently available for interpreting the estimates.

2 Parameter key overview

There are four arguments required for each parameter in the model.

  • abb - abbreviation for model parameter (we use latex coding)
  • desc - parameter description to appear in the table
  • panel - the panel label the parameter should appear under
  • trans - definition of how the parameter should be transformed

For example:

THETA1
  abb: "KA (1/h)"
  desc: "First order absorption rate constant"
  panel: struct
  trans: logTrans

The parameter key is usually written in a YAML file: pk-parameter-key.yaml. The advantage is that, depending how your model development progressed, you could potentially use the same parameter key for the base model, final model and bootstrap model parameter tables.

If you prefer to keep the parameter descriptions with the table code we provide an example of how that works here: pk-final-model-table-no-yml.R. The only significant difference between a parameter key yaml and data frame is that instead of having the name of the parameters be yaml variables, they are under “name” column.

2.1 Name

For each model parameter, you need to provide the NONMEM® parameter name and number (without any punctuation), for example,

THETA1
  abb: 
  desc: 
  panel: 
  trans: 

THETA2
  abb: 
  desc: 
  panel: 
  trans: 
    
OMEGA11
  abb: 
  desc: 
  panel: 
  trans: 

SIGMA11
  abb: 
  desc: 
  panel: 
  trans:

A note on YAML syntax: each item in the YAML file needs a unique descriptor, and for simplicity, we use the model parameter name and number to indicate each new variable. Here the NONMEM® parameter THETA(1) is under the variable THETA1. This model parameter name and number must exactly match the NONMEM® name/number (without punctuation) because it is used later to join this parameter key to the NONMEM® output.

2.2 Abbreviation and description

An abbreviation and description of each field should be provided for each model parameter:

  • The abb field should contain the abbreviation you want to appear in the parameter table. As MetrumRG reports are written in Latex we use latex coding in the abbreviation field.
  • The desc field should be a brief description that appears in the parameter table.
THETA1
  abb: "KA (1/h)"
  desc: "First order absorption rate constant"
THETA2
  abb: "V2/F (L)"
  desc: "Apparent central volume"
OMEGA11
  abb: "IIV-KA"
  desc: "Variance of absorption"
SIGMA11
  abb: "Proportional"
  desc: "Variance"

2.3 Panel options

The report-ready parameter tables split the parameters into key parameter types using panels. The panel field of the parameter key should contain specific arguments corresponding to the potential panel labels. We include several options the common panel labels (these can easily be expanded as needed):

  • struct - “Structural model parameters”
  • cov - “Covariate effect parameters”
  • IIV - “Interindividual covariance parameters”
  • IIV - “Interindividual variance parameters”
  • IOV - “Interoccasion variance parameters”
  • RV - “Residual variance”

For example:

THETA1
  abb: "KA (1/h)"
  desc: "First order absorption rate constant"
  panel: struct
THETA2
  abb: "V2/F (L)"
  desc: "Apparent central volume"
  panel: struct
OMEGA11
  abb: "IIV-KA"
  desc: "Variance of absorption"
  panel: IIV
SIGMA11
  abb: "Proportional"
  desc: "Variance"
  panel: RV

2.4 Transformations

Model parameters often need to be transformed during model development; the trans field tells R how to back-transform these parameters for the report-ready table. We again include several options for the common transformation (these can easily be expanded as needed):

  • none - untransformed parameters (e.g. THETAs or off-diagonals)
  • logTrans - THETAs estimated in the log domain
  • logitTrans - THETAs estimated using a logit transform
  • lognormalOm - log-normal OMEGAs
  • OmSD - OMEGAs where you want to return SD only
  • logitOmSD - OMEGAs using logit transform
  • addErr - additive error terms
  • propErr - proportional error terms

For example:

THETA1
  abb: "KA (1/h)"
  desc: "First order absorption rate constant"
  panel: struct
  trans: logTrans
THETA2
  abb: "V2/F (L)"
  desc: "Apparent central volume"
  panel: struct
  trans: logTrans
OMEGA11
  abb: "IIV-KA"
  desc: "Variance of absorption"
  panel: IIV
  trans: lognormalOm
SIGMA11
  abb: "Proportional"
  desc: "Variance"
  panel: RV
  trans: propErr

3 Example parameter key

When all parameters have been described in the parameter key YAML file (pk-parameter-key.yaml), use the file path to the parameter key as an input to the define_param_table and define_boot_boot_table pmparams functions.

key <- here::here("script", "pk-parameter-key.yaml")

3.1 Parameter key without a YAML file

If you prefer to keep all parameter table code in a single R file, then you can also define the parameters directly in R. We provide an example of this here: pk-final-model-table-no-yml.R. The only significant difference between a parameter key yaml and data frame is that instead of having the name of the parameters be yaml variables, they are under “name” column.