public class StoichiometryMath extends SBase
In SBML Level 2, product and reactant stoichiometries can be specified
using either the 'stoichiometry' attribute or a 'stoichiometryMath'
element in a SpeciesReference
object. The 'stoichiometry' attribute is
of type double
and should contain values greater than zero (0). The
'stoichiometryMath' element is implemented as an element containing a
MathML expression. These two are mutually exclusive only one of
'stoichiometry' or 'stoichiometryMath' should be defined in a given
SpeciesReference
instance. When neither the attribute nor the element
is present, the value of 'stoichiometry' in the enclosing
SpeciesReference
instance defaults to 1.
For maximum interoperability, SpeciesReference
's 'stoichiometry'
attribute should be used in preference to 'stoichiometryMath' when a
species' stoichiometry is a simple scalar number (integer or decimal).
When the stoichiometry is a rational number, or when it is a more
complicated formula, 'stoichiometryMath' must be used. The MathML
expression in 'stoichiometryMath' may also refer to identifiers of
entities in a model (except reaction identifiers). However, the only
species identifiers that can be used in 'stoichiometryMath' are those
referenced in the enclosing Reaction
's list of reactants, products and
modifiers.
The 'stoichiometry' attribute and the 'stoichiometryMath' element, when
either is used, is each interpreted as a factor applied to the reaction
rate to produce the rate of change of the species identified by the
'species' attribute in the enclosing SpeciesReference
. This is the
normal interpretation of a stoichiometry, but in SBML, one additional
consideration has to be taken into account. The reaction rate, which is
the result of the KineticLaw
's 'math' element, is always in the model's
substance per time units. However, the rate of change of the
species will involve the species' substance units (i.e., the units
identified by the Species
object's 'substanceUnits' attribute), and
these units may be different from the model's default substance
units. If the units are different, the stoichiometry must
incorporate a conversion factor for converting the model's substance
units to the species' substance units. The conversion factor is
assumed to be included in the scalar value of the 'stoichiometry'
attribute if 'stoichiometry' is used. If instead 'stoichiometryMath' is
used, then the product of the model's 'substance' units times the
'stoichiometryMath' units must match the substance units of the
species. Note that in either case, if the species' units and the
model's default substance units are the same, the stoichiometry ends
up being a dimensionless number and equivalent to the standard chemical
stoichiometry found in textbooks. Examples and more explanations of
this are given in the SBML specification.
The following is a simple example of a species reference for species
'X0'
, with stoichiometry 2
, in a list of reactants within a reaction
having the identifier 'J1':
<model> ... <listOfReactions> <reaction id='J1'> <listOfReactants> <speciesReference species='X0' stoichiometry='2'> </listOfReactants> ... </reaction> ... </listOfReactions> ... </model>
The following is a more complex example of a species reference for
species 'X0'
, with a stoichiometry formula consisting of
a rational number:
<model> ... <listOfReactions> <reaction id='J1'> <listOfReactants> <speciesReference species='X0'> <stoichiometryMath> <math xmlns='http://www.w3.org/1998/Math/MathML'> <cn type='rational'> 3 <sep/> 2 </cn> </math> </stoichiometryMath> </speciesReference> </listOfReactants> ... </reaction> ... </listOfReactions> ... </model>
Additional discussions of stoichiometries and implications for species
and reactions are included in the documentation of SpeciesReference
class.
The StoichiometryMath
construct is not defined in SBML Level 3
Version 1 Core. Instead, Level 3 defines the identifier of
SpeciesReference
objects as a stand-in for the stoichiometry of the
reactant or product being referenced, and allows that identifier to be
used elsewhere in SBML models, including (for example) InitialAssignment
objects. This makes it possible to achieve the same effect as
StoichiometryMath
, but with other SBML objects. For instance, to
produce a stoichiometry value that is a rational number, a model can use
InitialAssignment
to assign the identifier of a SpeciesReference
object
to a MathML expression evaluating to a rational number. This is
analogous to the same way that, in Level 2, the model would use
StoichiometryMath
with a MathML expression evaluating to a rational
number.
In SBML Level 2, the stoichiometry of a reactant or product is a
combination of both a biochemical stoichiometry (meaning, the
standard stoichiometry of a species in a reaction) and any necessary
unit conversion factors. The introduction of an explicit attribute on
the Species
object for a conversion factor allows Level 3 to avoid
having to overload the meaning of stoichiometry. In Level 3, the
stoichiometry given by a SpeciesReference
object in a reaction is a
'proper' biochemical stoichiometry, meaning a dimensionless number free
of unit conversions.
SpeciesReference
,
Reaction
Constructor and Description |
---|
StoichiometryMath(long level,
long version)
Creates a new
StoichiometryMath object using the given SBML level
values. |
StoichiometryMath(SBMLNamespaces sbmlns)
|
StoichiometryMath(StoichiometryMath orig)
Copy constructor creates a copy of this
StoichiometryMath . |
Modifier and Type | Method and Description |
---|---|
StoichiometryMath |
cloneObject()
Creates and returns a deep copy of this
StoichiometryMath object. |
boolean |
containsUndeclaredUnits()
Predicate returning
true if the math
expression of this StoichiometryMath object contains literal numbers
or parameters with undeclared units. |
void |
delete()
Explicitly deletes the underlying native object.
|
UnitDefinition |
getDerivedUnitDefinition()
Calculates and returns a
UnitDefinition object that expresses the
units returned by the math expression in this StoichiometryMath
object. |
String |
getElementName()
Returns the XML element name of this object, which for
StoichiometryMath , is
always 'stoichiometryMath'. |
ASTNode |
getMath()
Retrieves the mathematical formula within this
StoichiometryMath and
return it as an AST. |
int |
getTypeCode()
Returns the libSBML type code of this object instance.
|
boolean |
hasRequiredElements()
Predicate returning
true if
all the required elements for this StoichiometryMath object
have been set. |
boolean |
isSetMath()
Predicate to test whether the math for this
StoichiometryMath object
is set. |
int |
removeFromParentAndDelete()
Finds this
StoichiometryMath 's SpeciesReference parent and calls unsetStoichiometryMath() on it, indirectly deleting itself. |
void |
renameSIdRefs(String oldid,
String newid)
Renames all the SIdRef attributes on this element, including any found in MathML
|
void |
renameUnitSIdRefs(String oldid,
String newid)
Renames all the UnitSIdRef attributes on this element
|
int |
setMath(ASTNode math)
Sets the 'math' expression of this
StoichiometryMath instance to a
copy of the given ASTNode . |
addCVTerm, addCVTerm, appendAnnotation, appendAnnotation, appendNotes, appendNotes, disablePackage, enablePackage, equals, getAncestorOfType, getAncestorOfType, getAnnotation, getAnnotationString, getColumn, getCVTerm, getCVTerms, getElementByMetaId, getElementBySId, getLevel, getLine, getListOfAllElements, getListOfAllElementsFromPlugins, getMetaId, getModel, getModelHistory, getNamespaces, getNotes, getNotesString, getNumCVTerms, getNumPlugins, getPackageName, getPackageVersion, getParentSBMLObject, getPlugin, getPlugin, getResourceBiologicalQualifier, getResourceModelQualifier, getSBMLDocument, getSBOTerm, getSBOTermAsURL, getSBOTermID, getVersion, hashCode, hasValidLevelVersionNamespaceCombination, isPackageEnabled, isPackageURIEnabled, isSetAnnotation, isSetMetaId, isSetModelHistory, isSetNotes, isSetSBOTerm, matchesRequiredSBMLNamespacesForAddition, matchesSBMLNamespaces, removeTopLevelAnnotationElement, removeTopLevelAnnotationElement, renameMetaIdRefs, replaceTopLevelAnnotationElement, replaceTopLevelAnnotationElement, setAnnotation, setAnnotation, setMetaId, setModelHistory, setNamespaces, setNotes, setNotes, setNotes, setSBOTerm, setSBOTerm, toSBML, unsetAnnotation, unsetCVTerms, unsetId, unsetMetaId, unsetModelHistory, unsetName, unsetNotes, unsetSBOTerm
public StoichiometryMath(long level, long version) throws SBMLConstructorException
StoichiometryMath
object using the given SBML level
values.
level
- a long integer, the SBML Level to assign to this StoichiometryMath
version
- a long integer, the SBML Version to assign to this
StoichiometryMath
The StoichiometryMath
construct exists only in SBML Level 2. It
is an optional construct available for defining the stoichiometries of
reactants and products in Reaction
objects. Note that a different
mechanism is used in SBML Level 3, where StoichiometryMath
is not
available. Please consult the top of this libSBML StoichiometryMath
documentation for more information about the differences between SBML
Level 2 and 3 with respect to stoichiometries.
SBMLConstructorException
- Thrown if the given level
and version
combination, or this kind
of SBML object, are either invalid or mismatched with respect to the
parent SBMLDocument
object.
StoichiometryMath
object to an
SBMLDocument
(e.g., using
SpeciesReference.createStoichiometryMath()
), the SBML Level, SBML
Version and XML namespace of the document override the values used
when creating the StoichiometryMath
object via this constructor. This
is necessary to ensure that an SBML document is a consistent
structure. Nevertheless, the ability to supply the values at the time
of creation of a StoichiometryMath
is an important aid to producing
valid SBML. Knowledge of the intented SBML Level and Version
determine whether it is valid to assign a particular value to an
attribute, or whether it is valid to add an object to an existing
SBMLDocument
.public StoichiometryMath(SBMLNamespaces sbmlns) throws SBMLConstructorException
StoichiometryMath
object using the given SBMLNamespaces
object
sbmlns
.
The SBMLNamespaces
object encapsulates SBML Level/Version/namespaces
information. It is used to communicate the SBML Level, Version, and
(in Level 3) packages used in addition to SBML Level 3 Core.
A common approach to using this class constructor is to create an
SBMLNamespaces
object somewhere in a program, once, then pass it to
object constructors such as this one when needed.
sbmlns
- an SBMLNamespaces
object.
The StoichiometryMath
construct exists only in SBML Level 2. It
is an optional construct available for defining the stoichiometries of
reactants and products in Reaction
objects. Note that a different
mechanism is used in SBML Level 3, where StoichiometryMath
is not
available. Please consult the top of this libSBML StoichiometryMath
documentation for more information about the differences between SBML
Level 2 and 3 with respect to stoichiometries.
SBMLConstructorException
- Thrown if the given level
and version
combination, or this kind
of SBML object, are either invalid or mismatched with respect to the
parent SBMLDocument
object.
StoichiometryMath
object to an
SBMLDocument
(e.g., using
SpeciesReference.createStoichiometryMath()
), the SBML XML namespace
of the document overrides the value used when creating the
StoichiometryMath
object via this constructor. This is necessary to
ensure that an SBML document is a consistent structure. Nevertheless,
the ability to supply the values at the time of creation of a
StoichiometryMath
is an important aid to producing valid SBML.
Knowledge of the intented SBML Level and Version determine whether it
is valid to assign a particular value to an attribute, or whether it
is valid to add an object to an existing SBMLDocument
.public StoichiometryMath(StoichiometryMath orig) throws SBMLConstructorException
StoichiometryMath
.
orig
- the object to copy.
SBMLConstructorException
- Thrown if the argument orig
is null.
public StoichiometryMath cloneObject()
StoichiometryMath
object.
cloneObject
 in class SBase
