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 columnTYPEof 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
VALUEdenotes 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 columnIIV. - 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 columnIIV.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”.