public class EventAssignment extends SBase
Event
contains an optional element called 'listOfEventAssignments', of
class ListOfEventAssignments
. In every instance of an event definition
in a model, the object's 'listOfEventAssignments' element must have a
non-empty list of one or more 'eventAssignment' elements of class
EventAssignment
. The object class EventAssignment
has one required
attribute, 'variable', and a required element, 'math'. Being derived
from SBase
, it also has all the usual attributes and elements of its
parent class.
An Event
object defines when the event can occur, the variables that are
affected by the event, and how the variables are affected. The purpose
of the EventAssignment
object class is to define how variables are
affected by an Event
. In SBML Level 2, every Event
object instance
must have a nonempty list of event assignments in SBML Level 3,
the list of assignments is optional.
The operation of an Event
is divided into two phases (regardless of
whether a delay is involved): one phase when the event is triggered,
and the other when the event is executed. EventAssignment
objects
are interpreted when an event is executed. The effects are described
below.
The EventAssignment
attribute 'variable' must be the identifier of an
existing Compartment
, Species
, SpeciesReference
, or Parameter
instance defined in the model. When the event is executed, the value of
the model component identified by 'variable' is changed by the
EventAssignment
to the value computed by the 'math' element that is, a
species' quantity, species reference's stoichiometry, compartment's size
or parameter's value are reset to the value computed by 'math'.
Certain restrictions are placed on what can appear in 'variable':
EventAssignment
attribute
'variable' must not have its 'constant' attribute set to or default to
true.
(Constants cannot be affected by events.)
Event
.
EventAssignment
structures within a given Event
structure. In other
words, a single event cannot have multiple EventAssignment
objects
assigning the same variable. (All of them would be performed at the
same time when that particular Event
triggers, resulting in
indeterminacy.) However, separate Event
instances can refer to the
same variable.
EventAssignment
object
instance and also be assigned a value by an AssignmentRule
i.e., the
value of an EventAssignment
's 'variable' attribute cannot be the same as
the value of a AssignmentRule
' 'variable' attribute. (Assignment rules
hold at all times, therefore it would be inconsistent to also define an
event that reassigns the value of the same variable.)
Note that the time of assignment of the object identified by the
value of the 'variable' attribute is always the time at which the Event
is executed, not when it is triggered. The timing is
controlled by the optional Delay
in an Event
. The time of
assignment is not affected by the 'useValuesFromTriggerTime'
attribute on Event
&mdashthat attribute affects the time at which the
EventAssignment
's 'math' expression is evaluated. In other
words, SBML allows decoupling the time at which the
'variable' is assigned from the time at which its value
expression is calculated.
EventAssignment
The MathML expression contained in an EventAssignment
defines the new
value of the variable being assigned by the Event
.
As mentioned above, the time at which the expression in 'math' is
evaluated is determined by the attribute 'useValuesFromTriggerTime' on
Event
. If the attribute value is true
, the expression must be
evaluated when the event is triggered more precisely, the values of
identifiers occurring in MathML <ci>
elements in the
EventAssignment
's 'math' expression are the values they have at the
point when the event triggered. If, instead,
'useValuesFromTriggerTime''s value is false
, it means the values at
execution time should be used that is, the values of identifiers
occurring in MathML <ci>
elements in the
EventAssignment
's 'math' expression are the values they have at the
point when the event executed.
Between Version 4 and previous versions of SBML Level 2, the requirements regarding the matching of units between an EvengAssignment's formula and the units of the object identified by the 'variable' attribute changed. Previous versions required consistency, but in SBML Level 2 Version 4 and in SBML Level 3, unit consistency is only recommended. More precisely:
EventAssignment
sets the referenced
species' quantity (concentration or amount of substance) to the value
determined by the formula in the EventAssignment
's 'math' subelement.
The units of the 'math' formula should (in SBML Level 2
Version 4 and in Level 3) or must (in previous Versions of
Level 2) be identical to the units of the species.
EventAssignment
sets the stoichiometry of the reactant or product
referenced by the SpeciesReference
object to the value determined by the
formula in the 'math' element. The unit associated with the value
produced by the 'math' formula should be dimensionless
, because
reactant and product stoichiometries in reactions are dimensionless
quantities.
EventAssignment
sets the
referenced compartment's size to the size determined by the formula in
the 'math' subelement of the EventAssignment
. The overall units of the
formula should (in SBML Level 2 Version 4 and in Level 3)
or must (in previous Versions of Level 2) be identical to the units
specified for the size of the compartment identified by the
EventAssignment
's 'variable' attribute.
EventAssignment
sets the referenced
parameter's value to that determined by the formula in 'math'. The
overall units of the formula should (in SBML Level 2 Version 4
and Level 3) or must (in previous Versions of Level 2) be
identical to the units defined for the parameter.
Note that the formula placed in the 'math' element has no assumed
units. The consistency of the units of the formula, and the units
of the entity which the assignment affects, must be explicitly
established just as in the case of the value of the Delay
subelement.
An approach similar to the one discussed in the context of Delay
may be
used for the formula of an EventAssignment
.
Event
Constructor and Description |
---|
EventAssignment(EventAssignment orig)
Copy constructor creates a copy of this
EventAssignment . |
EventAssignment(long level,
long version)
|
EventAssignment(SBMLNamespaces sbmlns)
|
Modifier and Type | Method and Description |
---|---|
EventAssignment |
cloneObject()
Creates and returns a deep copy of this
EventAssignment object. |
boolean |
containsUndeclaredUnits()
Predicate returning
true if the math expression of this
EventAssignment contains literal numbers or parameters 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 EventAssignment . |
String |
getElementName()
Returns the XML element name of this object, which for
EventAssignment , is always 'eventAssignment'. |
ASTNode |
getMath()
Get the mathematical expression in this
EventAssignment 's 'math'
subelement. |
int |
getTypeCode()
Returns the libSBML type code of this object instance.
|
String |
getVariable()
Get the value of this
EventAssignment 's 'variable' attribute. |
boolean |
hasRequiredAttributes()
Predicate returning
true if all the required attributes for this
EventAssignment object have been set. |
boolean |
hasRequiredElements()
Predicate returning
true if all the required elements for this
EventAssignment object have been set. |
boolean |
isSetMath()
Predicate for testing whether the 'math' subelement of this
EventAssignment is set. |
boolean |
isSetVariable()
Predicate for testing whether the attribute 'variable' of this
EventAssignment is set. |
void |
renameSIdRefs(String oldid,
String newid)
Replaces all uses of a given
SIdRef type attribute value with another
value. |
void |
renameUnitSIdRefs(String oldid,
String newid)
Replaces all uses of a given
UnitSIdRef type attribute value with
another value. |
int |
setMath(ASTNode math)
Sets the 'math' subelement of this
EventAssignment to a copy of the
given ASTNode . |
int |
setVariable(String sid)
Sets the attribute 'variable' of this
EventAssignment to a copy of
the given identifier string. |
int |
unsetVariable()
Unsets the attribute 'variable' of this
EventAssignment . |
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 EventAssignment(long level, long version) throws SBMLConstructorException
level
- a long integer, the SBML Level to assign to this EventAssignment
version
- a long integer, the SBML Version to assign to this
EventAssignment
SBMLConstructorException
- Thrown if the given level
and version
combination are invalid
or if this object is incompatible with the given level and version.
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 EventAssignment(SBMLNamespaces sbmlns) throws SBMLConstructorException
EventAssignment
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.
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 EventAssignment(EventAssignment orig) throws SBMLConstructorException
EventAssignment
.
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 EventAssignment.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 EventAssignment.delete()
themselves.
public EventAssignment cloneObject()
EventAssignment
object.
cloneObject
 in class SBase
