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 Version 1 Core, 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 the SBML Level 3 Version 1
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>
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 . |
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)
Renames all the
SIdRef attributes on this element, including any
found in MathML. |
void |
renameUnitSIdRefs(java.lang.String oldid,
java.lang.String newid)
Renames all the
UnitSIdRef attributes on this element |
int |
setMath(ASTNode math)
|
addCVTerm, addCVTerm, appendAnnotation, appendAnnotation, appendNotes, appendNotes, disablePackage, enablePackage, equals, getAncestorOfType, getAncestorOfType, getAnnotation, getAnnotationString, getColumn, getCVTerm, getCVTerms, getElementByMetaId, getElementBySId, getLevel, getLine, getListOfAllElements, getListOfAllElements, getListOfAllElementsFromPlugins, getListOfAllElementsFromPlugins, getMetaId, getModel, getModelHistory, getNamespaces, getNotes, getNotesString, getNumCVTerms, getNumPlugins, getPackageName, getPackageVersion, getParentSBMLObject, getPlugin, getPlugin, getPrefix, getResourceBiologicalQualifier, getResourceModelQualifier, getSBMLDocument, getSBOTerm, getSBOTermAsURL, getSBOTermID, getURI, getVersion, hashCode, hasValidLevelVersionNamespaceCombination, isPackageEnabled, isPackageURIEnabled, isSetAnnotation, isSetMetaId, isSetModelHistory, isSetNotes, isSetSBOTerm, matchesRequiredSBMLNamespacesForAddition, matchesSBMLNamespaces, 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
public Delay(Delay orig) throws SBMLConstructorException
Delay
.
orig
- the object to copy.
SBMLConstructorException
- Thrown if the argument orig
is null.
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, or this kind
of SBML object, are either invalid or mismatched with respect to the
parent SBMLDocument
object.
Delay
object to an Event
(e.g., using
Event.setDelay(Delay d)
), the SBML Level, SBML Version
and XML namespace of the document override the values used when
creating the Delay
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 Delay
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 a
particular Delay
object to an existing Event
.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 level
and version
combination, or this kind
of SBML object, are either invalid or mismatched with respect to the
parent SBMLDocument
object.
Delay
object to an Event
(e.g., using
Event.setDelay(Delay d)
), the SBML Level, SBML Version
and XML namespace of the document override the values used when
creating the Delay
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 Delay
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 a
particular Delay
object to an existing Event
.public Delay cloneObject()
Delay
.
cloneObject
 in class SBase
Delay
.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 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 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 java.lang.String getElementName()
Delay
, is
always 'delay'.
getElementName
 in class SBase
'delay'.
Delay.getTypeCode()
public ASTNode getMath()
Delay
.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 &ldquoSBML_
&rdquo.
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_DELAY
(default).
Delay.getElementName()
,
SBase.getPackageName()
public boolean hasRequiredElements()
true
if
all the required elements for this Delay
object
have been set.
hasRequiredElements
 in class SBase
Delay
object are:
public boolean isSetMath()
true
if the formula (meaning the math
subelement) of
this Delay
is set, false
otherwise.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)
SIdRef
attributes on this element, including any
found in MathML.
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, comparing the identifiers to the value of
oldid
. If any matches are found, the matching identifiers 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)
UnitSIdRef
attributes on this element
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
unit identifiers to the value of oldid
. If any matches are found,
the matching identifiers are replaced with newid
. The method does
not descend into child elements.
renameUnitSIdRefs
 in class SBase
oldid
- the old identifiernewid
- the new identifier