Sensitivity indices, parameter relations and least identifiable parameters

Calculates sensitivity indices, parameter relations and/or the least identifiable parameters for a given model. It first computes the variational matrix for the model and then applies calcSensitivityFromMatrix.

calcSensitivityFromModel(
  outputs,
  model,
  parms,
  init,
  outputPred,
  times,
  vars = names(parms),
  parNorm = FALSE,
  outNorm = FALSE,
  symbolic = TRUE,
  chkModel = TRUE,
  Mthresh = NULL,
  normalizeM = TRUE,
  scaleM = TRUE,
  ...
)

Arguments

outputs

List of the indices and parameter relations to be determined. List of strings, where each element is one of "N", "S", "A", "R", "M", "L". They stand for null space dimension, skewing coefficient, skewing angle, parameter relations, minimal parameter relations and least identifiable parameters, respectively.

model

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

parms

Model parameter values, as named numeric vector.

init

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

outputPred

Function(y, p) of state variables and parameters specifying the model prediction, i.e., the output without residual. This function should return a numeric vector.

times

Numeric vector of times where variations are to be evaluated.

vars

Vector of names of variables q to be included in sensitivity analysis. Should be a subset of names(parms). By default equal to names(parms). Variations d(outputPred)/dq are calculated only for these parameters. If specified as NULL, it is set to names(parms).

parNorm

Vector (not necessarily named) of booleans of the same dimension as parms. The value TRUE means the corresponding individual parameter should be normalized in the FIM, FALSE means not. If the vector is named, the names should match vars. Instead of a vector, may also provide a single boolean, where TRUE stands for a vector of all TRUE, and FALSE (default) for a vector of all FALSE.

outNorm

TRUE if variations should be output-normalized, FALSE (default) if not.

symbolic

TRUE (default) if derivatives are to be computed symbolically, FALSE if numerically. See calcVariations for notes on using symbolic derivation.

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.

Mthresh

Threshold for minimal parameter relations. Parameter relations smaller than Mthresh/sqrt(k) (before scaling, see scaleM) are returned, where k is the number of parameters. The factor sqrt(k) makes Mthresh independent of dimension. If NULL, only the most minimal relation is returned.

normalizeM

TRUE (default) if the minimal parameter relations should be normalized, FALSE if not. This is not the same as parameter- or output-normalization of the sensitivity matrix. See calcSensitivityFromMatrix for more information.

scaleM

TRUE (default) if norms of the minimal parameter relations should be scaled to the range 0, 1, FALSE if not. If TRUE, the norms are divided by sqrt(k), where k is the number of parameters. If FALSE they are unchanged.

...

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

Value

A list with a named element for each element of 'outputs'. Elements for "N", "S", "A" are numeric values, while elements "R", "M" contain row-named matrices with the parameter relations defined by its columns, and "L" contains a named list with one element for each parameter, in increasing order of identifiability or distance, of the form "parameter name" = "distance of this parameter to the span of the others" in observation space. Distance (near) zero indicates non-identifiability of this parameter. Element M has an attribute "norm" specifying the norms of the minimal parameter relations, where near zero values correspond to non-identifiability, and large values to identifiability. The relations are provided in order of increasing norm (if there is more than one). It also has attributes "normalized" and "scaled" containing the values of the input parameters normalizeM

and scaleM, respectively.

If the variational matrix could not be computed or vars is not defined correctly, then the return value is NULL and an error message is shown. If there is a single parameter in vars, then elements S, A and L are NA.

Note

Output-normalization divides the vector dy_i/dp_j by y_i, and is recommended if the output is considered to be a multiplicative rather than an additive variable. Parameter-normalization multiplies the vector dy_i/dp_j by p_j, and is recommended if the input is considered to be a multiplicative rather than an additive variable. (A multiplicative variable is a variable where differences between values are considered on the log scale. So if e.g. values 0.001 and 0.01 are considered different because they differ by a factor of 10, then the variable is multiplicative. If they are considered approximately equal because they are both close to 0, then the variable is additive. Most PK inputs and outputs are multiplicative, likewise for many PD ones.)

Output-normalization is equivalent to considering the sensitivity matrix dlog(y)/dp rather than dy/dp. Parameter-normalization is equivalent to considering the sensitivity matrix dy/dlog(p) rather than dy/dp.

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