22 General Parameter Format (GPF)

This chapter introduces the General Parameter Format (GPF). See Basic terms for the definitions of terms such as model parameter and IIV used throughout this chapter.

The GPF is a human-readable and editable Excel-based format for specifying parameter point estimates, inter-individual parameter variability and parameter estimation uncertainty. IQRtools provides a set of R-functions capable of exporting MONOLIX and NONMEM results to the GPF.

22.1 The GPF excel file

A GPF file is an excel file with the following sheets:

  • The sheet called estimates lists all model parameters, the parameter type, the type of transformation to normal scale, and the point estimates of the parameter population values and inter-individual variability.
  • The sheet called uncertainty_correlation represents the correlation matrix of the estimate’s uncertainty distribution;

22.2 Columns in the GPF estimates sheet

Column Description
PARAMETER Parameter name for all parameter types, except IIV standard deviations.
TYPE Parameter type. Note that this is only used for human readability - the actual parameter type is inferred from the parameter name, following this naming convention.
VALUE Point estimate value on the original scale for all parameter types, except IIV standard deviations.
VALUE.RSE.PERCENT Relative standard error (in %) for all parameter types, except IIV standard deviations.
IIV For model parameters only: Point estimate of the IIV standard deviation on the parameters’ normal scale.
IIV.RSE.PERCENT Relative standard error (in %) of the IIV estimated value.
TRANSFORMATION For model parameters only: transformation type. It is assumed that after transformation, the IIV and uncertainty distributions of a model parameter are (approximately) normal. Possible values are ‘N’, ‘L’, and ‘G’. See Parameter transformations for details.
UNIT Unit of a model parameter on its original scale
COV.FORMULA Formula of covariate effect on reference population parameter value.
NAME A human readable descriptive parameter name
COV.REFERENCE Reference parameter value.
COMMENT Any additional human readable comment

22.2.1 Naming convention

The name of a parameter defines its functional type as follows:

  • Xyz1b2 (any alpha-numerical character string starting with a letter that does not match a pattern of another parameter type): model parameter
  • corr(X,Y): IIV correlation of model parameters X and Y on the parameters’ normal scale.
  • beta_X(COVRT): effect of continuous covariate COVRT on model parameter X. This effect is described further by the COV.FORMULA and COV.REFERENCE columns.
  • beta_X(COVRT_D): effect of value D for discrete covariate COVRT on model parameter X, where D is an integer.
  • error_PROP1, error_ADD1: proportional and absolute residual errors associated with model OUTPUT1.

22.2.2 Example GPF file

22.2.2.1 Example ‘estimates’ sheet

PARAMETER TYPE VALUE VALUE.RSE.PERCENT IIV IIV.RSE.PERCENT TRANSFORMATION UNIT COV.FORMULA NAME COV.REFERENCE COMMENT
Tlag1 MODEL PARAMETER 0.38 40.10 0.23 14 L
Absorption lag time
ka MODEL PARAMETER 0.51 12.00 0.38 22 L 1/hr Absorption rate
CL MODEL PARAMETER 19.00 6.00 0.37 11 L L/hr Apparent clearance
Vc MODEL PARAMETER 353.00 12.00 0.52 16 L L Apparent central volume
Q1 MODEL PARAMETER 71.20 13.00 0.61 17 L
Apparent intercompartmental clearance to first peripheral compartment
Vp1 MODEL PARAMETER 663.00 7.10 0.33 16 L hr Apparent first peripheral volume
corr(CL,Vc) IIV CORRELATION 0.71 16.00 0.00 0
Correlation IIV between CL and Vc
corr(CL,Q1) IIV CORRELATION -0.26 72.00 0.00 0
Correlation IIV between CL and Q1
corr(Vc,Q1) IIV CORRELATION -0.81 11.00 0.00 0
Correlation IIV between Vc and Q1
corr(CL,Vp1) IIV CORRELATION 0.60 23.00 0.00 0
Correlation IIV between CL and Vp1
corr(Vc,Vp1) IIV CORRELATION 0.11 235.00 0.00 0
Correlation IIV between Vc and Vp1
corr(Q1,Vp1) IIV CORRELATION 0.48 37.00 0.00 0
Correlation IIV between Q1 and Vp1
beta_CL(WT0) COVARIATE EFFECT 0.75 0.00 0.00 0
X=X_ref*(WT0/REF)^Beta Covariate effect of WT0 on CL 70
beta_Vc(WT0) COVARIATE EFFECT 1.00 0.00 0.00 0
X=X_ref*(WT0/REF)^Beta Covariate effect of WT0 on Vc 70
beta_Q1(WT0) COVARIATE EFFECT 0.75 0.00 0.00 0
X=X_ref*(WT0/REF)^Beta Covariate effect of WT0 on Q1 70
beta_Vp1(WT0) COVARIATE EFFECT 1.00 0.00 0.00 0
X=X_ref*(WT0/REF)^Beta Covariate effect of WT0 on Vp1 70
beta_CL(SEX_1) COVARIATE EFFECT 0.30 0.30 0.00 0
X=X_ref*exp(Beta) Covariate effect of SEX on CL 0
error_PROP1 ERROR 0.34 3.21 0.00 0
Proportional residual error of OZ439 concentration
error_ADD1 ERROR 0.10 10.00 0.00 0
Absolute residual error of OZ439 concentration

