public class KineticLaw extends SBase
An object of class KineticLaw
is used to describe the rate at which the
process defined by a given Reaction
takes place. KineticLaw
has
subelements called 'math' (for MathML content) and 'listOfParameters'
(of class ListOfParameters
), in addition to the attributes and
subelements it inherits from SBase
.
KineticLaw
's 'math' subelement for holding a MathML formula defines the
rate of the reaction. The formula may refer to other entities in a
model as well as local parameter definitions within the scope of the
Reaction
(see below). It is important to keep in mind, however, that
the only Species
identifiers that can be used in this formula are those
declared in the lists of reactants, products and modifiers in the
Reaction
structure. (In other words, before a species can be referenced
in the KineticLaw
, it must be declared in one of those lists.)
KineticLaw
provides a way to define local parameters whose
identifiers can be used in the 'math' formula of that KineticLaw
instance. Prior to SBML Level 3, these parameter definitions are
stored inside a 'listOfParameters' subelement containing Parameter
objects in SBML Level 3, this is achieved using a specialized
object class called LocalParameter
and the containing subelement is
called 'listOfLocalParameters'. In both cases, the parameters so
defined are only visible within the KineticLaw
they cannot be accessed
outside. A local parameter within one reaction is not visible from
within another reaction, nor is it visible to any other construct
outside of the KineticLaw
in which it is defined. In addition, another
important feature is that if such a Parameter
(or in Level 3,
LocalParameter
) object has the same identifier as another object in the
scope of the enclosing Model
, the definition inside the KineticLaw
takes
precedence. In other words, within the KineticLaw
's 'math' formula,
references to local parameter identifiers shadow any identical
global identifiers.
The values of local parameters defined within KineticLaw
objects cannot
change. In SBML Level 3, this quality is built into the
LocalParameter
construct. In Level 2, where the same kind of
Parameter
object class is used as for global parameters, the Parameter
objects' 'constant' attribute must always have a value of true
(either explicitly or left to its default value).
A common misconception is that different classes of objects (e.g.,
species, compartments, parameters) in SBML have different identifier
scopes. They do not. The implication is that if a KineticLaw
's local
parameter definition uses an identifier identical to any other
identifier defined in the model outside the KineticLaw
, even if the
other identifier does not belong to a parameter type of object, the
local parameter's identifier takes precedence within that KineticLaw
's
'math' formula. It is not an error in SBML for identifiers to shadow
each other this way, but can lead to confusing and subtle errors.
In SBML Level 2 Version 1, the SBML specification
included two additional attributes on KineticLaw
called 'substanceUnits'
and 'timeUnits'. They were removed beginning with SBML Level 2
Version 2 because further research determined they introduced many
problems. The most significant problem was that their use could easily
lead to the creation of valid models whose reactions nevertheless could
not be integrated into a system of equations without outside knowledge
for converting the quantities used. Examination of real-life models
revealed that a common reason for using 'substanceUnits' on KineticLaw
was to set the units of all reactions to the same set of substance
units, something that is better achieved by using UnitDefinition
to
redefine 'substance'
for the whole Model
.
As mentioned above, in SBML Level 2 Versions 2&ndash4, local
parameters are of class Parameter
. In SBML Level 3, the class of
object is LocalParameter
.
Constructor and Description |
---|
KineticLaw(KineticLaw orig)
Copy constructor creates a copy of this
KineticLaw . |
KineticLaw(long level,
long version)
|
KineticLaw(SBMLNamespaces sbmlns)
|
Modifier and Type | Method and Description |
---|---|
int |
addLocalParameter(LocalParameter p)
Adds a copy of the given
LocalParameter object to the list of local
parameters in this KineticLaw . |
int |
addParameter(Parameter p)
Adds a copy of the given
Parameter object to the list of local
parameters in this KineticLaw . |
KineticLaw |
cloneObject()
Creates and returns a deep copy of this
KineticLaw object. |
boolean |
containsUndeclaredUnits()
Predicate returning
true if
the math expression of this KineticLaw contains
parameters/numbers with undeclared units. |
LocalParameter |
createLocalParameter()
Creates a new
LocalParameter object, adds it to this KineticLaw 's list
of local parameters, and returns the LocalParameter object created. |
Parameter |
createParameter()
Creates a new
Parameter object, adds it to this KineticLaw 's list of
local parameters, and returns the Parameter object created. |
void |
delete()
Explicitly deletes the underlying native object.
|
UnitDefinition |
getDerivedUnitDefinition()
Calculates and returns a
UnitDefinition that expresses the units
of measurement assumed for the 'math' expression of this
KineticLaw . |
SBase |
getElementByMetaId(String metaid)
Returns the first child element it can find with the given
metaid , or null if no such object is found. |
SBase |
getElementBySId(String id)
Returns the first child element found that has the given
id in the model-wide SId namespace, or null if no such object is found. |
String |
getElementName()
Returns the XML element name of this object, which for
Species , is
always 'kineticLaw'. |
String |
getFormula()
Returns the mathematical formula for this
KineticLaw object and return
it as as a text string. |
ListOfLocalParameters |
getListOfLocalParameters()
Returns the list of local parameters in this
KineticLaw object. |
ListOfParameters |
getListOfParameters()
Returns the list of local parameters in this
KineticLaw object. |
LocalParameter |
getLocalParameter(long n)
Returns the nth
LocalParameter object in the list of local parameters in
this KineticLaw instance. |
LocalParameter |
getLocalParameter(String sid)
Returns a local parameter based on its identifier.
|
ASTNode |
getMath()
Returns the mathematical formula for this
KineticLaw object and return
it as as an AST. |
long |
getNumLocalParameters()
Returns the number of local parameters in this
KineticLaw instance. |
long |
getNumParameters()
Returns the number of local parameters in this
KineticLaw instance. |
Parameter |
getParameter(long n)
Returns the nth
Parameter object in the list of local parameters in
this KineticLaw instance. |
Parameter |
getParameter(String sid)
Returns a local parameter based on its identifier.
|
String |
getSubstanceUnits()
(SBML Level 2 Version 1 only) Returns the value of the
'substanceUnits' attribute of this
KineticLaw object. |
String |
getTimeUnits()
(SBML Level 2 Version 1 only) Returns the value of the
'timeUnits' attribute of this
KineticLaw object. |
int |
getTypeCode()
Returns the libSBML type code for this SBML object.
|
boolean |
hasRequiredAttributes()
Predicate returning
true if
all the required attributes for this KineticLaw object
have been set. |
boolean |
hasRequiredElements()
Predicate returning
true if
all the required elements for this KineticLaw object
have been set. |
boolean |
isSetFormula()
Predicate returning
true if this
KineticLaw 's 'formula' attribute is set. |
boolean |
isSetMath()
Predicate returning
true if this
Kinetic's 'math' subelement is set. |
boolean |
isSetSubstanceUnits()
(SBML Level 2 Version 1 only) Predicate returning
true if
this SpeciesReference 's 'substanceUnits' attribute is set. |
boolean |
isSetTimeUnits()
(SBML Level 2 Version 1 only) Predicate returning
true if
this SpeciesReference 's 'timeUnits' attribute is set. |
int |
removeFromParentAndDelete()
Finds this
KineticLaw 's Reaction parent and calls unsetKineticLaw() on it, indirectly deleting itself. |
LocalParameter |
removeLocalParameter(long n)
Removes the nth
LocalParameter object in the list of local parameters
in this KineticLaw instance and returns a pointer to it. |
LocalParameter |
removeLocalParameter(String sid)
Removes a
LocalParameter object with the given identifier in the list of
local parameters in this KineticLaw instance and returns a pointer to it. |
Parameter |
removeParameter(long n)
Removes the nth
Parameter object in the list of local parameters
in this KineticLaw instance and returns a pointer to it. |
Parameter |
removeParameter(String sid)
Removes a
Parameter object with the given identifier in the list of
local parameters in this KineticLaw instance and returns a pointer to it. |
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 |
setFormula(String formula)
Sets the mathematical expression of this
KineticLaw instance to the
given formula . |
int |
setMath(ASTNode math)
Sets the mathematical expression of this
KineticLaw instance to a copy
of the given ASTNode . |
int |
setSubstanceUnits(String sid)
(SBML Level 2 Version 1 only) Sets the 'substanceUnits'
attribute of this
KineticLaw object to a copy of the identifier given
in sid . |
int |
setTimeUnits(String sid)
(SBML Level 2 Version 1 only) Sets the 'timeUnits' attribute
of this
KineticLaw object to a copy of the identifier in sid . |
int |
unsetSubstanceUnits()
(SBML Level 2 Version 1 only) Unsets the 'substanceUnits'
attribute of this
KineticLaw object. |
int |
unsetTimeUnits()
(SBML Level 2 Version 1 only) Unsets the 'timeUnits'
attribugte of this
KineticLaw object. |
addCVTerm, addCVTerm, appendAnnotation, appendAnnotation, appendNotes, appendNotes, disablePackage, enablePackage, equals, getAncestorOfType, getAncestorOfType, getAnnotation, getAnnotationString, getColumn, getCVTerm, getCVTerms, 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 KineticLaw(KineticLaw orig) throws SBMLConstructorException
KineticLaw
.
orig
- the object to copy.
SBMLConstructorException
- Thrown if the argument orig
is null.
public KineticLaw(long level, long version) throws SBMLConstructorException
level
- a long integer, the SBML Level to assign to this KineticLaw
version
- a long integer, the SBML Version to assign to this
KineticLaw
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.
KineticLaw
object to an SBMLDocument
(e.g., using Reaction.setKineticLaw(KineticLaw kl)
), the SBML Level, SBML Version
and XML namespace of the document override the values used
when creating the KineticLaw
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 KineticLaw
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 KineticLaw(SBMLNamespaces sbmlns) throws SBMLConstructorException
KineticLaw
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.
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.
KineticLaw
object to an SBMLDocument
(e.g., using Reaction.setKineticLaw(KineticLaw kl)
), the SBML XML namespace of the
document overrides the value used when creating the KineticLaw
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 KineticLaw
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 int addLocalParameter(LocalParameter p)
LocalParameter
object to the list of local
parameters in this KineticLaw
.
p
- the LocalParameter
to add
KineticLaw.createLocalParameter()
KineticLaw
. Changes made to the original object
instance (such as resetting attribute values) will not affect the
instance in the KineticLaw
. In addition, the caller should make
sure to free the original object if it is no longer being used, or
else a memory leak will result. Please see
KineticLaw.createParameter()
for a method that does not lead to these issues.
public int addParameter(Parameter p)
Parameter
object to the list of local
parameters in this KineticLaw
.
p
- the Parameter
to add
KineticLaw.createParameter()
KineticLaw
. Changes made to the original object
instance (such as resetting attribute values) will not affect the
instance in the KineticLaw
. In addition, the caller should make
sure to free the original object if it is no longer being used, or
else a memory leak will result. Please see
KineticLaw.createParameter()
for a method that does not lead to these issues.
public KineticLaw cloneObject()
KineticLaw
object.
cloneObject
 in class SBase
KineticLaw
.public boolean containsUndeclaredUnits()
true
if
the math expression of this KineticLaw
contains
parameters/numbers with undeclared units.
true
if the math expression of this KineticLaw
includes parameters/numbers
with undeclared units, false
otherwise.
KineticLaw.getDerivedUnitDefinition()
true
indicates that the UnitDefinition
returned by
KineticLaw.getDerivedUnitDefinition()
may not accurately represent the units of the expression.
public LocalParameter createLocalParameter()
LocalParameter
object, adds it to this KineticLaw
's list
of local parameters, and returns the LocalParameter
object created.
LocalParameter
object instance
KineticLaw.addLocalParameter(LocalParameter p)
public Parameter createParameter()
Parameter
object, adds it to this KineticLaw
's list of
local parameters, and returns the Parameter
object created.
Parameter
object instance
KineticLaw.addParameter(Parameter p)
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 KineticLaw.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 KineticLaw.delete()
themselves.
public UnitDefinition getDerivedUnitDefinition()
UnitDefinition
that expresses the units
of measurement assumed for the 'math' expression of this
KineticLaw
.
The units are calculated based on the mathematical expression in the
KineticLaw
and the model quantities referenced by
<ci>
elements used within that expression. The
KineticLaw.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
expression of this KineticLaw
, or null
if one cannot be constructed.
KineticLaw.containsUndeclaredUnits()
KineticLaw
contains pure 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
KineticLaw.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. It is important that callers also
invoke the method
KineticLaw.containsUndeclaredUnits()
to determine whether this situation holds. Callers may
wish to take suitable actions in those scenarios.
public SBase getElementByMetaId(String metaid)
metaid
, or null
if no such object is found.
getElementByMetaId
 in class SBase
