The HexSimPLE Scenario


Overview

HexSimPLE is a flexible template within which users can rapidly construct spatially-explicit metapopulation models. HexSimPLE models consist of a distributed array of Leslie projection matrices that are linked by movement. Users supply a patch map (see below), and a single Leslie matrix is automatically assigned to each patch.

Each of HexSimPLE's Leslie matrices is of dimension 3, corresponding to a stage-stratified population of (for example) juveniles, sub-adults, and adults. Users can easily simulate a 2-stage population by setting the sub-adult and adult parameters the same. HexSimPLE would have to be edited a bit to simulate more than three stage classes.

To construct a custom application from the HexSimPLE template, users must supply workspace spatial data (discussed in detail below) having the following names:

  • Habitat Map
  • Matrices Map
  • Regions Map
  • Stress Map Fecundity
  • Stress Map Survival
  • Movement Barriers

These are all Hexmaps except for Movement Barriers, which is a Barrier map.  The Matrices Map and Regions map should not be time series (they should be static, consisting of a single Hexmap associated with time step 1). The remaining maps may be time series.

While these six maps must all exist in the workspace (unless HexSimPLE itself is altered) the two stress maps and the stochasticity regions map may consist entirely of ones, and the barrier map need not include any barrier segments. The matrices and habitat maps may be very simple, but need some nontrivial content in order for the model to be useful. Thus HexSimPLE can be run with just two non-trivial map inputs.

Users must also assign values to 15 parameters (HexSim Global Variables), and will probably want to customize the Movement events a bit. But otherwise, it should not be necessary to modify the HexSimPLE population parameters or the event sequence. The parameters that must be specified are listed below:

  • Fecundity (separately for stage 0, 1, and 2)
  • Survival Rate (separately for stage 0, 1, and 2)
  • Habitat Exponent (separately for fecundity and survival)
  • Stochasticity (separately for fecundity and survival)
  • Dispersal Path Length (minimum and maximum)
  • Per-hexagon Carrying Capacity
  • Data Sampling Delay

A schematic diagram of the HexSimPLE model is presented below. Note that a few identical boxes appear at the top and bottom of the figure. Doing so simplified the graphic.



The motivation for developing HexSimPLE was to provide users with a tool for rapidly constructing parsimonious spatial population models. HexSimPLE blends the simplicity of matrix algebra with an acknowledgement that space matters because habitat and disturbances are not uniform or static, and because landscape connectivity is a function of species' movement ability and behavior. HexSimPLE models also automatically generate many useful simulation products such as maps of cumulative population size and productivity (source-sink behavior).

Users should find the process of constructing a HexSimPLE model takes dramatically less effort than the development cycle associated with a traditional HexSim simulation. In HexSimPLE, the model structure is already complete, and it is only necessary to supply some maps, specify a limited number of parameter values, and customize movement behavior. Nevertheless, customizing HexSimPLE to meet your needs will require some familiarity with HexSim itself, and the documentation here assumes a basic working knowledge of the application.

For readers familiar with matrix population models, note that HexSimPLE assumes a post-breeding census. For more information, see the section below titled "Post-Breeding Census versus Pre-Breeding Census".

Spatial Data

The first step in customizing the HexSimPLE template for a new project will involve the construction of a workspace that fits the spatial data to be used. Once a new workspace has been developed, all of the workspace spatial data will have to be created. The discussion below should help users with this initial step. The actual workspace construction process is described in the HexSim User's Guide, and is not repeated here.

The Matrices Map

The Matrices Map (referred to above as a patch map) determines where to locate the Leslie matrices that control HexSimPLE's local plant or animal sub-populations. The Matrices Map must contain a collection of patches, with each patch being made up from one or more hexagons having the same integer score. The hexagons making up a patch need not be adjacent, thought this will typically be the case. An image of a possible Matrices Map is shown on the right. The patches here have a hexagonal shape because they are assembled from atomic hexagons arranged into concentric rings. The colors shown are derived from the hexagon scores, which are by definition the same across each patch. The patch IDs (the score of the hexagons from which a patch is assembled) were randomized here to make the figure easier to visualize. There is no reason why the patches cannot extend all the way to the landscape boundaries. The patches along the edges of this image were trimmed away to illustrate that HexSimPLE doesn't care how a Matrices Map is constructed.

