HexSimPLE

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 Barrier

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 must 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 meaningful 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 typically not be necessary to modify the HexSimPLE population parameters or the event sequence. The parameters that must be specified are summarized here, and described in greater detail 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

• Initial Population Size

• Data Sampling Delay

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, and the documentation here assumes a basic working knowledge of the application.

HexSimPLE makes use of numerous HexSim tricks that will likely be new to some users. But most of the processes that HexSimPLE works hard to accomplish are much easier to implement in a normal individual-based HexSim model. Thus we caution readers that HexSimPLE is in many ways a poor example of HexSim model design strategies. On the other hand, users wanting to significantly customize HexSimPLE will need to first carefully dissect its parts. 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, and of course the HexSimPLE model itself must be copied into the Scenarios folder. 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 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 never be assigned to the zero-valued (gray) hexagons. Because exactly one Leslie matrix will be assigned to each patch, the terms Leslie matrix and patch will at times be used interchangeably. Throughout this document, use of the terms patch, patches, or patch map should be assumed to be references to the contents of the Matrices Map, unless otherwise indicated.

The HexSimCommandLine.exe tool (supplied with HexSim) contains two utilities for constructing patch maps. The first is accessed by running HexSimCommandLine.exe 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 construct the full-size patches that are not clipped by the workspace boundaries. 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.

The Habitat Map

The Habitat Map is used to obtain the total resource quality of each patch and thus its carrying capacity. Patch quality in-turn influences the Leslie matrix vital rates, emigration rates, movement behavior, and density dependence. Every 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 Habitat Map may be a 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 the score of every non-zero hexagon to 1. This would create a map with one patch, and hence one region. There is presently no mechanism in HexSimPLE to ensure that nearby regions experience relatively similar environmental conditions. Further, within a region, survival and reproductive rates will be perfectly correlated, so a good year for survival will always be a good year for reproduction too, etc. 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. Therefore the stress maps must 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. Note therefore that for the stress maps, a value of 1 indicates zero stress, and a value of 0 implies maximal stress.

Since the stress maps are used to generate coefficients that multiply the vital rate parameters, they can also be used to supply the input vital rates to HexSimPLE in map format. To do so, users must take the steps outlined below. In this example, we assume that survival rates are to be coded into the Stress Map Survival time series, and that in optimal conditions the three survival parameters are to be: 0.3, o.6, and 0.9 for juveniles, subadults, and adults, respectively.

• Set the parameter Survival [ stage 2 ] to 1.

• Set the parameter Survival [ stage 1 ] to 0.6/0.9 = 2/3.

• Set the parameter Survival [ stage 0 ] to 0.3/0.9 = 1/3.

• Construct Stress Map Survival from a copy of the Matrices Map.

• Edit Stress Map Survival to assign each patch the desired adult survival rate.

• Repeat the previous step as needed if the stress map is a time series.

Since fecundity values often exceed 1, stress maps used to supply reproductive rates should not be constrained to the range 0-1. Of course, these types of modifications can also be achieved by altering the HexSimPLE model structure, making it obtain vital rates directly from separate maps or lookup tables instead of global parameters But the method outlined above does not require anywhere near that level of effort. The Stress Maps may be dynamic time series.

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

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, Matrix Map patches 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, which can be found at the Utilities section of this website, were developed to automate this process. The patch-dividing algorithm is illustrated above in the transition between the left and center images. In this case, the algorithm broke apart the yellow, blue, and light green patches. 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 Movement Barriers map may be a dynamic time series, but if the barrier locations are changed, that will likely produce conflicts with the Matrices map, which must be static. Users can safely make use of a dynamic Movement Barriers map time series to change barrier properties but not barrier locations. If barrier locations change dynamically, the Matrices map should be constructed to avoid having patches ever span barriers at any time step.

HexSimPLE Parameters

HexSimPLE's main parameters are stored in 15 Global Variables. Users will definitely want to modify most if not all of these values. HexSimPLE's parameters are all discussed below, though multiple parameters are often 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. These global variables have the following names:

• Fecundity [ stage 0 ]

• Fecundity [ stage 1 ]

• Fecundity [ stage 2 ]

The default values of these parameters are 0, 0.75, and 1.5. 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 all be discounted by the stage-0 survival rate. The differences between matrix models based on a post-breeding versus a pre-breeding census are discussed at the end of this web page.

Survival

Three parameters are also used to store the stage 0 (juvenile), stage 1 (subadult), and stage 2 (adult) survival rates:

• Survival [ stage 0 ]

• Survival [ stage 1 ]

• Survival [ stage 2 ]

