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.
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. |
java.lang.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(java.lang.String oldid,
java.lang.String newid)
Replaces all uses of a given
SIdRef type attribute value with another
value. |
void |
renameUnitSIdRefs(java.lang.String oldid,
java.lang.String newid)
Replaces all uses of a given
UnitSIdRef type attribute value with
another value. |
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, connectToChild, deleteDisabledPlugins, deleteDisabledPlugins, disablePackage, enablePackage, equals, getAncestorOfType, getAncestorOfType, getAnnotation, getAnnotationString, getColumn, getCVTerm, getCVTerms, getDisabledPlugin, getElementByMetaId, getElementBySId, getId, getIdAttribute, getLevel, getLine, getListOfAllElements, getListOfAllElements, getListOfAllElementsFromPlugins, getListOfAllElementsFromPlugins, getMetaId, getModel, getModelHistory, getName, getNamespaces, getNotes, getNotesString, getNumCVTerms, getNumDisabledPlugins, getNumPlugins, getPackageCoreVersion, getPackageName, getPackageVersion, getParentSBMLObject, getPlugin, getPlugin, getPrefix, getResourceBiologicalQualifier, getResourceModelQualifier, getSBMLDocument, getSBOTerm, getSBOTermAsURL, getSBOTermID, getURI, getVersion, hashCode, hasValidLevelVersionNamespaceCombination, isPackageEnabled, isPackageURIEnabled, isPkgEnabled, isPkgURIEnabled, isSetAnnotation, isSetId, isSetIdAttribute, isSetMetaId, isSetModelHistory, isSetName, isSetNotes, isSetSBOTerm, isSetUserData, matchesRequiredSBMLNamespacesForAddition, matchesSBMLNamespaces, removeTopLevelAnnotationElement, removeTopLevelAnnotationElement, removeTopLevelAnnotationElement, renameMetaIdRefs, replaceTopLevelAnnotationElement, replaceTopLevelAnnotationElement, setAnnotation, setAnnotation, setId, setIdAttribute, setMetaId, setModelHistory, setName, setNamespaces, setNotes, setNotes, setNotes, setSBOTerm, setSBOTerm, toSBML, toXMLNode, unsetAnnotation, unsetCVTerms, unsetId, unsetIdAttribute, unsetMetaId, unsetModelHistory, unsetName, unsetNotes, unsetSBOTerm, unsetUserData
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
.
SBMLConstructorException
- Thrown if the given level
and version
combination are invalid
or if this object is incompatible with the given level and version.
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.
, Attempting to add an object to an SBMLDocument
having a different
combination of SBML Level, Version and XML namespaces than the object
itself will result in an error at the time a caller attempts to make the
addition. A parent object must have compatible Level, Version and XML
namespaces. (Strictly speaking, a parent may also have more XML
namespaces than a child, but the reverse is not permitted.) The
restriction is necessary to ensure that an SBML model has a consistent
overall structure. This requires callers to manage their objects
carefully, but the benefit is increased flexibility in how models can be
created by permitting callers to create objects bottom-up if desired. In
situations where objects are not yet attached to parents (e.g.,
SBMLDocument
), knowledge of the intented SBML Level and Version help
libSBML determine such things as whether it is valid to assign a
particular value to an attribute.
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 libSBML's SBMLNamespaces
facilities is to create an
SBMLNamespaces
object somewhere in a program once, then hand that object
as needed to object constructors that accept SBMLNamespaces
as arguments.
sbmlns
- an SBMLNamespaces
object.
SBMLConstructorException
- Thrown if the given sbmlns
is inconsistent or incompatible
with this object.
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.
, Attempting to add an object to an SBMLDocument
having a different
combination of SBML Level, Version and XML namespaces than the object
itself will result in an error at the time a caller attempts to make the
addition. A parent object must have compatible Level, Version and XML
namespaces. (Strictly speaking, a parent may also have more XML
namespaces than a child, but the reverse is not permitted.) The
restriction is necessary to ensure that an SBML model has a consistent
overall structure. This requires callers to manage their objects
carefully, but the benefit is increased flexibility in how models can be
created by permitting callers to create objects bottom-up if desired. In
situations where objects are not yet attached to parents (e.g.,
SBMLDocument
), knowledge of the intented SBML Level and Version help
libSBML determine such things as whether it is valid to assign a
particular value to an attribute.
public StoichiometryMath(StoichiometryMath orig) throws SBMLConstructorException
StoichiometryMath
.
orig
- the object to copy.SBMLConstructorException
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 StoichiometryMath cloneObject()
StoichiometryMath
object.
cloneObject
 in class SBase
