Event(namestr, triggerint|func(model), repeatboolFalse, **kwargs)

An event triggers on a certain user-defined criterion. When triggered, an event stores the data output at that time and registers on the visualizer. TimeSeries, for example, draws a vertical line on the plots (see the image to the right), and Charts will flash the background. In the image to the right there are two events, marking the increase and leveling off of population.

This class should not be instantiated directly; use Events.add() or the @model.event decorator instead.

WARNING: This is an internal class. Its use in user code is not recommended or supported, and its signature can change in future updates without warning. Use one of the suggested functions above instead, if applicable.

Initialization Parameters

• name — str, required

  The name of the event.

• trigger — int|func(model), required

  A timestamp at which to trigger the event, or a function that takes the model object and returns a boolean, True when the event is to be triggered.

• repeat — bool, optional

  Whether the event should trigger once, or every time the criterion is satisfied. If repeat==False, event.data and event.triggered will be a dict and an int, respectively; otherwise, lists with items corresponding to each trigger.

  Default value: False

• **kwargs — optional

  Further options to be passed to the visualizer's event() method. TimeSeries.event(), for example, draws a vertical line on the plot area, and takes color, linestyle, and linewidth arguments to customize its appearance.

  Default value: {}

Methods

Click a method name for more detailed documentation.

• reset( )

  Clears Event.data and sets Event.triggered to False.

• check( model )

  Runs the user-defined event function to determine whether the event is triggered and records the model state. If Event.repeat==False, this function will return False so long as Event.trigger returns False, True the first time Event.trigger returns True, and False thereafter. If Event.repeat==True, the function returns True whenever Event.trigger returns True.

Object Properties

• name — str

  The name of the event.

• trigger — int|func(model)

  A timestamp at which to trigger the event, or a function that takes the model object and returns a boolean, True when the event is to be triggered.

• repeat — bool

  Whether the event should trigger once, or every time the criterion is satisfied.

  Initial value: False

• **kwargs —

  Additional arguments to be passed to the visualizer's event() method.

  Initial value: {}

• triggered — bool|int|list[int]

  If a nonrepeatable event, False if the event has not been triggered yet, or the model time when the event was triggered. If a repeatable event, a list of model times when the criterion was satisfied. Note that since an empty list evaluates to False, an if statement like if event.triggered: will work for both repeatable and nonrepeatable events.

  Initial value: False

• data — dict|list[dict]

  The row of collected model data from the period the event was triggered, or a list of such rows if this is a repeatable event.