The patches in a Matrices Map need not have any particular shape or size, and every patch may be unique if desired. A Leslie matrix will not be assigned to the zero-valued (gray) background hexagons visible at the edges of the example Matrices Map. Because exactly one Leslie matrix will be assigned to each patch, the terms Leslie matrix and patch may be used interchangeably.

The HexSimCommandLine.exe tool (supplied with HexSim) contains two utilities for constructing patch maps. The first is called using the flag -generateHexPatchMap, and it constructs a Hexmap of hexagonal-shaped patches. The second is called using the flag -generateRectanglePatchMap, and it constructs a Hexmap of rectangular patches. These tools will only add full-size patches. The Matrices Map shown here was developed using an analogous stand-alone algorithm called build_hexmap_hexagons.c that can be found at the Utilities section of this website. A second utility there called build_hexmap_blocks.c can be used to develop a space-filling map of rectangular patches. The Matrices Map must not be a time series -- it must include a Hexmap only for time step 1.

The Habitat Map

The Habitat Map is used to [1] to modify Leslie matrix vital rates (they will be lower in resource-poor areas), [2] to establish a per-patch carrying capacity, which affects density dependence and numbers of dispersers, and [3] to influence dispersal behavior. The habitat map's hexagon scores must fall between 0.0 and 1.0. HexSimPLE will assume that a hexagon score of 1.0 represents optimal habitat, and a score of 0.0 represents non-habitat. The vital rates provided to the model interface will be realized in optimal habitat, and they will decline as habitat quality drops towards zero. The relationship between habitat quality and the vital rates is given by:
rq = ro [ 1 - (1 - q)η ]
Where q is the habitat quality, η is the habitat exponent (a model parameter) associated with either fecundity or survival, ro is a survival or fecundity value supplied as a model parameter, and rq is the vital rate experienced in habitat of quality = q. For any given ro, this function produces a family of curves spanning the range from linear (η = 0) to a bimodal step function (η = infinity). By selecting a specific habitat exponent parameter, users are effectively setting a habitat quality below which survival or fecundity begins dropping rapidly. Note that q here is actually the mean of habitat quality values taken over any given patch.

When a local population exceeds carrying capacity, excess individuals will be forced to disperse. As they move, these Dispersers will be increasingly attracted to better quality habitat. Finally, post-dispersal, individuals will be culled from patches that exceed their carrying capacity. The Habitat Map may be a dynamic time series.

The Regions Map

Some HexSimPLE models will make use of very large study areas. In such cases, users may choose to break the landscape into regions that exhibit different patterns of environmental stochasticity. The Regions map makes doing this easy. The Regions Map is a patch map containing one or more patches that together occupy the same area as the Matrices Map. When HexSimPLE sets the environmental quality value for each time step (e.g. whether this is a good, bad, or average year), it will do so independently for each patch in the Regions Map. Users wanting a single landscape-wide value for environmental stochasticity (per time step) can just build the Regions Map from a copy of the Matrices Map by setting every non-zero hexagon to 1.0. This would create a map with one patch, and hence one region... There is presently no mechanism in HexSimPLE to allow nearby regions to experience spatial auto-correlation in yearly environmental conditions. Likewise, within a region, survival and reproductive rates will be perfectly correlated (e.g. a good year for survival will always be a good year for reproduction). The Regions Map must not be a time series.

The Stress Maps

HexSimPLE uses separate spatial data sets to capture the impact of spatially-distributed stressors on survival and fecundity. These Hexmap series are called Stress Map Survival and Stress Map Fecundity. The hexagon scores in these maps are averaged, on a patch-by-patch basis, to extract coefficients that are subsequently used to multiply the individual Leslie matrix survival and fecundity rates. Thus the stress maps should normally be composed of hexagons with scores falling between 0.0 and 1.0.

For example, when a patch falls over a portion of a fecundity stress map that is composed entirely of zeros, the mean value taken over that patch will be zero, and its three fecundity rates will therefore be multiplied by zero.  If, in contrast, the mean value of the survival stress map in that same area is 0.75, then the corresponding Leslie matrix will have effective survival rates that are 3/4 of what they would have been in the absence of stress.

Each Leslie matrices' final survival and reproductive rates (for a given time step) can be represented using the equation re = [qsv] ro where re is the effective vital rate (e.g. juvenile survival in one patch, at one point in time) ro is the original vital rate (e.g. the juvenile survival input parameter), and q, s, and v are coefficients that capture the influence of habitat quality, stress, and environmental variability, respectively. Ignoring the habitat quality and environmental variability terms for the moment, we can reorder the above equation and write re = sro. Now, if ro = 1.0, then this equation reduces to re = s, suggesting that the stress maps may be used to represent the actual vital rates prior to modification by habitat quality and environmental stochasticity. This works as long as the vital rate input parameters are set to 1.0.

