The HexSimPLE Scenario


Introduction

HexSimPLE is a flexible template within which users can rapidly construct spatially-explicit metapopulation models. HexSimPLE models consist of a distributed array of Leslie matrices that are linked by movement.

Each of HexSimPLE's Leslie matrices is of dimension 3, corresponding to a stage-stratified population of 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 edited a bit to add extra stage classes.

The HexSimPLE model has been designed with the intent that the population vector represents a post-breeding census. This means specifically that the fecundity terms used to simulate matrix multiplication will be discounted by the corresponding survival rates. For example, the stage-2 reproductive output will be computed as (number of stage 2 individuals) x (survival rate for stage 2 individuals) x (fecundity of stage 2 individuals). Of course, the number of individuals, the survival rate, and the fecundity, will vary from place to place, and from time to time.

To construct a custom application from the template, users must supply a habitat map, and a map indicating where each Leslie matrix is to be located. Optionally, users may also supply separate maps of spatially distributed stressors impacting survival and reproduction, and a map of movement barriers. These three optional maps must exist in the workspace, but the stress maps can consist entirely of zeros, and the barrier map need not include any barrier segments. All of these maps may be dynamic time series except for the map designating the matrix locations, which must be static. Users must also assign values to 16 parameters, and customize the Movement events. But otherwise, it should not be necessary to modify the HexSimPLE population parameters or the event sequence.

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. And HexSimPLE models 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 overall program.

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 is developed, then all of the workspace spatial data will have to be re-created. The discussion below should help users with this initial step. The actual workspace construction process is described in the User's Guide, and is not repeated here.

The Matrices Map

The Matrices Map determines where to place the Leslie matrices that hold HexSimPLE's plant or animal population. The Matrices Map must contain a collection of patches, with a 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 the Matrices Map supplied with HexSimPLE is shown on the right. The patches have a hexagonal shape because they are assembled from concentric rings of hexagons. Each of the full size patches is made up from 91 individual hexagons. The colors shown are correlated with the hexagon scores, which by definition are the same across each patch. The patch ID (the score of the hexagons from which it was constructed) was randomized to make the patch structure easier to visualize. There is no reason why the patches should not extend all the way to the landscape boundaries. The patches along the edges were trimmed away to make the point that HexSimPLE doesn't care how this map is constructed. Smaller patches will contain less habitat, have a lower carrying capacity, and thus contribute proportionally less to the population than larger patches.

The Matrices Map shown above consists of 99 patches. Its will make HexSimPLE distribute 99 Leslie matrices across the landscape. The zero-valued background hexagons will be excluded from HexSimPLE simulations, meaning matrices will not be located in these areas, and dispersers will not be allowed to move to them. The Leslie matrices will not extend into zero-valued hexagons, and individual dispersers will be restricted from entering these hexagons.

The HexSimCommandLine.exe tool (supplied with HexSim) contains two utilities for constructing patch maps similar to those displayed here. 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 a stand-alone algorithm called build_hexmap_hexagons.c that is available from the Utilities section of this website. An analogous tool there called build_hexmap_blocks.c can be used to develop a space-filling map of rectangular patches. The Matrices Map included with HexSimPLE was further modified when some perimeter patches were removed, and the patch IDs were randomized.

The Matrices Map must not be a time series. That is, it must include a Hexmap only for time step 1.

The Habitat Map

The Habitat Map (shown on the right) is used to set a per-patch or per-Leslie matrix carrying capacity, but it also influences dispersal behavior. One Leslie matrix will be assigned to each patch, so the terms matrix and patch can be used interchangeably. The habitat map's hexagon scores must fall between 0 to 100. HexSimPLE will assume that a hexagon score of 100 represents optimal habitat, and a score of 0 represents non-habitat. The vital rates provided to the model interface will be realized in optimal habitat, and they decline as habitat quality drops to zero. The form of the function linking vital rates to patch quality depends on the Density Exponent and Min Density Coefficient parameters. Dispersers will be increasingly attracted to better habitat, with the amount of attraction increasing linearly from zero towards non-habitat to a maximum towards hexagons with a score of 100. The HexSimPLE model is not set up to use repulsion in Movement, though this can easily be changed.

HexSimPLE habitat maps may be binary, identifying only habitat versus non-habitat areas. In such cases, the habitat hexagons should be scored 100. The Habitat Map may be a dynamic time series.