The default values of these parameters are 0.85, 0.95 and 095. 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-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.

These exponents are used to modify each matrix's vital rates based on the resource quality in that location. This is done by converting habitat quality into a coefficient ranging from 0 to 1 using a function influenced by the exponent (see figure to the right). The relationship between habitat quality and the vital rates is given by:

rq = ro [ 1 - (1 - q)η ]

Where q is a patch's mean habitat quality, η is the habitat exponent associated with either fecundity or survival, ro is a survival or fecundity rate 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 ranging from linear, when η = 1, to a bimodal step function when η approaches infinity. By selecting a specific habitat exponent, users are effectively setting a habitat quality below which survival or fecundity rates begin dropping rapidly.

Concave curves can be generated by setting the habitat exponent to a fractional value between 0 and 1, but doing so may not be biologically meaningful. The habitat exponents do not affect carrying capacity, which scales with the sum (not mean) of a patch's habitat quality scores.

Percent Stochasticity

HexSimPLE allows users to add environmental stochasticity to simulations, and does this separately for fecundity and survival. There are two global variables governing stochasticity:

• Percent Stochasticity [ fecundity ]

• Percent Stochasticity [ survival ]

The default value of each parameter is 10%.

These parameters determine how much each patch's survival or reproductive rates will vary from one time step to the next, reflecting for example year to year variability in weather. HexSimPLE converts these two parameters into coefficients that vary randomly between 1-x and 1+x, where x = (Percent Stochasticity / 100). Each time step, every stochasticity region is assigned a single value, drawn from a uniform distribution, that represents the degree to which the area it represents is experiencing good or bad environmental conditions. This single random value is used to generate the stochasticity coefficients for both survival and reproduction, which are therefore perfectly correlated. The two stochasticity coefficients are subsequently used to modify projection matrix's three fecundity and three survival rates.

Note that HexSimPLE users must supply a "Regions Map" and that the amount of environmental stochasticity imposed upon individual projection matrices will be computed separately for each region. When a matrix's patch spans multiple regions, the amount of stochasticity it actually experiences will be the spatially-weighted average of the coefficients associated with each region it overlaps. The Regions Map may contain just a single region, which would ensure that all matrices vary up and down in synchrony. HexSimPLE presently has no mechanism allowing users to correlate the environmental conditions assigned to nearby regions.

Users wishing to turn off environmental stochasticity can simply set one or both stochasticity parameters to zero.

Dispersal Min & Max

When individuals in a HexSimPLE simulation move, the distance they travel (in hexagons) will be bounded by the two model parameters called:

• Dispersal Minimum [ hexagons ]

• Dispersal Maximum [ hexagons ]

The default values for these parameters are 5 and 25 hexagons. Every individual that moves will separately select a movement path length from a uniform distribution bounded by these two parameter values. The value chosen will determine how far that individual travels at that particular moment in time. The further individuals move, the more likely they will be to leave their current sub-population (e.g. matrix or patch) and travel to another sub-population elsewhere in the landscape. However, the dispersal path length is not the same as displacement distance, and the actual straight-line distance moved will depend on the path length, the degree of spatial auto-correlation, and other movement parameters such as repulsion and attraction.

The movement process itself is discussed in greater detail below.

Carrying Capacity

A single parameter is used to relate landscape carrying capacity to habitat quality:

• Carrying Capacity [ per-hexagon ]

The default value of this parameter is 0.04. This parameter defines the number of individuals that can be supported per single atomic hexagon when that hexagon has the maximum score of 1.0. Each patch will set it's own carrying capacity by multiplying the per-hexagon maximum carrying capacity (this parameter) by the sum of the scores of the hexagons it contains, as determined by the Matrices and Habitat maps. For example, the HexSimPLE workspace's default Matrices Map has a maximum patch size of 625 hexagons, thus the maximum patch quality would be 625 (assuming every hexagon had a habitat score of 1.0). The maximum carrying capacity capacity for this example is therefore 0.04 x 625 = 25 individuals. Many patches will have a habitat sum falling below the maximum, and will therefore have a lower carrying capacity.

After the HexSimPLE model conducts movement, it culls individuals to bring any overly-dense patches back down to carrying capacity.

Initial Population Size

HexSimPLE uses a single parameter to set the initial population size:

• Initial Population Size [ per matrix ]

The default value of this parameter is 10 individuals. This parameter determines the number of individuals that will be added to each patch's population vector when the HexSimPLE simulation starts up. When the model begins, every one of these individuals will be an adult.

Begin Sampling

A single parameter is used to delay the construction of generated hexmaps for the quantities Cumulative Population Size, Cumulative Productivity, and Cumulative Dispersal Flux:

• Begin Sampling [ cumulative hexmaps ]

The default value of this parameter is 10 time steps. The values in these cumulative maps are not meaningful when a HexSimPLE simulation starts up because there is no history then with which to construct them. When the simulation time step is less than this parameter value, these generated hexmaps will be blank.

The Event Sequence

The HexSimPLE structure is conceptually straightforward. Some of the model mechanics will appear complex, but that reflects the need to trick an IBM into behaving as an 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 some of the machinery controlling Movement. Users will frequently want to open the movement event groups, locate and open the Movement events themselves, go to the Dispersal tab, and update the auto-correlation parameter values. Doing so is straightforward

Lastly, some simple changes can make to speed up HexSimPLE simulations. These include toggling off some movement-related event groups (e.g. the red and blue event groups in the image above affecting subadults and adults), and possibly toggling off the Construct Output Maps event group if the simulation products it constructs are not of interest. The Construct Output Maps event group is not visible in the image above.

Initialize Simulation

This event group is set to only trigger on time step 1. Two Patch Introduction events creates the initial matrix and region populations, one per patch found in the Matrices and Regions maps, respectively. These are followed by three Accumulate events that record each of the Matrix map patch sizes, initialize each patch's stage vectors, and set each patch's initial carrying capacity.

Conduct Movement

The Conduct Movement event group consists mostly of three event groups that recruit individuals, plus three event groups that perform dispersal. These procedures are preceded by Accumulate events that perform some simple bookkeeping. The various recruitment and dispersal event groups are almost identical, so users interested in their mechanics need only examine one of each in detail. Because these event groups take time to execute (particularly dispersal), users may want to toggle them off if their corresponding stage classes are not moving.

What makes the movement event groups complicated is that they must create, move, record, and destroy HexSim individuals in order to simulate individual-based movement within a population model. 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.

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.

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. By default, there is no repulsion in the dispersal behavior, but there is an attraction to higher-valued habitat hexagons and a moderately high level of auto-correlation. Dispersers may or may not end up leaving their patches. A Generated Hexmap event is used to identify each dispersing individual's final location, so it can be absorbed into the appropriate population vector. A Survival event is used to remove the dispersers.

While doing all of this, the movement 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.

The Set Vital Rates event group adjusts the input vital rates based on each patch's habitat quality, its exposure to stress, and in order to account for environmental stochasticity. Leslie matrices are composed of fecundity and survival terms. Ignoring stochasticity, the vital rates entered as parameters represent the maximum values that can be experienced in any patch. That's because these input parameters set the rates that will be observed in ideal habitat absent of any stress -- in sub-optimal or stressed habitat areas these vital rates will decline. The stochasticity coefficients vary symmetrically around 1.0, thus they have the unique ability to increase a vital rate beyond the parameterized value.

Each Leslie matrices' adjusted survival and reproductive rates 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 parameterized 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 for both fecundity and survival as long as the relevant input parameters are set to 1.0.

The Matrix Multiplication event group multiplies each patch's population vector by its Leslie matrix, thus producing an updated population vector corresponding to the subsequent time step. The population vectors hold the number of stage class 0 (juvenile), stage class 1 (subadult), and stage class 2 (adult) individuals. Matrix multiplication is performed after the Leslie matrices have been modified due to habitat quality, stress, and stochasticity.

The three remaining Data Probe events write the fecundity coefficients and adjusted fecundity values, the survival coefficients and adjusted survival values, plus several measures of population size and productivity. These data are 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 Get Output Map Data event group compiles the data used to develop these maps, and gets this information ready for the Generate Hexmap events that write out the imagery. These Generate HexMap events are collected into a separate top-level event group, which is done to give user's the option to speed up simulations using event triggering (writing generated hexmaps can be time-consuming).

A HexSim feature made constructing the two productivity maps a bit complicated. When HexSim displays maps that are part of a time series, the color scale is set to match the global minimum and maximum values. This can complicate the display of a time series in which some maps have small hexagon scores and other maps have large scores (positive or negative). The maps with small scores will end up utilizing just a portion of the color scale. For example, suppose the color ramp being used ranges from blue to yellow to 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 its built-in scaling tool to ensure that every individual map ranges between 0 and 100. But this scaling tool isn't useful when a map's 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, you'll find that HexSimPLE is tracking the positive and negative cumulative productivity scores separately, and then re-scaling them independently. This way the entire time series can be re-scaled to exhibit both common largest negative and largest positive values.

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

Construct Output Maps

This event group contains the six Generated Hexmap events that write 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. For example, the two events that map population size are both quite straightforward. In contrast, the two Generated Hexmap events that map productivity are a bit more complex.

