The Disease Scenario


The Disease scenario was originally developed from the Basic scenario, though it is now quite different. But like Basic, it is straightforward and useful for illustrating HexSim mechanics. The two videos HexSim Disease Demo 1 and HexSim Disease Demo 2 (see the Videos page in this section of the website) were constructed using the output from this model. This model can be thought of as having two principal components: demography and disease.


Unlike the Basic model, individuals from this population live in groups. The groups tend to reside within the habitat patches because the Population Parameters Range Data were set to preclude low quality habitat from being part of groups' ranges. The exact values of these parameters, for example the maximum group size or the stage-stratified resource targets, are not that critical. The basic population dynamics observed in the videos would still emerge if these parameters were altered.

For the non-disease elements of demography, the population really just depends on a single accumulated trait called Stage Class. A location trait is used principally for data gathering, but for simplicity this trait is also used in the vaccination scheme described below. The remaining traits are all tied to the disease components of the model.

The life cycle begins with two events that illustrates how a population can be introduced into a map that doesn't exist in the workspace. These two events, Generated Hexmap and Introduction, only trigger during the first time step. This initial Generated Hexmap event produces a map that is all zero except for a single hexagon at the center of patch 3. The subsequent Introduction event places 10 individuals into that single hexagon. The scenario's other introduction event, which initiates the disease epidemic, also makes use of this generated hexmap.

Accumulate events keep track of individual's age and stage class, and their locations. The Reproduction event is placed right after the triggered disease Introduction event to facilitate initial disease spread. Juveniles always disperse away from the natal group (this also aids in disease spread) but they are allowed to join any group that will accept them, including their natal group. As was the case in the Basic model, two Survival events are used to impose mortality, here based on both stage class and disease status.


The population has one accumulated and one probabilistic trait dedicated to the mechanics of disease spread. The accumulated trait is called Exposure Class, and it responds to an accumulator called Exposure. For simplicity, individuals in this model are either unexposed or exposed (in reality the amount of exposure may matter). The probabilistic trait is called Disease Status, and it has five trait values: Susceptible, Exposed, Infected, Recovered, and Vaccinated.

The three events titled Clear Exposure, Compute Exposure, and Disease Progression together control disease dynamics in this simulation. A fourth, the Introduction event labeled Introduce Disease triggers once at time step 500, at which point it adds 10 infected individuals to the center of patch 3. The 500 time step delay gives the population a chance to reach steady-state before being subjected to this initial stress.

Each time step the Exposure accumulator is cleared (set to zero), and then incremented for susceptible individuals whose explored area overlaps with that of an infected individual. These two events ensure that every individual's Exposure Class trait is set to Unexposed, and then only susceptibles who encounter an infected individual end up being assigned the Exposed trait value.

The Transition event labeled Disease Progression shifts individuals through the five disease classes. Susceptible individuals who have been exposed are place into the exposed class with certainty. Otherwise, they remain susceptible. The remaining state transitions take place at the same rete regardless of exposure. Exposed individuals have a 50% chance of becoming infected. Infected individuals have a 20% chance of recovering. Recovered individuals always transition back to the susceptible class (they are only immune for a single time step).


The vaccination methodology used in this simulation is very simple. A Transition event called Set Vaccination Class is begins triggering in time step 600, which gives the disease 100 time steps to become established. The Transition event is stratified by location, so users can simulate a vaccination program for which effort varies from patch to patch. The event sets a dedicated binary probabilistic trait called Vaccination Class. A second Transition event then assigns vaccinated susceptibles the vaccinated disease status, and has no affect on other individuals. Vaccination, in this case, is ineffective for exposed or infected animals. Successfully vaccinated individuals never transition out back to the susceptible class, and so they never contract the disease.

Hexmap Generation

The two videos mentioned at the top if this page were created using the output from the Infection Dynamics and Map Disease Dynamics Generated Hexmap events.

The Cumulative Infections Generated Hexmap event illustrates simple recursion. The drawback of recursion is that the Hexmap values will likely continue to increase as the simulation runs. When viewed as a time series, such as within the Simulation Viewer, all of the Hexmaps will be scaled by the extreme hexagon values present in the series as a whole, which will make the earlier maps appear fairly monochromatic (relative to the series maximum, their values will all be small). This problem can be solved by copying the generated Hexmap and then re-scaling the copy using a fixed range, which is precisely what the Infection Dynamics Generated Hexmap event does. The re-scaling has to be done in a copy, or else the recursion will become meaningless.

The Disease Dynamics generated Hexmap (see image to the right) illustrates how a small number of specific colors can be used to convey a precise set of conditions. In this case, the variables h1, h2, and h3 represent the habitat map score, the presence or absence of range hexagons, and the number of infected individuals. The generated Hexmap is constructed from four nested Cond() statements.

Note that Cond (x, y, z) can be translated: If (x > 0) return y, else return z.

Working from left to right, the statement:

Cond ( h3, -2, Cond ( h2, 2, Cond ( h1 - 5, 1, Cond ( h1, -1, 0 ))))

says to set hexagons occupied by an infected individual to -2. Otherwise if the hexagon is part of a group's range (meaning it is occupied), set the value to +2. Otherwise if the hexagon has a score greater than 5 (meaning it is good habitat) set the value to +1. Otherwise if the hexagon is nonzero, set the value to -1. Otherwise the hexagon must be zero-values, so set it to zero.

The resulting Hexmap will be comprised of the following scores, which correspond to the 5 colors in the image above. This image was constructed using the Blue-Red color scheme.

  • -2 -> occupied, infection. Blue.
  • -1 -> low quality habitat. Green.
  •  0 -> non-habitat. Gray.
  • +1 -> high quality habitat. Yellow.
  • +2 -> occupied, no infection. Red.

When HexSim displays a Hexmap that has both negative and positive scores, it divides the color spectrum up into two equal parts, which it assigns to the ranges [min, 0) and (0, max]. This ensures that the five categories above will be assigned five distinct colors, as in the image above.