In summary, one or both of the stress maps can be used to supply the input vital rates to HexSimPLE (in map format). Users just need to set the corresponding survival or fecundity parameters to 1.0.

The Movement Barriers Map

HexSimPLE is delivered with a barrier map that could potentially restrict the movement of individuals from patch to patch. However, this default barrier map, named Movement Barriers, contains no barrier edges. Users wanting to impose barriers on their HexSimPLE population will need to develop a Movement Barriers map with barrier edges in it.

HexSimPLE's Leslie matrices are assigned to patches, but when barriers are used they will typically bisect some of these patches. If that is allowed to happen, then individuals who emigrate into a sub-divided patch will effectively cross the barrier when they become absorbed into the patch's population vector. For example, consider the yellow patch in the left-most image below. An immigrant coming from the right might stop in the patch without encountering the barrier. Once it becomes part of the patch's population, it has no specific location other than the patch as a whole. If that individual was then to leave the patch, it could start from any patch hexagon, including a hexagon on the left side of the barrier. If that happened, the individual would have effectively tunneled through the barrier.

Similarly, one side of a bisected patch might be frequently occupied while the other half was never visited. HexSimPLE occupancy and source-sink maps would fail to account for this discrepancy because they would assign a single property to the entire patch.  To avoid these problems, patch maps should be split along barriers anytime barriers are used in a HexSimPLE model. Two utilities named barriers_divide_patches.c and barriers_merge_patches.c are available (at the HexSim website) to automate this process. The utility of the patch-dividing algorithm is illustrated above, in the transition between the left and center images. In this case, the algorithm divided the yellow, blue, and light green patches. The utility of the patch-merging algorithm is illustrated above, in the transition between the center and right images. In this case, the algorithm merged the two small fragments with their adjoining patches.

The Population Parameters

HexSimPLE's main parameters are stored in 15 Global Variables. Users will want to modify these values. HexSimPLE's parameters are all discussed below, though in some cases multiple parameters are grouped under a single heading.

Fecundity

Three parameters are used to store the stage 0 (juvenile), stage 1 (subadult), and stage 2 (adult) fecundity values. Fecundity is used instead of reproductive rates because HexSimPLE is a females-only model. The fecundity values will be modified due to habitat quality, disturbance, and environmental stochasticity. HexSimPLE assumes the population vector represents a post-breeding census, so the fecundity terms will be discounted by the stage-0 survival rate.

Survival

Three parameters are used to store the stage 0 (juvenile), stage 1 (subadult), and stage 2 (adult) survival rates. Stage 0 survival specifies the rate at which individuals transition into Stage 1. Stage 1 survival specifies the rate at which individuals transition into Stage 2. Stage 2 Survival specifies the rate at which individuals remain in this class. The quantity (1.0 - survival) is the stage class-specific mortality rate. The survival rates will be modified due to habitat quality, disturbance, and environmental stochasticity. HexSimPLE will impose additional mortality when the local population size exceeds the patch carrying capacity.

Habitat Exponents

Users provide separate habitat exponents for survival and fecundity. The habitat exponents are used to lower the corresponding vital rates through their conversion into a coefficient taking a value varying between 0 and 1. Habitat exponents are described in detail in the the section above titled "The Habitat Map". The graphic to the right illustrates how the habitat coefficient (the value vital rates will be multiplied by) changes as a function of mean patch quality. Concave curves can be generated by setting the habitat exponent to a fractional value falling between 0 and 1, but doing so may not be biologically meaningful...

Percent Stochasticity

xyz

Dispersal Min & Max

xyz

Carrying Capacity

xyz

Initial Population Size

xyz

Begin Sampling

xyz

[+] Initial Patch Population

This sets the number of individuals that will be added to each patch when HexSimPLE starts up. These individuals will all be placed into stage class 2 (adults). Remember, they are not actual HexSim individuals. They are really just a value in a stage matrix, because HexSimPLE is a population model.

[+] Density Exponent