metaid
- string representing the metaid of objects to find
metaid
.public SBase getElementBySId(String id)
id
in the model-wide SId namespace, or null
if no such object is found.
getElementBySId
 in class SBase
id
- string representing the id of objects to find.
id
.public String getElementName()
Species
, is
always 'kineticLaw'.
getElementName
 in class SBase
'kineticLaw'.
public String getFormula()
KineticLaw
object and return
it as as a text string.
This is fundamentally equivalent to
KineticLaw.getMath()
.
This variant is provided principally for compatibility compatibility
with SBML Level 1.
KineticLaw
.
KineticLaw.getMath()
public ListOfLocalParameters getListOfLocalParameters()
KineticLaw
object.
KineticLaw
.public ListOfParameters getListOfParameters()
KineticLaw
object.
KineticLaw
.public LocalParameter getLocalParameter(long n)
LocalParameter
object in the list of local parameters in
this KineticLaw
instance.
n
- the index of the LocalParameter
object sought
LocalParameter
of this KineticLaw
.public LocalParameter getLocalParameter(String sid)
sid
- the identifier of the LocalParameter
being sought.
LocalParameter
object in this KineticLaw
instace having the
given 'id', or null
if no such LocalParameter
exists.public ASTNode getMath()
KineticLaw
object and return
it as as an AST.
This is fundamentally equivalent to
KineticLaw.getFormula()
.
The latter is provided principally for compatibility compatibility
with SBML Level 1, which represented mathematical formulas in
text-string form.
ASTNode
representation of the mathematical formula.
KineticLaw.getFormula()
public long getNumLocalParameters()
KineticLaw
instance.
KineticLaw
.public long getNumParameters()
KineticLaw
instance.
KineticLaw
.public Parameter getParameter(long n)
Parameter
object in the list of local parameters in
this KineticLaw
instance.
n
- the index of the Parameter
object sought
Parameter
of this KineticLaw
.public Parameter getParameter(String sid)
sid
- the identifier of the Parameter
being sought.
Parameter
object in this KineticLaw
instace having the
given 'id', or null
if no such Parameter
exists.public String getSubstanceUnits()
KineticLaw
object.
public String getTimeUnits()
KineticLaw
object.
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).
KineticLaw.getElementName()
public boolean hasRequiredAttributes()
true
if
all the required attributes for this KineticLaw
object
have been set.
hasRequiredAttributes
 in class SBase
