public class Rule extends SBase
In SBML, rules provide additional ways to define the values of
variables in a model, their relationships, and the dynamical behaviors
of those variables. They enable encoding relationships that cannot be
expressed using Reaction
nor InitialAssignment
objects alone.
The libSBML implementation of rules mirrors the SBML Level 3
Version 1 Core definition (which is in turn is very similar to the
Level 2 Version 4 definition), with Rule
being the parent
class of three subclasses as explained below. The Rule
class itself
cannot be instantiated by user programs and has no constructor only the
subclasses AssignmentRule
, AlgebraicRule
and RateRule
can be
instantiated directly.
In SBML Level 3 as well as Level 2, rules are separated into three subclasses for the benefit of model analysis software. The three subclasses are based on the following three different possible functional forms (where x is a variable, f is some arbitrary function returning a numerical result, V is a vector of variables that does not include x, and W is a vector of variables that may include x):
Algebraic: | left-hand side is zero | 0 = f(W) |
Assignment: | left-hand side is a scalar: | x = f(V) |
Rate: | left-hand side is a rate-of-change: | dx/dt = f(W) |
In their general form given above, there is little to distinguish between assignment and algebraic rules. They are treated as separate cases for the following reasons:
InitialAssignment
.)
The approach taken to covering these cases in SBML is to define an
abstract Rule
structure containing a subelement, 'math', to hold the
right-hand side expression, then to derive subtypes of Rule
that add
attributes to distinguish the cases of algebraic, assignment and rate
rules. The 'math' subelement must contain a MathML expression defining the
mathematical formula of the rule. This MathML formula must return a
numerical value. The formula can be an arbitrary expression referencing
the variables and other entities in an SBML model.
Each of the three subclasses of Rule
(AssignmentRule, AlgebraicRule
,
RateRule
) inherit the the 'math' subelement and other fields from SBase
.
The AssignmentRule
and RateRule
classes add an additional attribute,
'variable'. See the definitions of AssignmentRule
, AlgebraicRule
and
RateRule
for details about the structure and interpretation of each one.
An important design goal of SBML rule semantics is to ensure that a model's simulation and analysis results will not be dependent on when or how often rules are evaluated. To achieve this, SBML needs to place two restrictions on rule use. The first concerns algebraic loops in the system of assignments in a model, and the second concerns overdetermined systems.
The combined set of InitialAssignment
, AssignmentRule
and KineticLaw
objects in a model constitute a set of assignment statements that should be
considered as a whole. (A KineticLaw
object is counted as an assignment
because it assigns a value to the symbol contained in the 'id' attribute of
the Reaction
object in which it is defined.) This combined set of
assignment statements must not contain algebraic loops&mdashdependency
chains between these statements must terminate. To put this more formally,
consider a directed graph in which nodes are assignment statements and
directed arcs exist for each occurrence of an SBML species, compartment or
parameter symbol in an assignment statement's 'math' subelement. Let the
directed arcs point from the statement assigning the symbol to the
statements that contain the symbol in their 'math' subelement expressions.
This graph must be acyclic.
SBML does not specify when or how often rules should be evaluated. Eliminating algebraic loops ensures that assignment statements can be evaluated any number of times without the result of those evaluations changing. As an example, consider the set of equations x = x + 1, y = z + 200 and z = y + 100. If this set of equations were interpreted as a set of assignment statements, it would be invalid because the rule for x refers to x (exhibiting one type of loop), and the rule for y refers to z while the rule for z refers back to y (exhibiting another type of loop). Conversely, the following set of equations would constitute a valid set of assignment statements: x = 10, y = z + 200, and z = x + 100.
An SBML model must not be overdetermined that is, a model must not
define more equations than there are unknowns in a model. An SBML model
that does not contain AlgebraicRule
structures cannot be overdetermined.
LibSBML implements the static analysis procedure described in Appendix B of the SBML Level 3 Version 1 Core specification for assessing whether a model is overdetermined.
(In summary, assessing whether a given continuous, deterministic, mathematical model is overdetermined does not require dynamic analysis it can be done by analyzing the system of equations created from the model. One approach is to construct a bipartite graph in which one set of vertices represents the variables and the other the set of vertices represents the equations. Place edges between vertices such that variables in the system are linked to the equations that determine them. For algebraic equations, there will be edges between the equation and each variable occurring in the equation. For ordinary differential equations (such as those defined by rate rules or implied by the reaction rate definitions), there will be a single edge between the equation and the variable determined by that differential equation. A mathematical model is overdetermined if the maximal matchings of the bipartite graph contain disconnected vertexes representing equations. If one maximal matching has this property, then all the maximal matchings will have this property i.e., it is only necessary to find one maximal matching.)
SBML Level 1 uses a different scheme than SBML Level 2 and Level 3 for distinguishing rules specifically, it uses an attribute whose value is drawn from an enumeration of 3 values. LibSBML supports this using methods that work with the enumeration values listed below.
RULE_TYPE_RATE
: Indicates
the rule is a 'rate' rule.
RULE_TYPE_SCALAR
:
Indicates the rule is a 'scalar' rule.
RULE_TYPE_INVALID
:
Indicates the rule type is unknown or not yet set.
Constructor and Description |
---|
Rule(Rule orig)
Copy constructor creates a copy of this
Rule . |
Modifier and Type | Method and Description |
---|---|
Rule |
cloneObject()
Creates and returns a deep copy of this
Rule object. |
boolean |
containsUndeclaredUnits()
Predicate returning
true if the math expression of this Rule contains
parameters/numbers with undeclared units. |
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 Rule . |
java.lang.String |
getElementName()
Returns the XML element name of this object.
|
java.lang.String |
getFormula()
Returns the mathematical expression of this
Rule in text-string form. |
int |
getL1TypeCode()
Returns the SBML Level 1 type code for this
Rule object. |
ASTNode |
getMath()
|
int |
getType()
Returns a code representing the type of rule this is.
|
int |
getTypeCode()
Returns the libSBML type code for this SBML object.
|
java.lang.String |
getUnits()
Returns the units for the
mathematical formula of this
Rule . |
java.lang.String |
getVariable()
Get the value of the 'variable' attribute of this
Rule object. |
boolean |
hasRequiredAttributes()
Predicate returning
true if all the required attributes for this Rule
object have been set. |
boolean |
hasRequiredElements()
Predicate returning
true if all the required elements for this Rule
object have been set. |
boolean |
isAlgebraic()
|
boolean |
isAssignment()
|
boolean |
isCompartmentVolume()
Predicate returning
true if this Rule is an CompartmentVolumeRule
or equivalent. |
boolean |
isParameter()
Predicate returning
true if this Rule is an ParameterRule or
equivalent. |
boolean |
isRate()
|
boolean |
isScalar()
Predicate returning
true if this Rule is an AssignmentRule (SBML
Levels 2&ndash3) or has a 'type' attribute value of 'scalar'
(SBML Level 1). |
boolean |
isSetFormula()
Predicate returning
true if this Rule 's mathematical expression is
set. |
boolean |
isSetMath()
Predicate returning
true if this Rule 's mathematical expression is
set. |
boolean |
isSetUnits()
Predicate returning
true if this Rule 's 'units' attribute is set. |
boolean |
isSetVariable()
Predicate returning
true if this Rule 's 'variable' attribute is set. |
boolean |
isSpeciesConcentration()
Predicate returning
true if this Rule is a SpeciesConcentrationRule
or equivalent. |
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 |
setFormula(java.lang.String formula)
Sets the 'math' subelement of this
Rule to an expression in text-string
form. |
int |
setL1TypeCode(int type)
Sets the SBML Level 1 type code for this
Rule . |
int |
setMath(ASTNode math)
|
int |
setUnits(java.lang.String sname)
Sets the units for this
Rule . |
int |
setVariable(java.lang.String sid)
Sets the 'variable' attribute value of this
Rule object. |
int |
unsetUnits()
Unsets the 'units' for this
Rule . |
int |
unsetVariable()
Unsets the value of the 'variable' attribute of this
Rule object. |
addCVTerm, addCVTerm, appendAnnotation, appendAnnotation, appendNotes, appendNotes, connectToChild, deleteDisabledPlugins, deleteDisabledPlugins, disablePackage, enablePackage, equals, getAncestorOfType, getAncestorOfType, getAnnotation, getAnnotationString, getColumn, getCVTerm, getCVTerms, getDisabledPlugin, getElementByMetaId, getElementBySId, getLevel, getLine, getListOfAllElements, getListOfAllElements, getListOfAllElementsFromPlugins, getListOfAllElementsFromPlugins, getMetaId, getModel, getModelHistory, getNamespaces, getNotes, getNotesString, getNumCVTerms, getNumDisabledPlugins, getNumPlugins, getPackageName, getPackageVersion, getParentSBMLObject, getPlugin, getPlugin, getPrefix, getResourceBiologicalQualifier, getResourceModelQualifier, getSBMLDocument, getSBOTerm, getSBOTermAsURL, getSBOTermID, getURI, getVersion, hashCode, hasValidLevelVersionNamespaceCombination, isPackageEnabled, isPackageURIEnabled, isPkgEnabled, isPkgURIEnabled, isSetAnnotation, isSetMetaId, isSetModelHistory, isSetNotes, isSetSBOTerm, isSetUserData, matchesRequiredSBMLNamespacesForAddition, matchesSBMLNamespaces, removeFromParentAndDelete, removeTopLevelAnnotationElement, removeTopLevelAnnotationElement, removeTopLevelAnnotationElement, renameMetaIdRefs, replaceTopLevelAnnotationElement, replaceTopLevelAnnotationElement, setAnnotation, setAnnotation, setMetaId, setModelHistory, setNamespaces, setNotes, setNotes, setNotes, setSBOTerm, setSBOTerm, toSBML, toXMLNode, unsetAnnotation, unsetCVTerms, unsetId, unsetMetaId, unsetModelHistory, unsetName, unsetNotes, unsetSBOTerm, unsetUserData
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 Rule.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 Rule.delete()
themselves.
public Rule cloneObject()
Rule
object.
cloneObject
 in class SBase