HexSimPLE matrices' survival and reproduction rates decline as population density increases. Density is measured relative to each patch's carrying capacity, which is in turn dependent on habitat quality and a user-defined Per-Hexagon Carrying Capacity parameter. The Density Exponent parameter controls the shape of the curve relating population density to the reduction in vital rates (see the section below on demography for a more thorough explanation). The Density Exponent will typically fall in a range between roughly 1.0 and 3.0. The amount and spatial distribution of density-dependent feedback affecting the population's vital rates can be quite sensitive to this parameter value.

[+] Per-Hexagon Carrying Capacity

This is the carrying capacity of a single atomic HexSim hexagon with a score of 100. Remember that each fully-resolved hexagonal patch in the bundled Matrices Map contains 91 of these atomic hexagons. Thus, a patch of 91 hexagons, for which each hexagon had a Habitat Map score of 100, would have a carrying capacity of 455. Smaller patches, or patches composed of hexagons with lower Habitat Map scores, will have a lower carrying capacity. HexSimPLE's density dependence model will tend to drive excessively large patch populations back down to their carrying capacity. Because the Habitat Map can by temporally dynamic, any given patch's carrying capacity can change over time.

[+] Min Density Coefficient Fecundity

This parameter sets the smallest value allowed for the density coefficient applied to fecundity. As a patch's population approaches zero, this coefficient will increase to 1.0. As a patch's population reaches carrying capacity, this coefficient will decrease to its minimum value. The reproductive rates are multiplied by the density coefficient, so the rates will be highest when the coefficient is 1.0. Setting this parameter to 0.0, for example, stipulates that the reproductive rates in patches at or above carrying capacity will be reduced to zero. The valid range for this parameter is [0 - 1].

[+] Min Density Coefficient Survival

This parameter sets the smallest value allowed for the density coefficient applied to survival. As a patch's population approaches zero, this coefficient will increase to 1.0. As a patch's population reaches carrying capacity, this coefficient will decrease to its minimum value. The survival rates are multiplied by the density coefficient, so the rates will be highest when the coefficient is 1.0. Setting this parameter to 0.5, for example, stipulates that the survival rates in patches at or above carrying capacity will be reduced by 50%. The valid range for this parameter is [0 - 1].

[+] Percent Stage 0 Dispersing

This parameter is used to determine how many stage class 0 individuals will disperse each time step. This number of individuals will disperse, but this does not guarantee they will leave their patch. Because HexSimPLE is a population model, there are normally no actual individuals to move. So HexSimPLE temporarily creates dispersers when needed, and moves those special individuals. After dispersal, these individuals are absorbed into the matrix associated with their ending patch. The valid range for this parameter is [0 - 100].

[+] Percent Stage 1 Dispersing

This parameter is used to determine how many stage class 1 individuals will disperse each time step. This number of individuals will disperse, but this does not guarantee they will leave their patch. Because HexSimPLE is a population model, there are normally no actual individuals to move. So HexSimPLE temporarily creates dispersers when needed, and moves those special individuals. After dispersal, these individuals are absorbed into the matrix associated with their ending patch. The valid range for this parameter is [0 - 100].

[+] Percent Stage 2 Dispersing

This parameter is used to determine how many stage class 2 individuals will disperse each time step. This number of individuals will disperse, but this does not guarantee they will leave their patch. Because HexSimPLE is a population model, there are normally no actual individuals to move. So HexSimPLE temporarily creates dispersers when needed, and moves those special individuals. After dispersal, these individuals are absorbed into the matrix associated with their ending patch. The valid range for this parameter is [0 - 100].

[+] Percent Stochasticity Fecundity

This parameter determines how much the reproductive rates will vary from one time step to the next. Each time step, this value will be converted into a coefficient that varies between 1-x and 1+x, where x = (Percent Stochasticity Fecundity / 100). This coefficient will then be used to modify the matrices' reproductive rates.

[+] Percent Stochasticity Survival

This parameter determines how much the survival rates will vary from one time step to the next. Each time step, this value will be converted into a coefficient that varies between 1-x and 1+x, where x = (Percent Stochasticity Survival / 100). This coefficient will then be used to modify the matrices' survival rates.

The Event Sequence

The HexSimPLE structure is conceptually straightforward. Some of the model mechanics may appear complex, but that is mostly a consequence of tricking an IBM into behaving like a linked array of population models. The event sequence is broken into distinct parts, using five separate top-level Event Groups. Each of these event groups is discussed below.

Users should not need to change anything about the event sequence except for the three Movement event's Dispersal tab Path Length and Percent Auto-Correlation parameters. These parameters will need to be modified for every simulation. The other parameters associated with movement should not need to be altered by users.