StoichiometryMath
.public boolean containsUndeclaredUnits()
true
if the math
expression of this StoichiometryMath
object contains literal numbers
or parameters with undeclared units.
The StoichiometryMath.getDerivedUnitDefinition()
method returns what
libSBML computes the units of the Stoichiometry to be, to the extent
that libSBML can compute them. However, if the expression contains
literal numbers or parameters with undeclared units, libSBML may not
be able to compute the full units of the expression and will only
return what it can compute. Callers should always use
StoichiometryMath.containsUndeclaredUnits()
when using
StoichiometryMath.getDerivedUnitDefinition()
to decide whether the
returned units may be incomplete.
true
if the math expression of this StoichiometryMath
includes numbers/parameters with undeclared units, false
otherwise.
StoichiometryMath.getDerivedUnitDefinition()
true
indicates that the UnitDefinition
returned by StoichiometryMath.getDerivedUnitDefinition()
may not
accurately represent the units of the expression.
public void delete()
In general, application software will not need to call this method directly. The Java language binding for libSBML is implemented as a language wrapper that provides a Java interface to libSBML's underlying C++/C code. Some of the Java methods return objects that are linked to objects created not by Java code, but by C++ code. The Java objects wrapped around them will be deleted when the garbage collector invokes the corresponding C++ finalize()
methods for the objects. The finalize()
methods in turn call the StoichiometryMath.delete()
method on the libSBML object.
This method is exposed in case calling programs want to ensure that the underlying object is freed immediately, and not at some arbitrary time determined by the Java garbage collector. In normal usage, callers do not need to invoke StoichiometryMath.delete()
themselves.
public UnitDefinition getDerivedUnitDefinition()
UnitDefinition
object that expresses the
units returned by the math expression in this StoichiometryMath
object.
The units are calculated based on the mathematical expression in the
StoichiometryMath
and the model quantities referenced by
<ci>
elements used within that expression. The
StoichiometryMath.getDerivedUnitDefinition()
method returns the
calculated units.
Note that the functionality that facilitates unit analysis depends
on the model as a whole. Thus, in cases where the object has not
been added to a model or the model itself is incomplete,
unit analysis is not possible and this method will return null.
UnitDefinition
that expresses the units of the math,
or null
if one cannot be constructed.
StoichiometryMath.containsUndeclaredUnits()
StoichiometryMath
instance contains literal numbers or parameters with
undeclared units. In those cases, it is not possible to calculate the
units of the overall expression without making assumptions. LibSBML
does not make assumptions about the units, and
StoichiometryMath.getDerivedUnitDefinition()
only returns the units
as far as it is able to determine them. For example, in an expression
X + Y, if X has unambiguously-defined units and
Y does not, it will return the units of X. When
using this method, it is critical that callers also invoke the
method StoichiometryMath.containsUndeclaredUnits()
to determine whether this situation holds. Callers
should take suitable action in those situations.
public String getElementName()
StoichiometryMath
, is
always 'stoichiometryMath'.
getElementName
 in class SBase