Rule
object.public java.lang.String getFormula()
Rule
in text-string form.
The text string is produced by
libsbml.formulaToString()
please consult
the documentation for that function to find out more about the format
of the text-string formula.
Rule
.
Rule.getMath()
public ASTNode getMath()
ASTNode
, the value of the 'math' subelement of this Rule
.
Rule.getFormula()
public java.lang.String getVariable()
Rule
object.
In SBML Level 1, the different rule types each have a different
name for the attribute holding the reference to the object constituting
the left-hand side of the rule. (E.g., for SBML Level 1's
SpeciesConcentrationRule the attribute is 'species', for
CompartmentVolumeRule it is 'compartment', etc.) In SBML Levels 2
and 3, the only two types of Rule
objects with a left-hand side
object reference are AssignmentRule
and RateRule
, and both of them use the
same name for attribute: 'variable'. In order to make it easier for
application developers to work with all Levels of SBML, libSBML uses a
uniform name for all such attributes, and it is 'variable', regardless of
whether Level 1 rules or Level 2&ndash3 rules are being used.
Rule
, or null
if this object is an AlgebraicRule
object.public java.lang.String getUnits()
Rule
.
Rule
.
public boolean isSetFormula()
true
if this Rule
's mathematical expression is
set.
This method is equivalent to isSetMath(). This version is present for easier compatibility with SBML Level 1, in which mathematical formulas were written in text-string form.
true
if the mathematical formula for this Rule
is
set, false
otherwise.
Rule.isSetMath()
public boolean isSetMath()
true
if this Rule
's mathematical expression is
set.
This method is equivalent to isSetFormula().
true
if the formula (or equivalently the math) for this
Rule
is set, false
otherwise.
Rule.isSetFormula()
public boolean isSetVariable()
true
if this Rule
's 'variable' attribute is set.
In SBML Level 1, the different rule types each have a different
name for the attribute holding the reference to the object constituting
the left-hand side of the rule. (E.g., for SBML Level 1's
SpeciesConcentrationRule the attribute is 'species', for
CompartmentVolumeRule it is 'compartment', etc.) In SBML Levels 2
and 3, the only two types of Rule
objects with a left-hand side
object reference are AssignmentRule
and RateRule
, and both of them use the
same name for attribute: 'variable'. In order to make it easier for
application developers to work with all Levels of SBML, libSBML uses a
uniform name for all such attributes, and it is 'variable', regardless of
whether Level 1 rules or Level 2&ndash3 rules are being used.
true
if the 'variable' attribute value of this Rule
is
set, false
otherwise.public boolean isSetUnits()
true
if this Rule
's 'units' attribute is set.
true
if the units for this Rule
is set, false
otherwise
public int setFormula(java.lang.String formula)
Rule
to an expression in text-string
form.
This is equivalent to setMath(ASTNode math). The provision of
using text-string formulas is retained for easier SBML Level 1
compatibility. The formula is converted to an ASTNode
internally.
formula
- a mathematical formula in text-string form.
Rule.setMath(ASTNode math)
public int setMath(ASTNode math)
math
- the AST structure of the mathematical formula.
Rule.setFormula(String formula)
public int setVariable(java.lang.String sid)
Rule
object.
In SBML Level 1, the different rule types each have a different
name for the attribute holding the reference to the object constituting
the left-hand side of the rule. (E.g., for SBML Level 1's
SpeciesConcentrationRule the attribute is 'species', for
CompartmentVolumeRule it is 'compartment', etc.) In SBML Levels 2
and 3, the only two types of Rule
objects with a left-hand side
object reference are AssignmentRule
and RateRule
, and both of them use the
same name for attribute: 'variable'. In order to make it easier for
application developers to work with all Levels of SBML, libSBML uses a
uniform name for all such attributes, and it is 'variable', regardless of
whether Level 1 rules or Level 2&ndash3 rules are being used.
sid
- the identifier of a Compartment
, Species
or Parameter
elsewhere in the enclosing Model
object.
public int setUnits(java.lang.String sname)
Rule
.
sname
- the identifier of the units
public int unsetVariable()
Rule
object.
Rule.setVariable(String sid)
,
Rule.isSetVariable()
,
Rule.getVariable()
public int unsetUnits()
Rule
.
public UnitDefinition getDerivedUnitDefinition()
UnitDefinition
that expresses the units of
measurement assumed for the 'math' expression of this Rule
.
The units are calculated based on the mathematical expression in the
Rule
and the model quantities referenced by <ci>
elements used within that expression. The method
Rule.getDerivedUnitDefinition()
returns the calculated units, to the
extent that libSBML can compute them.
getDerivedUnitDefinition
 in class SBase