There are also some simple changes users can make to speed up HexSimPLE simulations. These include toggling off any of the dispersal event groups that correspond to stage classes that will not be moving, and toggling off the Construct Output Maps event group when its simulation products are not of interest.

Initialize Simulation

This event group is set to only trigger on time step 1. A Patch Introduction event creates the initial matrix population, one per patch. This is followed by three Accumulate events that record each patch's size, initialize each patch's stage matrix, and set each patch's initial carrying capacity. The Patch Size accumulator is not used in the simulation (every other accumulator is), but is included anyway because patch size is useful information to have easy access to.

Conduct Movement

The Conduct Movement event group consists mostly of three other Event Groups that perform dispersal separately for the three stage classes. These three procedures are bracketed by Accumulate events that perform some simple bookkeeping. The three dispersal event groups are almost identical, so users interested in their mechanics need only examine one in detail. Because these dispersal event groups take time to execute, users may want to toggle them off if their corresponding stage classes are not dispersing.

What makes the dispersal event groups complicated is that they must create, move, record, and destroy new HexSim individuals in order to simulate movement within the overall population model construct. The population that you are actually tracking in a HexSimPLE simulation is a collection of vectors (one per patch), not individuals. But when movement is to be simulated, some of these vector individuals need to be temporarily converted into real HexSim individuals. Then they must move, and finally they must be absorbed into the population vectors associated with the patches they end up in.

First, an Accumulate event computes the stage-specific number of dispersers that will depart from each patch. This value is based on the number of individuals each patch holds that are in the specified stage class, and on the Percent Dispersing model parameters. Then a Propagation event adds the specified number of individuals to each patch. This is followed by a Transition event that labels the newly created individual by assigning them the appropriate stage class. A second Accumulate event is used to set an accumulator to 1.0 for these individuals, and zero for everyone else. This is important for the Generated Hexmap event described below.

Next, a Movement event makes the newly created individuals disperse. Individual dispersal paths are influenced by quality of habitat in the Habitat Map, but they are excluded from zero-valued hexagons in the Matrices map. There is no repulsion in the movement behavior, but there is an attraction to higher-valued habitat hexagons. These dispersers may or may not end up leaving their patches. A Generated Hexmap event then identifies each dispersing individual's final location and increments that hexagon's value using the accumulator that was above set to 1.0. Dispersers are prohibited from entering zero-valued hexagons in the Matrices Map (see the Population Parameters Properties tab), so they are guaranteed to end up in a patch. The Generated Hexmap provides a way of communicating these ending locations back to the patches they stop in. A third Accumulate event uses the Generated Hexmap to increment each patch's population by the number of dispersers that ended up settling there. Finally, a Survival event removes the dispersers.

The Propagation event that creates the dispersers takes advantage of the Locate individuals within Explored Area feature. When this check-box is checked, newly propagated individuals will be located randomly within their mother's explored area. The use of this feature in HexSimPLE ensures that dispersers will depart from a random location within their patch. Otherwise, each individual would depart from its parent's location. In this case, the parents are located in the patch centers.

While it is doing all of this, the dispersal event groups also keep track of the number of emigrants and immigrants, on a patch-by-patch basis. This information is used to construct output Hexmaps that illustrate some of the population dynamics.

Perform Demography

HexSimPLE demography is broken into two parts. First, an Event Group called Set Vital Rates is used to assign values to each matrix element, separately for each patch. A subsequent Event Group called Matrix Multiplication multiplies each patch's matrix by its stage vector, producing a new stage vector.

Leslie matrices are composed of fecundity and survival terms. In HexSimPLE, the vital rates entered as parameters are considered the maximum possible values that can be experienced in an average year. These values are modified by three coefficients:

  • Density        range = [min, 1]
  • Stress         range = [0, 1]
  • Stochasticity  range = [1-x, 1+x]
The density coefficient decreases from 1 to its minimum value (specified by the Min Density Coefficient Fecundity or Min Density Coefficient Survival parameters) as the population in a patch increases from zero to the carrying capacity. The form of the relationship between patch density and the density coefficient is governed by the equation to the right. Here, x, a linear function of patch density, is 0 when a patch is empty and 1 when a patch is at or above carrying capacity. The density coefficient is 1 when y is 1, and decreases to its minimum value when y is o. Alpha is the Density Exponent parameter.

