Creating a model library

Model libraries are useful to have consistent high-quality basic models that can be used as a model itself or as a building block for other models.

Model library conventions within nlmixr2lib

Compartment and parameter names should be all lower case when on their own and should use snakeCase when combined in some way.

Compartment and parameter names are selected to align with those used by rxode2::linCmt() which are described in the vignette: vignette(“rxode2-model-types”, package = “rxode2”).

Compartment naming

Compartment naming follows compartment names with the linCmt() with augmentation for other compartments:

Estimated parameter naming

To enable more consistent cross-model compatibility, the following conventions should be used unless there is a strong reason for an exception:

Parameter naming

PK models should use the following parameter naming conventions:

When micro-constants are used, they should use the following naming conventions:

Parameter transforms

Parameters are often estimated on a transformed scale. For instance, a natural logarithm transform is often used for parameters that must be positive, and a logit transform is often used when a parameter must remain within a specific range.

Transformed parameters should be prefixed with an indicator of the transformation. Preferred transformation prefixes are:

Generally, for any transform other than natural logarithm, include the full name as a prefix. For example, natural logarithm-transformed ka would be lka and logit-transformed emax would be logitemax.

Random effects

Random effects are estimates as part of a distribution varying by some grouping factor. The grouping factor is often a subject in a clinical trial. (For NONMEM users, random effects are often referred to as inter-individual variability.)

Random effect parameters should prefix the (transformed) parameter name with eta. For example, a random effect on log-transformed clearance would be named etalcl.

Drug effects

Different drug effects may be investigated during model building. And, multiple drug effect styles (linear, Emax, threshold, etc.) may be investigated by the user.

To enable simpler changes to drug effects and to minimize the chance of parameter name collisions when combining models, the following rules are strongly recommended:

Model files

Files in a model library should have the following characteristics:

If a function to modify, self-start, or otherwise help the user would make sense, add it as a new file in the R/ directory with the file name and function name updateModelName() using the word update followed by the model name in camelCase (e.g. updateOncologyXenograftSimeoni2004). If such a function is added, please add it in the messages described above, as well. Update functions must be able to take in a function, an rxUi object, or an nlmixr2fitCore object and should usually return an rxUi object.

For examples, see the package installation directory.