Calculate first and second order variations for FIM

Calculates the variational matrix of the given model, that is, the first and second order derivatives of the model outputs with respect to the model parameters, at given times. This is tailored for use with the FIM methods. Therefore derivatives of individual and residual error parameters are evaluated at 0, and so only their names need to be provided as input.

calcVariationsFim(
  model,
  p,
  init,
  output,
  times,
  theta,
  nmeta,
  nmeps,
  vartheta = names(theta),
  vareta = nmeta,
  vareps = nmeps,
  symbolic = TRUE,
  chkModel = TRUE,
  ...
)

Arguments

model

Function(t, y, p) of time, state variables and parameters, specifying the differential equations. This function should return the numeric vector dy/dt.

p

Function(theta, eta) of population and individual parameters specifying the model parameters. This function should return a named numeric vector.

init

Function(p) of parameters specifying the initial state (at time 0) of the model.

output

Function(y, p, eps) of state variables, parameters and residual errors specifying the model outputs. This function should return a numeric vector.

times

Numeric vector of times where variations are to be evaluated. Should all be >= 0, but do not need to include the dose time 0.

theta

Population parameter values, as named numeric vector. May be NULL if none are needed.

nmeta

Names of individual parameters, as string vector. May be NULL if none are needed.

nmeps

Names of residual parameter values, as string vector. May be NULL if none are needed.

vartheta

Vector of names of population parameters for which variations are to be calculated. Should be a subset of names(theta), or NULL for none. By default equal to names(theta).

vareta

Vector of names of individual parameters for which variations are to be calculated. Should be a subset of nmeta, or NULL for none. By default equal to nmeta.

vareps

Vector of names of residual parameters for which variations are to be calculated. Should be a subset of nmeps, or NULL for none. By default equal to nmeps.

symbolic

TRUE (default) if derivatives are to be computed symbolically, FALSE if numerically. See calcVariations for details.

chkModel

TRUE (default) if it has to be checked whether model components (model, p, init, output) are formatted correctly for symbolic manipulation, FALSE if not.

...

Named arguments to be passed to lsoda. Can be used for example to pass events or error tolerances.

Value

A data frame with columns 't' for time, 'i' for the index of the output element, 'y' for the outputs, 'dy/d<v1>' for the first derivatives and 'd2y/d<v1>_<v2>' for the second derivatives. In the column names, variables v1 and v2 are replaced by the names in vartheta, vareta and vareps. The data frame has an attribute 'theta' listing the values of theta as a named vector, and attributes 'eta' and 'eps' containing named vectors with 0 values for all parameters in nmeta and nmeps. The 'type' attribute is set to 'VariationalMatrix', 'secOrd' to TRUE and 'symbolic' to the value of symbolic. The variational matrix is not normalized, as reflected in the attributes 'parameterNormalized' and 'outputNormalized', that record input and output normalization, respectively. The attribute 'parameterNormalized' is set to a named boolean vector of FALSE, with the theta, eta and eps parameter names as names. The attribute 'outputNormalized' is set to FALSE. The function displays an error and returns NULL if vartheta contains elements not in names(theta), and likewise for nmeta and nmeps, or if times includes a negative value.

Note

The inputs vareta and vareps should contain all random parameters with nonzero variance, even if the FIM calculation considers the variance and covariances of such a parameter as fixed (that is, derivatives with respect to these variance and covariances do not appear in the FIM). That is, random parameters may be dropped from vareta and vareps only if they have zero variance. Notice that any variance and covariance parameters appearing in the FIM necessarily correspond to random parameters with nonzero variance, so inclusion of all random parameters with nonzero variance is not only necessary but also sufficient. That is, vareta and vareps can be set equal to the sets of all individual and residual parameters with nonzero variance, respectively.

It is recommended to use symbolic derivation (symbolic==TRUE) rather than numerical derivation, as it is more accurate, especially for derivatives that are formally zero. See calcVariations for details.

Author

Martijn van Noort