The plot to the right shows this relationship graphically for three values of alpha. The x and y values in the equation correspond to the x- and y-axes in the plot. Decreasing alpha lowers growth rates because the density impacts are experienced at smaller population sizes. As patch density ranges from 0 to carrying capacity, x ranges from 0 to 1. As x ranges from 0 to 1, y ranges from 1 to 0. When y is 1, the density coefficient will also be 1. When y is 0, the density coefficient will be set to its minimum value (either Min Density Coefficient Fecundity or Min Density Coefficient Survival). As population density increases, the rate at which y travels between 1 and 0 is determined by the Density Exponent parameter.

The stress coefficient increases from 0 to 1 as the mean value of the portion of a stress map falling under a patch decreases from 100 to 0. The stochasticity coefficient varies symmetrically around 1.0, and is the only one that can increase the value of a vital rate.

The Matrix Multiplication Event Group essentially multiplies each patch's population vector by its Leslie matrix to obtain an updated population vector. The population vectors hold the number of stage class 0 (juvenile), stage class 1 (subadult), and stage class 2 (adult) individuals. At this point, the patches' Leslie matrices have already been modified by the density, stress, and stochasticity coefficients.

The three remaining Data Probe events write the fecundity coefficients and final values, the survival coefficients and final values, and several measures of population size and productivity. These data will be stored in three different CSV files, within the simulation results.

Get Output Map Data

HexSimPLE simulations construct 6 separate output Hexmap time series that display:

  • Population size
  • Cumulative population size
  • Population density
  • Cumulative population density
  • Cumulative productivity (births - deaths)
  • Cumulative productivity (emigration - immigration)

The data used to develop these maps is generated in other parts of the simulation. For example, the Perform Demography event group generates the births and deaths tallies, and the Conduct Movement event group tracks emigration and immigration. This Event Group gets these data ready for the Generate Hexmap events that actually construct the output imagery.

A HexSim feature made constructing the productivity maps a bit complicated. When HexSim displays maps that are part of a time series, the color scale is set to the global minimum and maximum values. This can interfere with the display of a time series in which some maps have small hexagon scores (in magnitude), and other maps have large scores (positive or negative). The maps with small scores will be displayed using just a portion of the color scale. For example, suppose the color ramp being used goes from blue-yellow-red. And suppose a Hexmap time series contains two maps, the first having values between -1 and +1, and the second having values between -10 and +10. When the second map is displayed, the full spectrum of colors will be observed, with the hexagons scored -10 shown in blue and the hexagons scored +10 shown in red. But when the first map is displayed, all the hexagons will appear in shades of yellow because they all fall roughly in the center of the range -10 to +10.

The map of cumulative population size doesn't suffer from this problem because the Generated Hexmap event that creates it uses the scaling tool to ensure that every individual map ranges between 0 and 100. But this scaling tool isn't useful when the hexagon scores are both positive and negative. So some extra machinery was developed for HexSimPLE that automatically re-scales the two cumulative productivity Hexmap time series. For those interested in the details, HexSimPLE is tracking the positive and negative cumulative productivity scores separately. This allows the two ranges of scores to be re-scaled independently, and then added back together later on when the actual Hexmaps are written to the results.

The maps of population density and cumulative population density are useful when the patches owned by individual matrices have different sizes. These maps are generated by dividing the population size, or cumulative population size, by the individual patch areas (in hexagons).

Generate Output Maps

This Event Group contains 4 Generated Hexmap events that actually create HexSimPLE's output imagery. As described in the preceding section, these events would all be extremely simple if no attempt had been made to re-scale the productivity Hexmaps. This can be seen in the two events that map population size, which are both quite straightforward.

The two Generated Hexmap events that map productivity have to do a bit more work. They round and then re-scale the positive and negative portions of the maps separately, and then sum the two parts. This technique produces a time series of productivity Hexmaps in which every individual map has hexagons ranging between -100 and +100. When displayed, for example, in the Simulation Viewer tool, these productivity maps will provide the maximum possible contrast.

Post-Breeding Census versus Pre-Breeding Census

HexSimPLE emulates matrix multiplication, though it does this separately within each habitat patch, and adds a spatially-explicit individual-based dispersal process for additional realism. For simplicity, HexSimPLE assumes the sub-population in each patch is composed of 3 distinct stage classes. The numbers of individuals in each stage class is represented by a vector with 3 elements, and a dimension-3 Leslie matrix is used to project the stage vector for time T forward to time T+1.

