two_reaction_model_with_encapsulation_doc
A Simple Two Reaction Pathway Model with Encapsulation
Table of Contents
This document continues the demonstration of recommended “best practices” for marking up models of biochemical reactions in CellML begun in the basic reaction example and the two reaction model. The current example extends the two reaction example by adding encapsulation.
It is assumed that you are already familiar with the basic reaction example and the two reaction model. Concepts covered in these examples are not duplicated here.
You might find it helpful to refer to a full printout of the CellML document that makes up this example as you progress through this documentation. The various forms available online are presented in the section “Download This Model”.
This model defines the reversible reaction:
A + B + 2E <-> 2F
The total reaction is composed of two elementary reactions:
A + B <-> 2C + D
C + E <-> F
The conventional rendering (pathway diagram) for the simple two reaction model is shown in Figure 1. In this rendering the reactants and products are shown as rounded rectangles on opposite ends of bidirectional arrows representing the reaction.
In CellML, models are thought of as connected networks of discrete components. These components may correspond to physiologically separated regions or chemically distinct objects, or may be useful modelling abstractions. This simple two reaction model has eight components representing chemically distinct objects (six chemical species and two reactions) and two components defined purely for modelling convenience: the component that represents the total reaction, which will be used to encapsulate other parts of the model and another “abstract” component which will store variables such as time. The CellML rendering of the simple two reaction model is shown in Figure 2 (the different shapes in the diagram are explained in the notation guide).
time. The variables in the model are shown next to the components in which their value may be modified, and alongside the connections along which they are passed to other components (where their value may not be modified).
The root <model> element of the CellML document for this model is identical to the corresponding element in the simple electrophysiological model, and the set of <units> elements (with which a set of named units is created for use in the model) is extremely similar to the set defined in the simple electrophysiological model (readers should refer to the analysis of that model for discussion of these parts of the model).
The components in this model are very similar to the components in the unencapsulated two reaction model. The primary difference is the addition of a new component to represent the overall, or total, reaction. This component is shown in Figure 3.
total_reaction component. This component represents the overall reaction defined by the model.
The first set of variables in this component (A, B, E, F, and time) are imported from unencapsulated (sibling) components (public_interface="in") and passed on to encapsulated components (private_interface="out"). These variables are required by the encapsulated reactions and species.
The delta variables (delta_A, delta_B, delta_E, and delta_F), which represent the changes in the concentrations of the corresponding species due to the reaction process, are imported from encapsulated components (private_interface="in") and exported to the rest of the network (public_interface="out"). In this way the delta variables are exposed to the rest of the model. Note that the chemical species C and D are completely hidden by the encapsulation. These chemical species can not be used outside of the encapsulated intermediate reactions. For this reason a modeller would normally only encapsulate chemical species components that represent uninteresting by-products of an intermediate reaction.
Encapsulation is represented in CellML using the <group> element. The group element indicating the encapsulation relationship between the total_reaction component and its subcomponents is shown in Figure 4. The participants in the group are named in <component_ref> elements. The <component_ref> elements nest inside other <component_ref> elements in order to indicate how the components relate to one another. A <relationship_ref> element with a relationship attribute value of "encapsulation" signifies that the components first_reaction, second_reaction, C, and D are logically encapsulated by the total_reaction component, and, therefore, are hidden from components A, B, E, F, and environment. For a better understanding of grouping hierarchies, see Section 6.2 of the CellML specification.
Adding encapsulation to the two reaction model necessitates an extra layer of connections. The variables representing the input chemical species must be passed from their respective components to the total_reaction component and from the total_reaction component to the encapsulated elementary reactions (first_reaction and second_reaction). Similarly, the variables representing the changes in concentration of the chemical species must be passed from the elementary reaction components to the total_reaction component, and then from the total_reaction component to the corresponding species components. Figure 5 demonstrates this for the chemical species F, which is the final product of the overall reaction in this model.
F species component and the encapsulate second_reaction component must be passed through the total_reaction component.
The variable representing time is also defined outside of the encapsulated set of components. While the time variable can still be passed directly to the unencapsulated species components A, B, E, and F, it must be passed to the total_reaction component, and then on to the encapsulated components representing the chemical species C and D. The difference in passing the time variable to unencapsulated and encapsulated components is shown in Figure 6 using the A and D components as examples.
The CellML description of the model that this documentation discusses is available in a number of formats. If you have your browser set up to view text files served with the “text/xml” MIME type, then you can have a look at the XML file directly here. If not, you can save the target of that link to disk by shift-clicking on the preceding link. A “pretty-printed” browsable HTML version of the XML file is available here
—
note that you cannot download and save this version for later viewing since it makes use of stylesheets for formatting. If you wish to save or print out the “pretty-printed” version of the XML, a PDF version is also available here.
Here are those links again:
two_reaction_model_with_encapsulation.xml — the raw XML.
two_reaction_model_with_encapsulation.html — an HTML version for browsing online.
two_reaction_model_with_encapsulation.pdf — a PDF version suitable for printing.
two_reaction_model_with_encapsulation_maths.pdf — a PDF of the equations described in the model generated directly from the CellML description using the MathML Renderer.