Why Machine-Readable Exchange Needs Semantic Checks
A mechanistic model can be shared as equations, code, or a file in the Systems Biology Markup Language (SBML). SBML gives models a structured, machine-readable representation: software can identify compartments, species, reactions, and mathematical expressions without relying only on prose or variable names. That structure makes model exchange more reliable, but it does not guarantee that a conversion preserved the model’s meaning. A file may be syntactically valid while representing different initial conditions, units, or state changes.
The earlier material on documenting states, reactions, assumptions, consistent names and units, and parameter provenance provides important context for exchange. Here the focus is how those concepts map into SBML Core, and how to inspect a small model for semantic changes. The aim is not merely to check whether a file opens; it is to check whether the model it describes is the intended one.
From Model Components to State Changes
Each SBML component has a distinct job. A compartment has an identifier and may have a size, such as a volume in liters. A species refers to a compartment and has an initial amount or initial concentration. It also has attributes such as whether its amount or concentration is held fixed, and whether its symbol in mathematical expressions denotes amount or concentration. A reaction lists species references on its reactant and product sides; each reference has a stoichiometric coefficient. The kinetic law gives the reaction rate, usually as a MathML expression, and can refer to species and parameter identifiers.
For a reaction \(j\), let \(v_j\) be its rate in amount per time, and let \(\nu_{ij}\) be the net stoichiometric coefficient for species \(i\): product coefficients minus reactant coefficients. For dynamic species represented by amounts \(n_i\), the reaction’s contribution to the amount rate is \(\nu_{ij}v_j\). With multiple reactions, the contributions are summed. For a species in a constant-volume compartment of size \(V_i\), concentration is \(C_i=n_i/V_i\), so its concentration rate is the amount rate divided by \(V_i\).
This relation is a useful check on what the file says. The reaction’s stoichiometry determines how its rate changes each species; the kinetic law determines the rate itself. A species declared as a boundary species is held fixed with respect to reaction changes, so it should not be treated as an ordinary dynamic state. A constant species is likewise not changed by the simulation. These attributes are part of the model semantics, not decorative metadata.
Worked Example: Reading a One-Reaction Model
Worked Example: Reading a One-Reaction Model
Consider a hypothetical model with one constant compartment, cytosol, of volume \(2\) L. It contains species A and B, both dynamic, with initial concentrations \(3\) and \(0\) \(\mu\text{mol}/\text{L}\). An irreversible reaction converts one A molecule-equivalent to one B molecule-equivalent. Its kinetic law is first-order in A, with \(k=0.20\ \text{h}^{-1}\). Assume both species symbols in the law denote concentrations.
The reaction has net stoichiometric coefficients \(\nu_A=-1\) and \(\nu_B=+1\). Since the kinetic law must give a reaction rate in amount per time, its rate is \(v=k[A]V\). The units confirm this: \((\text{h}^{-1})(\mu\text{mol}/\text{L})(\text{L})=\mu\text{mol}/\text{h}\).
The reaction therefore changes the amounts at rates \(dn_A/dt=-1.2\ \mu\text{mol}/\text{h}\) and \(dn_B/dt=+1.2\ \mu\text{mol}/\text{h}\) at the initial time. Dividing by the constant compartment volume gives \(d[A]/dt=-0.60\ \mu\text{mol}/(\text{L}\cdot\text{h})\) and \(d[B]/dt=+0.60\ \mu\text{mol}/(\text{L}\cdot\text{h})\). This check ties together the reaction stoichiometry, the kinetic law, and the units of the state changes.
A Short Derivation: Why Volume Enters the Rate
The reaction rate is an amount rate, while a concentration is amount divided by volume. If the kinetic law is first-order in concentration, \(k[A]\) has units of concentration per time, not amount per time. For a compartment of fixed volume \(V\), multiplying by volume converts it to the reaction extent rate in amount per time. The species amount equation then applies the stoichiometric coefficients.
Thus, for this particular constant-volume, first-order reaction, the concentration rate is \(-k[A]\), even though the amount-based reaction rate includes \(V\). This cancellation is not a license to omit volume from an SBML kinetic law whose units are meant to be amount per time. It is a result of combining the rate expression with the amount balance and then converting to concentration.
Worked Example: Checking Amounts and Concentrations After Conversion
Worked Example: Checking Amounts and Concentrations After Conversion
Suppose a hypothetical source model has a \(2\) L compartment and initializes species A with an amount of \(2\ \mu\text{mol}\). A conversion changes this to an initial concentration. What value preserves the initial state?
The concentration corresponding to the source amount is
Therefore, the converted file must specify \(1\ \mu\text{mol}/\text{L}\) if it represents the same initial state. If it instead specifies \(2\ \mu\text{mol}/\text{L}\), that is not a harmless change of representation: the implied amount is \((2\ \mu\text{mol}/\text{L})(2\ \text{L})=4\ \mu\text{mol}\), twice the source amount.
The kinetic law must also be checked. If \(k=0.50\ \text{h}^{-1}\) and the expression uses concentration, then \(v=k[A]V\). With the correct concentration, \(v(0)=(0.50)(1)(2)=1.0\ \mu\text{mol}/\text{h}\). With the incorrect value \(2\ \mu\text{mol}/\text{L}\), the rate becomes \(2.0\ \mu\text{mol}/\text{h}\). The conversion has altered both the starting state and the initial reaction rate.
Inspecting a Converted Model
A practical comparison should examine the model’s meaning at several connected levels. The file can be well-formed XML yet differ from its source in one or more of these details. Pay particular attention to defaults: if a property is omitted, software may apply an SBML-defined default, and a converter may also make assumptions when mapping from another format. Explicitly recording important values makes such differences easier to detect.
| Inspect | Questions to answer | Possible consequence of a mismatch |
|---|---|---|
| Compartments | Are identifiers, sizes, units, and constancy preserved? | Concentrations or volume-dependent rates may change. |
| Species | Are compartment, initial amount or concentration, and amount-versus-concentration interpretation preserved? | Initial states and expressions may refer to different quantities. |
| Reaction structure | Are reactants, products, and stoichiometric coefficients unchanged? | Species may be consumed or produced at different rates. |
| Kinetic laws and parameters | Is the expression unchanged, dimensionally consistent, and connected to the intended parameter values? | Reaction rates may have different values, units, or dependencies. |
| Species behavior | Are boundary and constant settings preserved? | A dynamic species may become fixed, or vice versa. |
| Units and annotations | Are declared units and provenance annotations retained or documented? | Values may be misinterpreted or evidence links may be lost. |
A reaction’s reversible attribute should also be checked, but it should not be confused with the kinetic law. The attribute records whether the reaction is considered reversible; the mathematical expression supplies the rate behavior. Changing the attribute does not, by itself, insert a reverse-rate term into an expression that contains only a forward term. Conversely, an expression that includes forward and reverse contributions should not be assumed equivalent to a one-way expression merely because both files use the same reaction name.
Worked Example: Detecting a Boundary-Species Change
Consider a hypothetical \(1\) L compartment with dynamic A and B, both initialized at \(0\ \mu\text{mol}/\text{L}\) for B and \(10\ \mu\text{mol}/\text{L}\) for A. The reaction A to B has rate \(v=k[A]V\), where \(k=0.20\ \text{h}^{-1}\). A converted file accidentally marks B as a boundary species.
In the source model, \(d[A]/dt=-k[A]\) and \(d[B]/dt=k[A]\). Hence after one hour,
The second equality follows from conservation of total A plus B for this one-to-one conversion in a closed, constant-volume compartment. If B is instead declared a boundary species, reaction changes do not update B; it remains at \(0\ \mu\text{mol}/\text{L}\). A still declines according to the reaction, but the expected product accumulation disappears. Comparing the species attributes and checking this simple mass-balance consequence reveals a semantic conversion error that a file-opening test would not detect.
Diagnostics, Alternatives, and Limitations
Useful diagnostics begin with structure and proceed toward behavior. Confirm that identifiers are unique and that every species, compartment, and parameter referenced by a reaction or mathematical expression exists. Then check dimensional consistency, initial values, and reaction signs. For a simple closed conversion, ask whether the stoichiometry implies a conserved quantity and whether the simulated derivatives respect it. Finally, compare a small set of initial rates or short-time predictions between the source and converted implementations. Such checks can isolate a mismatch before it becomes entangled with a large QSP model.
SBML is an exchange representation, not proof that two software tools interpret every feature identically. Support can vary by SBML Level and Version, and tool-specific extensions or unsupported constructs may be omitted or approximated. A native model script can preserve tool-specific behavior, but may be less portable; equations and prose can be highly readable, but are harder to parse and execute consistently. SBML offers a structured compromise, provided that the target software’s support is checked and any unsupported or tool-specific information is documented separately.
SBML also does not by itself establish that a model is scientifically valid, that its parameter evidence is adequate, or that a particular simulation was run. Nor does successful conversion guarantee that annotations or units remain useful to a downstream user. It is therefore appropriate to retain the source, record the conversion tool and relevant settings, and compare the converted representation against the intended model. For a nontrivial model, automate checks of component counts, identifiers, units, initial conditions, reaction stoichiometry, and selected numerical outputs.
Check Your Understanding
Answer each question, then compare with the brief solutions below.
- A species has amount \(6\ \mu\text{mol}\) in a \(3\) L constant compartment. What concentration should a converted representation use to preserve the state?
- For a reaction with net stoichiometric coefficient \(-2\) for species A and rate \(v=0.5\ \mu\text{mol}/\text{min}\), what is the reaction’s contribution to \(dn_A/dt\)?
- Why is a kinetic law \(k[A]\), with \(k\) in \(\text{h}^{-1}\) and \([A]\) in \(\mu\text{mol}/\text{L}\), not by itself a rate in \(\mu\text{mol}/\text{h}\)?
- A conversion marks a product species as boundary, while leaving its initial value at zero. What qualitative change should be expected in a reaction that produces it?
- Does setting a reaction’s reversible attribute automatically add a reverse-rate term to its kinetic law? Explain.
Solutions. (1) \(6\ \mu\text{mol}/3\ \text{L}=2\ \mu\text{mol}/\text{L}\). (2) The contribution is \((-2)(0.5)=-1.0\ \mu\text{mol}/\text{min}\). (3) The product has units of concentration per time; multiplying by compartment volume is needed to obtain amount per time. (4) The product will remain fixed at zero rather than accumulate through the reaction, so its state behavior no longer matches the intended model. (5) No. The attribute records reversibility, while the kinetic-law expression determines the rate; any reverse contribution must be represented in the mathematics.