Matrix multiplication, used for population projection, necessitates making the assumption that survival, reproduction, and the shifting of individuals between stage classes can be be collapsed into a single event per time step. There are three processes that take place simultaneously when a Leslie matrix multiplies a population vector to produce a new population vector (representing the subsequent time step). The first process is reproduction, which is controlled by the top row of the matrix. The second process is survival, which is controlled by the remaining rows in the matrix. The final process captures the aging or growth of individuals, causing them to shift into subsequent stage classes. Importantly, new individuals added to the population by the reproduction process should experience mortality. But if the top row of the Leslie matrix contains only fecundity terms, then the newborn individuals will not experience any mortality whatsoever until their second year of life.

When projection matrices (including the Leslie matrices discussed here) are constructed from empirical data, this issue of mortality in the first year of life must be addressed. In most cases, this done using one of two alternative approaches. The difference between these approaches stems from the interpretation of the stage class vector used to represent population size. When researchers census populations exhibiting pulsed breeding events (e.g. one reproductive event per year), they typically perform this census either just before the breeding pulse, or just after the breeding pulse.

When a census is taken just before the breeding pulse, the youngest individuals will have been alive for almost a full time interval (these individuals were born in the previous time step, so now they are about to turn one). There are no true newborns represented in such a census. The youngest individuals in the census represent actual individuals who by then will have already experienced the mortality expected for stage class 0. This is referred to as a pre-breeding census.

When the census is taken just after the breeding pulse, the youngest individuals will be at the very beginning of their life. The youngest individuals in the census represent actual individuals who have not yet have experienced the mortality expected for stage class 0. This is referred to as a post-breeding census.

The decision about whether the projection matrix you construct should reflect a pre-breeding or post-breeding census should be made based on the empirical data being used to estimate the vital rates. The post-breeding structure is commonly encountered and a bit more intuitive, so the HexSimPLE model has been assembled to simulate a post-breeding census.

The figures below illustrate the differences between 3-stage Leslie matrices developed for post-breeding and pre-breeding censuses. In both cases, the life cycle involves just reproduction, survival, and transitioning between stage classes, since that is specifically what projection matrix multiplication accomplishes. The differences between the two cases stem from the timing of the census. In the post-breeding census case, the census is conducted just after reproduction. Thus the life cycle can be thought of as consisting of the steps:

  • Census
  • Survival
  • Reproduction
  • Transition
  • repeat...

In the pre-breeding census case, the census takes place just before reproduction. Thus the life cycle can be thought of as consisting of the steps

  • Census
  • Reproduction
  • Transition
  • Survival
  • repeat...


In a post-breeding census, we count the population just before survival. Then the first computation involves multiplying each element of the just-measured stage vector by the corresponding survival rate. This step is represented in the figure above by the stage vector with the yellow, blue, and green cells. Next, the reproductive output of the surviving individuals is summed and placed into the juvenile location in the new stage vector (see the yellow cell in the top matrix, above). Finally, the surviving juveniles (stage 0 individuals) are shifted to the subadult location in the new stage vector, and the surviving subadults and adults (stages 1 and 2) are summed and placed into the adult location in the new stage vector. This last step is indicated by the blue and green cells in the top matrix, above.

For a post-breeding census, the population's transition between time steps can be captured using a Leslie matrix with the structure shown at the bottom of the figure.



In a pre-breeding census, we count the population just before reproduction. The first computation involves multiplying each element of the just-measured stage vector by the corresponding reproductive rate. These reproductive outputs are indicated in the figure above by the stage vector with the yellow, blue, and green cells. Next, the total number of offspring is obtained by summing the output from each stage class (the yellow, blue, and green cells in the top matrix, above). Then, individuals are transitioned into the subsequent stage classes. The new juveniles are assigned to stage-0, the previous time step's juveniles are assigned to stage-1, and the previous time steps's subadults and adults are shifted into stage-2. Finally, the stage-0 mortality rate (S0) is imposed upon the new juveniles, the stage-1 mortality rate (S1) is imposed upon the new subadults, and the stage-2 mortality rate (S2) is imposed upon the adults. Note that the survival terms (shown in red in the above figure) are not arranged in the same order as the survival terms in the post-breeding Leslie matrix.

For a pre-breeding census, the population's transition between time steps can be captured using a Leslie matrix with the structure shown at the bottom of the figure.


Note that the Leslie matrices derived based upon post-breeding and pre-breeding assumptions will produce exactly the same population growth rates. Their lambda values will be identical.

Customizing and Running HexSimPLE

