Events

Overview

Each HexSim event has a unique purpose, interface, and parameter set. Two things that most events do have in common are their Output and Description tabs. Output tabs are used to control what data the event writes to the simulation log file. Since log files can easily become quite large, there can be value in turning elements of the logging process off. Logging is always set on by default. If any part of logging is turned off, a icon will be placed to the right of the event type, in the main window's Event Sequence. There is one exception to this rule: in Census events, the logging of genomes is off by default, and this does not cause the icon to be displayed. The description tabs allow users to record notes, which will then be stored in the scenario XML file.

HexSim includes an extensive validation scheme that attempts to flag invalid parameter values. In most cases, invalid parameters and events will be identified with a icon. Also, a tool-tip (a small message window) will pop up when the mouse is placed over the red exclamation point. These tool-tips can be valuable parameterization aids.

All of the basic operations that act on events can be accessed through the event context menu (see image below). This context menu has options for event creation, editing, copying, renaming, and deletion. The context menu also provides access to event coloring, triggering, and some display parameters.

Each HexSim event can be assigned a color. This is done using tools available in the event context menu. Coloring events can add clarity to the life cycle structure. Automatically generated events will be colored black (when added by population creation) or gray (when added by trait builders), but these colors can be changed.

Event triggers can be used to make events active for just a subset of the simulation time steps. Events may trigger once, or during a period defined by a starting and ending time step. In the latter case, a periodicity setting is also available. For example, suppose an event starts at time step 5, has a period of 3, and triggers for just 1 time step per period. The event will then execute on time steps 5, 8, 11, 14, etc. An event that starts at time step 5 and has a period of 10 will execute on time steps 5, 15, 25, 35, etc. If the time step is a day, and an event starts on step 150, triggers with period 365, and triggers for 30 time steps per period, then the event will fire for a month each year, beginning on the 150 day of the year.

Event triggers can also be used to turn an event off entirely. This is done by selecting the Toggle Event On/Off context-menu option.

When triggering is set, an icon will be displayed in the event sequence, just to the left of the event. If an event has been turned off, then a icon will be displayed. A icon is displayed when the event will trigger just once. A icon indicates that the event will trigger more than once. The arrow icons will both turn red if triggering somehow becomes corrupted. The triggering conditions will be displayed in a tool-tip when the mouse is placed over a triggering icon. When triggering is off, events will be active in every time step. In addition to the context menu, the triggering dialog can be accessed by double-clicking the triggering icons.

HexSim Events: