public class Delay extends SBase
An Event
object defines when the event can occur, the variables that
are affected by the event, and how the variables are affected. The
effect of the event can optionally be delayed after the occurrence of
the condition which invokes it. An event delay is defined using an
object of class Delay
.
The object class Delay
is derived from SBase
and adds a single
subelement called 'math'. This subelement is used to hold MathML
content. The mathematical formula represented by 'math' must evaluate
to a numerical value. It is used as the length of time between when the
event is triggered and when the event's assignments are
actually executed. If no delay is present on a given Event
, a time
delay of zero is assumed.
The expression in 'math' must be evaluated at the time the event is triggered. The expression must always evaluate to a nonnegative number (otherwise, a nonsensical situation could arise where an event is defined to execute before it is triggered!).
Delay
In SBML Level 2 versions before Version 4, the units of the
numerical value computed by the Delay
's 'math' expression are
required to be in units of time, or the model is considered to have a
unit consistency error. In Level 2 Version 4 as well as SBML
Level 3, this requirement is relaxed these
specifications only stipulate that the units of the numerical value
computed by a Delay
instance's 'math' expression should match the
model's units of time (meaning the definition of the time
units in
the model). LibSBML respects these requirements, and depending on
whether an earlier Version of SBML Level 2 is in use, libSBML may
or may not flag unit inconsistencies as errors or merely warnings.
Note that units are not predefined or assumed for the contents
of 'math' in a Delay
object rather, they must be defined explicitly for
each instance of a Delay
object in a model. This is an important point
to bear in mind when literal numbers are used in delay expressions. For
example, the following Event
instance would result in a warning logged
by SBMLDocument.checkConsistency()
about the fact that libSBML cannot
verify the consistency of the units of the expression. The reason is
that the formula inside the 'math' element does not have any declared
units, whereas what is expected in this context is units of time:
<model> ... <listOfEvents> <event useValuesFromTriggerTime='true'> ... <delay> <math xmlns='http://www.w3.org/1998/Math/MathML'> <cn> 1 </cn> </math> </delay> ... </event> </listOfEvents> ... </model>
The <cn> 1 </cn>
within the mathematical formula
of the delay
above has no units declared. To make the
expression have the needed units of time, literal numbers should be
avoided in favor of defining Parameter
objects for each quantity, and
declaring units for the Parameter
values. The following fragment of
SBML illustrates this approach:
<model> ... <listOfParameters> <parameter id='transcriptionDelay' value='10' units='second'/> </listOfParameters> ... <listOfEvents> <event useValuesFromTriggerTime='true'> ... <delay> <math xmlns='http://www.w3.org/1998/Math/MathML'> <ci> transcriptionDelay </ci> </math> </delay> ... </event> </listOfEvents> ... </model>
In SBML Level 3, an alternative approach is available in the form
of the units
attribute, which SBML Level 3 allows to appear on
MathML cn
elements. The value of this attribute can be used to
indicate the unit of measurement to be associated with the number in the
content of a cn
element. The attribute is named units
but,
because it appears inside MathML element (which is in the XML namespace
for MathML and not the namespace for SBML), it must always be prefixed
with an XML namespace prefix for an SBML Level 3
namespace. The following is an example of this approach:
<model timeUnits='second' ...> ... <listOfEvents> <event useValuesFromTriggerTime='true'> ... <delay> <math xmlns='http://www.w3.org/1998/Math/MathML' xmlns:sbml='http://www.sbml.org/sbml/level3/version1/core'> <cn sbml:units='second'> 10 </cn> </math> </delay> ... </event> </listOfEvents> ... </model>
In SBML Level 3 Version 2, the requirement that a Delay
have a 'math' subelement was relaxed, making it optional. In
this case, the Delay
remains undefined, and unless that information
is provided in some other form (such as with an SBML Level 3
package), the Event
behaves as if it had no Delay
.
Constructor and Description |
---|
Delay(Delay orig)
Copy constructor creates a copy of this
Delay . |
Delay(long level,
long version)
|
Delay(SBMLNamespaces sbmlns)
|
Modifier and Type | Method and Description |
---|---|
Delay |
cloneObject()
Creates and returns a deep copy of this
Delay object. |
boolean |
containsUndeclaredUnits()
Predicate returning
true if the 'math' expression in this Delay
instance contains parameters with undeclared units or literal numbers. |
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 Delay . |
java.lang.String |
getElementName()
Returns the XML element name of this object, which for
Delay , is
always 'delay'. |
ASTNode |
getMath()
Get the mathematical formula for the delay 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 Delay object
have been set. |
boolean |
isSetMath()
Predicate to test whether the formula for this delay is set.
|
int |
removeFromParentAndDelete()
|
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)
|
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 Delay(long level, long version) throws SBMLConstructorException
level
- a long integer, the SBML Level to assign to this Delay
.
version
- a long integer, the SBML Version to assign to this
Delay
.
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 Delay(SBMLNamespaces sbmlns) throws SBMLConstructorException
Delay
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 Delay(Delay orig) throws SBMLConstructorException
Delay
.
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 Delay.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 Delay.delete()
themselves.
public Delay cloneObject()
Delay
object.
cloneObject
 in class SBase