StoichiometryMath
object.public ASTNode getMath()
StoichiometryMath
and
return it as an AST.
StoichiometryMath
, or null
if the math is not set.
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 boolean isSetMath()
StoichiometryMath
object
is set.
true
if the formula (meaning the math
subelement) of
this StoichiometryMath
is set, false
otherwise.
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 setMath(ASTNode math)
StoichiometryMath
instance to a
copy of the given ASTNode
.
math
- an ASTNode
representing a formula tree.
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 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.
getDerivedUnitDefinition
 in class SBase
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 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.
containsUndeclaredUnits
 in class SBase
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 int getTypeCode()
LibSBML attaches an identifying code to every kind of SBML object. These
are integer constants known as SBML type codes. The names of all
the codes begin with the characters SBML_
.
In the Java language interface for libSBML, the
type codes are defined as static integer constants in the interface class
libsbmlConstants
. Note that different Level 3
package plug-ins may use overlapping type codes to identify the package
to which a given object belongs, call the
method on the object.
SBase.getPackageName()
getTypeCode
 in class SBase
SBML_STOICHIOMETRY_MATH
(default).
StoichiometryMath.getElementName()
,
SBase.getPackageName()
public java.lang.String getElementName()
StoichiometryMath
, is
always 'stoichiometryMath'.
getElementName
 in class SBase
'stoichiometryMath'.
public boolean hasRequiredElements()
true
if
all the required elements for this StoichiometryMath
object
have been set.
hasRequiredElements
 in class SBase
StoichiometryMath
object are:
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(java.lang.String oldid, java.lang.String newid)
Replaces all uses of a given SIdRef
type attribute value with another
value.
In SBML, object identifiers are of a data type called SId
.
In SBML Level 3, an explicit data type called SIdRef
was
introduced for attribute values that refer to SId
values in
previous Levels of SBML, this data type did not exist and attributes were
simply described to as 'referring to an identifier', but the effective
data type was the same as SIdRef
in Level 3. These and
other methods of libSBML refer to the type SIdRef
for all
Levels of SBML, even if the corresponding SBML specification did not
explicitly name the data type.
This method works by looking at all attributes and (if appropriate)
mathematical formulas in MathML content, comparing the referenced
identifiers to the value of oldid
. If any matches are found, the
matching values are replaced with newid
. The method does not
descend into child elements.
renameSIdRefs
 in class SBase
oldid
- the old identifier.newid
- the new identifier.public void renameUnitSIdRefs(java.lang.String oldid, java.lang.String newid)
Replaces all uses of a given UnitSIdRef
type attribute value with
another value.
In SBML, unit definitions have identifiers of type UnitSId
. In
SBML Level 3, an explicit data type called UnitSIdRef
was
introduced for attribute values that refer to UnitSId
values in
previous Levels of SBML, this data type did not exist and attributes were
simply described to as 'referring to a unit identifier', but the effective
data type was the same as UnitSIdRef
in Level 3. These and
other methods of libSBML refer to the type UnitSIdRef
for all
Levels of SBML, even if the corresponding SBML specification did not
explicitly name the data type.
This method works by looking at all unit identifier attribute values
(including, if appropriate, inside mathematical formulas), comparing the
referenced unit identifiers to the value of oldid
. If any matches
are found, the matching values are replaced with newid
. The method
does not descend into child elements.
renameUnitSIdRefs
 in class SBase
oldid
- the old identifier.newid
- the new identifier.