22.2.2.2 Example ‘uncertainty_correlation’ sheet:

PARAMETER Tlag1 ka CL Vc Q1 Vp1 omega(Tlag1) omega(ka) omega(CL) omega(Vc) omega(Q1) omega(Vp1) corr(CL,Vc) corr(CL,Q1) corr(Vc,Q1) corr(CL,Vp1) corr(Vc,Vp1) corr(Q1,Vp1) error_PROP1
Tlag1 1.00
ka 0.15 1.00
CL 0.00 0.01 1.00
Vc 0.05 0.61 0.48 1.00
Q1 0.00 -0.34 -0.20 -0.76 1.00
Vp1 -0.05 -0.50 0.44 -0.40 0.58 1
omega(Tlag1) 1.00
omega(ka) -0.03 1.00
omega(CL) 0.00 0.00 1.00
omega(Vc) 0.00 -0.27 0.35 1.00
omega(Q1) 0.00 -0.10 0.05 0.56 1.00
omega(Vp1) 0.00 -0.17 0.27 0.06 0.25 1
corr(CL,Vc) 1.00
corr(CL,Q1) -0.64 1.00
corr(Vc,Q1) 0.13 0.51 1.00
corr(CL,Vp1) -0.04 0.43 0.44 1.00
corr(Vc,Vp1) 0.64 -0.14 0.44 0.65 1.00
corr(Q1,Vp1) -0.59 0.58 0.06 -0.38 -0.72 1
error_PROP1 1

22.3 Parameter transformations