'stoichiometryMath'.
public ASTNode getMath()
StoichiometryMath
and
return it as an AST.
StoichiometryMath
.
The StoichiometryMath
construct exists only in SBML Level 2. It
is an optional construct available for defining the stoichiometries of
reactants and products in Reaction
objects. Note that a different
mechanism is used in SBML Level 3, where StoichiometryMath
is not
available. Please consult the top of this libSBML StoichiometryMath
documentation for more information about the differences between SBML
Level 2 and 3 with respect to stoichiometries.
public int getTypeCode()
LibSBML attaches an identifying code to every
kind of SBML object. These are known as SBML type codes. In
other languages, the set of type codes is stored in an enumeration in
the Java language interface for libSBML, the type codes are defined as
static integer constants in the interface class libsbmlConstants
. The names of the type codes all begin with the
characters SBML_.
getTypeCode
 in class SBase
SBML_UNKNOWN
(default).
StoichiometryMath.getElementName()
public boolean hasRequiredElements()
true
if
all the required elements for this StoichiometryMath
object
have been set.
hasRequiredElements
 in class SBase
StoichiometryMath
object are:
public boolean isSetMath()
StoichiometryMath
object
is set.
true
if the formula (meaning the math
subelement) of
this StoichiometryMath
is set, false
otherwise.
The StoichiometryMath
construct exists only in SBML Level 2. It
is an optional construct available for defining the stoichiometries of
reactants and products in Reaction
objects. Note that a different
mechanism is used in SBML Level 3, where StoichiometryMath
is not
available. Please consult the top of this libSBML StoichiometryMath
documentation for more information about the differences between SBML
Level 2 and 3 with respect to stoichiometries.
public int removeFromParentAndDelete()
StoichiometryMath
's SpeciesReference
parent and calls unsetStoichiometryMath() on it, indirectly deleting itself. Overridden from the SBase
function since the parent is not a ListOf
.
removeFromParentAndDelete
 in class SBase
public void renameSIdRefs(String oldid, String newid)
renameSIdRefs
 in class SBase
oldid
- the old identifiernewid
- the new identifierpublic void renameUnitSIdRefs(String oldid, String newid)
renameUnitSIdRefs
 in class SBase
oldid
- the old identifiernewid
- the new identifierpublic int setMath(ASTNode math)
StoichiometryMath
instance to a
copy of the given ASTNode
.
math
- an ASTNode
representing a formula tree.
The StoichiometryMath
construct exists only in SBML Level 2. It
is an optional construct available for defining the stoichiometries of
reactants and products in Reaction
objects. Note that a different
mechanism is used in SBML Level 3, where StoichiometryMath
is not
available. Please consult the top of this libSBML StoichiometryMath
documentation for more information about the differences between SBML
Level 2 and 3 with respect to stoichiometries.