Metapopulations Model

All of the life history events comprising the Metapop model have been collected into event groups. The first of these, called Initialize Simulation, only triggers at time step 1. The last event group, named Export Results, only triggers during the final time step (time step 500). If users modify the Number of Time Steps parameter, then the triggering time for the Export Results event group should be changed to match. The simulation products written by the Export Results event group are cumulative measures of population performance, and therefore only need be to be saved once, after the simulation has finished.

The Critters population's life cycle is simple, and similar to that of the Basic scenario. All of this life cycle machinery is contained within the event group called Execute Life Cycle. Each member of the Patches population is placed into a single landscape patch, and is assigned an explored area equal to it's entire patch. Members of the Patch population are used in a Generated Hexmap event to create a map called Patches, that in turn affects the Critters population. All of the dynamic Hexmap construction machinery is contained within the Assemble Patch Map event group.

By changing the Hexmap used to define the available landscape patches, and modifying the Undisturbed Patches [%] and Disturbance Frequency [%] Global Variables (see below), users can develop a suite of metapopulation examples illustrating a wide range of model behaviors.

Workspace Spatial Data

The Metapop model requires a single Hexmap called Patch Map. But it comes with a small collection of patch maps stored in a spatial data time series called Patch Maps. Any one of these maps can be used to replace the Patch Map Hexmap, thereby modifying the metapopulation landscape structure.

Users alter the metapopulation structure by deleting the Patch Map spatial data, and replacing it with one of the Hexmaps stored in Patch Maps. For example, the patch map that Metapop comes with is the Hexmap shown above, with the single large patch and the 20 small patches. Another patch map can be substituted for this Hexmap by taking the following steps:

• Right-click on the Patch Map Hexmap, and select Delete from the context menu.

• Expand the Patch Maps time series by clicking on the +.

• Right-click on one of the 7 time steps, and select Copy TimeStep from the context menu.

• Set New Series to "Patch Map" and New Step to "1".

• Click OK.

The collection of seven patch map candidates stored in the Patch Maps time series is shown in the figure below.

The first four images are designed to be used in constructing dynamic patch maps (see below). The Hexmaps assigned to time steps 5 and 7 are intended to be temporally static. The Hexmap assigned to time step 6 (the default Patch Map) can be used to construct either dynamic or a static patch map.

Users are encouraged to construct their own novel patch maps to complement those provided here. The Hexmaps included in the Patch Maps time series allow you to get started experimenting with the model, but the Metapop model can be run with landscapes of any size (i.e. placed in different workspaces), and with any patch map constructs that users might envision

Global Variables

The Metapop model makes use of two Global Variables to control disturbance frequency and pattern. These variables are titled Undisturbed Patches [%] and Disturbance Frequency [%]. They influence the Patches population, which in turn is used to create a time series of maps in which patches sometimes appear and at other times disappear.

The Disturbance Frequency parameter is used to specify how frequently individual patches will be allowed to change state. When patches change state, all possible transitions are allowed:

• Extant patches remain extant (stay on)

• Extant patches disappear (switch off)

• Missing patches reappear (switch on)

• Missing patches remain missing (stay off)

If, for example, Disturbance Frequency is 25%, then each patch will be reevaluated -- on average -- one out of four time steps. If Disturbance Frequency is 75%, then each patch will be reevaluated every three out of four time steps, on average. The Disturbance Frequency parameter treats extant and missing patches exactly the same. Patches that are extant can remain extant after turnover, and patches that are missing can remain missing after turnover. But patches cannot change state until they are flagged for turnover.

The Undisturbed Patches parameter is used to specify how likely a patch is to be set on (extant) or off (missing), after it has been flagged for turnover. If Undisturbed Patches is 20%, then all flagged patches will have a 20% chance of being set to the on (extant) state, and an 80% chance of being set to the off (missing) state. If Undisturbed Patches is 60%, then all flagged patches will have a 60% chance of being set on, and a 40% chance of being set off

Patches Population Parameters