The Habitat Map bundled with HexSimPLE is artificial, and was developed from the image named Jackson Pollock 4.bmp, which is available in the Bitmaps.zip download on the Accessories page of this website.

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 process used to create the stress maps bundled with HexSimPLE is described in the Build Patch Map and Build Stress Maps sections of this website.

The stress maps that come with HexSimPLE are artificial, as are all of the spatial data included in this workspace. Users developing their own applied HexSimPLE models will want to replace the patch map with, for example, a map in which the patches delineate natural areas and agricultural fields. Then, the stress maps might provide a spatial depiction of pesticide impacts on species' survival and reproductive rates, which could vary by chemical, application rate, and application timing. Many other examples could be developed, but the main point is that HexSimPLE gives you a straightforward mechanism for imposing any spatially distributed disturbance regime on a population of interest.

Zero-valued hexagons in the Stress Map will not impose any stress upon the population. Therefore, turning of one of the disturbance processes is done by setting the corresponding stress map's hexagons all to zero. The Stress Map Survival Hexmap bundled with HexSimPLE provides an example.

The Movement Barriers Map

The HexSimPLE Movement Barriers map makes it easy to incorporate the impacts of movement barriers on a simulation. The Movement Barriers map bundled with HexSimPLE provides a simple illustration of HexSim barrier maps. In this map, all of the barrier edges are associated with a single category pair, and they impose a 10% probability of mortality and 90% probability of deflection. The barriers were drawn so as to coincide with features found in the Habitat Map, but were then adjusted to fall along the patch boundaries. The HexSimPLE scenario expects its workspace to include a Movement Barriers map, but users who have no need for movement barriers can just simply use an empty barrier map.

In HexSimPLE simulations, barriers that subdivide patches will exhibit a counter-intuitive property. Such barriers will impact individuals moving throughout the landscape exactly as anticipated. But the Propagation event that creates these dispersers will place them at random locations within their starting patches. Dispersers leaving a patch bisected by a barrier may begin their movements from either side of the barrier. Thus for emigration, patch-bisecting barriers will appear permeable, while for immigration they will function normally. The solution to this complication is to ensure that HexSimPLE barriers are always placed along patch edges, or between patches (if the patches are not space-filling).

The Population Parameters

The only part of HexSimPLE's Population Parameters that users should need to modify are the 16 accumulators that hold model parameters. These special accumulators have names that begin with the string [+], which makes them easy to identify. The 16 HexSimPLE parameters are described below. In the Population Parameters Traits tab, these accumulators are listed in alphabetic order. Here, they are instead organized by topic.

[+] 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.

[+] Stage 0 Fecundity

Stage 0 Fecundity specifies the number of female offspring per Stage 0 female. HexSimPLE is a females-only model, so this parameter really specifies the juvenile reproductive rate. This value will be modified due to density dependence, disturbance, and environmental stochasticity. HexSimPLE assumes the population vector represents a post-breeding census, so this fecundity term will be discounted by the stage-0 survival rate.

[+] Stage 1 Fecundity

Stage 1 Fecundity specifies the number of female offspring per Stage 1 female. HexSimPLE is a females-only model, so this parameter really specifies the subadult reproductive rate. This value will be modified due to density dependence, disturbance, and environmental stochasticity. HexSimPLE assumes the population vector represents a post-breeding census, so this fecundity term will be discounted by the stage-1 survival rate.

[+] Stage 2 Fecundity

Stage 2 Fecundity specifies the number of female offspring per Stage 2 female. HexSimPLE is a females-only model, so this parameter really specifies the adult reproductive rate. This value will be modified due to density dependence, disturbance, and environmental stochasticity. HexSimPLE assumes the population vector represents a post-breeding census, so this fecundity term will be discounted by the stage-2 survival rate.

[+] Stage 0 Survival

Stage 0 Survival specifies the rate at which juvenile individuals transition into subadults. The quantity (1.0 - [+] Stage 0 Survival) is the juvenile mortality rate. This value will be modified due to density dependence, disturbance, and environmental stochasticity.

[+] Stage 1 Survival

Stage 1 Survival specifies the rate at which subadult individuals transition into adults. The quantity (1.0 - [+] Stage 1 Survival) is the subadult mortality rate. This value will be modified due to density dependence, disturbance, and environmental stochasticity.

[+] Stage 2 Survival

Stage 2 Survival specifies the rate at which adult individuals remain in the adult class. The quantity (1.0 - [+] Stage 2 Survival) is the adult mortality rate. This value will be modified due to density dependence, disturbance, and environmental stochasticity.

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 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.