Delay
object.public ASTNode getMath()
Delay
, or null
if the math is not set.public boolean isSetMath()
true
if the formula (meaning the math
subelement) of
this Delay
is set, false
otherwise.public int setMath(ASTNode math)
math
- an ASTNode
representing a formula tree.
public UnitDefinition getDerivedUnitDefinition()
UnitDefinition
that expresses the units
of measurement assumed for the 'math' expression of this Delay
.
Delay
elements in SBML express a time delay for an Event
. Beginning
with SBML Level 2 Version 2, the units of that time are
calculated based on the mathematical expression and the model quantities
referenced by <ci>
elements used within that
expression. (In SBML Level 2 Version 1, there exists an
attribute on Event
called 'timeUnits'. This attribute can be used to set
the units of the Delay
expression explicitly.) The method
Delay.getDerivedUnitDefinition()
returns what libSBML computes the units
to be, to the extent that libSBML can compute them.
getDerivedUnitDefinition
 in class SBase
UnitDefinition
that expresses the units of the math
expression of this Delay
, or null
if one cannot be constructed.
Delay.containsUndeclaredUnits()
null.
Delay
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
Delay.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
Delay.containsUndeclaredUnits()
to determine whether this
situation holds. Callers should take suitable action in those
situations.
public boolean containsUndeclaredUnits()
true
if the 'math' expression in this Delay
instance contains parameters with undeclared units or literal numbers.
Delay
elements in SBML express a time delay for an Event
. Beginning
with SBML Level 2 Version 2, the units of that time are
calculated based on the mathematical expression and the model quantities
referenced by <ci>
elements used within that
expression. (In SBML Level 2 Version 1, there exists an
attribute on Event
called 'timeUnits'. This attribute can be used to set
the units of the Delay
expression explicitly.) The method
Delay.getDerivedUnitDefinition()
returns what libSBML computes the units
to be, 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 Delay.containsUndeclaredUnits()
when using
Delay.getDerivedUnitDefinition()
to decide whether the returned units
may be incomplete.
containsUndeclaredUnits
 in class SBase
true
if the math expression of this Delay
includes
numbers/parameters with undeclared units, false
otherwise.
Delay.getDerivedUnitDefinition()
true
indicates that the UnitDefinition
returned by Delay.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_DELAY
(default).
Delay.getElementName()
,
SBase.getPackageName()
public java.lang.String getElementName()
Delay
, is
always 'delay'.
getElementName
 in class SBase
'delay'.
Delay.getTypeCode()
public boolean hasRequiredElements()
true
if
all the required elements for this Delay
object
have been set.
hasRequiredElements
 in class SBase
Delay
object are:
public int removeFromParentAndDelete()
Delay
's Event
parent and calls unsetDelay() 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.