We call a parameter transformation an invertible function \(f(\cdot)\), where \(\cdot\) is a model parameter. Such transformations are needed in order to facilitate parameter estimation, in particular, for parameters which’s uncertainty and IIV distributions deviate from normal. This would be the case, e.g. for parameters which can only assume non-negative values. Let \(X\) be such a parameter and let \(Y=f(X)\) be a transformation of \(X\), such that the statistical uncertainty and the IIV distributions of \(Y\) are approximately normal. Then, the estimates in transformed (normal) units of the parameter value, \(\hat{Y}\), and its standard error, \(\hat{SE}_{Y}\), are back-transformed to the original units using the formulae: \[ \hat{X}=g(\hat{Y})=f^{-1}(\hat{Y})\\ \hat{SE}_{X}=J_{g}(\hat{Y})\hat{SE}_{Y}=\frac{\partial{g}}{\partial{Y}}(\hat{Y})\hat{SE}_{Y}, \] where \(g(Y)=f^{-1}(Y)\) is the inverse transformation function, and \(J_{f/g}\) denotes the Jacobian of \(f\) or \(g\) (for mathematical details, see section Transformation between original and normal units. For model parameters, the transformation is specified in the column TRANSFORMATION of the estimates sheet with:

  • \(f\equiv\text{identity}\) if TRANSFORMATION="N";
    • \(f\equiv\log\) if TRANSFORMATION="L";
    • \(f\equiv\text{logit}\) if TRANSFORMATION="G".

For the other types of parameters, the following convention holds:

  • TRANSFORMATION="L" for IIV standard deviation parameters (always non-negative). Keep in mind that the IIV value is interpreted as the IIV standard deviation on the parameter’s normal scale.
  • TRANSFORMATION="N" for IIV correlation parameters (can be positive or negative).
  • TRANSFORMATION="N" for covariate parameters (can be positive or negative).
  • TRANSFORMATION="L" for residual error parameters (always non-negative).

22.3.1 Transformation between original and normal units

22.3.1.1 TRANSFORMATION="N": no transformation

For TRANSFORMATION="N", the columns VALUE and VALUE.RSE.PERCENT correspond to the estimate and relative standard error in the original units and no transformations are done during the sampling. For TRANSFORMATION="L" and TRANSFORMATION="G", the transformations are described as follows:

22.3.1.2 TRANSFORMATION="L": Log-normal transformation

If TRANSFORMATION="L", it is assumed that the log-transformed parameter \(Y=\log(X)\) has a normal distrubtion.

Entity Left-hand values in original units Left-hand values in transformed units
Parameter \(X\) \(Y\)
Transformation \(X=g(Y)=f^{-1}(Y)=\exp(Y)\) \(Y=f(X)=\log(X)\)
Jacobian \(J_{g}(Y)=\frac{\partial{g}}{\partial{Y}}(Y)=\exp(Y)\) \(J_{f}(X)=\frac{\partial{f}}{\partial{X}}(X)=\frac{1}{X}\)
Estimate \(\hat{X}=\exp(\hat{Y})\) (=VALUE) \(\hat{Y}=\log(\hat{X})\)
SE \(\hat{SE}_{X}=J_{g}(\hat{Y})\hat{SE}_{Y}=\exp(\hat{Y})\hat{SE}_{Y}\) \(\hat{SE}_{Y}=J_{f}(\hat{X})\hat{SE}_{X}=\frac{1}{\hat{X}}\hat{SE}_{X}\)
RSE \(\hat{RSE}_{X}=\frac{\hat{SE}_{X}}{|\hat{X}|}=\frac{\exp(\hat{Y})\hat{SE}_{Y}}{\exp(\hat{Y})}=\hat{SE}_{Y}\) (=VALUE.RSE.PERCENT/100) \(\hat{RSE}_{Y}=\frac{\hat{SE}_{Y}}{|\hat{Y}|}=\frac{\frac{1}{\hat{X}}\hat{SE}_{X}}{\log(\hat{X})}=\frac{\hat{SE}_{X}}{\hat{X}\log(\hat{X})}\)

22.3.1.3 TRANSFORMATION="G": Logit transformation

If TRANSFORMATION="G", it is assumed that the logit-transformed parameter \(Y=\text{logit}(X)\) has a normal distrubtion.

Entity Left-hand values in original units Left-hand values in transformed units
Parameter \(X\) \(Y\)
Transformation \(X=g(Y)=f^{-1}(Y)=\text{logistic}(Y)=\frac{\exp(Y)}{\exp(Y)+1}\) \(Y=f(X)=\text{logit}(X)=\log(\frac{X}{1-X})\)
Jacobian \(J_{g}(Y)=\frac{\partial{g}}{\partial{Y}}(Y)=\frac{\exp(Y)}{[\exp(Y)+1]^2}\) \(J_{f}(X)=\frac{\partial{f}}{\partial{X}}(X)=\frac{1}{X(1-X)}\)
Estimate \(\hat{X}=\text{logistic}(\hat{Y})\) (=VALUE) \(\hat{Y}=\text{logit}(\hat{X})\)
SE \(\hat{SE}_{X}=J_{g}(\hat{Y})\hat{SE}_{Y}=\frac{\exp(\hat{Y})}{[\exp(\hat{Y})+1]^2}\hat{SE}_{Y}\) \(\hat{SE}_{Y}=J_{f}(\hat{X})\hat{SE}_{X}=\frac{1}{\hat{X}(1-\hat{X})}\hat{SE}_{X}\)
RSE \(\hat{RSE}_{X}=\frac{\hat{SE}_{X}}{|\hat{X}|}=\frac{\frac{\exp(\hat{Y})}{[\exp(\hat{Y})+1]^2}\hat{SE}_{Y}}{|\text{logistic}(\hat{Y})|}=\frac{\hat{SE}_{Y}}{\exp(\hat{Y})+1}\) (=VALUE.RSE.PERCENT/100) \(\hat{RSE}_{Y}=\frac{\hat{SE}_{Y}}{|\hat{Y}|}=\frac{\frac{1}{\hat{X}(1-\hat{X})}\hat{SE}_{X}}{|\text{logit}(\hat{X})|}\)

22.4 Basic terms

  • parameters – a general term including model parameters, as well as parameters used to describe uncertainty distributions of point estimates, the dependency of model parameters on covariates, the inter-individual variability (IIV) distributions of model parameters, and the residual (error) distribution.
  • model parameters – the list of parameters in an IQRmodel$parameters, or in the PARAMETERS section of a “model.txt” file. In equations, we use capital latin letters, e.g. \(X\) and \(Y\), to denote single model parameters and vector notation \(\vec{X}\) to denote the ensemble of model parameters. The model parameters have a value “MODEL PARAMETER” in the column TYPE of the estimates sheet. In the example GPF files, these are Tlag1, ka, CL, Vc, Q1 and Vp1. Model parameters have values at three levels:
    • reference population values: values that are drawn from the point estimates’ uncertainty distribution or taken equal to the point estimates themselves. These parameter values are global for a clinical trial population and provide the input for calculating typical individual values. Denoted by \(X_{ref,pop}\), \(Y_{ref,pop}\) and \(\vec{X}_{ref,pop}\).
    • typical individual values: estimates for a subset of individuals in a population having the same covariate values. For a model parameter \(X\), this is a deterministic function \[ X_{typ} = \text{Covrt}(X_{ref,pop}, C_{X,1},...,C_{X,m}, \beta_{X,1,pop},..., \beta_{X,m,pop}), \] where \(C_{X,1},...,C_{X,m}\) denote covariates affecting \(X\), and \(\beta_{X,1,pop},..., \beta_{X,m,pop}\) denote corresponding covariate parameters estimated at the population level. In NLME modeling terms, the typical individual parameter values represent fixed effects.
    • individual values: the vector of model parameter values \(\vec{X}_{i}\) for an individual in a population. This is a vector drawn at random from the inter-individual variability distribution, i.e. \[ \vec{X}_{i}\sim \mathcal{D}(\vec{X}_{typ,i}, \Sigma_{IIV,pop}), \] where \(\mathcal{D}\) denotes the type of inter-individual variability distribution, \(\vec{X}_{typ,i}\) denotes the vector of typical individual values for an individual with the same covariate values as \(i\) and \(\Sigma_{IIV,pop}\) denotes the inter-indevidual variability (IIV) variance-covariance matrix on a normal scale (see parameter transformation below). Note that by this definition of \(\vec{X}_{i}\) the center of the IIV distribution (\(\vec{X}_{typ,i}\)) depends on the individual’s covariate values but the variance-covariance matrix (\(\Sigma_{IIV,pop}\)) is global for the population.
  • point estimates – values of parameters estimated based on training data, hereby denoted by \(\hat{\cdot}\) where \(\cdot\) denotes a parameter. In the input estimates table, the column VALUE denotes the point estimates for \(\vec{X}\), \(\vec{\rho}\) and \(\vec{\beta}\) (original parameter scale, see term parameter transformation below); for \(\vec{\omega}\), the point estimates are in the column IIV.
  • uncertainty distribution – a distribution representing the statistical uncertainty around the point estimates of \(\vec{X}\), \(\vec{\omega}\), \(\vec{\rho}\), \(\vec{\beta}\) and \(\vec{\sigma}\). This uncertainty originates from the limited size of the data used for the estimation and not from biological sources of variation. The uncertainty distribution is described by the relative standard error (RSE) for the point estimate defined as the absolute ratio in percent units of the standard error (note that, here, the terms standard error and standard deviation have the same meaning) and the point estimate on the original parameter scale (see term parameter transformation below). For \(\vec{X}\), \(\vec{\rho}\), \(\vec{\beta}\) and \(\vec{\sigma}\), the RSE estimates are in the column VALUE.RSE.PERCENT; for \(\vec{\omega}\), the RSE estimates are in the column IIV.RSE.PERCENT. In addition the sheet called “uncertainty_correlation” sepcifies the uncertainty correlation matrix between estimated couples of parameters (see example input).
  • Inter-individual variability (IIV) distribution – a distribution representing the biological variability of the model parameters between individuals with the same covariate values. This distribution is described on a normal scale by the parameters \(\vec{\omega}\) and \(\vec{\rho}\).
  • population values – values of different types of parameters which are global at the population level. These include:
    • reference population values of model parameters, hereby denoted by \(X_{ref,pop}\), \(Y_{ref,pop}\) and \(\vec{X}_{ref,pop}\);
    • population values of IIV distribution standard deviations on a normal scale, hereby denoted by \(\omega(X)\), where \(X\) is a single model parameter, or \(\vec{\omega}\) for the ensemble of model parameters. In the uncertainty correlation sheet of the GPF file, these parameters are denoted by “omega(X)”.
    • population values of IIV distribution correlaitons between pairs of model parameters on a normal scale. Denoted by \(\rho(X,Y)\), where \(X\) and \(Y\) are model paramters, or by \(\vec{\rho}\) for all estimated correlations of model parameter couples, or by \(R_{IIV}(\vec{X})\) denoting the \(|\vec{X}|\times|\vec{X}|\) symmetric correlation matrix of the ensemble of model parameter couples. By convention, the estimated correlation coefficients are named “corr(X,Y)” in the input estimates and uncertainty correlation tables. If not estimated the model parameter correlations are set to 0.
    • population values of covariate parameters used to calculate the typical individual values of model parameters. Notation: \(\beta_{X,j,pop}(C_{X,j})\), where \(X\) is a model parameter and \(C_{X,j}\) is the \(j^{\text{th}}\) covariate influencing \(X\); \(\vec{\beta}_{pop}\) for the ensemble of all \(\beta\)’s.
  • error parameters – parameters describing the residual distribution for the model’s dependent variables. Hereby denoted by \(\vec{\sigma}\) for all error parameters. In the GPF file, these parameters are named by “error_PROPi”.