KineticLaw
object are:
public boolean hasRequiredElements()
true
if
all the required elements for this KineticLaw
object
have been set.
hasRequiredElements
 in class SBase
KineticLaw
object are:
public boolean isSetFormula()
true
if this
KineticLaw
's 'formula' attribute is set.
This is functionally identical to the method
KineticLaw.isSetMath()
. It is
provided in order to mirror the parallel between
KineticLaw.getFormula()
and
KineticLaw.getMath()
.
true
if the formula (meaning the math
subelement) of
this KineticLaw
is set, false
otherwise.
KineticLaw.isSetMath()
public boolean isSetMath()
true
if this
Kinetic's 'math' subelement is set.
This is identical to the method
KineticLaw.isSetFormula()
.
It is provided in order to mirror the parallel between
KineticLaw.getFormula()
and
KineticLaw.getMath()
.
true
if the formula (meaning the math
subelement) of
this KineticLaw
is set, false
otherwise.
KineticLaw.isSetFormula()
public boolean isSetSubstanceUnits()
true
if
this SpeciesReference
's 'substanceUnits' attribute is set.
true
if the 'substanceUnits' attribute of this KineticLaw
object is set, false
otherwise.
public boolean isSetTimeUnits()
true
if
this SpeciesReference
's 'timeUnits' attribute is set.
true
if the 'timeUnits' attribute of this KineticLaw
object
is set, false
otherwise.
public int removeFromParentAndDelete()
KineticLaw
's Reaction
parent and calls unsetKineticLaw() on it, indirectly deleting itself. Overridden from the SBase
function since the parent is not a ListOf
.
removeFromParentAndDelete
 in class SBase