Users wanting to speed up HexSimPLE simulations can toggle this event group off, or use event triggering to limit the number of times it is executed.

Customizing and Running HexSimPLE

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

• A habitat map

• A patch map (the Matrices map)

• Three fecundity estimates

• Three survival estimates

• Nine other simulation parameters

The simulation parameters are described in the section above titled The Population Parameters. Users must also generate four additional maps:

• Stress impacts on survival

• Stress impacts on reproduction

• A map of stochasticity regions

• Movement barriers

But the stress maps can consist entirely of zeros, the regions map may consist entirely of ones, and the barrier map need not include any barrier segments. All of the maps listed above may be dynamic time series except for the Matrices and Regions maps.

Users may also want to customize the Movement events, of which HexSimPLE has three. However, many HexSimPLE applications will not necessitate use of all three Movement events. When a Movement event is modified, the Percent Auto-Correlation parameter will typically be the only value that is changed.

Note that placing the HexSimPLE template within a new workspace is likely to cause the Maximum Range Area parameter to change (in the Population Parameters Range Data tab). This value is stored in the XML file as a number of hectares, and switching workspaces can cause it to become invalid. 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), assigning them simple null values can minimize confusion.

Analyzing HexSimPLE Results

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 contains the following data columns:

• Replicate

• Time Step

• Population

• Individual ID

• Carrying Capacity

• 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, this file will include one row for every patch in the patch map. This file is used to generate basic population size data for plots, etc. But before a plot can be made of population size through time, the data in this file corresponding to each time step must be summed across all patches. This can be done easily using the program called read_data_probe.c that is available from the Utilities page of this website. In this case, users will want to call read_data_probe with the sum flag.

In a traditional HexSim simulation, population size data would be obtained from Census events in a ready-to-plot format. In HexSimPLE simulations, this data must be derived from Data Probe output because HexSimPLE individuals are really objects that store counts representing the each patch's juvenile, subadult, and adult numbers. There are no actual juveniles, subadults, or adults to census, except momentarily when movement is being conducted. HexSimPLE does use a Census event to count the number of dispersers created during movement.

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. In these cases, users will want to call read_data_probe with the mean flag.

Post-Breeding Census versus Pre-Breeding Census

HexSimPLE emulates matrix multiplication, though it does this separately within each habitat patch, and adds individual-based dispersal to increase realism. For simplicity, HexSimPLE assumes the sub-population in each patch is composed of 3 distinct stage classes. The number of individuals in each stage class is represented using a "stage 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.

Replicating matrix multiplication in HexSimPLE necessitates making survival, reproduction, and the transition of individuals between stage classes function as if they were performed simultaneously, since this is the case when a Leslie matrix multiplies a population vector. Reproduction is controlled by the top row of the matrix, while survival and transition are controlled by the remaining rows. 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. This is typically done using one of two alternative approaches. The difference between these approaches stems from the interpretation of the stage vector used to represent population size. When researchers census populations exhibiting pulsed breeding events (e.g. one synchronized reproductive event per year), they typically perform this census either just before 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 (they were born in the previous time step and are about to turn one). So these individuals will already have experienced the mortality that has been associated with 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 lives. These individuals will not yet have experienced the mortality associated with 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. However, the post-breeding census matrix structure is commonly encountered and a bit more intuitive, so HexSimPLE has been designed 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 illustrations include reproduction, survival, and transitions between stage classes. The differences between the two cases stem entirely from the timing of the census.

In the post-breeding census case, the census is conducted just before survival. Thus the life cycle can be thought of as consisting of the following steps:

Post-Breeding Census

• Census

• Survival

• Reproduction

• Transition between stage classes

• repeat...

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 position (the top) in the new stage vector. Finally, the surviving juveniles are shifted to the subadult location (the middle) in the new stage vector, and the surviving subadults and adults are summed and placed into the adult location (the bottom) in the new stage vector.

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

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 following steps:

Pre-Breeding Census

• Census

• Reproduction

• Transition between stage classes

• Survival

• repeat...

The first computation involves multiplying each element of the just-measured stage vector by the corresponding reproductive rate. This step is represented in the figure above by the stage vector with the yellow, blue, and green cells. The total number of offspring is obtained by summing the output from each stage class. Then, individuals are transitioned into their new stage classes. The just-born individuals are placed into the juvenile position (the top) in the new stage vector. The previous time step's juveniles are are placed into the subadult position (the middle) in the new stage vector. And the previous time steps's subadults and adults are summed and placed into the adult position (the bottom) in the new stage vector. 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.

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

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.