To construct a custom application from the template, users must supply these items:

  • A habitat map
  • A patch map
  • Three fecundity estimates
  • Three survival estimates
  • Ten other simulation parameters

The simulation parameters are described in the section above titled The Population Parameters.

Users must also generate three additional maps:

  • Stress impacts on fecundity
  • Stress impacts on reproduction
  • Movement barriers

But the stress maps can consist entirely of zeros, and the barrier map need not include any barrier segments.

All of the maps listed above may be dynamic time series except for the patch map, which is used to designate the matrix locations.

In addition, users will want to customize the Movement events, of which HexSimPLE has three. However, many HexSimPLE applications will not use all three Movement events. When a Movement event is modified, only the Path Length and Percent Auto-Correlation parameters should be changed.

When you download HexSimPLE, you will have examples of all the input maps and parameter values. This should help you become familiar with what is needed to develop your own custom application of the model.

Note that placing the HexSimPLE template within a new workspace is likely to cause the Maximum Range Area parameter to change. This value is stored in the XML file as a number of hectares, but its representation in hexagons is a function of the workspace's hexagon size. The HexSim template uses a Maximum Range Area of 1 hexagon, and a Maximum Range Span of 0. While these parameters will not affect the simulations (HexSimPLE individuals are always floaters), it is minimally-confusing if they are assigned simple null values.

Analyzing HexSimPLE Results

As delivered, the HexSimPLE template is highly stochastic and the results will differ considerably from replicate to replicate. If you run a single iterate of this model, the results you obtain may be quite different than those depicted below.

HexSimPLE simulations produce the following outputs:

  • Generated Hexmap time series for population size
  • Generated Hexmap time series for cumulative population size
  • Generated Hexmap time series for population density
  • Generated Hexmap time series for cumulative population density
  • Generated Hexmap time series for cumulative productivity (births - deaths)
  • Generated Hexmap time series for cumulative productivity (emigration - immigration)
  • Data Probe population size metrics
  • Data Probe fecundity metrics
  • Data Probe survival metrics
  • A log file

The Data Probe metrics are all contained in a folder called Data Probe that resides within the simulation results folder. The population size metrics are in a file called "Matrices-[Perform Demography] Census Population-accumulators.csv". This CSV file has the following data columns:

  • Replicate
  • Time Step
  • Population
  • Individual ID
  • Number Stage 0
  • Number Stage 1
  • Number Stage 2
  • Number Total
  • Number Births
  • Number Deaths
  • Number Emigrants
  • Number Immigrants

For each replicate and time step, there will be a row for every patch in the patch map. This file can be used to generate the basic population size data that you will want to examine. But before a plot can be made of population size vs. time step, the data in this file corresponding to each unique replicate-time step combination must be summed. This can be done easily using the program called read_data_probe.c that is available from the Utilities page of this website.

At this point, it is worth mentioning that there is no easy way to produce a HexSim census that would package this information in a ready-to-plot format. This is because the individuals in HexSimPLE are just objects that store counts representing the number of each patch's juveniles, sub-adults, and adults. So there are no actual juveniles, sub-adults, or adults to census, except momentarily when movement is being conducted.

The Data Probe fecundity and survival metrics are stored in files named "Matrices-[Perform Demography] Census Vital Rates [ fecundity ]-accumulators" and "Matrices-[Perform Demography] Census Vital Rates [ survival ]-accumulators". These two CSV files store the fecundity and survival coefficients, and the final Leslie Matrix elements. The read_data_probe.c utility mentioned above will also be useful for working with these simulation products.

The four generated spatial data time series produced by HexSimPLE simulations display population size and productivity. One Hexmap series shows the current population size at each time step. Another series shows the cumulative population size. Both are re-scaled to ensure that the range of values always falls between 0 and 100. Both of the productivity maps display cumulative values. One is constructed using births - deaths, while the other is constructed from emigration - immigration. At steady-state, these measures of productivity will be essentially identical. When a model is far from steady-state, they can differ significantly. Both of these Hexmap time series are re-scaled so that every individual map ranges between -100 and +100. The two Hexmaps displayed above are showing cumulative population size (top) and emigration - immigration (bottom).

Finally, the log file produced by HexSimPLE simulations can be used to generate reports and tallies, and to drive the Simulation Viewer. Given the structure of HexSimPLE, the Dispersal Flux tally will probably be the most useful post-simulation product that can be generated from the log file. But using the Simulation Viewer to visualize movement should also be extremely informative.