public LocalParameter removeLocalParameter(long n)
LocalParameter
object in the list of local parameters
in this KineticLaw
instance and returns a pointer to it.
The caller owns the returned object and is responsible for deleting it.
n
- the index of the LocalParameter
object to remove
LocalParameter
object removed. As mentioned above,
the caller owns the returned item. null
is returned if the given index
is out of range.public LocalParameter removeLocalParameter(String sid)
LocalParameter
object with the given identifier in the list of
local parameters in this KineticLaw
instance and returns a pointer to it.
The caller owns the returned object and is responsible for deleting it.
sid
- the identifier of the LocalParameter
to remove
LocalParameter
object removed. As mentioned above, the
caller owns the returned object. null
is returned if no LocalParameter
object with the identifier exists in this KineticLaw
instance.public Parameter removeParameter(long n)
Parameter
object in the list of local parameters
in this KineticLaw
instance and returns a pointer to it.
The caller owns the returned object and is responsible for deleting it.
public Parameter removeParameter(String sid)
Parameter
object with the given identifier in the list of
local parameters in this KineticLaw
instance and returns a pointer to it.
The caller owns the returned object and is responsible for deleting it.
sid
- the identifier of the Parameter
to remove
Parameter
object removed. As mentioned above, the
caller owns the returned object. null
is returned if no Parameter
object with the identifier exists in this KineticLaw
instance.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 setFormula(String formula)
KineticLaw
instance to the
given formula
.
The given formula
string is copied. Internally, libSBML stores the
mathematical expression as an ASTNode
.
formula
- the mathematical expression to use, represented in
text-string form.
KineticLaw.setMath(ASTNode math)
public int setMath(ASTNode math)
KineticLaw
instance to a copy
of the given ASTNode
.
This is fundamentally identical to
KineticLaw.setFormula(String formula)
.
The latter is provided principally for compatibility compatibility with
SBML Level 1, which represented mathematical formulas in text-string
form.
math
- an ASTNode
representing a formula tree.
KineticLaw.setFormula(String formula)
public int setSubstanceUnits(String sid)
KineticLaw
object to a copy of the identifier given
in sid
.
sid
- the identifier of the units to use.
public int setTimeUnits(String sid)
KineticLaw
object to a copy of the identifier in sid
.
sid
- the identifier of the units to use.
public int unsetSubstanceUnits()
KineticLaw
object.
public int unsetTimeUnits()
KineticLaw
object.