UnitDefinition
that expresses the units of the math
expression of this Rule
, or null
if one cannot be constructed.
Rule.containsUndeclaredUnits()
null.
Rule
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 Rule.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
Rule.containsUndeclaredUnits()
to determine whether this
situation holds. Callers may wish to take suitable actions in
those scenarios.
public boolean containsUndeclaredUnits()
true
if the math expression of this Rule
contains
parameters/numbers with undeclared units.
containsUndeclaredUnits
 in class SBase
true
if the math expression of this Rule
includes
parameters/numbers with undeclared units, false
otherwise.
Rule.getDerivedUnitDefinition()
true
indicates that the UnitDefinition
returned by getDerivedUnitDefinition() may not accurately represent
the units of the expression.
public int getType()
public boolean isAlgebraic()
true
if this Rule
is an AlgebraicRule
, false
otherwise.public boolean isAssignment()
true
if this Rule
is an AssignmentRule
, false
otherwise.public boolean isCompartmentVolume()
true
if this Rule
is an CompartmentVolumeRule
or equivalent.
This libSBML method works for SBML Level 1 models (where there is
such a thing as an explicit CompartmentVolumeRule), as well as other Levels of
SBML. For Levels above Level 1, this method checks the symbol
being affected by the rule, and returns true
if the symbol is the
identifier of a Compartment
object defined in the model.
true
if this Rule
is a CompartmentVolumeRule, false
otherwise.public boolean isParameter()
true
if this Rule
is an ParameterRule or
equivalent.
This libSBML method works for SBML Level 1 models (where there is
such a thing as an explicit ParameterRule), as well as other Levels of
SBML. For Levels above Level 1, this method checks the symbol
being affected by the rule, and returns true
if the symbol is the
identifier of a Parameter
object defined in the model.
true
if this Rule
is a ParameterRule, false
otherwise.public boolean isRate()
public boolean isScalar()
true
if this Rule
is an AssignmentRule
(SBML
Levels 2&ndash3) or has a 'type' attribute value of 'scalar'
(SBML Level 1).
true
if this Rule
is an AssignmentRule
(Level 2) or has
type 'scalar' (Level 1), false
otherwise.public boolean isSpeciesConcentration()
true
if this Rule
is a SpeciesConcentrationRule
or equivalent.
This libSBML method works for SBML Level 1 models (where there is
such a thing as an explicit SpeciesConcentrationRule), as well as
other Levels of SBML. For Levels above Level 1, this method
checks the symbol being affected by the rule, and returns true
if
the symbol is the identifier of a Species
object defined in the model.
true
if this Rule
is a SpeciesConcentrationRule, false
otherwise.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 getPackageName()
method on the object.
getTypeCode
 in class SBase