EventAssignment
object.public String getVariable()
EventAssignment
's 'variable' attribute.
EventAssignment
.public ASTNode getMath()
EventAssignment
's 'math'
subelement.
ASTNode
of an abstract syntax tree representing the
mathematical formula in this EventAssignment
.public boolean isSetVariable()
EventAssignment
is set.
true
if the 'variable' attribute of this EventAssignment
is set, false
otherwise.public boolean isSetMath()
EventAssignment
is set.
true
if this EventAssignment
has a 'math' subelement,
false
otherwise.public int setVariable(String sid)
EventAssignment
to a copy of
the given identifier string.
sid
- the identifier of a Compartment
, Species
or (global)
Parameter
defined in this model.
public int unsetVariable()
EventAssignment
.
public int setMath(ASTNode math)
EventAssignment
to a copy of the
given ASTNode
.
math
- an ASTNode
that will be copied and stored as the
mathematical formula for this EventAssignment
.
public UnitDefinition getDerivedUnitDefinition()
UnitDefinition
that expresses the units of
measurement assumed for the 'math' expression of this EventAssignment
.
The units are calculated based on the mathematical expression in the
EventAssignment
and the model quantities referenced by
<ci>
elements used within that expression. The method
EventAssignment.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 EventAssignment
, or null
if one cannot be constructed.
EventAssignment.containsUndeclaredUnits()
null.
EventAssignment
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
EventAssignment.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
EventAssignment.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
EventAssignment
contains literal numbers or parameters with undeclared
units.
The units are calculated based on the mathematical expression in the
EventAssignment
and the model quantities referenced by
<ci>
elements used within that expression. The method
EventAssignment.getDerivedUnitDefinition()
returns the calculated units,
to the extent that libSBML can compute them.
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 EventAssignment.containsUndeclaredUnits()
when using
EventAssignment.getDerivedUnitDefinition()
to decide whether the
returned units may be incomplete.
containsUndeclaredUnits
 in class SBase
true
if the math expression of this EventAssignment
includes parameters/numbers
with undeclared units, false
otherwise.
EventAssignment.getDerivedUnitDefinition()
true
indicates that the UnitDefinition
returned by EventAssignment.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 getPackageName()
method on the object.
getTypeCode
 in class SBase
SBML_EVENT_ASSIGNMENT
(default).
EventAssignment.getElementName()
,
SBase.getPackageName()
public String getElementName()
EventAssignment
, is always 'eventAssignment'.
getElementName
 in class SBase
'eventAssignment'.
public boolean hasRequiredAttributes()
true
if all the required attributes for this
EventAssignment
object have been set.
The required attributes for a EventAssignment
object are:
hasRequiredAttributes
 in class SBase
true
if the required attributes have been set, false
otherwise.public boolean hasRequiredElements()
true
if all the required elements for this
EventAssignment
object have been set.
hasRequiredElements
 in class SBase
EventAssignment
object are:
public void renameSIdRefs(String oldid, 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(String oldid, 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