Why Make a Portable Parameter Table?
A parameter value is not portable just because its number has been copied correctly. The number 0.09, for example, could represent a variance, a standard deviation, or a parameter on a transformed scale. Without its name, units, scale, and role in the model, it is easy to transfer a value that looks plausible but produces a different model.
A portable parameter table is a software-neutral record of what each estimated quantity means and how it should enter a destination model. It makes the link between estimation output and simulation input explicit. This is especially useful when an estimation tool and a simulation tool use different parameter names, parameterizations, or representations of variability.
The table supports a transfer; it does not establish that the source and destination models are equivalent. That depends on the full model specification, including parameter definitions and how the destination uses random effects and residual error. Here the focus is the parameter record and its use in a simulation interface.
What the Table Needs to Preserve
At minimum, use one record for each scalar parameter or variability element. A useful schema includes a canonical name, role, source name, estimate, units, estimate scale, transformation, variability metadata, and destination name. Add a status or note when a value is fixed, derived, omitted, or needs conversion. For a covariance matrix, record which pair of effects each covariance belongs to; a bare list of numbers is not sufficient.
| Field | What to record | Why it matters |
|---|---|---|
| Canonical name and role | For example, typical clearance, IIV variance, or proportional residual SD | Distinguishes quantities with different functions in the model |
| Source name and estimate | The source output field and its reported value | Lets a reviewer trace the transferred value |
| Units | For example, L/h, L, or h-1 | Prevents a numerically correct value being used with incompatible units |
| Scale and transformation | Natural scale, log scale, or another explicitly defined scale | Shows whether conversion is needed before use |
| Variability metadata | Effect distribution and variance, covariance, SD, correlation, or residual error form | Preserves how individual values or observations vary around model predictions |
| Destination name and interpretation | The destination field and how the simulator uses it | Connects the recorded quantity to the implemented model |
Keep three types of quantities distinct. A structural parameter describes the model’s typical behavior, such as typical clearance. Interindividual variability describes how individual parameters vary around that typical value. Residual variability describes differences between observations and model predictions. An estimation standard error, by contrast, describes uncertainty in an estimate; it is not itself a variability parameter to simulate.
Record transformations as equations, not vague labels. For example, if \( \theta_{\mathrm{CL}} \) is estimated as \( \log(CL) \), record that \( CL=\exp(\theta_{\mathrm{CL}}) \). Similarly, if a lognormal individual parameter is defined by \( CL_i=CL_{\mathrm{typ}}\exp(\eta_{\mathrm{CL},i}) \), state that convention and record the distribution of \( \eta_{\mathrm{CL},i} \). The estimate \( CL_{\mathrm{typ}} \) and the variance of \( \eta_{\mathrm{CL}} \) are different quantities on different scales.
Assumptions Before Transfer
A table is only interpretable given a model definition. Before transferring estimates, confirm that the source and destination refer to the same parameter meanings, units, and transformations. For the example below, assume a one-compartment oral model whose typical parameters are apparent clearance \(CL/F\), apparent volume \(V/F\), and absorption rate constant \(k_a\). The model uses lognormal interindividual effects on \(CL/F\) and \(V/F\), with a joint normal distribution on the eta scale. Its residual model is proportional.
These assumptions give the fields their interpretation. The diagonal entries of \( \Omega \) are eta variances, and its off-diagonal entry is an eta covariance. They are not variances in L/h or L. A proportional residual SD is dimensionless under the stated model. If the destination uses another residual-error convention, the same number cannot be assumed to have the same meaning.
Worked Example: Turning R Output into a Table
Suppose a hypothetical R estimation workflow reports \( \theta_{\log(CL/F)}=1.6094 \), \( \theta_{\log(V/F)}=3.9120 \), and \( \theta_{\log(k_a)}=0.1823 \). It also reports \( \Omega_{\mathrm{CL,CL}}=0.0900 \), \( \Omega_{\mathrm{V,V}}=0.0400 \), \( \Omega_{\mathrm{CL,V}}=0.0180 \), and a proportional residual SD of 0.2000. Assume the source output defines each theta as the natural logarithm of its corresponding typical parameter.
Convert the typical parameters by exponentiating the reported estimates:
The resulting records should retain both the original source estimate and the converted value. For example: canonical name “typical apparent clearance”; source field \( \theta_{\log(CL/F)} \); source estimate 1.6094 on the log scale; conversion \( \exp(\theta) \); destination value 5.000 L/h. This makes the calculation auditable and prevents a later user from exponentiating the value a second time.
The variability records are not exponentiated. Under the stated model, the omega entries already describe the eta covariance matrix. Its diagonal elements are 0.0900 and 0.0400, and the off-diagonal covariance is 0.0180. The proportional residual SD is 0.2000, so the corresponding residual variance is \(0.2000^2=0.0400\) if the destination requires variance. The table should label which representation is provided rather than silently substituting one for the other.
Transferring the Table to a Simulation Interface
Once the table is complete, transfer records by meaning, not by position in an output vector. A simulation interface may require natural-scale typical parameters, an omega covariance matrix, and a residual SD or variance. It may use names unlike the source names. A portable table supplies the explicit mapping and conversion needed for each field.
Check the parameter definitions, units, random-effect structure, and residual model expected by the destination.
Apply the recorded transformation once, keeping the source estimate and converted value visible.
Transfer each variance and covariance to the correct effects, and convert SD to variance or vice versa only when the interface requires it.
Verify names, units, matrix order, and error-model convention against the table before running a simulation.
Worked Example: Populating a Simulation Interface
Use the converted records from the hypothetical R output above. Suppose a simulation interface expects natural-scale typical values named CL, V, and KA, an eta covariance matrix ordered as \( (\eta_{\mathrm{CL}},\eta_{\mathrm{V}}) \), and a proportional residual SD named SIG_PROP. A software-neutral transfer record maps the values as follows: CL = 5.000 L/h, V = 50.00 L, KA = 1.200 h-1, and SIG_PROP = 0.2000.
The variability matrix in the declared order is:
The diagonal values are the eta variances, and the symmetric off-diagonal values are the covariance between the clearance and volume effects. If the interface accepts the matrix directly, enter these entries with the stated order. If it accepts only separate named fields, map each diagonal and covariance to its corresponding field. Do not provide only the two diagonal values: that would omit the estimated correlation structure.
A basic numerical check is that the implied correlation is \(0.0180/(\sqrt{0.0900}\sqrt{0.0400})=0.3000\). The matrix is positive definite because its first diagonal value is positive and its determinant is \(0.0900(0.0400)-(0.0180)^2=0.003276>0\). These checks do not prove the full implementations agree, but they catch common transcription errors. The interface’s residual field receives 0.2000 if it requests an SD, or 0.0400 if it requests a variance under the same proportional-error equation.
Before running the simulation, compare each destination field against the table: CL and V are in natural units, KA is an inverse time, the omega matrix is on the eta scale in the declared order, and SIG_PROP is an SD rather than a variance. That final comparison is part of the transfer, not an optional formatting step.
When Variability Is Reported Differently
Different outputs can describe the same variability using variances, standard deviations, or correlations. Conversions are straightforward only when the source definition is known. For two random effects \( \eta_1 \) and \( \eta_2 \), with SDs \( \omega_1 \) and \( \omega_2 \) and correlation \( \rho_{12} \), the covariance is \( \rho_{12}\omega_1\omega_2 \). The diagonal variances are \( \omega_1^2 \) and \( \omega_2^2 \).
Worked Example: Converting SDs and a Correlation
A hypothetical output reports eta SDs of 0.3000 for clearance and 0.2000 for volume, with correlation 0.3000. A destination expects the covariance matrix. The clearance variance is \(0.3000^2=0.0900\), and the volume variance is \(0.2000^2=0.0400\). The off-diagonal covariance is \(0.3000(0.3000)(0.2000)=0.0180\).
Thus the destination matrix is the same matrix shown in the previous example. The equality is a useful check, but only because both outputs refer to the same eta definitions and effect order. If the reported SDs were on a different scale, or the correlation referred to different random effects, the conversion would not preserve the intended model.
Diagnostics, Alternatives, and Limitations
Several warning signs indicate that a transfer table needs review. A value has no units or scale; a transformation is described only as “log”; an omega entry has no associated effect names; an interface field expects a variance but receives an SD; or a parameter appears in the source output but has no destination mapping. A covariance matrix with mismatched row and column order can also attach valid numbers to the wrong effects. Resolve these issues before simulation rather than trying to infer the intended meaning from numerical plausibility.
The table approach has a small overhead compared with copying values directly into code, but direct copying is fragile and hard to review. A source-specific export script can automate repeated transfers, while a manually reviewed table is useful for a one-time or unfamiliar transfer. These approaches are complementary: an automated script can use the table as its specification, and the table can make script mappings reviewable. Neither replaces a comparison of model equations or simulation behavior.
A portable table also has limits. It records parameter values and metadata; it does not capture every detail of an estimation run, event handling, covariate implementation, or numerical solver. Nor does it establish that the destination interprets all fields as intended. Preserve source provenance, model version, and any relevant fixed or omitted parameters. Then use appropriate model-level checks after transfer. Comparisons of objective function values and formal prediction-equivalence assessments require separate analyses.
A common mistake is to assume that a matching label and number imply a matching parameter. For example, an R output field called “omega” might report an SD, while the destination expects a variance. Copying 0.30 into a variance field would use 0.30 instead of \(0.30^2=0.0900\). The correction is to record the source definition and convert according to the destination’s documented convention, retaining both values and their labels in the table.
Check Your Understanding
Answer each question using the definitions and conventions in this tutorial.
- A source reports \( \log(CL)=\log(8.0) \), with CL measured in L/h. The destination expects natural-scale CL. What value should be transferred, and what information should remain in the table?
- An eta SD is 0.25 and the destination expects an eta variance. Calculate the value to transfer.
- For eta SDs 0.2 and 0.5 with correlation 0.4, calculate the covariance.
- Why should a proportional residual SD of 0.2 not be placed in a field that expects residual variance?
Solutions. (1) Transfer CL = 8.0 L/h, retaining the source field, its log-scale estimate, the exponential transformation, and the converted value. (2) The variance is \(0.25^2=0.0625\). (3) The covariance is \(0.4(0.2)(0.5)=0.0400\). (4) The variance is the square of the SD, \(0.2^2=0.0400\); entering 0.2 as a variance changes the residual model’s variability.