The patches population is added after the simulation begins (in the Initialize Simulation event group), so the initial population size is set to zero (in the Population Parameters' Properties tab). The Properties and Range Data tab parameters are essentially unused. However, the patches population does make use of a number of accumulators, and a pair of binary accumulated traits.

Patches Life History Events

The Metapop model includes five top-level Event Groups. All but the center one (titled Execute Life Cycle) contain some commands specific to the Patches population. In general, the Patches population is used to (a) create dynamics patch maps in which individual patches disappear and later reappear, and (b) to keep track of patch-scale population statistics such as occupancy rates, patch extinction and rescue events, etc. Each life history event involving the Patches population is discussed below, in order of occurrence.

Initialize Simulation Event Group

Patch Introduction [ Add Patch Population ]: This event adds members of the Patches population to the simulation. These individuals represent the entire population -- no others are added, these individuals never reproduce, and they never die. Patch Introduction events add a single individual to each patch present in the Patch Map, the Hexmap that structures the simulation landscape. A single individual is added for each patch present in the Patch Map. Each individual is assigned an explored area equal to the entire patch it is placed within. The Metapop model will used these explored areas to make the patches appear dynamic.

Assemble Patch Map Event Group

Accumulate [ Update Patch Status]: This Accumulate event contains four updater functions, all within the global tab. The Accumulate event has no stratified updater tabs.

The first updater function sets the Time Step accumulator to the current time step.

The second updater function sets the Turnover Trigger accumulator to either 0 or 1, depending on the Disturbance Frequency parameter. Rand() returns a uniformly distributed random number in the range [0, 1). Rand() summed with Disturbance Frequency (expressed as a fraction) will have a range of [0, 2). Because this sum will be a non-negative real number strictly less than 2.0, the Floor() operator will either return 1 (when the sum is 1.0 or more) or 0 (when the sum is less than 1.0). For example, if Disturbance Frequency is 70%, then Turnover Trigger will be set to one 70% of the time, and will be set to zero 30% of the time.

The third updater function resets Turnover Trigger to 1 in the first time step only. This is done strictly to initialize the patch map correctly when the model first starts up.

The forth updater function sets the Patch Status accumulator to:

• Zero, if Turnover Trigger is 1 and Floor(Rand() + Undisturbed Patches) = 1.

• One, if Turnover Trigger is 1 and Floor(Rand() + Undisturbed Patches) = 0.

• Itself, if Turnover Trigger is 0.

This means that the Patch Status (visible vs invisible) will only change when the Turnover Trigger has been set to 1. In the cases where Patch Status can change, a patch will be set visible (1) with a frequency dictated by Undisturbed Patches, and will otherwise be set invisible (0). As described above, this machinery allows users to control how frequently the landscape will change, and what fraction of the patch map will be visible at any given time. See the description of the Turnover Trigger, in this section, for additional detail describing the Floor() and Rand() functions.

Generated Hexmap [ Construct Patch Map]: This event constructs a new copy of the Patches generated Hexmap from the Patch Status Accumulator values. Recall that each member of the Patches population has an explored area set equal to the entire patch they were introduced into. This Generated Hexmap event writes out the Patch Status values assigned to each individual (0 or 1) to each individual's explored area. The event thus creates a temporary patch map with some patches being visible (the patches whose individual had a Patch Status Accumulator set to 1), and the rest being invisible (the patches whose individual had a Patch Status Accumulator set to 0). The character of this patch map is tied to the Patch Map workspace spatial data, since that map was used to locate the Patches population. But this dynamic generated Hexmap (the one named Patches) is what the Critters population references in it's life history events. The Metapop model writes these Generated Hexmaps to the Results folder every time step, so users may examine the resulting time series of patch maps. And these maps can be used within the Simulation Viewer to visualize Metapop's population dynamics after a simulation has finished.

Assemble Results Event Group

Accumulate [ Clear Occupancy Counter ]: This Accumulate event contains two updater functions that have both been placed in the global tab. No stratified updater tabs are used by this Accumulate event. The first updater sets the Occupancy [ past ] Accumulator to either 0 or 1, using the Trait Value Index function. The second updater clears the Occupancy [ present ] Accumulator, which in turn resets the Occupancy trait to Vacant.

Interaction [ Set Occupancy Counter ]: This Interaction event allows each member of the Patches population to count up how many group members from the Critters population own a range that falls within their patch. Members of the Critters population are only allowed single-hexagon ranges, so these ranges cannot fall into more than one patch at a time. The Patches population members store this count in their Occupancy [ present ] Accumulator. When this Accumulator is set to zero, an individual's Occupancy trait will be set to Vacant. When the Occupancy [ present ] Accumulator exceeds zero, the Occupancy trait will be set to Occupied.

Accumulate [ Update Tallies ]: This Accumulate event is used to update three Accumulators that the Patches population uses to track patch occupancy and vacancy rates, numbers of extinctions (transitions from occupied to vacant), and numbers of rescues (transitions from vacant to occupied). This Accumulate event makes use of two stratified updater tabs. First, the event sets the Time Step Accumulator in the global tab, affecting all members of the population. The event next operates on just the vacant patches. It begins by incrementing a count of the number of times each patch was vacant. The event next increments a count of the number of times each patch experienced an extinction. This calculation requires knowing the patches previous occupancy state, but this information was recorded earlier. Next, if it is the first time step, then the extinctions tally is reset to zero. This final calculation is necessary to properly initialize the tally. The second stratified updater tab is used to perform an analogous set of calculations that record patch occupancy and rescue events.

Export Results Event Group

This event group is intended to be triggered only in the final time step of the simulation. The events it contains keep track of summary data, so this data need only be written out once, when the model has finished.

Data probe [ Record Tallies ]: The Patches population uses an accumulated trait called Patch History to distinguish between patches that were occupied at least once, and those that were never occupied. This trait is used to allow the Data Probe event to write out data only for patches that were used in a simulation, which simplifies interpretation of the results. For such patches, the Data Probe event records the total numbers of occupancy, vacancy, extinction, and rescue events.

Generated Hexmap [ Map Occupancy ]: This Generated Hexmap event constructs a map from the occupancy tally. This map indicates the number of time steps for which each patch was occupied.

Generated Hexmap [ Map Rescues ]: This Generated Hexmap event constructs a map from the rescues tally. This map indicates the number of times steps for which each patch was rescued.

Generated Hexmap [ Map Turnover ]: This Generated Hexmap event constructs a map illustrating the frequency of patch turnover. Patch turnover is represented here as the product of the occupancy and rescues tallies. The idea is that turnover must be zero both for patches that were never occupied, and for patches that were never rescued. Our metric, the product of the occupancy and rescues tallies, has this property. Further, the number of rescues should decrease as the occupancy rate increases, since a patch must be vacant to be rescued, and the occupancy rate should decrease as the number of rescues increases. Our turnover metric also exhibits this behavior, and will reach its maximum for the patch that experienced the largest number of transitions between occupied and unoccupied states.

Critters Population Parameters

The Critters population is added manually in the Event Sequence, so the Initial Population Size parameter is set to zero in the Population Parameters (as is done for the Patches population). Members of the Critters population do attempt to form groups, but their group size is limited to one, as is their maximum range area. Critters can build a group and range in any hexagon that has a score greater than zero, which means any hexagon that forms part of a patch (as long as the hexagon isn't already taken by another individual).

Unlike the Patches population, the Critters population does not make use of any special Accumulators that were designed to function as model parameters.

The Critters population makes use of three accumulated traits that track Age Class (juvenile, subadult, adult), Group Status (floater vs. group member), and Location (in the matrix vs. in a patch)

Critters Life History Events

The Critters population makes use of three of Metapop's five top-level Event Groups. The initialization Event Group is used to add the initial members of the Critters population. In the Event Group used for patch map construction, the Critters population individuals are assigned to patches, or the matrix hexagons falling outside the patches. Individuals in this matrix are then removed. The machinery used to simulate demography and movement for the Critters population has all been placed in the Event Group named Execute Life Cycle.

Initialize Simulation Event Group

Patch Introduction [ Add Critter Population ]:

This event adds members of the Critters population to the simulation. Patch Introduction events add a single individual to each patch present in the Patch Map, the Hexmap that structures the simulation landscape. A single individual is added for each patch present in the Patch Map. Each individual is assigned an explored area equal to the entire patch it is placed within.

Accumulate [ Set Propagation Mean ]:

The Metapop model is designed to begin with one member of the Critters population located in every hexagon of every patch in the Patch Map. The Patch Introduction event described above adds one individual to every patch, so to fill a patch composed of ten hexagons, nine more individuals would have to be added. This Accumulate event computes this value for each patch, by first using an Explored Hexagons updater function to measure the size of the patch each individual was introduced into. Next, the event sets an Accumulator named Value to the patch size (in hexagons) minus 1.

Propagation [ Add Remaining Critters ]:

The Propagation event is used to add the remaining members of the Critters population necessary to fill every patch hexagon present in the Patch Map. In the above step, the Value Accumulator was set equal to the number of individuals required to fill each patch. In this step, the Propagation event is passed the Value Accumulator as a mean, plus an Accumulator set equal to zero as the standard deviation. The Propagation event thus makes each founding member of the Critters population (one per patch) reproduce another n individuals, where n it's patch size in hexagons minus 1. The Propagation event is set up to locate these new individuals randomly within the founding individual's explored area, which was earlier set to the entire patch. Thus, a patch of size n hexagons will be initialized with n individuals, and these n individuals will be distributed randomly across the patch. There is no reason why a patch must be initialized with a number of individuals equal exactly to its size in hexagons. This simply serves as a simple and functional way to start the model off.

Assemble Patch Map Event Group

Accumulate [ Get Location ]:

At this point in the simulation, the Patches population has just constructed the Patches Hexmap (a Generated Hexmap). Here, the Critters population uses an Individual Locations updater function to identify which patch (based on the Patches map) each Critter individual is located in (or if they are not in a patch at all). The purpose of this event is to prepare for the subsequent Survival event, in which critters not residing in a patch are removed.

Survival [ Location-Based ]:

Here, each member of the Critters population not occupying a patch (based on the dynamic Patches Generated Hexmap) is removed. This enforces a convention that individuals must transit from patch to patch in order to survive. Users may, of course, explore the consequences of relaxing this constraint.

Execute Life Cycle Event Group

Accumulate [ Increment Age ]:

This Accumulate event is used to increment the age of each member of the Critters population.

Reproduction [ Stage-Based ]:

This Reproduction event is stratified by stage class, and used to allow adult members of the Critterspopulation to reproduce. Juveniles and subadults have zero reproductive output. The adults have a single offspring, with certainty. And since Reproduction events only operate on group members, only adult group members will reproduce. Recall that, at this point in the simulation, the Critterspopulation resides exclusively in the patches. Users may elect to change these reproductive rates.

Survival [ Stage-Based ]:

This Survival event is stratified by stage class. Juveniles, subadults, and adults are assigned survival rates of 0.3, 0.6, and 0.9, respectively. Users may elect to change these survival rates.

Floater Creation [ Stage-Based ]:

This Floater Creation event is set up to force the juvenile members of the Critters population to leave their groups. Once these individuals become floaters, they can then disperse through the landscape.

Movement [ All Floaters ]:

This Movement event operates on all floaters regardless of age. These floaters will disperse and then prospect for an available territory (a unused patch hexagon). Dispersing individuals are assigned path lengths drawn from a lognormal distribution having a mean of 10 hexagons, and a standard distribution of 10. Dispersal paths are bounded by a maximum allowed path length of 100 hexagons. A quality stopping criteria is used to force dispersers to stop if they encounter a patch hexagon, but only after at least 9 steps have already been taken (they may stop beginning with their 10th step). The movement autocorrelation parameter is set to 75%, and the repulsion and attraction mechanisms are effectively turned off. After dispersal has completed, the floaters use a greedy search strategy to explore a maximum of 37 hexagons, in search of a vacant patch hexagon to occupy. (For reference, a hexagon-shaped patch with a diameter of 7 contains 37 hexagons.) Prospecting individuals are assigned a Start New else Join Existing exploration goal. Since the maximum group size parameter was set to one in the Population Parameters, individuals will not be allowed to join existing groups. But if users change the maximum group size, then this Movement event will allow multi-individual groups to form via immigration. Users will frequently want to explore the consequences of changing some of these Movement event settings.

Accumulate [ Set Group Size ]:

This Accumulate event updates the Group Size Accumulator for each member of the Critters population. This in turn updates the Group Status trait. Updating this trait value is necessary since the previous Movement event will have likely changed the group / floater status of some members of the population.

Census [ Stage Class ]:

This Census event records the number of juvenile, subadult, and adult members of the Critters population.

Early Termination Event Group

The Early Termination event group detects if the Critters population has dropped to zero. If this happens, the scenario then terminates the simulation by removing all members of the Patches population. HexSim simulations end automatically when all populations have declined to zero

Getting Started

First, open the Example Workspace in HexSim. Then, double-click on the Metapop model. HexSim should appear as shown below:

Notice that the Hexmap being used for this simulation (displayed above) has one large patch and 20 small patches. The large shifts in population size depicted in the image above-right correlate with the removal and reappearance of the large patch. The loss and gain of the smaller patches has a less dramatic affect on the overall population size.

The Simulation Viewer

HexSim can’t show you everything that’s happening in a simulation while the model is running. But it can write an enormous amount of information to a log file, that can later be used to visualize the simulation dynamics. The tool that you’ll use to play back simulation details is called the Simulation Viewer. Launch the Simulation Viewer from the HexSim menu.

Once the Simulation Viewer is running, switch to its Data tab. Select the Log File produced by the simulation you just ran (it is probably the only one available from the drop-down menu). Select the Critters population.

Before selecting Spatial Data, deselect the Restricted check-box on the right side of the GUI, adjacent to the Spatial Data menu. Doing so makes all workspace spatial data appear in the menu, including spatial data generated while the simulation was running. When the Restricted check-box is selected, only the spatial data provided as inputs to the scenario will be available for playback. Select GEN: Metapop-[1]/Patches from the Spatial Data drop-down menu. Here, the GEN refers to the fact that the Hexmap series was generated, or built on-the-fly as the simulation ran.  Metapop is the name of the simulation. The text [1] denotes that these are results from replicate one. Since you likely only ran a single replicate, this should be the only choice. But if multiple replicates were run, users would then pick one member of the collection to display. Finally, Patches is the actual name of the Generated Hexmap series we want to display. This is the generated spatial time series that shows which patches were extant and which were absent at every time period.

We did not use any Barrier maps, so leave the Barriers drop-down menu set to None Selected.

For the Visualization Type, select Movement. Leave Dispersal checked, and Exploration unchecked. Place a check mark in the All Trait Combinations check-box.

Next, select the Display tab. From the View menu, use the Zoom Out option twice. Alternatively, tap the minus key twice. Either action will zoom out as much as possible, allowing more of the Hexmap to be shown on a given amount of computer screen. Then, stretch the size of the window until the entire Hexmap can be seen at once on your computer. If the screen is too small to visualize the entire Hexmap, then just make the window as large as possible. Use the View menu to turn off the Navigation Window (shown in the upper-left, with cross-hairs), or alternatively type Alt-N, or simply right-click.

Below are some suggestions for users who'd like to begin exploring the Metapopulations model.

The Metapop model can be modified in a number of different ways, some of which are listed below:

• Replacing Patch Map with a different Hexmap.

• Adjusting the Undisturbed Patches [%] and Disturbance Frequency [%] Global Variables.

• Adding movement barriers.

• Modifying the Survival and Reproduction event parameter values.

• Changing the Movement event parameter values.

The remainder of this section will describe each of these changes in more detail.

Replacing Metapop’s Spatial Data

The Metapop model uses the workspace spatial data time series named Patch Map. This is a static Hexmap series, meaning that it consists only of time step 1 (a single Hexmap). The spatial data time series named Patch Maps is simply a collection of seven alternative Hexmaps that can each be used to replace Patch Map.

To replace Patch Map with one of the seven Hexmaps from the Patch Maps series, do the following:

1. Delete Patch Map using the context menu. Right-click on the entire series, not time step 1.

2. Expand Patch Maps so you can see all seven time steps.

3. Right-click on the time step you want to use, and select Copy TimeStep.

4. Under New Series, enter Patch Map (make sure this is singular… not “Maps”).

5. Under New Step, enter 1. Then hit OK.

6. Display Patch Map to confirm that you accomplished what you intended.

The HexSim Example Workspace comes with Patch Map being a copy of Patch Maps’ time step 6. But note that the Hexmap colors will look different if you compare Patch Map to Patch Maps step 6. This is because the color map being used is assigned to the range of hexagon scores present in an entire Hexmap time series.  Patch Map only has a single time step, so HexSim’s entire colormap (100 colors) is spread across the range of values in that one map. In contrast, Patch Maps contains 7 time steps, and time step 1 is a Hexmap with scores that range from 0 - 1372. So when displaying maps within the Patch Maps time series, the colormap is spread over 1372 colors. Hexmaps corresponding to individuals time steps within Patch Maps (e.g. time tep 6) may have a much smaller range of hexagon scores, and thus appear to have less color variation.

The Patch Map that the Example Workspace comes with (Patch Maps / time step 6) is intended to be used with little or no patch turnover. The default parameters are set to:

Undisturbed Patches [%] = 90

Disturbance Frequency [%] = 5

Time steps 1 - 4 of the Patch Maps spatial data time series are intended to be used with slightly higher rates of patch turnover. Recommended starting values for these Hexmaps are:

Undisturbed Patches [%] = 20

Disturbance Frequency [%] = 5

Time steps 5 and 7 of the Patch Maps spatial data time series are intended to be used without patch turnover. To eliminate patch turnover entirely, set the parameter values to:

Undisturbed Patches [%] = 100

Disturbance Frequency [%] = 0

Adding Movement Barriers

The HexSim Example Workspace comes without any movement barriers. To add a barrier series, first display the Patch Map (actually, any Hexmap will do for this, but the Patch Map is ideal because this is what Metapop is using).

With Patch Map displayed, click on the File menu, and then select Create New Barrier Data.

Supply a name for the new barrier series. Then, a Barrier Attributes window will appear.

Supply Probability of Mortality and Probability of Deflection parameters. Make these values the same for both categories 1 and 2. HexSim barriers can have different properties depending on which side individual’s encounter, but we won’t use that feature here. The Probability of Transmission is automatically set to 1.0 - Pmortality - Pdeflection. Deflection means bouncing off a barrier, but individuals actually do a sort of bounce-skid hybrid, hence the term.

After setting the barrier attributes, click the Accept button.

Next, make sure that as much of the Patch Map can be seen on the screen as possible. Then select Edit Barriers from the Edit menu. This action makes editing tools appear at the top of the Hexmap display window. Use the Add Segments and Toggle Segments tools to add barriers to the map. Some trial and error will be necessary to become comfortable with the tools. More information on using HexSim barrier maps can be found in the Users Guide.

Accept or cancel your changes once you are done.

To use the barrier map you just created, you must do the following:

• Go to the Metapop Scenario tab.

• Open the Execute Life Cycle event group.

• Open the Movement event.

• Supply the barrier map name to the drop-down menu named Barriers, in the Global tab.

Modifying Metapop’s Vital Rates and Movement Behavior

Metapop’s Survival, Reproduction, and Movement life history events are all located within the Execute Life Cycle event group. Each of these events will have a significant effect on the model dynamics, and each can be easily experimented with. Users wishing to experiment with alterations to the Critters' vital rates and movement behavior should first be comfortable with the use of HexSim Survival, Reproduction, and Movement events. More information on these life history events can be found in HexSim's Users Guide.