The ini block

The ini block specifies initial conditions, including initial estimates and boundaries for those algorithms which support them (currently, the built-in nlme and saem methods do not). Nomenclature is similar to that used in NONMEM, Monolix and other similar packages. In the NONMEM world, the ini block is analogous to $THETA, $OMEGA and $SIGMA blocks.

f <- function(){ # Note that arguments to the function are currently
                 # ignored by nlmixr
    ini({
        # Initial conditions for population parameters (sometimes
        # called THETA parameters) are defined by either '<-' or '='
        lCl <- 1.6      # log Cl (L/hr)
        
        # Note that simple expressions that evaluate to a number are
        # OK for defining initial conditions (like in R)
        lVc = log(90)  # log V (L)
        
        ## Also, note that a comment on a parameter is captured as a parameter label
        lKa <- 1       # log Ka (1/hr)
        
        # Bounds may be specified by c(lower, est, upper), like NONMEM:
        # Residuals errors are assumed to be population parameters
        prop.err <- c(0, 0.2, 1)
        
        # IIV terms will be discussed in the next example
    })
    
    # The model block will be discussed later
    model({})
}

As shown in the above example:

• Simple parameter values are specified using an R-compatible assignment
• Boundaries my be specified by c(lower, est, upper).
• Like NONMEM, c(lower,est) is equivalent to c(lower,est,Inf)
• Also like NONMEM, c(est) does not specify a lower bound, and is equivalent to specifying the parameter without using R’s c() function.

These parameters can be named using almost any R-compatible name. Please note that:

• Residual error estimates should be coded as population estimates (i.e. using = or <-, not ~).
• Variable names that start with _ are not supported. Note that R does not allow variable starting with _ to be assigned without quoting them.
• Naming variables that start with rx_ or nlmixr_ is not allowed, since RxODE and nlmixr use these prefixes internally for certain estimation routines and for calculating residuals.
• Variable names are case-sensitive, just like they are in R. CL is not the same as Cl.

In mixture models, multivariate normal individual deviations from the normal population and parameters are estimated (in NONMEM these are called “ETA” parameters). Additionally, the variance/covariance matrix of these deviations are is also estimated (in NONMEM this is the “OMEGA” matrix). These also take initial estimates. In nlmixr, these are specified by the ~ operator. This that is typically used in statistics R for “modeled by”, and was chosen to distinguish these estimates from the population and residual error parameters.

Continuing from the prior example, we can annotate the estimates for the between-subject error distribution…

f <- function(){
    ini({
        lCl <- 1.6      # log Cl (L/hr)
        lVc = log(90)   # log V (L)
        lKa <- 1        # log Ka (1/hr)
        prop.err <- c(0, 0.2, 1)
        
        # Initial estimate for ka IIV variance
        # Labels work for single parameters
        eta.ka ~ 0.1    ## BSV Ka

        # For correlated parameters, you specify the names of each
        # correlated parameter separated by a addition operator `+`
        # and the left handed side specifies the lower triangular
        # matrix initial of the covariance matrix.
        eta.cl + eta.vc ~ c(0.1,
                            0.005, 0.1)
                            
        # Note that labels do not currently work for correlated
        # parameters.  Also, do not put comments inside the lower
        # triangular matrix as this will currently break the model.
    })
    
    # The model block will be discussed later
    model({})
}

As shown in the above example:

• Simple variances are specified by the variable name and the estimate separated by ~.
• Correlated parameters are specified by the sum of the variable labels and then the lower triangular matrix of the covariance is specified on the left handed side of the equation. This is also separated by ~.
• The initial estimates are specified on the variance scale, and in analogy with NONMEM, the square roots of the diagonal elements correspond to coefficients of variation when used in the exponential IIV implementation.

Currently, comments inside the lower triangular matrix are not allowed.

The model block

The model block specifies the model, and is analogous to the $PK, $PRED and $ERROR blocks in NONMEM.

Once the initialization block has been defined, you can define a model in terms of the variables defined in the ini block. You can also mix RxODE blocks into the model if needed.

The current method of defining a nlmixr model is to specify the parameters, and then any required RxODE lines. Continuing the annotated example:

f <- function(){
    ini({
        lCl <- 1.6       # log Cl (L/hr)
        lVc <- log(90)   # log Vc (L)
        lKA <- 0.1       # log Ka (1/hr)
        prop.err <- c(0, 0.2, 1)
        
        eta.Cl ~ 0.1     # BSV Cl
        eta.Vc ~ 0.1     # BSV Vc
        eta.KA ~ 0.1     # BSV Ka
    })
    model({
        # Parameters are defined in terms of the previously-defined
        # parameter names:
        Cl <- exp(lCl + eta.Cl)
        Vc =  exp(lVc + eta.Vc)
        KA <- exp(lKA + eta.KA)
        
        # Next, the differential equations are defined:
        kel <- Cl / Vc;
        
        d/dt(depot)  = -KA*depot;
        d/dt(centr)  =  KA*depot-kel*centr;
        
        # And the concentration is then calculated
        cp = centr / Vc;
        # Finally, we specify that the plasma concentration follows
        # a proportional error distribution (estimated by the parameter 
        # prop.err)
        cp ~ prop(prop.err)
    })

}

A few points to note:

• Parameters are defined before the differential equations. Currently directly defining the differential equations in terms of the population parameters is not supported.
• The differential equations, parameters and error terms are in a single block, instead of multiple sections.
• Additionally state names, calculated variables, also cannot start with either rx_ or nlmixr_ since these are used internally in some estimation routines.
• Errors are specified using the tilde, ~. Currently you can use either add(parameter) for additive error, prop(parameter) for proportional error or add(parameter1) + prop(parameter2) for combined additive and proportional error. You can also specify norm(parameter) for additive error, since it follows a normal distribution.
• Some routines, like saem, require parameters expressed in terms of Pop.Parameter + Individual.Deviation.Parameter + Covariate*Covariate.Parameter. The order of these parameters does not matter. This is similar to NONMEM’s mu-referencing, though not as restrictive. This means that for saem, a parameterization of the form Cl <- Cl*exp(eta.Cl) is not allowed.
• The type of parameter in the model is determined by the ini block; covariates used in the model are not included in the ini block. These variables need to be present in the modeling dataset for the model to run.