reaction_element_examples_doc

This document demonstrates how CellML's <reaction> element can be used within a model to describe various types of biological reaction. The reactions here are not based on any real biology but are merely examples to serve as a guide.

This <reaction> element defines the simple reversible reaction

The conventional rendering (pathway diagram) for the simple model is shown in Figure 1. In this rendering (and all following) the reactants and products are shown as rounded squares on opposite ends of bidirectional arrows representing the reaction.

Figure 1. The conventional rendering (pathway diagram) for the simple reversible reaction.

The CellML description of the simple reversible reaction shown in Figure 1 is given in Figure 2. The <reaction> element may contain a reversible attribute to indicate that the reaction defined may proceed in both directions; in this case, the value is "yes". Note that the reversible attribute is unnecessary in this example because the default value of the reversible attribute is "yes".

Each <variable_ref> element may contain one or more <role> elements. The role attribute of each <role> element declares the way in which the referenced variable participates in the reaction. Reactants A and B are labelled with role attribute values of "reactant", and the products C and D are given role attribute values of "product". Species may also assume roles of "catalyst", "activator", "inhibitor", "modifier", and "rate".

The direction attribute on the <role> element defines which direction the variable referenced serves in the role mentioned. The direction attribute may have a value of "forward", "reverse", or "both". The forward direction is the one in which the reactant is being consumed (i.e, the time-derivatives of their concentrations are negative). Variables with a role attribute value of "reactant" or "product" must only have a direction attribute value of "forward". Note that the direction attribute is unnecessary on all of the <role> elements in this example because the default value of the direction attribute is "forward".

The delta_variable attribute on the <role> element is used to associate a delta variable with the principle variable referenced in the parent <variable_ref> element. The delta variable represents the change in the concentration of the principle variable due to its involvement in the current reaction. A delta_variable attribute may only appear on <role> elements with a role attribute value of "reactant" or "product", as these are the only forms of reaction participation where the concentration of the participating species is changed. In the simple example, the variable delta_A is declared to be the delta variable associated with variable A, delta_B is declared to be the delta variable associated with variable B, and so on.

The stoichiometry attribute on the <role> element defines the stoichiometry of the current variable relative to the other reaction participants. In this example the stoichiometry attributes on each of the <role> elements allow us to form the chemical expression for the reaction. Different values of stoichiometry may be defined on different <role> elements within the same variable reference, allowing for instance, a species to participate as a reactant with one stoichiometry and as an inhibitor with another.

When both delta_variable and stoichiometry attributes are defined on the same <role> element, it implicitly defines an equation relating the delta variable to the reaction rate. The reaction rate variable is indicated by a <variable_ref> element containing a <role> element with a role attribute value of "rate" — in this example that variable is r. The implied equation equates the delta variable with the product of the stoichiometry and rate, producing the following equation:

delta_A = 1.0 ⋅ r             (1)

If math is to be implicitly defined using the scheme just described, then the <reaction> element must contain a variable reference which assigns a role of "rate" to one of the participants. This variable may participate in the reaction in no other way, and a <role> element with a role attribute value of "rate" must not contain direction, delta_variable, or stoichiometry attributes. It is recommended that the equation or system of equations used to calculate the value of the rate variable be placed inside the <role> element to make it easier for software or readers to find the relevant equation(s).

To view the full model of the above reaction, see the Simple Reaction/Pathway Model.

This <reaction> element defines the reversible reaction

The conventional rendering (pathway diagram) of the reversible reaction with catalysis is shown in Figure 3.

Figure 3. The conventional rendering (pathway diagram) for the simple reversible reaction with catalysis.

The CellML description of the reversible reaction with catalysis is given in Figure 4. The reversible reaction with catalysis is similar to the simple reversible reaction described in the section “Simple Reversible Reaction”. Here, as the <role> element shows, species C acts as a catalyst in the forward direction only. A catalyst must not be assigned a delta variable.

This <reaction> element defines the reversible reaction

The conventional rendering (pathway diagram) of an auto-catalysis reaction is shown in Figure 5.

Figure 5. The conventional rendering (pathway diagram) for an auto-catalysis reaction.

The CellML description of the auto-catalysis reaction is given in Figure 6. The auto-catalysis reaction is also much like the simple reversible reaction shown in the section “Simple Reversible Reaction”. Here, though, species A is both a reactant and a catalyst to this reaction. The dual roles of species A is demonstrated by assigning two separate <role> elements to the <variable_ref> element that references variable A. The first, with a role attribute of "reactant", includes the delta_variable and stoichiometry to provide the processing software with the mathematics necessary to calculate the change in the concentration of species A. The second has a role attribute value of "catalyst".

This <reaction> element defines the reversible reaction

The conventional rendering (pathway diagram) of a reversible reaction with catalysis and substrate inhibition is shown in Figure 7.

Figure 7. The conventional rendering (pathway diagram) for the reversible reaction with catalysis and substrate inhibition.

The CellML description of the reversible reaction with catalysis and substrate inhibition is given in Figure 8. In this example the species A inhibits the reverse reaction, thus the <variable_ref> element that references variable A contains two <role> elements. The first has a role attribute value of "reactant" in the forward direction only. The second has a role attribute value of "inhibitor" in the reverse direction only. A <role> element with a "role" attribute value of "inhibitor" must not contain a delta_variable attribute.

This <reaction> element defines the irreversible reaction

The conventional rendering (pathway diagram) of an irreversible reaction with catalysis and product inhibition is shown in Figure 9.

Figure 9. The conventional rendering (pathway diagram) for the irreversible reaction with catalysis and product inhibition.

The CellML description of the irreversible reaction with catalysis and product inhibition is given in Figure 10. Since this example shows an irreversible reaction, the <reaction> element defines a reversible attribute with a value of "no". In the CellML description, the direction attributes on the <role> elements have been omitted. It is invalid to specify a direction attribute with a value other than "forward" inside an irreversible reaction.