libSBML C API
libSBML 5.8.0 C API
|
Implementation of SBML's Reaction construct.
A reaction represents any transformation, transport or binding process, typically a chemical reaction, that can change the quantity of one or more species. In SBML, a reaction is defined primarily in terms of the participating reactants and products (and their corresponding stoichiometries), along with optional modifier species, an optional rate at which the reaction takes place, and optional parameters.
As with other major object in SBML, Reaction has a mandatory attribute, "id", used to give the compartment type an identifier. The identifier must be a text string conforming to the identifer syntax permitted in SBML. In SBML Level 2 and Level 3, the reaction "id" identifier can be used in mathematical formulas elsewhere in an SBML model to represent the rate of that reaction; this usage is explained below. Reaction also has an optional "name" attribute, of type string
. The "id" and "name" must be used according to the guidelines described in the SBML specification.
The species participating as reactants, products, and/or modifiers in a reaction are declared using lists of SpeciesReference and/or ModifierSpeciesReference instances stored in subelements "listOfReactants", "listOfProducts" and "listOfModifiers". Certain restrictions are placed on the appearance of species in reaction definitions:
The ability of a species to appear as a reactant or product of any reaction in a model is governed by certain flags in that species' definition; see the definition of Species for more information.
Any species appearing in the mathematical formula of the subelement "kineticLaw" (described below) of a Reaction must be declared in at least one of that Reaction's lists of reactants, products, and/or modifiers. Put another way, it is an error for a reaction's kinetic law formula to refer to species that have not been declared for that reaction.
A reaction can contain up to one KineticLaw object in a subelement named "kineticLaw". It defines the speed at which the process defined by the reaction takes place. The description of KineticLaw provides more details about its use. Note that although the inclusion of a KineticLaw object in an instance of a Reaction component is optional, there is no useful default that can be substituted in place of a missing rate expression in a reaction. Moreover, a reaction's rate cannot be defined in any other way in SBML—InitialAssignment, AssignmentRule, RateRule, AlgebraicRule, Event, and other constructs in SBML cannot be used to set the reaction rate separately. Nevertheless, for some modeling applications, reactions without any defined rate can be perfectly acceptable.
Reaction also has a boolean attribute named "reversible" for indicating whether the reaction is reversible. This attribute is optional in SBML Level 2, with a default of true
; it is mandatory in SBML Level 3 (with no default value). To say that a reaction is reversible is to say it can proceed in either the forward or the reverse direction. Although the reversibility of a reaction can sometimes be deduced by inspecting its rate expression, this is not always the case, especially for complicated expressions. Moreover, the need in SBML to allow rate expressions (i.e., KineticLaw) to be optional leads to the need for a separate flag indicating reversibility. Note that labeling a reaction as irreversible is an assertion that the reaction always proceeds in the given forward direction. (Why else would it be flagged as irreversible?) This implies the rate expression in the KineticLaw always has a non-negative value during simulations. Software tools could provide a means of optionally testing that this condition holds. The presence of reversibility information in two places (i.e., the rate expression and the "reversible" attribute on Reaction) leaves open the possibility that a model could contain contradictory information, but the creation of such a model would be an error on the part of the software generating it.
The Reaction object class has another boolean attribute called "fast". This attribute is optional in SBML Level 2, with a default of false
; it is mandatory in SBML Level 3 (with no default value). It is used to indicate that a reaction occurs on a vastly faster time scale than others in a system. Readers are directed to the SBML Level 2 Version 4 specification, which provides more detail about the conditions under which a reaction can be considered to be fast in this sense. The attribute's default value is false
. SBML Level 1 and Level 2 Version 1 incorrectly claimed that software tools could ignore this attribute if they did not implement support for the corresponding concept; however, further research in SBML has revealed that this is not true, and "fast" cannot be ignored if it is set to true
. SBML Level 2 Versions 2–4 therefore stipulate that if a model has any reactions with "fast" set to true
, a software tool must be able to respect the attribute or else indicate to the user that it does not have the capacity to do so. Analysis software cannot ignore the value of the "fast" attribute because doing so may lead to different results as compared to a software system that does make use of "fast".
In SBML Level 3 Version 1, the Reaction object has an additional optional attribute named "compartment", whose value must be the identifier of a compartment defined in the enclosing Model object. The "compartment" attribute can be used to indicate the compartment in which the reaction is assumed to take place. If the attribute is present, its value must be the identifier of a Compartment object defined in the enclosing Model object. Similar to the "reversible" attribute, the value of the "compartment" attribute has no direct impact on the construction of mathematical equations for the SBML model. When a kinetic law is given for a reaction, the compartment location may already be implicit in the kinetic law (although this cannot always be guaranteed). Nevertheless, software tools may find the "compartment" attribute value useful for such purposes as analyzing the structure of the model, guiding the modeler in constructing correct rate formulas, and visualization purposes.
Readers are urged to read the SBML specification for more details about the proper use of Reaction.