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 . |
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(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)
|
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, 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 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 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.
Delay
object to an Event
(e.g., using
Event.setDelay(Delay d)
), the SBML XML namespace of
the document overrides the value 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. The Delay.getDerivedUnitDefinition()
method returns
what libSBML computes the units to be, 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 Delay.containsUndeclaredUnits()
when using Delay.getDerivedUnitDefinition()
to decide whether the
returned units may be incomplete.
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. The Delay.getDerivedUnitDefinition()
method returns
what libSBML computes the units to be, to the extent that libSBML can
compute them.
(Prior to SBML Level 2 Version 2, there existed an attribute
on Event
called 'timeUnits'. This attribute could be used to set the
intended units of the delay expression. For such models, this will
return a UnitDefinition
object that corresponds to the declared
'timeUnits' 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 Delay
, or null
if one cannot be constructed.
Delay.containsUndeclaredUnits()
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 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 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).
Delay.getElementName()
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(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 identifier