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 Eventmdashthat 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
.
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 . |
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)
Renames all the SIdRef attributes on this element, including any found in MathML
|
void |
renameUnitSIdRefs(String oldid,
String newid)
Renames all the UnitSIdRef attributes on this element
|
int |
setMath(ASTNode math)
Sets the 'math' 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. |
addCVTerm, addCVTerm, appendAnnotation, appendAnnotation, appendNotes, appendNotes, disablePackage, enablePackage, equals, getAncestorOfType, getAncestorOfType, getAnnotation, getAnnotationString, getColumn, getCVTerm, getCVTerms, getElementByMetaId, getElementBySId, getLevel, getLine, getListOfAllElements, getListOfAllElementsFromPlugins, getMetaId, getModel, getModelHistory, getNamespaces, getNotes, getNotesString, getNumCVTerms, getNumPlugins, getPackageName, getPackageVersion, getParentSBMLObject, getPlugin, getPlugin, getResourceBiologicalQualifier, getResourceModelQualifier, getSBMLDocument, getSBOTerm, getSBOTermAsURL, getSBOTermID, getVersion, hashCode, hasValidLevelVersionNamespaceCombination, isPackageEnabled, isPackageURIEnabled, isSetAnnotation, isSetMetaId, isSetModelHistory, isSetNotes, isSetSBOTerm, matchesRequiredSBMLNamespacesForAddition, matchesSBMLNamespaces, removeFromParentAndDelete, 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 EventAssignment(EventAssignment orig) throws SBMLConstructorException
EventAssignment
.
orig
- the object to copy.
SBMLConstructorException
- Thrown if the argument orig
is null.
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, or this kind
of SBML object, are either invalid or mismatched with respect to the
parent SBMLDocument
object.
EventAssignment
object to an SBMLDocument
(e.g., using Event.addEventAssignment(EventAssignment ea)
),
the SBML Level, SBML Version and XML namespace of the document
override the values used when creating the EventAssignment
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 EventAssignment
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 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 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.
EventAssignment
object to an SBMLDocument
(e.g., using Event.addEventAssignment(EventAssignment ea)
),
the SBML XML namespace of the document overrides the value used
when creating the EventAssignment
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 EventAssignment
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 EventAssignment cloneObject()
EventAssignment
.
cloneObject
 in class SBase
EventAssignment
.public boolean containsUndeclaredUnits()
true
if the math
expression of this EventAssignment
contains literal numbers or
parameters with undeclared units.
The EventAssignment.getDerivedUnitDefinition()
method returns what
libSBML computes to be the units of the 'math', 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
EventAssignment.containsUndeclaredUnits()
when using
EventAssignment.getDerivedUnitDefinition()
to decide whether the
returned units may be incomplete.
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 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 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
EventAssignment.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 EventAssignment
, or null
if one cannot be constructed.
EventAssignment.containsUndeclaredUnits()
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 String getElementName()
EventAssignment
, is always 'eventAssignment'.
getElementName
 in class SBase
'eventAssignment'.
public ASTNode getMath()
EventAssignment
's 'math'
subelement.
ASTNode
of an abstract syntax tree representing the
mathematical formula in this EventAssignment
.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).
EventAssignment.getElementName()
public String getVariable()
EventAssignment
's 'variable' attribute.
EventAssignment
.public boolean hasRequiredAttributes()
true
if
all the required attributes for this EventAssignment
object
have been set.
hasRequiredAttributes
 in class SBase
EventAssignment
object are:
public boolean hasRequiredElements()
true
if
all the required elements for this EventAssignment
object
have been set.
hasRequiredElements
 in class SBase
EventAssignment
object are:
public boolean isSetMath()
EventAssignment
is set.
true
if this EventAssignment
has a 'math' subelement,
false
otherwise.public boolean isSetVariable()
EventAssignment
is set.
true
if the 'variable' attribute of this EventAssignment
is set, false
otherwise.public void renameSIdRefs(String oldid, String newid)
renameSIdRefs
 in class SBase
oldid
- the old identifiernewid
- the new identifierpublic void renameUnitSIdRefs(String oldid, String newid)
renameUnitSIdRefs
 in class SBase
oldid
- the old identifiernewid
- the new identifierpublic int setMath(ASTNode math)
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 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.