Consistent Names and Units in Shared Models

Why Names and Units Are Part of the Model

A shared QSP model is interpretable only if its entries communicate what is represented and how quantities are measured. An identifier such as IL6 might refer to a molecule, a concentration in plasma, a concentration in tissue, or an assay result. A parameter called clearance might have units of inverse time or volume per time, depending on the equation in which it is used. Those are not cosmetic differences: confusing them can change the mathematical model while leaving its equations superficially plausible.

Naming and unit conventions should therefore make model meaning explicit, not attempt to replace a definition or equation. The conventions in this tutorial are practical choices for a project; no single identifier grammar is universal. The essential requirement is that a reader can determine each entry's biological referent, location, quantity type, unit and role without guessing.

These terms should not be collapsed into one label. For example, “IL-6” names an entity, “IL-6 concentration in plasma” names a state, and “serum IL-6 immunoassay result” names an observable that may be calculated from one or more states. A state is not automatically identical to what an assay measures.

A Practical Naming Convention

A useful convention combines a readable identifier with structured documentation. For state variables, a project might use the pattern entity_compartment_form, such as IL6_plasma_free. A complex can name both partners, as in IL6_IL6R_plasma_complex. The exact ordering is less important than applying it consistently and defining it in a project glossary.

Identifiers should be stable, unique, and specific enough to distinguish states that differ in location, molecular form, or biological meaning. Use a documented spelling and capitalization scheme; avoid spaces and punctuation that different software may parse differently. If an entity has species-of-origin or species-of-experiment distinctions, record them explicitly, for example in a species field or a controlled prefix such as human_IL6 and mouse_IL6. Do not rely on a reader to infer whether “species” means organism or molecular species.

For parameters, names should communicate the process and, where needed, the interacting entities or compartment. Examples include kon_IL6_IL6R_plasma and koff_IL6_IL6R_plasma. The identifier alone does not fully define a parameter. Its record should also state its description, units, scope, value or source, and any conditions or assumptions that delimit its use. Provenance belongs with that record; a plausible name is not evidence for a value.

Observable identifiers should distinguish the measured quantity from internal states. A name such as serum_IL6_total_pg_per_mL signals a matrix, quantity, and reporting unit. Documentation should additionally specify the assay or measurement definition, any transformation from model states, and whether the readout is total, free, or otherwise selective. If an observable uses a unit different from the underlying state, the conversion and its assumptions must be explicit.

Units Must Follow the Equations

A unit convention is useful only when it is checked against the mathematical definition. For each state, record whether it is an amount, concentration, fraction, or another quantity, together with its unit. Record parameter units as well. State the model's base time unit, and keep conversions explicit when combining data or processes expressed on different scales.

Dimensional analysis provides a direct check: every term added or subtracted in an equation must have the same units. For a concentration state \(C\) measured in nM, its derivative with respect to time measured in h has units nM/h. In the equation below, \(k_{\mathrm{in}}\) must therefore be in nM/h, and \(k_{\mathrm{out}}\) must be in h\(^{-1}\).

Indeed, \(k_{\mathrm{out}}C\) has units \(\mathrm{h}^{-1}\times\mathrm{nM}=\mathrm{nM}/\mathrm{h}\), matching both the derivative and the input term. This check can expose an identifier that suggests one quantity while the equation uses another.

Justifying a Unit Conversion

A shared model may use concentrations in a mechanistic state while an assay reports mass per volume. A conversion requires a molecular mass and an explicit assumption about what molecular form the measurement represents. For a species with molecular mass \(M\) in g/mol and concentration \(C\) in mol/L, the mass concentration is \(CM\) in g/L. Unit conversion then gives the assay-scale value. This dimensional relation does not establish that the assay detects that species selectively; that is a separate measurement assumption.

For example, a molecular mass of 20 kDa is \(20{,}000\) g/mol. A concentration of 1 nM is \(10^{-9}\) mol/L, so its mass concentration is \(20{,}000\times10^{-9}=2.00\times10^{-5}\) g/L. Since \(1\) g/L equals \(10^6\) ng/mL, this is \(20.0\) ng/mL, or \(20{,}000\) pg/mL.

Reviewing Shared Entries Systematically

A structured review helps identify problems before a collaborator reuses an entry. For each state, parameter and observable, ask what it represents, where it applies, what quantity it is, which units it uses, and how it connects to equations or measurements. When a model contains multiple organisms, tissues, molecular forms, or assay readouts, check that the distinctions are expressed consistently throughout equations, tables, plots, and documentation.

Common failure signals include identifiers reused for different entities, a compartment omitted where several are modelled, equations whose terms have incompatible dimensions, and plot labels that omit a unit or report a different unit from the underlying state. These are reasons to inspect the definition and model logic. They are not necessarily fixed by changing a display label.

A controlled glossary with stable identifiers and explicit units is generally easier to review than free-form names alone. Conversely, a rigid naming grammar can become unwieldy when it tries to encode every detail in a single string. A practical compromise is a concise, unique identifier supported by structured fields for entity, compartment, quantity type, unit, role, and description. Unit conversion can likewise be handled either by converting inputs to a common internal unit or by preserving source units and applying explicit conversions. In either case, conversions must be visible and testable.

Common Mistakes and Limitations

• Treating a familiar name as a definition. “Clearance” is not enough to determine whether a parameter is a volume-per-time clearance or a first-order rate constant. State its equation role and units.
• Using a molecule name for an assay output. An assay may measure total, free, or selectively detected material. Name and document the observable accordingly.
• Changing units without changing the numeric value. A concentration expressed in nM cannot be relabelled as pg/mL without a conversion and the assumptions needed for that conversion.
• Assuming matching names imply matching meaning. Two collaborators may use the same identifier for different compartments or molecular forms. Compare definitions and equations, not labels alone.
• Assuming unit consistency proves biological validity. Dimensional consistency is necessary for a coherent equation, but it does not establish that the chosen mechanism, parameter value, or measurement mapping is biologically appropriate.

Naming standards also have limits. They cannot resolve a genuinely ambiguous biological definition, establish the correct compartment structure, or guarantee that a parameter is supported by evidence. Those questions require explicit model documentation and scientific review. The purpose of consistent names and units is to make such questions visible and to let collaborators check whether they are using the same model concepts.