Event¶
An instantaneous change of the model when a condition becomes true.
An event describes a discontinuous change: when its trigger turns from false to true, the assignments of the event are executed and set new values for compartments, species, stoichiometries or parameters. A dose which is given at a fixed time, a switch which flips at a threshold or a medium which is exchanged are events. The change can be delayed, and a priority decides which of several simultaneous events is executed first.
The report shows the rendered trigger, the priority and the delay of an event, the flags of its trigger and the table of its assignments, and opens the trigger, the priority and the delay as elements of their own.
Attributes¶
| attribute | type | required | meaning | specification |
|---|---|---|---|---|
| useValuesFromTriggerTime | boolean |
required | whether the assignments use the values of the moment the event was triggered | core 4.12.1 |
| trigger | Trigger |
optional | the condition of the event, as an element of its own | core 4.12.2 |
| trigger | Math |
optional | the condition whose change from false to true fires the event | core 4.12.2 |
| initialValue | boolean |
required | whether the condition is taken to be true just before the simulation starts | core 4.12.2 |
| persistent | boolean |
required | whether the event is still executed when its condition becomes false again before execution | core 4.12.2 |
| priority | Priority |
optional | the element which orders the event against other events of the same moment | core 4.12.3 |
| priority | Math |
optional | the formula which orders this event against other events of the same moment | core 4.12.3 |
| delay | Delay |
optional | the element which postpones the execution of the event | core 4.12.4 |
| delay | Math |
optional | the formula which gives the time between the trigger and the execution | core 4.12.4 |
| listOfEventAssignments | list |
optional | the changes the event makes when it is executed | core 4.12.5 |
Every element of a model also carries the common attributes of SBase.
useValuesFromTriggerTime
An event which is delayed is triggered at one moment and executed at another, and the two moments can give different values. With "true" the formulas of the assignments are evaluated when the event triggers, with "false" when it is executed.
The report shows the flag as a mark in the column "values from trigger time".
21206(error): If an <event>'s 'useValuesFromTriggerTime' attribute has the value 'false', then the <event> must contain a <delay> element. The implication of 'useValuesFromTriggerTime=false' is that there is a delay between the time of trigger and the time of value assignments performed by the <event>.
trigger
Every event has a trigger, the element which holds the condition and the two flags which say how it is read. The report opens it in the inspector, with its own SBO term, notes and annotations.
Default: the event can never be triggered.
21201(error): An <event> object must have a 'trigger'. In SBML Level 3 Version 2 this rule was relaxed to stating that an <event> object must have at most one 'trigger' element.
trigger
The trigger holds an expression which returns a boolean value, and the event fires at the moment that expression turns from false to true. It can fire again whenever the expression makes that transition again. An event without a trigger can never fire.
The report renders the condition in the column "trigger" and in the inspector.
Default: the event is never triggered.
21202(error): An <event>'s <trigger> expression must evaluate to a value of type Boolean.21209(error): A Trigger object must contain exactly one MathML <math> element. The <math> element is optional in L3V2 and beyond.
initialValue
To know whether an event may already fire at time zero, a simulator has to know what the condition was just before. With "true" it is taken to have been true, so the event cannot fire at the start; with "false" it may fire immediately.
The report shows the flag as a mark, in the column "initial value" and in the inspector.
21229(error): The attribute 'initialValue' on a Trigger object must have a value of type Boolean.
persistent
Between the moment an event triggers and the moment it is executed, its condition may turn false again, because the event is delayed or because another event changed the model. With "true" the assignments are carried out anyway, with "false" the event is dropped.
The report shows the flag as a mark, in the column "persistent" and in the inspector.
21228(error): The attribute 'persistent' on a Trigger object must have a value of type Boolean.
priority
An event may carry a priority, the element whose formula decides which of several events of one moment is executed first. An event without a priority has none, and the order of simultaneous events is then not fixed.
Default: the order of the event among simultaneous events is not fixed.
21230(error): An Event object may contain at most one Priority object.
priority
When several events are executed at the same moment, the one with the higher priority goes first; a larger number means a higher priority and the value is dimensionless.
The report renders the priority in the column "priority" of the events and in the inspector.
Default: the event behaves as one without a priority.
21231(error): An Priority object must contain exactly one MathML <math> element. The <math> element is optional in L3V2 and beyond.
delay
An event may carry a delay, the element whose formula gives the time between the trigger and the execution. An event without a delay is executed immediately.
Default: the event is executed at the moment it triggers.
21206(error): If an <event>'s 'useValuesFromTriggerTime' attribute has the value 'false', then the <event> must contain a <delay> element. The implication of 'useValuesFromTriggerTime=false' is that there is a delay between the time of trigger and the time of value assignments performed by the <event>.21221(error): An Event object may contain at most one Delay object.
delay
The delay is evaluated at the moment the event triggers and has to be a value which is not negative, in the time units of the model.
The report renders the delay in the column "delay" of the events and in the inspector.
Default: the event is executed as one without a delay.
21210(error): A Delay object must contain exactly one MathML <math> element. The <math> element is optional in L3V2 and beyond.
listOfEventAssignments
The list holds the event assignments of the event, each of which sets one element of the model to the value of a formula.
The report shows the assignments in the column "assignments", every one of them as the element it sets and the formula it assigns, and as a table in the inspector of the event.
Default: the event changes nothing when it is executed.
21203(error): An <event> object must have at least one <eventAssignment> object in its <listOfEventAssignments>.21222(error): An Event object may contain at most one ListOfEventAssignments object.21223(error): Apart from the general Notes and Annotation subobjects permitted on all SBML components, a ListOfEventAssignments container object may only contain EventAssignment objects.
Validation rules¶
10710(warning): The value of the 'sboTerm' attribute on an <event> is expected to be an SBO identifier (http://www.biomodels.net/SBO/) referring to an occurring entity representation defined in SBO (i.e., terms derived from SBO:0000231, "occurring entity representation").21205(error): The order of subelements within <event> must be the following: <trigger>, <delay>, <listOfEventAssignments>. The <delay> element is optional, but if present, must follow <trigger>.21225(error): An Event object must have the required attribute 'useValuesFromTriggerTime' and in addition may have the optional attributes 'metaid', 'sboTerm', 'id', and 'name'. No other attributes from the SBML Level 3 Core namespace are permitted on an Event object.
Related elements¶
- Trigger: the condition of an event, whose change from false to true fires it
- Priority: the formula which orders an event against the other events of the same moment
- Delay: the formula which gives the time between the trigger of an event and its execution
- EventAssignment: the new value an event gives to one element of the model
Specification¶
SBML Level 3 Version 2 Core, Section 4.12 (Hucka et al. 2019, J Integr Bioinform 16(2):20190021).