SBML_ASSIGNMENT_RULE
,
SBML_RATE_RULE
, or
SBML_ALGEBRAIC_RULE
for SBML Core.
Rule.getElementName()
,
SBase.getPackageName()
public int getL1TypeCode()
Rule
object.
This method only applies to SBML Level 1 model objects. If this is
not an SBML Level 1 rule object, this method will return
SBML_UNKNOWN
.
Rule
(namely,
SBML_COMPARTMENT_VOLUME_RULE
,
SBML_PARAMETER_RULE
,
SBML_SPECIES_CONCENTRATION_RULE
, or
SBML_UNKNOWN
).public java.lang.String getElementName()
The returned value can be any of a number of different strings,
depending on the SBML Level in use and the kind of Rule
object this
is. The rules as of libSBML version 5.13.0
are the following:
'rateRule'
'assignmentRule'
'algebraicRule'
'specieConcentrationRule'
'speciesConcentrationRule'
'compartmentVolumeRule'
'parameterRule'
'unknownRule'
Beware that the last ('unknownRule'
) is not a valid SBML element
name.
getElementName
 in class SBase
public int setL1TypeCode(int type)
Rule
.
type
- the SBML Level 1 type code for this Rule
. The allowable
values are SBML_COMPARTMENT_VOLUME_RULE
,
SBML_PARAMETER_RULE
, and
SBML_SPECIES_CONCENTRATION_RULE
.
LIBSBML_OPERATION_SUCCESS
LIBSBML_INVALID_ATTRIBUTE_VALUE
if given type
value is not one of the above.
public boolean hasRequiredElements()
true
if all the required elements for this Rule
object have been set.
The only required element for a Rule
object is the 'math' subelement.
hasRequiredElements
 in class SBase
public boolean hasRequiredAttributes()
true
if all the required attributes for this Rule
object have been set.
The required attributes for a Rule
object depend on the type of Rule
it is. For AssignmentRule
and RateRule
objects (and SBML
Level 1's SpeciesConcentrationRule, CompartmentVolumeRule, and
ParameterRule objects), the required attribute is 'variable' for
AlgebraicRule
objects, there is no required attribute.
hasRequiredAttributes
 in class SBase
true
if the required attributes have been set, false
otherwise.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 identifiernewid
- the new identifierpublic 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 identifiernewid
- the new identifier