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:

depot: The extravascular dosing compartment (for example, the gut for oral dosing or subcutaneous space for subcutaneous dosing)
central: The intravascular compartment used for intravenous dosing or for typical pharmacokinetic (PK) model sampling of the drug
peripheral1, peripheral2: The first and second peripheral compartments for 2- and 3-compartment PK models
effect: The compartment for effect compartment models
Therapeutic-area-specific models should use consistent compartment and parameter naming. When adding a new therapeutic area model to the library, please discuss naming first in a new GitHub issue.

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:

Pharmacokinetic concentrations in the central compartment should be named cp. cp should be used even when using a linCmt() model (in which case cp <- linCmt() should be used and the residual error should be applied to the cp parameter).
Therapeutic-area-specific models should use consistent compartment and parameter naming. When adding a new therapeutic area model to the library, please discuss naming first in a new GitHub issue.

Parameter naming

PK models should use the following parameter naming conventions:

ka: absorption rate
cl: clearance
q: intercompartmental clearance (central to and from peripheral1 compartments)
q2: second intercompartmental clearance (central to and from peripheral2 compartments)
vc: central volume of distribution
vp, vp2: first and second peripheral compartment volumes

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

kel elimination rate (cl/vc)
k12, k21, k13, k31: intercompartmental transit rates (q/vc, q/vp, q2/vc, and q2/vp2, respectively)

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:

l (lower case L): natural log transform
logit: logit transform
probit: probit transform
Any other transform should similarly include the full transform as the prefix

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.