Why Parameter Tables Need Versions
A PBPK parameter table is not merely a list of numbers. Each input has a meaning, unit, applicability, and evidence trail. As new evidence appears, a value may change; a source may be corrected; a transformation may be revised; or a parameter may be added or retired. If the table is overwritten without a durable record of those changes, a later analyst may be unable to determine which inputs produced a simulation or why an input was selected.
Versioning makes those revisions explicit. It allows a team to identify the exact parameter records used for a model run, explain what changed between releases, and recover a prior set without relying on memory or an old spreadsheet copied to an unknown folder. The central practice is to keep parameter identity stable while treating each released table as an immutable snapshot.
The earlier material on provenance for derived and model-dependent inputs establishes why the evidence and transformation behind an input need to be recorded. Version control adds a time dimension: it preserves the state of those records at each release and documents the transition from one state to the next.
Stable Identifiers and Immutable Releases
An identifier should remain unchanged when the value is updated or a better source is found, provided the input still represents the same quantity, biological context, and model role. For example, an identifier such as human.adult.hepatic_blood_flow could persist across revisions of its value. An identifier such as hepatic_blood_flow_90 is fragile because a value change makes the identifier misleading. If the meaning changes materially—for example, from total hepatic blood flow to flow per kilogram—the new input should normally receive a distinct identifier, with a documented relationship to the retired one.
A parameter record should contain enough information to interpret and trace the input. Typical fields include the stable identifier, value, unit, parameter definition, population or experimental context, source identifier and link, source location, reported qualifier, transformation or derivation, uncertainty, applicability limits, and record status. Not every field applies to every input, but an absent field should not be silently mistaken for a known value.
Represent a release as both a set of identifiers and a mapping from each identifier to its record. Let \(I_v\) be the set of identifiers in release \(v\), and let \(r_v(i)\) be the record associated with identifier \(i\). A revision specifies identifiers to update \(U\), retire \(D\), and add \(A\). Here \(U\) and \(D\) are subsets of existing identifiers, while \(A\) contains new identifiers. Assume \(U\), \(D\), and \(A\) are pairwise disjoint, and that \(U\cup D\subseteq I_v\) and \(A\cap I_v=\varnothing\). The identifier set for the next release is:
The equation says that unchanged identifiers remain, updated identifiers remain present, retired identifiers leave the active set, and new identifiers enter. The equation does not itself contain the records. Record contents are assigned separately: for each \(i\in U\), the next release has a new record \(r_{v+1}(i)\); for each \(i\in A\), it has the added record \(r_{v+1}(i)\); and for each unchanged \(i\in I_v\setminus(U\cup D)\), the record is carried forward unchanged. This separation prevents a type error between identifiers and records.
A release should be frozen after publication. Corrections are made by issuing another release, not by silently editing an earlier snapshot. The release identifier should be stored with the model configuration and simulation outputs. A checksum or other content fingerprint can help detect accidental changes to a released file, but it does not explain the scientific reason for a revision; that belongs in the change log.
What a Useful Change Log Records
A change log is the human-readable account of each revision. At minimum, it should identify the release, date, stable parameter identifier, type of change, prior and new states where applicable, reason, evidence, and person or process responsible for the change. For a value change, give both values with units, not just a statement that the input was “updated.” For a source change, record the old and new source links and state whether the numerical value changed.
| Change-log field | Purpose |
|---|---|
| Release identifier and date | Locates the snapshot and indicates when it was issued |
| Stable parameter identifier | Connects the log entry to the same model input across releases |
| Change type | Distinguishes value, source, transformation, metadata, status, or schema changes |
| Old state and new state | Shows exactly what changed, including units and qualifiers when relevant |
| Reason and evidence link | Explains why the revision was made and lets a reviewer trace its basis |
| Impact and review status | Notes possible model consequences and whether the change was checked |
Source links should be sufficiently precise to find the cited evidence again. A DOI or accession number is generally more durable than a bare webpage address; a URL, publication details, page or table location, and access date may also be needed. If a source is likely to change or disappear, retain an allowed archival copy or a fingerprint of the exact file used. A source link alone does not show which number was extracted from it or how that number became the model input.
A version-number policy should be written down and used consistently. One practical policy resembles semantic versioning: a major increment marks an incompatible schema or a change in parameter meaning; a minor increment marks scientifically meaningful additions or input revisions; and a patch increment marks non-scientific corrections that do not alter model inputs. This is a local convention, not a universal PBPK standard. The important requirements are an unambiguous release identifier, a documented policy, and no reuse of an identifier for different contents.
Worked Example: Updating a Directly Sourced Input
Suppose a hypothetical PBPK table release 1.0.0 contains the record human.adult.hepatic_blood_flow with value \(90.0\ \mathrm{L/h}\), for a specified adult reference population. The record links to a hypothetical source and identifies the relevant table and population. A later review finds a more applicable source reporting \(84.0\ \mathrm{L/h}\) for that same defined input. The team records release 1.1.0 under its policy that a scientific input change increments the minor version.
Identifier decision. The input definition remains hepatic blood flow for the same population and context, so its stable identifier is retained. The value is not part of the identifier.
Record change. The record in release 1.0.0 has \(r_{1.0.0}(i)=90.0\ \mathrm{L/h}\); the record in release 1.1.0 has \(r_{1.1.0}(i)=84.0\ \mathrm{L/h}\), where \(i\) is the identifier above. The absolute difference is \(84.0-90.0=-6.0\ \mathrm{L/h}\). Relative to the old value, the change is \((-6.0/90.0)\times100=-6.67\%\).
Change-log entry. The entry identifies the parameter, both values and units, the old and new source links, the relevant population descriptions, and the reason for preferring the new source. It states that the numerical input changed by \(-6.0\ \mathrm{L/h}\), or \(-6.67\%\) relative to release 1.0.0, and flags that predictions sensitive to hepatic flow may be affected. The old release remains available for exact reconstruction.
Recording Changes to Derived Inputs
A derived model input needs version information not only for its final value but also for the inputs and procedure that generated it. Record the source measurements, units, equations, scaling assumptions, and any rounding or conversion. If a source measurement changes, or a transformation is corrected, the log should say which changed. Otherwise, a new value can appear to have been directly measured when it was actually recalculated.
Worked Example: Revising a Scaling Factor
Consider a hypothetical intrinsic-clearance input scaled from a microsomal measurement. The reported value is \(1.8\ \mathrm{\mu L/min/mg}\), the microsomal protein yield is initially \(40\ \mathrm{mg/g}\) liver, liver mass is \(25.7\ \mathrm{g/kg}\), and body weight is \(70\ \mathrm{kg}\). The team uses the following stated multiplication to obtain a whole-person value:
The units cancel to \(\mathrm{\mu L/min}\). Since \(1{,}000{,}000\ \mathrm{\mu L}=1\ \mathrm{L}\), this is \(0.129528\ \mathrm{L/min}\). Multiplying by \(60\ \mathrm{min/h}\) gives \(7.77168\ \mathrm{L/h}\), reported here as \(7.772\ \mathrm{L/h}\).
Suppose a new, applicable hypothetical source supports a yield of \(45\ \mathrm{mg/g}\), while the other inputs and the calculation remain unchanged. The revised calculation is \(1.8\times45\times25.7\times70=145{,}719\ \mathrm{\mu L/min}\). Converting gives \(0.145719\ \mathrm{L/min}\times60=8.74314\ \mathrm{L/h}\), or \(8.743\ \mathrm{L/h}\). The increase is \(8.74314-7.77168=0.97146\ \mathrm{L/h}\), approximately \(12.5\%\) of the original value.
The log should identify the derived-input record, the earlier and revised values, and the changed yield source. It should also record the calculation and retain the unchanged measurement and scaling factors, making clear that the revision arose from the yield input rather than a changed intrinsic-clearance measurement. This calculation is valid only under the stated scaling assumptions; the version record preserves those assumptions but does not establish their biological suitability.
Reconstructing a Prior Parameter Set
Reconstruction means retrieving the complete snapshot that was used, not selecting a few familiar values from an old log. A reproducible model run therefore needs a release identifier and, where relevant, the model version, population definition, simulation configuration, and analysis code version. The parameter-table release is one necessary part of the run specification; it is not a substitute for the rest.
Use the release identifier recorded with the original run, not a date guessed from a file name.
Check its content fingerprint if one was recorded, and confirm that the parameter identifiers and records belong to that release.
Use the model version and configuration associated with the run, including population and any parameter-selection rules.
Check that required identifiers are present and that values, units, source links, and transformations match the archived records.
Log the release retrieved, verification performed, and any discrepancy. Do not repair the historical snapshot in place.
Worked Example: Reproducing Release 1.0.0
Suppose a hypothetical simulation used release 1.0.0 with three active identifiers: \(I_{1.0.0}=\{\texttt{hepatic\_blood\_flow},\texttt{fu\_plasma},\texttt{scaled\_CLint}\}\). Its records give \(90.0\ \mathrm{L/h}\), \(0.10\) as a fraction, and \(7.772\ \mathrm{L/h}\), respectively. Release 1.1.0 later updates hepatic blood flow to \(84.0\ \mathrm{L/h}\) and scaled intrinsic clearance to \(8.743\ \mathrm{L/h}\), leaving the fraction unchanged.
To reproduce the earlier run, retrieve the complete 1.0.0 snapshot. Its identifier set remains the three listed identifiers, and its records are read through the release-specific mapping \(r_{1.0.0}(i)\). In particular, the restored records must return \(90.0\ \mathrm{L/h}\) and \(7.772\ \mathrm{L/h}\), not the newer records from 1.1.0. The unchanged \(0.10\) fraction is also taken from the 1.0.0 snapshot so the run uses one coherent release.
The simulation is then run with the matching model version and configuration. If the archived release is absent, or its contents fail the recorded fingerprint check, the exact parameter set cannot be verified from the release label alone. A current table with selected old values copied into it is not a valid substitute, because it may omit other changes or combine records that never coexisted.
Diagnostics, Alternatives, and Common Pitfalls
Warning signs include values changing without a corresponding log entry; identifiers that change whenever a value changes; a logged source update with no indication of whether the value changed; missing units or population context; an archived release whose contents no longer match its fingerprint; and model outputs that cannot be connected to a precise table release. A useful review asks whether each revised record can be traced backward to its evidence and forward to the releases and runs that used it.
Overwriting one spreadsheet is easy but destroys historical states unless separate, verified snapshots are preserved. Dated copies help only if their contents are immutable, consistently named, and accompanied by explanations. A version-control system can retain file history and expose textual differences, but a raw file diff may not explain the scientific significance of a changed record. Structured change logs complement such systems by describing the meaning, evidence, and impact of changes. Databases can support controlled access and queries, but they still need explicit release snapshots and audit trails.
Versioning also has limits. It cannot make weak evidence strong, resolve conflicting sources by itself, or show that a parameter is biologically appropriate for every population. A perfectly reproducible input set can still be unsuitable for its intended context. The purpose is narrower and essential: to make the identity, evidence, and history of the chosen inputs inspectable and the earlier set recoverable.
Check Your Understanding
Answer each question, then compare your reasoning with the solutions below.
- A parameter changes from \(0.12\) to \(0.09\), but its definition and model role remain the same. Should its stable identifier change?
- A source is replaced, but the selected value remains \(3.4\ \mathrm{mg/L}\). What should the log make explicit?
- Why is copying two old values into a current table not necessarily equivalent to restoring the old release?
- A derived clearance changes because a scaling factor was revised. Name two pieces of information, beyond the final value, that should be retained.
- What should be done if an archived release does not match its recorded fingerprint?
Solutions. (1) No, not if the input still has the same meaning and context; update its record while retaining its stable identifier. (2) Record both source links and state clearly that the source changed but the selected value did not; include any changed source details or interpretation. (3) Other records may also have changed, and mixing selected values can create a combination that was never a released table. Retrieve the complete immutable snapshot. (4) Retain the original and revised scaling-factor values and sources, and document the transformation and units; the underlying measurement and assumptions should also remain traceable. (5) Do not treat the contents as verified or alter the historical release silently. Investigate the discrepancy, document it, and recover a verified copy if available.