HexSim: A Life History Simulator for Terrestrial Wildlife Populations Users Guide

September 30, 2008 By Nathan H. Schumaker U.S. Environmental Protection Agency Western Ecology Division, 200 SW 35th Street Corvallis, OR 97330

HexSim HexSim is a spatially-explicit, individual-based, multi-species computer model designed for simulating terrestrial wildlife population dynamics and interactions. HexSim is very general, with landscapes, life histories, disturbance regimes, and most other details being supplied by the user at run-time. HexSim also employs a sophisticated graphical user interface. HexSim is freely available, but still under active development. Surprise The PATCH model is now superceded by HexSim HexSim is being developed jointly by the U.S. Environmental Protection Agency and the University of Washington HexSim is compiled for Windows XP and a 32-bit CPU. Use with Vista or 64-bit CPUs is not presently supported.

NOTICE This document is a preliminary draft. It has not been formally released by the U.S. Environmental Protection Agency, and should not be construed to represent Agency policy. It is being circulated for comments on its technical merit. Do not quote or cite. The information in this document has been funded in part by the U.S. Environmental Protection Agency. It has been subjected to the Agency's peer and administrative review, and it has been approved for publication as an EPA document. Reference herein to any specific commercial products, process, or service by trade name, trademark, manufacturer, or otherwise, does not necessarily constitute or imply its endorsement, recommendation, or favoring by the United States Government. The views and opinions of authors expressed herein do not necessarily state or reflect those of the United States Government and shall not be used for advertising or product endorsement purposes. The development of HexSim was performed in part by the University of Washington, through support provided by the Strategic Environmental Research and Development Program (SERDP). Preferred Citation: Schumaker N. H., HexSim Users Guide (Day,Month,Year), ON LINE. U.S. EPA, Washington, D. C. EPA/600/R-YY/XXXX, Available: http://www.epa.gov/wed/pages/models/hexsim/index.htm

1

1). Introduction 1.2 - Overview The HexSim Concept HexSim is a spatially-explicit and individual-based life history simulator. HexSim can be used with one or more wildlife populations, and it will follow populations individual-by-individual, gathering data on birth, death, movement, and multiple other events. HexSim is unique principally in its generality. It has been designed for use with terrestrial wildlife populations, but it does not otherwise contain "hard-wired" assumptions about species' life history, landscape structure, disturbance regimes, and so on. HexSim is also somewhat unique in that it has a sophisticated Graphical User Interface (GUI) that can be used to parameterize and run the model, and to view certain model outputs. To use HexSim, you will have to: 1. Assemble Spatial Data, and Build HexMaps 2. Assemble Life History Data and Construct a Life Cycle 3. Fully Parameterize the Model 4. Run and Analyze a Simulation HexSim Workspaces HexSim organizes each project into a workspace. Each HexSim workspace contains a grid file, plus Spatial Data, Parameters, and Results folders. The Spatial Data folder itself contains additional structure. The user should not alter this basic folder structure except by possibly adding additional folders. The HexSim workspace folder structure is displayed below.

The HexSim workspace makes accessing saved data sets particularly simple. At most ,a couple of mouse clicks are all that is necessary to retrieve complete parameterization scenarios, including spatial data and all model settings. HexSim Spatial Data HexSim reads 8-bit (256 colors) raster files in a Microsoft Bitmap (bmp) format. These bitmaps may not be compressed. HexSim contains a flexible tool called the Hexagon Data Constructor that converts bmp files into a grid format containing hexagonal cells. Each HexSim workspace will contain a single grid file. Grid files describe basic geometry, such as the number of hexagons per row and column, and where in space the grid is situated. Within each HexSim grid there may be one or more spatial data time series themes. Each such theme has a title, and is composed of one or more spatial data time steps. A spatial data time step is a single file, and a spatial data time series is a collection of

2

such files all having a common title. When the HexSim Hexagon Data Constructor builds a grid, it places a copy of the bitmap file in the Spatial Data / Bitmaps folder. The spatial time series data is always placed in the Spatial Data / Hexagons folder. Each spatial data time series theme is assigned its own sub-folder. The time series theme in turn contains a series of one or more spatial data time steps. A spatial data time series theme titled "demo" consisting of steps 1, 5, and 10, would be represented by three files named demo.1.hxn, demo.5.hxn, and demo.10.hxn. All three files would be placed in a folder named "demo" within the Spatial Data / Hexagons workspace folder. HexSim will create these structures automatically when its grid files are built. It will be convenient to refer to an arbitrary HexSim spatial data time step as a HexMap. There are two important concepts to keep in mind when working with HexSim spatial data. The first is that you may use as much or as little spatial data as you like. A single HexMap is adequate for running a simulation. On the other hand, multiple spatial data themes, each represented by multiple time steps, may be used in a single simulation. And these themes might be quite diverse, with some representing habitat, others representing disturbance regimes, and others still representing landscape barriers. The second important concept is that all HexSim spatial data are inherently time series. Each HexSim spatial data theme must at minimum have a HexMap representing time step one. This time step will be used initially. Subsequent time steps will always be automatically inserted at the appropriate time by the model. The model GUI provides a mechanism for changing theme names, and time steps. But since both are stored in the spatial data file and folder names, technically proficient users can also make such modifications directly from the operating system. For further information, see the section called Generating Spatial Data. HexSim Life Cycles HexSim simulations are conducted in one or more replicates, with each replicate consisting of a fixed number of time steps. The user has complete control of what actually happens within a time step. The duration of a HexSim time step is defined implicitly by what is contained within it. Typically, a time step will be a year, but it does not have to be. Each population modeled with HexSim will have a life cycle composed of a series of events. A time step is one complete pass through the entire life cycle. Users construct life cycles by selecting events from a menu. Any given event type can be added multiple times to the life cycle, and the order of events can be easily altered. Each event has parameters that the user must set. It is through setting these (and other) parameters that the user develops the specific life histories and conditions that are to be evaluated in a given simulation. The HexSim life cycle data, and all other model parameters, are stored collectively in Scenario files. The model interface provides the user with a list of all the scenarios available within the active workspace. Through the GUI, scenarios can be quickly retrieved, edited, used to launch new simulations, etc. Before You First Run HexSim The HexSim model relies on two Microsoft libraries that may not be installed on your computer. These are freely available, and quick to install. See the section titled Installing Missing Libraries for help getting these libraries installed on your computer.

1.3 - Installing Missing Libraries Two Microsoft libraries may be missing from your computer The HexSim model will not run without two Microsoft libraries that are missing from many computers. These are both "redistributable" packages, meaning that you can download them and legally share them with others. The first is called the Microsoft .NET Framework Version 2.0 Redistributable Package (x86) The Add or Remove Programs tool (in the Windows control panel) can be used to see if this library has been installed on your computer. If it has already been installed, you’ll see an entry labeled “Microsoft .NET Framework 2.0” in the Add or Remove Programs tool. If you do not have this library, then you can download it from Microsoft at: 3

http://www.microsoft.com/downloads/details.aspx?FamilyID=0856eacb-4362-4b0d-8eddaab15c5e04f5&displaylang=en The second library is called the Microsoft Visual C++ 2005 SP1 Redistributable Package (x86) Again, the Add or Remove Programs tool can be used to see if this has already been installed. Look for an entry labeled “Microsoft Visual C++ 2005 Redistributable”. But even if it appears there, it is likely not the SP1 redistributable package. The original redistributable package produced the same listing in Add or Remove Programs. You can download the current version from Microsoft at: http://www.microsoft.com/downloads/details.aspx?familyid=200B2FD9-AE1A-4A14-984D389C36F85647&displaylang=en The new package installs correctly over the old one, so there is no need to remove the original.

2). HexSim Basics 2.1 - Generating Spatial Data Start by calling up the Hexagon Data Constructor From the main HexSim window, use the HexSim drop down menu to select the Generate HexMap option.

This will call up the Hexagon Data Constructor. The first step involved in using this tool is to Read Raster Data.

4

Once a raster file has been read in, the Hexagon Data Constructor can be used to develop a HexSim workspace, including a grid file. The Hexagon Data Constructor can also be used to develop individual HexMaps to be associated with an existing grid. In addition, you may use this tool to generate histograms and to write bitmap files. The Hexagon Data Constructor can read and process bitmap files of any size, given that your computer has sufficient memory. Overcoming constraints on file sizes necessitated developing bitmap reading and writing tools by hand. As a result, only 8-bit uncompressed Windows bitmap files can be read at this time. HexSim requires some ancillary data in order to create a grid from a bitmap file. This information is presently stored in a control file -- a text file with a ".ctrl" extension. A typical control file looks as follows:

Bitmaps and control files are placed in the Workspace/Spatial Data/Bitmaps folder. If a control file is missing, HexSim will build one for you. If a control file is missing, but a BPW World File (an ESRI

5

creation) exists, then HexSim will build a control file using the data stored in the BPW file. Control files are text files built using the following conventions: 1. Lines starting with a "#" character are comments. 2. North, South, East, and West describe the location of the top, bottom, right, and left edges of the bitmap, respectively. Values are associated with pixel centers. 3. Either North or South, and East or West can be left undefined. HexSim will compute the missing data based on the pixel size. 4. Size indicates the size of a pixel, in meters. Pixels are assumed to be perfectly square. The majority of a control file is typically devoted to specifying the red, green, and blue values, and titles, to be associated with each data category found in the bitmap file. Each line of information of this type has the structure: Pixel ID: R G B : Title. The red (R), green (G), and blue (B) values must be integers in the range 0-255. Generic category titles are supplied by HexSim, but these can be customized. The key thing to remember when using control files is that HexSim is not a GIS system. Distances are measured in meters, and areas in hectares. The coordinates used in the control file assign a location in space to the edges of the raster data. A HexSim grid file developed from this raster data will have a coordinate system derived from the control file parameters. But HexSim's world is perfectly flat. That said, if you use one bitmap and control file to generate a grid, and then a second bitmap and control file to develop an complementary HexMap, the two bitmaps need not have identical North, South, East, and West values. HexSim will correctly handle a lack of registration between bitmaps (as specified by their control files). Bitmaps also need not use the same pixel size. Video on Workspace Construction

2.2 - The HexSim Interface Overview HexSim is really a collection of several tools. Its principal components include a model engine, a graphical user interface (GUI) for the model engine, the hexagon data constructor, a simulation viewer, and a simulation monitor. The HexSim model components are typically delivered as a zip file. They should be unzipped into a folder and always kept together. HexSim will not run correctly unless all of its parts are in a single folder. Once the model has been unzipped, a shortcut can be made to the HexSim.exe file. This shortcut can be put in a convenient place (e.g. the desktop) and then used to launch the model. An easy way to create a Windows shortcut is to click on the target and drag-anddrop to the destination while holding down the key. The Workspace Tab HexSim organizes input and output data in a collection of folders called a workspace. Workspaces contain scenarios, spatial data, and other information. The HexSim workspace tab displays the scenarios and spatial data present in the workspace that is currently open. HexSim scenarios are XML input files that fully parameterize a simulation. HexSim spatial data are time series of HexMap and barrier data. Each scenario will reference some or all of the spatial data sets present within the workspace.

6

A scenario context menu can be accessed by right-clicking on a scenario in the Workspace Tab. The scenario context menu items are described below: •

Select this Scenario opens the scenario and creates a new workspace tab to display the scenario data. Double-clicking a scenario will also select the scenario.

•

Revert to Saved Scenario backs-out any changes to the scenario that have been stored on the disk. Modified scenarios are stored as tilde-file (a scenario file that ends with a "~" character). When HexSim opens a workspace, it loads scenario tilde-files if they exist, and in this way is able to capture and use scenario modifications that have not yet been formally saved. The Revert to Saved Scenario function removes the tilde-file, and then reloads the saved version of the scenario. This menu item will only be available if a tilde-file exists.

•

Destroy this Scenario removes the scenario from the scenario listing in the Workspace Tab, closes the scenario tab if it exists, and then sends the scenario file to the recycle bin. Tildefiles are also sent to the recycle bin.

•

Display File Dates toggles the scenario file modification date on and off in the Workspace Tab. If a tilde-file exists, the scenario date is not displayed.

Workspace spatial data should be thought of as time series, and they consist of a name (or theme) followed by one or more time steps. HexSim uses a construct called a Tree View Object to display spatial data. Thus each spatial data time series has a little + sign to its left, which if clicked opens the series to display its content. The content consists of a list of one or more time steps, indicated by a green arrow and time step number. Every spatial data time series must at minimum contain a HexMap for time step 1. The HexMap corresponding to time step 1 will be used for all simulation time steps unless the user supplies additional HexMaps corresponding to subsequent time steps. During a HexSim simulation, the model will automatically use the spatial data that corresponds to the current time step. For example, lets suppose a scenario references a spatial data time series called Habitat, and that Habitat consists of 5 HexMaps that correspond to time steps 1, 10, 20, 30, and 40. If the simulation is run for 50 years, then it will use Habitat time step 1 for simulation time steps 1-9, Habitat time step 10 for simulation time steps 10-19, Habitat time step 20 for simulation time steps 20-29, Habitat time step 30 for simulation time steps 30-39, and Habitat time step 40 for all remaining simulation time steps. The HexSim interface provides tools for reorganizing and renaming spatial data. But its useful to know that this can easily be done from the operating systems too. A spatial data time series is really just a sub-folder that resides in the Workspace Spatial Data folder. And the spatial data time series 7

HexMaps are individual files (with a ".hxn" extension) that reside within the time series sub-folder, and that follow a specific naming convention. Individual HexMaps must share the overall time series title, and their time step is recorded as a numeric extension to this file name. Therefore, a spatial data time series named Habitat, with time steps 1, 10, and 20, will correspond to the a folder named Habitat in the workspace Spatial Data location. Within the Habitat folder, there will then be three HexMaps named Habitat.1.hxn, Habitat.10.hxn, and Habitat.20.hxn. Spatial data context menus can also be accessed by right-clicking on a spatial data time series or on an individual time step. The context menus change depending on whether the target is a series or a time step, and if it is a HexMap or a barrier file.

Workspace-specific functions are located within the HexSim pull-down menu.

These menu items are described below: •

Set Workspace is used to select and load a workspace. Only one workspace can be opened at a time, for each HexSim instance.

•

Add Workspace opens another instance of HexSim. This allows you to work with multiple workspaces simultaneously.

•

Add Scenario creates a new blank scenario. A scenario is a collection of all the parameters necessary to run a HexSim simulation.

8

•

Copy Workspace creates a duplicate copy of an existing workspace.

•

Import Scenario is used to copy a scenario from another workspace into the current workspace.

•

Import Barrier Data is used to import a HexSim barrier file from another disk location. This tool can also be used to construct a HexSim barrier file from an ESRI Shapefile.

•

Import HexMap Data is used to construct a HexMap from an ESRI Shapefile, or from a comma-separated variable (CSV) file. CSV files are also allowed to have a TXT extension.

•

Start Viewer calls up the HexSim Simulation Viewer. A variety of simulation outputs can be visualized using the simulation viewer.

•

Generate HexMap calls up the Hexagon Data Constructor. This tools is used to build HexSim workspaces, grid files, and HexMap files. The Hexagon Data Constructor uses 8-bit BMP files to construct the HexSim input files.

•

Grid Info displays a dialog box with the grid coordinates, grid dimensions, and hexagon dimensions.

•

Exit and Save Current State records what workspace is being used, and which scenarios are presently loaded. This information is then stored for use later. The HexSim session is then ended. The next time HexSim is launched, it will open up with in the previous workspace, and with the previous scenarios already loaded.

The Scenario Tab The HexSim workspace tab contains a list of the scenarios present in the workspace. When a scenario is selected (by double-clicking, or by using the context menu), it opens up in a scenario tab. Multiple scenarios can be opened simultaneously, and each will appear in its own tab. Each scenario tab contains an event sequence, a list of the scenario's spatial data, a list of HexSim populations, and a set of simulation parameters. These constructs are discussed below. Different scenarios need not have any commonalities, but they must all reference their parent workspace's spatial data.

• The Event Sequence contains the list of actions that the model will perform for each time step. Some bookkeeping activities are performed automatically at the start of each new time step. These are not visible in the event sequence. The event sequence is populated with actions called

9

events. The user assembles the event sequence at run-time by selecting events from an event palette (a list of available events drawn from a context menu drop-down list). The order of the events can be changed using the up and down arrows supplied above and below the event sequence. Each event has a corresponding parameterization window, which can be opened by double-clicking the event, or through its context menu. The event sequence and parameterization data are stored in HexSim scenario files. A HexSim simulation is comprised of one or more replicates, and each replicate is a collection of time steps. A time steps is defined implicitly by the event sequence. The collection of events assembled by the user, their order, and their parameterization together make up the core of a HexSim simulation. Typically, the majority of effort that goes into constructing a HexSim scenario is devoted to parameterizing events. There is only a single event sequence per scenario. If a scenario includes multiple populations, then the events for each population are interspersed throughout this single event sequence. The event sequence context menu provides access to a standard suite of actions (e.g. edit, rename, etc), and also allows the user to select which columns of data are displayed. The available choices include population, event type, and event name. Each HexSim event is discussed in detail in a subsequent section of this Users Guide. •

The Scenario Spatial Data provides a list of the spatial data used by the events in the event sequence. A scenario's events may use some or all of the spatial data available in the workspace. Thus, the scenario spatial data is necessarily a subset of the workspace spatial data (though a scenario may reference all of the workspace spatial data). The context menu items associated with the workspace and scenario spatial data differ. The scenario spatial data context menu allows users to display the data, but it is also used to set up cycling, and to toggle the ignored state. Cycling is used to define a time stop at which the model will loop back to the beginning of a spatial data time series. If the cycling context menu item is selected (from the scenario spatial data context menu), then a window will pop up that allows you to set the cycle length. A cycle length of zero is used to indicate that cycling has been turned off. Non-zero cycle lengths set the number of time steps for which HexSim will proceed normally through the spatial data. At the time step equal to the cycle length + 1, HexSim will start over with the initial time step associated with that particular spatial data time series. The example below illustrates how cycling works in HexSim.

The cycle length has been set to 450 and 500 for the HexMap time series named Binary and Complex, in the figure. And the Cycle context menu item is visible next to the interface object for the Complex HexMap time series. In the case illustrated by the figure, HexSim would step through the spatial data called Binary from 1, to 2, to 25, at time steps 1, 2, 25, etc. The HexMap for time step 400 would be installed at time step 400, and would then remain in place through time step 450. At time step 451, the HexMap for time step 1 will be reinstalled, since the cycle length was set to 450. At time step 452, the HexMap for time step 2 will be reinstalled, and so on. The cycling of the HexMaps would continue on this way as long as the simulation continued to execute. A HexSim scenario can also be instructed to ignore specific spatial data time steps. The context menu item called toggle ignored state makes this possible. When a time step has the ignore flag set, a red X

10

appears over the arrow icon. Toggling the state of an ignored time step removes the red X, and sets it up to be used in a simulation again . The figure below indicates that time steps 1, 50, 100, 150, (and so on) of the spatial data named Binary would be used in the simulation.

•

HexSim Populations are a principle component of a scenario. All HexSim simulations involve one or more populations, and each population shares an event sequence and a set of population-specific parameters. The population-specific parameters are collected in the population parameters window. Adding populations simply involves right-clicking in the Populations section of the main scenario interface window , and selecting the Create a New Population option (see below). The population parameters window is discussed in detail in a subsequent section of this Users Guide.

•

The Simulation Parameters provide the user with control over the number of replicates time steps that will be used when the simulation is run. The other controls present in the Simulation Parameters box (see above) are being relocated to other parts of the model interface.

2.3 - HexSim Inputs and Outputs HexSim input and output files are typically stored within workspaces, and this facilitates the exchange of information. Simply zip up a workspace and send it to a colleague, and they will have everything they need to replicate your analysis. The model's input and output structure is presently in a state of flux. This section will become more complete in time.

11

Inputs When a HexSim simulation is run, what actually happens is that the model engine (HexSimEngine.exe) is called and passed the name of an XML scenario file. This can be done using the model interface via the scenario menu Run Simulation option, which calls up the HexSim Monitor window. The HexSim monitor then calls HexSimEngine.exe when a simulation is launched. But a HexSim simulation can also be launched by hand in a command window. In this case, the user calls the model engine explicitly, and includes the scenario file name on the command line. The scenario file will contain the full path to a HexSim workspace, where the HexSim engine will be able to locate the spatial data it needs to perform the simulation. A valid scenario file will also contain all of the parameters expected by the model engine. Users can edit the XML scenario files by hand, but doing so is not recommended. These files are complex and easily broken. When running a simulation from the GUI, any scenario files that are to be used must be located in the workspace parameters folder. Otherwise, the model will not be aware of them. However, when running the model engine directly from the command line, the location of the scenario file is irrelevant, since the file contains the absolute path to a HexSim workspace. When a simulation is launched, a sub-folder is created within the workspace Results folder, which is used to store the model output. This results file creation takes place the same way regardless of whether the GUI or command line option is used to launch the model. Outputs There are three types of products generated by HexSim. The model can be used to build workspaces and spatial data (HexMaps). Workspaces can be located anywhere, but spatial data are always placed in the current workspace's Spatial Data folder. The second category of model outputs are the simulate on results. Results are always placed in the current workspace's Results folder, in a sub-folder assigned the same name as the scenario being simulated. All other model outputs are written to a location selected by the user, but the default location will always be the current workspace's Analysis folder. Simulation results come in two principle types. Most events can write output to a log file. A single log file is written per simulation, but it can be used to store a great diversity of information. Tools are being developed to extract useful outputs from the HexSim log files. Census events write commaseparated variable (CSV) files that contain information about population size, stratified by various population-level criteria.

3). Population Parameters 3.1 - Population Basics This chapter is devoted to the HexSim Population Parameters window. Populations are accessed from a list box in the lower right of each Scenario tab, within the main HexSim interface window. Each HexSim scenario must utilize at least one population. If multiple populations have been defined, then they can be made to interact using HexSim's Interaction Events. Populations may be thought of as different species, or just different segments drawn from a single species. An example of the former would be a simulation of predators and their prey. An example of the latter would be a scenario in which males and females were represented as two interacting populations. Within a given workspace (and thus any scenarios contained there), all populations are constrained to live within the same grid. This is because there is only a single grid per workspace. However, separate populations may use very different types and amounts of resources. This is easy to implement in HexSim because use of space is governed by Range Data, which is specified on a per-population basis. In addition, separate populations might be instructed to work with different spatial data and barriers. The events that comprise their life cycle may also vary greatly. Having said this, newcomers to HexSim should master its application in the context of a single population before advancing to interacting populations. The 12

Population Parameters window has four tabs titled: Properties, Range Data, Traits and Accumulators, and Description. The Description tab is generic in that most HexSim events have one. This is just a place for the user to create notes. The other three tabs are discussed in the subsequent sections of this chapter.

3.2 - The Properties Tab The Population Parameters Properties tab is used to define a few basic details associated with the population. Some of these features will change in the near future.

•

Initial Population

The size of the initial population. This is effective at the beginning of each replicate. •

Initial Siting

Used to determine whether the initial population will be placed into the best areas of the landscape, or simply distributed randomly. •

No Initial Groups

If No Initial Groups is checked, then the initial population will be composed strictly of floaters. Otherwise, HexSim will attempt to construct groups at initialization. •

Barrier Memory 1. No Memory --> Individuals do not retain information regarding barriers edges they have already interacted with. 2. Memory Retained per Event --> Individuals will not try to cross a single barrier edge more than once per event. 3. Memory Retained per Replicate --> Individuals will not try to cross a single barrier edge more than once per replicate.

•

Exclusion Series

Used to select a spatial data time series, and establish the conditions under which hexagons will be excluded. Members of the population will never be allowed to enter excluded hexagons.

13

3.3 - The Range Data Tab The Population Parameters Range Data tab is used to set the parameters that govern the formation of groups and ranges, and some related items. These values are referred to as the Static Range Parameters, because they remain constant for the population. However, the Resource Exploration event allows these values to be overridden with a set of temporary values that will exist just for the duration of that event.

•

Range Spatial Data

Specifies which spatial data time series will be used to govern group and range formation. Spatial data must be selected. The G option is used to generate a HexMap on-the-fly for this specific event. •

Range Barriers

Specifies which, if any, barrier time series will be used to limit range formation. Barrier data need not be specified. If used, range barriers will modify with range establishment because ranges are not allowed to span range barriers. Ranges can form around the end of a barrier, but they cannot cross any of the barrier edges. When barriers are used in range formation, the barrier properties (ie. the probabilities of mortality, deflection, and transmission) are ignored. They are treated as simply being present or absent. •

Maximum Range Area

Limits the maximum size for all ranges. This can be specified in either hectares, or in hexagons, by clicking on the appropriate button. This data is actually stored in hectares, so fractional values of hexagons are allowed. •

Maximum Range Span

Limits the maximum span for all ranges. This can be specified in meters or in hexagons, by clicking on the appropriate button. This data is actually stored in meters, so fractional values of hexagons are allowed. Range span is measured as the distance separating the furthest two hexagons in a range, measured from hexagon center to hexagon center. As illustrated below, if range area is fixed at seven hexagons, then the minimum possible range span would be 2 hexagons, and the maximum possible range span would be 6 hexagons.

14

The maximum range span context menu (obtained by right-clicking) allows you to select the effective lower and upper bounds. In the example above, selecting the Set Effective Lower Bound option would set range span to 2 hexagons. Selecting the Set Effective Upper Bound would set range span to 6 hexagons. •

Maximum Group Members

Defines the maximum group size. The maximum group size is enforced during Resource Exploration, if individuals try to join existing groups. It also may be enforced by Floater Creation events, but can be turned off by users. The maximum range size is often exceeded as a result of reproduction, since recruits always start out as members of their natal group. This is not a problem, but users must be careful to make sure that the range resources are sufficient to support a groups needs. The Floater Creation event can help by forcing excess individuals out of the group. Users may also assign recruits a resource target of zero, which assumes that their needs have already been accounted for when resources were allocated to their parents. •

Resource Target per Individual

This parameter is in the process of being replaced with a trait-based resource target scheme. •

Hexagons Range-Eligible if Value Exceeds

This parameter is being changed from a maximum value that is ineligible for inclusion in a range, to a minimum value that is eligible for inclusion. When ranges are constructed, they man not incorporate any hexagons that fall below this threshold value. •

Minimum Range Resource

This parameter establishes the minimum allowed range resource value. During range formation, no ranges will be established unless they have at least this total resource value. •

Floater Preemption of Group Resources (%)

This parameter determines the extent to which floaters are allowed to take resources away from groups. The parameter is most useful in situations where groups have been allocated most or all of the habitat available in some portion of a landscape. In these cases, floaters would be unable to co-exist with the group members without some mechanism that provides them access to group resources. But we know that floaters often gravitate to the best parts of a landscape, and this parameter allows users to simulate such behavior. Both floaters and group members have explored and allocated areas. Group members allocated areas are simply their ranges, except that some of this resource may be preempted by floaters. Floater allocated areas consist of the subset of their explored areas that are not already allocated to other floaters (any given hexagon may only be allocated to a single floater -- a restriction designed to minimize source code complexity). To this, floaters may add hexagons from their explored area that form part of a group's range. In such cases, the floater will be assigned a percent of the hexagon's resources equal to the Floater Preemption of Group Resources parameter value. Only one floater may preempt any given hexagon, and preemption will only take place to the extent that it is necessary to meet the individual's resource target. When floaters build an allocated area from an explored area, they

15

work from the hexagon last explored to the hexagon first explored. Each hexagon is examined to see if its owned by another floater (in which case it is ignored), or if its owned by a group. If the hexagon is unowned, then the floater claims it and all of its resources. If the hexagon is owned by a group, and if preemption is non-zero, then the floater will claim access to the hexagon and the percent of its resources that can be preempted. This process continues until the entire explored area has been exhausted, or until the floater's target resource has been met. The fact that a floater may have claimed a hexagon does not preclude a group from later adding it to its range. The important thing to remember about floater preemption is that it sets the percent of any given hexagon that can be shared by a group and a single floater. The floater takes what it needs to meet its resource target, up to but not exceeding the fraction of the hexagon's resources specified by the preemption parameter. Any resources preempted by floaters are then no longer available to group members. So through preemption, floaters can lower group members productivity. Floater preemption can be easily turned off by setting this parameter to zero.

3.4 - Traits and Accumulators The Population Parameters Traits and Accumulators tab is used to define probabilistic and accumulated traits. This tab is also used to define accumulators, which are variables that take on unique values for each individual, and are used to modify accumulated traits.

•

Traits

Traits presently come in two types, Probabilistic and Accumulated. Eventually a third class of heritable traits will be introduced. All traits consist principally of a set of Trait Values. Traits are defined for a population as a whole, but separate copies are held by every individual. Thus traits are used to introduce characteristics that can vary from individual to individual. Accumulated and probabilistic traits differ principally in how the trait values are altered. Accumulated trait values are altered automatically when an associated accumulator changes value. Probabilistic traits are altered by transition events.

16

•

Accumulators

Accumulators are analogous to traits in that they are defined for a population, but copies are assigned separately to each individual. An accumulator is simply a variable. The user gives it a name, and indicates what values it should have when the model is initialized, and when new individuals are created. Accumulate events are used to change accumulator values. Accumulation events have functions called Updaters that let users define how each accumulator will be altered. •

An Example

A straightforward example uses stage classes. Suppose a population can be characterized by four stage classes. We can implement such a scheme in HexSim using either accumulated or probabilistic traits. The Traits list has a context menu that can be used to select either a new accumulated or probabilistic trait. The parameterization windows for accumulated and probabilistic traits are shown below (accumulated on the left). In this case, the trait has been named "Stage Class", and the trait values have been labeled "Stage 0", "Stage 1", "Stage 2", and "Stage 3". As you can see, accumulated traits require specification of an Accumulator. For this reason, its preferable to define the accumulator before the accumulated trait. And accumulated traits have a series of threshold values. Probabilistic traits do not require thresholds because their trait values are modified using Transition events.

The relationship between the accumulated trait named Stage Class, and its Age accumulator is as follows: [0 - 1) --> Stage Class 0 [1 - 2) --> Stage Class 1 [2 - 3) --> Stage Class 2 [3 +++) --> Stage Class 3 Here, the square brackets indicate the endpoint is included, and the round brackets indicate that it is not. So if some variable x falls in the range [0 - 1) then x is greater than or equal to zero, but strictly less than one. In reality, the Stage Class trait will be set to Stage 0 for all values of Age less than 1, since there is no earlier stage class that can be applied. An accumulator is created using the Accumulators list's context menu. When a new accumulator is added, the parameterization window below is opened.

17

Here the accumulator can be assigned a name, given a maximum value, and supplied with ranges for initialization and birth. In this case, the accumulator is named "Age", and it has not been given a maximum value. Upon initialization, each individual's copy of the Age accumulator will be assigned a value drawn from a uniform distribution with range [0, 3]. Upon birth, each individual will be assigned an age drawn from a uniform distribution with range [0, 0]. Thus all individuals will be created at age zero. For the sake of example, assume that each HexSim time step represents a year, and that the stage classes are intended to represent age (in years), except that all ages 3 and greater will be placed into Stage Class 3. If the above accumulator and accumulated trait is used to capture age and stage, then the user has a choice of using an Aging event, or an Accumulate Event, once per time step, to increment the Age accumulator. If the probabilistic trait is used instead, then the user must include a single Transition event per time step. The Transition event matrix would be used to increment stage classes, which for a 4-stage model would be: 0000 1000 0100 0011

4). HexSim Standard Events 4.1 - The Survival Event The Survival event processes a target population one individual at a time. For each individual, it forces a survival decision to be made, which either results in death, or in nothing at all. That is, a survival events does not change an individual unless it causes its death. Survival is implemented by assigning an individual expected survival probability, and then drawing a random number to determine if the individual dies. The process of assigning expected survival probabilities is discussed later in this section. While Survival events operate on an entire population, its easy to effectively turn the event off for a subset of the population. This is done by indicating that some individuals have a survival probability of 1.0. •

The Properties Tab

This tab allows the user to select a population, spatial data, a resource allocation model and interpolator, and a set of traits with which to stratify survival. Users must always specify a population, and at least one trait must be selected. The trait selection is used to develop survival categories, so that individuals can vary in their mortality rates. The spatial data may be specified, or left unspecified. The resource allocation and interpolator parameters will only be active if a spatial data time series has been selected. The G next to the Spatial Data pull-down menu is used when the spatial data type is set to Generated. This tells HexSim that the event's spatial data is to be constructed on-the-fly at the time of

18

the event, based on model state and map algebra, as defined in a Spatial Data Generator popup window. The button labeled G is used to access this parameterization window when generated spatial data is implemented.

When survival is based on spatial data, the actual survival rate assigned to any given individual is adjusted based on its access to resources. The resource allocation models determines how an individual's resources are computed. The consequences of selecting a resource model are different for group members and floaters, and are described in the following table:

Target Group Members

Floaters

Method Per capita

Resource Base Computation of Individual Resources Allocated Area (Sum of Range Resource - Preemption) / (Group Size)

Mean

Allocated Area

(Sum of Range Resource - Preemption) / (Hexagons in Range)

Sum

Allocated Area

Sum of Range Resource - Preemption

Per capita

Allocated Area

Sum of Floater Allocated Area Resources

Mean

Explored Area

Mean of Floater Explored Area Resources

Sum

Explored Area

Sum of Floater Explored Area Resources

Once a resource model has been selected, then an interpolator can be defined. Interpolators are used to pick an expected survival rate, based on floor and ceiling values for resource allocation and vital rates. See the section called Vital Rate Interpolators for more background on this topic. The resource floor and ceiling values are specified in the Survival event's Properties tab. These parameters are labeled Floor and Ceiling, and they appear with the other interpolator parameters. The vital rate floor and ceiling values are specified in the Vectors tab. But the content that appears in the Vectors tab changes depending on whether a spatial data time series has been selected, and what traits are selected. Separate survival rates must be supplied (in the Vectors tab) for each combination of every trait selected in the Traits list. For example, assume that two traits exist called Stage and Fitness. Assume further that the Stage trait has values of Stage 0, Stage 1, and Stage 2, and that the Fitness trait has values of Low and High. Then if just Stage was selected, survival rates would be supplied for Stage 0, Stage 1, and Stage 2 individuals. If just Fitness was selected, then survival rates would be supplied for Low and High fitness values. But if both traits were selected, then survival rates would have to be supplied for all of the combinations, which are: Stage 0 + Low Fitness, Stage 0 + High Fitness, Stage 1 + Low Fitness, Stage 1 + High Fitness, Stage 2 + Low Fitness, and Stage 2 + High Fitness.

19

The interpolator data is used to obtain an expected survival rate for each individual, based on its resource allocation and the floor and ceiling survival rates assigned to the trait combinations that match this individual. Put another way, each individual will match one, and only one, trait combination. This trait combination will be assigned floor and ceiling survival rates. The individual will also have a resource allocation. The interpolator will use this data to identify the expected survival rate for this individual given its trait data and resources. However, if the user has not specified any spatial data for the Survival event, then only a single vector of trait combinations will be constructed for the event's Vectors tab. This is because the interpolators modify vital rates based upon resource allocations, and the allocation of resources is made relative to the spatial data selected for the event. If no spatial data are specified, then there can be no interpolation, and so the Survival event becomes purely categorical. This is often a desirable simplification. When spatial data are specified, this means the user wishes to stratify survival by trait combinations, and for each trait combination, wants to scale survival by individual resource allocations. The figure below illustrates the Survival event's Properties tab when spatial data is not selected.

•

The Vectors Tab

The figure below illustrates the Survival event's Vectors tab when spatial data has not been specified. In this case, only a single vital rates vector is constructed. Interpolation is not being performed, and the rates in the vector become the expected survival rates for individuals in each of the trait combinations.

20

The figure below shows the Survival event Vectors tab as it looks when a spatial data has been specified, and a single stage class trait has been selected. This corresponds to the Properties tab data illustrated in the figure at the top of this section. In the Vectors tab, all trait combinations corresponding to the selected trait values are listed vertically along the left side of the interface window. One or two vectors of vital rates are then paired with this list, depending on whether spatial data was selected or not. If spatial data was selected, then users are presented with Floor and Ceiling vital rates vectors. For each trait combination, these set the low and upper limits on the survival rate. These values are passed to an interpolator (see the section on Vital Rate Interpolators later in this chapter) that determines what the expected survival rate for each trait combination should be, based on these data and the interpolator parameters present in the Parameters tab. If you wish to guarantee zero mortality for some trait combination, you need simply set both the floor and ceiling survival rates to one.

HexSim can be made to simulate environmental stochasticity by supplying Survival and/or Reproduction events with collections of vital rates vectors. When more than one vital rates vector has been added to a Survival or Reproduction event, then each time the event is triggered, a single vector,

21

or vector pair, is selected from the collection, with replacement. This selection is random, but a future enhancement will also allow vectors to be selected from the list in order. Lets refer to the vital rates in a single floor and ceiling vector pair as a a "set". There are two important caveats concerning environmental stochasticity in HexSim. First, HexSim restricts the number of vital rate sets that Survival and Reproduction events may contain. This set size may be 1, or it may be some constant value greater than 1. That is, the set size for every Survival and Reproduction event in a given HexSim scenario must be either 1 or N, where N is a single constant value. There is no place in the model interface where this number N is specified. Rather, the model simply will not run a simulation if any two Survival and/or Reproduction events have vital rate sets of sizes M and N where M and N are unequal, and both greater than one. The second caveat addresses the concern that users will likely want to correlate good years for survival with good years for reproduction. To make this possible, HexSim indexes the sets of vital rate vectors for Survival and Reproduction events with a set size greater than one. As just discussed, each Survival and Reproduction event will have a set size of 1 or N, where N is a constant. For the purpose of this discussion, we can ignore any events with a set size of one. For events with a set size of N, the index just mentioned is simply a value between 1 and N. If N is 10, and the index is 4, then the 4th element in the set of 10 objects will be selected. What HexSim does is select an index randomly once at the beginning of each time step. This single index value is then used for all Survival and Reproduction events with set sizes greater than one, for the entire time step. This way, if a user wants to correlate good and bad years between events, they need only ensure that the sets of survival and reproductive rates are correlated across indices. Multiple pairs of vital rate vectors are inserted using the Add button at the bottom of the Survival event's Vectors tab. This adds an additional vector pair, which the user can then edit. But in most cases it will be much more convenient to use HexSim's Import and Export features for this purpose. Export writes the current vector set to a file, and Import reads a vector set from a file and places it into the event structure. The Import does not augment vector data, it replaces it. So any existing vector data will be lost upon Import. A Delete button can be used to remove unwanted vector pairs.

4.2 - The Reproduction Event The Reproduction event processes a target population one group at a time. At present, the reproductive output for the entire group is determined collectively. This will be a real number, but it is subsequently rounded to an integer. This discrete number of new offspring is then redistributed across the group members proportionately to their original reproductive output. This will change soon. We will instead adopt a scheme that can be used to assign probabilities to each possible outcome (number of offspring), and this will be implemented on a per-individual basis. Only group members can reproduce -- floater reproduction is always zero. If HexSim is used to simulate females only, then the reproductive rates entered into the model will be fecundities -- the number of female offspring per breeding female. But HexSim traits can be used to simulate both males and females, and in such a case the recruits may be assigned either gender. In such cases, the reproductive rates may be males + females per female.

22

•

The Properties Tab

This tab allows the user to select a population, spatial data, a resource allocation model and interpolator, and a set of traits with which to stratify reproduction. Users must always specify a population, and at least one trait must be selected. The trait selection is used to develop reproductive categories, so that individuals can vary in their rates. The spatial data may be specified, or left unspecified. The resource allocation and interpolator parameters will only be active if a spatial data time series has been selected. The G next to the Spatial Data pull-down menu is used when the spatial data type is set to Generated. This tells HexSim that the event's spatial data is to be constructed on-thefly at the time of the event, based on model state and map algebra, as defined in a Spatial Data Generator popup window. The button labeled G is used to access this parameterization window when generated spatial data is implemented. When reproduction is based on spatial data, the actual reproductive rate assigned to any given individual is adjusted based on its access to resources. The resource allocation models determines how an individual's resources are computed. The consequences of selecting a resource model are described in the following table:

Method Per capita Mean Sum

Resource Base Allocated Area Allocated Area Allocated Area

Computation of Individual Resources (Sum of Range Resource - Preemption) / (Group Size) (Sum of Range Resource - Preemption) / (Hexagons in Range) Sum of Range Resource - Preemption

Once a resource model has been selected, then an interpolator can be defined. Interpolators are used to pick an expected reproductive rate, based on floor and ceiling values for resource allocation and vital rates. See the section called Vital Rate Interpolators for more background on this topic. The resource floor and ceiling values are specified in the Reproduction event's Properties tab. These parameters are labeled Floor and Ceiling, and they appear with the other interpolator parameters. The vital rate floor and ceiling values are specified in the Vectors tab. But the content that appears in the Vectors tab changes depending on whether a spatial data time series has been selected, and what traits are selected. Separate reproductive rates must be supplied (in the Vectors tab) for each combination of every trait selected in the Traits list. For example, assume that two traits exist called Stage and Fitness. Assume

23

further that the Stage trait has values of Stage 0, Stage 1, and Stage 2, and that the Fitness trait has values of Low and High. Then if just Stage was selected, reproductive rates would be supplied for Stage 0, Stage 1, and Stage 2 individuals. If just Fitness was selected, then reproductive rates would be supplied for Low and High fitness values. But if both traits were selected, then reproductive rates would have to be supplied for all of the combinations, which are: Stage 0 + Low Fitness, Stage 0 + High Fitness, Stage 1 + Low Fitness, Stage 1 + High Fitness, Stage 2 + Low Fitness, and Stage 2 + High Fitness. The interpolator data is used to obtain an expected reproductive rate for each individual, based on its resource allocation and the floor and ceiling fecundities assigned to the trait combinations that match this individual. Put another way, each individual will match one, and only one, trait combination. This trait combination will be assigned floor and ceiling reproductive rates. The individual will also have a resource allocation. The interpolator will use this data to identify the expected reproductive rate for this individual given its trait data and resources. However, if the user has not specified any spatial data for the Reproduction event, then only a single vector of trait combinations will be constructed for the event's Vectors tab. This is because the interpolators modify vital rates based upon resource allocations, and the allocation of resources is made relative to the spatial data selected for the event. If no spatial data are specified, then there can be no interpolation, and so the Reproduction event becomes purely categorical. This is often a desirable simplification. When spatial data are specified, this means the user wishes to stratify reproduction by trait combinations, and for each trait combination, wants to scale the reproductive rate by individual resource allocations. The figure below illustrates the Reproduction event's Properties tab when spatial data is not selected.

•

The Vectors Tab

The figure below illustrates the Reproduction event's Vectors tab when spatial data has not been specified. In this case, only a single vital rates vector is constructed. Interpolation is not being performed, and the rates in the vector become the expected reproductive rates for individuals in each of the trait combinations.

24

The figure below shows the Reproduction event Vectors tab as it looks when a spatial data has been specified, and a single stage class trait has been selected. This corresponds to the Properties tab data illustrated in the figure at the top of this section. In the Vectors tab, all trait combinations corresponding to the selected trait values are listed vertically along the left side of the interface window. One or two vectors of vital rates are then paired with this list, depending on whether spatial data was selected or not. If spatial data was selected, then users are presented with Floor and Ceiling vital rates vectors. For each trait combination, these set the low and upper limits on the reproductive rate. These values are passed to an interpolator (see the section on Vital Rate Interpolators later in this chapter) that determines what the expected reproductive rate for each trait combination should be, based on these data and the interpolator parameters present in the Parameters tab. If you wish to guarantee zero reproduction for some trait combination, you need simply set both the floor and ceiling reproductive rates to zero.

HexSim can be made to simulate environmental stochasticity by supplying Survival and/or Reproduction events with collections of vital rates vectors. When more than one vital rates vector has been added to a Survival or Reproduction event, then each time the event is triggered, a single vector, or vector pair, is selected from the collection, with replacement. This selection is random, but a future 25

enhancement will also allow vectors to be selected from the list in order. Lets refer to the vital rates in a single floor and ceiling vector pair as a a "set". There are two important caveats concerning environmental stochasticity in HexSim. First, HexSim restricts the number of vital rate sets that Survival and Reproduction events may contain. This set size may be 1, or it may be some constant value greater than 1. That is, the set size for every Survival and Reproduction event in a given HexSim scenario must be either 1 or N, where N is a single constant value. There is no place in the model interface where this number N is specified. Rather, the model simply will not run a simulation if any two Survival and/or Reproduction events have vital rate sets of sizes M and N where M and N are unequal, and both greater than one. The second caveat addresses the concern that users will likely want to correlate good years for survival with good years for reproduction. To make this possible, HexSim indexes the sets of vital rate vectors for Survival and Reproduction events with a set size greater than one. As just discussed, each Survival and Reproduction event will have a set size of 1 or N, where N is a constant. For the purpose of this discussion, we can ignore any events with a set size of one. For events with a set size of N, the index just mentioned is simply a value between 1 and N. If N is 10, and the index is 4, then the 4th element in the set of 10 objects will be selected. What HexSim does is select an index randomly once at the beginning of each time step. This single index value is then used for all Survival and Reproduction events with set sizes greater than one, for the entire time step. This way, if a user wants to correlate good and bad years between events, they need only ensure that the sets of survival and reproductive rates are correlated across indices. Multiple pairs of vital rate vectors are inserted using the Add button at the bottom of the Reproduction event's Vectors tab. This adds an additional vector pair, which the user can then edit. But in most cases it will be much more convenient to use HexSim's Import and Export features for this purpose. Export writes the current vector set to a file, and Import reads a vector set from a file and places it into the event structure. The Import does not augment vector data, it replaces it. So any existing vector data will be lost upon Import. A Delete button can be used to remove unwanted vector pairs.

4.3 - Vital Rate Interpolators The interpolator concept is pretty straightforward. The user sets minimum and maximum resource levels. Think of these as the limits on the horizontal axis of an X-Y plot. The minimum resource value is called the Floor. The maximum resource value is called the Ceiling. The user also sets floor and ceiling vital rates. These set the minimum and maximum values of the vertical axis of the X-Y plot. As the resource increases from the floor to the ceiling, the interpolator is used to shift the vital rate from the floor vital rate to the ceiling rate. If the resource is below the resource floor, the floor vital rate is used. If the resource is greater than the ceiling value, then the vital rate ceiling is used. The vital rates in question can be either survival rates or fecundities. The interpolator concept is diagramed in the figure below. The blue and purple lines in the figure illustrate linear and convex interpolators.

26

At the moment, HexSim has thee different interpolators to choose from. These are referred to as linear, concave, and convex. The linear interpolator is simple defined as Y = mX with the slope being defined implicitly by the resource and vital rate floor and ceiling values. The concave interpolator is proportional to Y = Xr, and the convex interpolator is proportional to Y = 1 - (1 - X)r. These each have an exponent (r) that can be defined in the interpolator interface. A logistic interpolator will be added soon. The two figures below illustrate the convex and concave interpolators for a variety of exponents. The top figure displays the convex functions in red, and the concave functions in green. The exponents used were 2, 3, 5, and 10. The larger the exponent, the further the curve bends away from the line Y = X. The bottom plot was generated using fractional exponents of 1/10. You can see that when the exponent is less than one, the shapes of the curves no longer match their names. There is no clear advantage to the use of fractional exponents, but the exponents themselves are only restricted to be non-negative real numbers.

4.4 - The Dispersal Event The Dispersal event is designed to move floaters across the landscape. It presently contains parameters that govern floater creation, but these will soon disappear and be replaced with a Floater Creation event. Group members do not disperse. To move a group member, it must first be made into a floater. For this reason, users will typically want to run a Floater Creation event before a Dispersal event. But this is not necessary with the current version of Dispersal. The Dispersal event's Global tab is illustrated below.

27

•

The Global Tab

Using a Dispersal event necessitates selecting a population and a spatial data time series within which the movement will take place. The selection of dispersal barriers is optional. If selected, dispersal barriers will impact dispersers when the enter a hexagon by crossing over an edge that includes a barrier. This is illustrated in the figure below. The black arrow is meant to indicated a dispersal path that crosses a barrier (the blue and purple lines). Barriers are bi-directional, and can impose different mortality and deflection probabilities depending on the side that a disperser encounters. In this example, the disperser would encounter the purple barrier because that is the side that is crossed when entering a hexagon. The blue barrier was crossed when the disperser exited the previous hexagon.

An option also exists to impose per-step dispersal mortality. This is done by specifying mortality spatial data time series. Each hexagon of every HexMap in a mortality spatial data time series is interpreted as a probability. If per-step mortality is imposed, then each time a disperser enters a hexagon, the hexagon score is used as the probability that death will result. This feature must be used with caution, or the entire population will quickly perish. By way of a reminder, a separate checkbox is included in the interface that, when unchecked (the default setting) prevents dispersal mortality spatial data from being selected. Both dispersal barriers and per-step dispersal mortality can be imposed simultaneously. It is also necessary to determine who the dispersal event will act on, and this is done by selecting a set of traits and trait combinations. The trait combinations that are available result from the users choice of traits. When a trait combinations is selected, every floater possessing these attributes will disperse. The conditions for range abandonment are used to convert group members into floaters prior to dispersal. As mentioned above, this functionality will soon be removed from the Dispersal event and replaced by a Floater Creation event. At present, there are two conditions for range abandonment. First, the user may impose a rule that individuals will become floaters when the group size exceeds the maximum group size specified in the population parameters. The order that individuals are selected is randomized, from the set of individuals that the Dispersal event is set up to act upon. The Floater Creation event will provide finer-grained controls. Second, users will become floaters if their access to resources is limited. Users have the choice to effectively turn this off (Never Abandon Range), or force individuals to move for all resource levels (Always Abandon Range). You can also set the threshold for range abandonment to a specific resource value. •

The Dispersal Tab

The parameters that govern dispersal behavior are collected in the Dispersal tab. The options available include picking the distribution that will govern dispersal path lengths, establishing dispersal stopping criteria, implementing repulsion and attraction to landscape features, and setting the degree of movement autocorrelation. A feature called affinity is also in development. This tool will allow dispersers to return to sites visited in their past.

28

Three types of distributions can be selected for use in setting dispersal path lengths. These are referred to as Fixed, Uniform, and Lognormal. Fixed implies that all dispersers have the same dispersal path length. If fixed is used, then its only necessary to set a single path length parameter. Uniform implies that each disperser will select their path length from a uniform distribution. Thus when uniform is selected, both a path length minimum and maximum must be specified. Lognormal implies that dispersal path lengths will be drawn from a lognormal distribution. The lognormal is characterized by two parameters, a mean and a standard deviation.. But in addition, the user must also select both minimum and maximum path length parameters. If HexSim draws a path length (from the lognormal distribution) that falls outside of these bounds, then this value will be rejected and another draw made. The path length bounds parameters are all specified in hexagons. The path length parameters are used to establish what distribution individual path lengths will be drawn from. Then when each individual gets ready to move, it will simply draw a path length from this distribution. In the absence of stopping criteria (discussed below) the individual will then walk this number of steps, proceeding from hexagon to hexagon. The lognormal distribution is the only one that is tricky to parameterize correctly. The figure below shows a histogram built from 100,000 random variates drawn from a lognormal distribution with a mean of 20 and a standard distribution of 2.

29

If the path length distribution is set to Uniform then all path lengths between the minimum and maximum will be equally likely. If the distribution is set to Fixed, then all individuals will be assigned the exact same path length. The stopping criteria are used to terminate dispersal early. The intent is that the stopping criteria will give the individual disperser the ability to stop immediately if favorable conditions are encountered. Favorable conditions are quantified as a mean available resource experienced over some fixed path length. The user must select this mean resource level, and also must indicate over what path length this mean must be observed. For example, suppose the dispersal stopping criteria were set for a mean available resource of 50, observed over a path length of 10. This would imply that after every step, the resources available in the ten most recently visited hexagons would be averaged. If that average was at least 50, then the disperser would stop were they were. Available resource means resources not already allocated to another member of the same population. (NEED TO EXPAND ON EXACTLY HOW AVAILABLE RESOURCE IS COMPUTED) A problem with the dispersal stopping criteria is that it is not presently taking the presence of other floaters into account. Thus individuals who stop dispersing based on the presence of sufficient available resources may in fact be stopping in a location already densely populated by other dispersers who moved before. The actual available resource would not necessarily be sufficient to support all of the dispersers who stop in the area. A future update to HexSim will address this shortcoming. Repulsion and attraction are used to influence dispersal behavior away from some portions of a landscape, and towards other areas. Autocorrelation is used to make dispersers move in a more random or more linear fashion. In the absence of repulsion and attraction, zero autocorrelation produces random walks, and 100% autocorrelation produces straight-line trajectories. But repulsion, attraction, and autocorrelation all work together to determine the dispersal path characteristics.

The figure above will help to illustrate how repulsion, autocorrelation, and attraction all work together to influence dispersal behavior. Landscape barriers or excluded areas my restrict which hexagons a disperser can move to. But ignoring this complication for the moment, lets assume a disperser is on a hexagon which we'll call the focal hexagon, and that it will next move to one of this focal hexagon's six neighbors. The neighboring hexagons will all have a score and a direction relative to the focal hexagon In HexSim, the concept of the forward direction is obtained as the mode of the last N steps, where N is the parameter referred to in the interface as the Trend Period. That is, each time a step is taken, HexSim records the direction it was taken in, and then the most common direction from the past N (the Trend Period) steps is used to define the forward direction for the next step. The Trend Period parameter provides some inertia that keeps individuals moving in one general direction. Shorter Trend Periods provide less inertia, and longer Trend Periods provide more inertia. However, there is not much value in increasing the Trend Period for small values of Percent Autocorrelation.

30

The left gray box in the figure above diagrams this concept. The arrow points in the forward direction, and the neighboring six hexagons are labeled DA, AL, AR, BL, BR, and DB, for directly ahead, ahead left, ahead right, behind left, behind right, and directly behind. The HexSim Percent Autocorrelation parameter is related to alpha. Specifically, if Percent Autocorrelation is represented by A, then alpha = 1 - (A / 100) is a number between zero and one. The probabilities of moving in the six possible directions are expressed as functions of alpha, and hence as functions of Percent Autocorrelation. The six autocorrelation probabilities (PDA, PAL, PAR, PBL, PBR, PDB) are all smoothly varying, and sum to one. The expressions for PALand PAR are designed so PDA = PAL + PAR when the Percent Autocorrelation parameter is set to 50%, This scheme is entirely our own creation, but it seems to work quite nicely. Repulsion and attraction are used to obtain a scaling factor that is used as a coefficient (Z) for autocorrelation probability. The right gray box in the figure above diagrams this concept. And the number line at the top of the above figure illustrates the separate attraction and repulsion zones, which are not allowed to overlap. A single hexagon can be either repulsive (x < b), attractive (x > c), or neutral (b < x < c). For hexagons with a score less than the maximum repulsion, Z is fixed at zero. As the hexagon's score increases from the maximum to minimum repulsion values, Z increases linearly from zero to one. Z remains at one until the hexagon's score increases to the minimum attraction value. When the hexagon's score increases from the minimum to maximum attraction value, Z again increases linearly with slope 1/c. For hexagon scores greater than the maximum attraction, Z is fixed at d/c. All of this machinery is used to determine which of the neighboring hexagons to move to when dispersing. If a disperser is located in our focal hexagon, and ready to take another step, then each of the six neighbors is assigned a value equal to PZ, where P is the Autocorrelation Probability assigned to it, based on its direction relative to the current movement direction (the direction most commonly encountered over the past N steps, where N is equal to the Trend Period). At maximum repulsion, PZ = 0. When a neighbor's score lies in between the zones of repulsion and attraction, PZ = P. At maximum attraction, PZ = dP/c. The values of PZ scale linearly when the hexagon score falls in between these limiting values. Finally, a uniformly distributed random number is drawn and used to select a specific neighbor to move to. The larger a neighbor's value for PZ, the higher the likelihood that this specific neighbor will be selected. As mentioned above, the Affinity parameter is a work-in-progress, and not yet intended for use. The concept we are working towards is that affinity targets -- locations that are to be revisited -- will be stored in trait values, and thus personalized. The affinity algorithm will override the Trend Period, and set HexSim's notion of the forward direction to the direction that will take the individual to the affinity target. Then by turning on the affinity tool, dispersers will be forced to move towards sites that they have previously visited. Affinity will also be useful for moving groups as a whole. In this case, a single group member (a scout) will disperse initially, Then, the remainder of the group will be assigned an affinity target equal to the endpoint of the scout's dispersal path. Each subsequent group member will then disperse with affinity towards the scout's ending location.

4.5 - The Resource Exploration Event The Resource Exploration event is a versatile companion to the Dispersal event. Individuals can use Resource Exploration to start new, or join existing groups. It can also be used to update an individual's explored area without making any modifications to its group status or range. Resource Exploration can also be used to break up and reform existing groups, and it can be used to modify the range of a group without altering its membership. The Resource Exploration's Global tab is depicted below.

31

•

The Global Tab

The Resource Exploration event's Global tab is used to select a target population, and to set the Event Goal. The user is also allowed to specify whether the range parameters should be altered for this event. If the Modify Range Parameters checkbox is checked, then the Range Parameters tab becomes active. Modifications made to the range parameters will persist only as long as the event. As soon as the event has finished, the static range parameters (those set in the population parameters range data tab). The options available for setting the Event Goal are indicated in the table below. Event Goal

Method

Group Range Acquisition

Floater Range Acquisition

Exploration Only Join Existing Group

Function Each individual will perform an exploration. The consequence will be an updated explored area. Group and range properties will not be modified. Floaters perform an exploration in search of existing groups to join. If joining a group is not possible, then the individual will remain a floater.

Floaters perform an exploration in search of a new range. If a range can be constructed, then a new group will be started by the floater. Otherwise, the individual will remain a floater. Join Existing else Start Same as Join Existing Group, except that the individual will attempt to start a new group if it is not possible to join a group. New Start a New Group

Start New else Join Existing Split Groups Apart

Preserve Group Structure

Same as Start a New Group, except that the individual will attempt to join an existing group if it is not possible to start a new group. Group members will all become floaters. Then they will each attempt to join an existing group. If joining an existing group is not possible, they will attempt to start a new group. The group membership will remain intact. But the group will modify its range to try to best accommodate the resource needs of its members. Groups with excessive range will give some resources away. Groups with too little range will attempt to acquire additional resources.

The Exploration Only option is useful particularly as a prelude to an Interactions event. The Interactions event bases the probability that any two individuals will interact on the overlap between their explored or allocated areas. If you wanted a group member, for example, to search for prey 32

without modifying its group or range, the Exploration Only option could accomplish this. That is, the group member could update its explored area to simulate a search for prey that extended beyond its range. Then this new explored area could be used as the basis for an Interactions event, in which prey was consumed. Any prey falling within the new explored area would become potential targets for consumption. All of the event goals necessitate setting exploration parameters except group range acquisition where group structure is preserved. In this latter case, only range parameters are necessary. But the range parameters can still be modified for the Resource Exploration event, if the user so desires. If the event goal is to split groups apart, then the Floater Creation event is called (behind the scenes) to make every group member a floater. These floaters then reassemble into groups based on the parameters specified in the Exploration tab. The Exploration tab is discussed below. •

The Exploration Tab

The Exploration tab uses trait combination selectors to determine which individuals will perform an exploration. The Resource Exploration event thus makes it easy to convert group members into floaters (set the goal to split groups apart) but prohibit them from subsequently forming or joining a group. Thus users should think carefully before specifying that only individuals with certain trait combinations may perform explorations. Remember that it does not matter what traits are selected -for any trait or traits, if all of the trait combinations are selected, then the action will apply to every member of a population. Exploration barriers are optional. If a barrier time series is specified for exploration, then the barriers will impact individuals as they perform their explorations. Thus there can be mortality or deflection taking place during exploration. Exploration barriers work the same way that dispersal barriers do. But HexSim allows you to set them independently. That way the barriers may impact just one event, or another. Or the impacts of barriers may vary from one event to event. Per-step mortality may also be added to the exploration process. This is done by specifying mortality spatial data time series. Each hexagon of every HexMap in a mortality spatial data time series is interpreted as a probability. If per-step mortality is imposed, then each time an explorer enters a hexagon, the hexagon score is used as the probability that death will result. This feature must be used with caution, or the entire population will quickly perish. By way of a reminder, a separate checkbox is included in the interface that, when unchecked (the default setting) prevents exploration mortality spatial data from being selected. Both exploration barriers and per-step exploration mortality can be imposed simultaneously. The exploration process is a search for resources. And the user must specify the Maximum Search Area, which is specified in hexagons. If the exploration goal involves joining or building a range, then an implicit stopping condition exists that can terminate exploration before the maximum number of hexagons has been examined. Each individual has a resource target, and if its goal (joining or starting a group) can be met while simultaneously fulfilling this resource target, then the exploration will stop. The assumption is that there is no point in continuing to explore if the goal can be achieved without compromise. However, if the goal of the Resource Exploration event is set to Exploration Only, then exploration will always continue until the Maximum Search Area has been reached. This is because setting the goal to Exploration Only means that individuals will not try to join or start a group. Finally, if for some reason the user wanted to force exploration to continue until the Maximum Search Area was reached, this could be done by modifying the range parameters for the event. The exploration process can be conducted using one of three search strategies. The Uniform strategy simply performs the search in concentric rings spreading out from the starting point (the endpoint of dispersal). Still, the landscape edges, excluded areas, and barriers must be respected. So the ultimate search area may not be a simple set of concentric rings. The Greedy strategy keeps track of every hexagon that has been explored, and every unexplored hexagon that touches an explored hexagon. The list of unexplored hexagons neighboring explored ones is prioritized at every step, and the best neighbor is always the next site to be explored. Again, landscape boundaries, excluded areas, and barriers are all taken into consideration. For both the Uniform and Greedy strategies, the process continues until a range that meets the individual's target resource has been found, or the Maximum

33

Search Area has been reached. In either case, the entire explored area becomes the new range, as long as it meets the minimum resource criteria for ranges (specified in the range parameters). The Optimal exploration strategy is a bit more complex. When it is used, individuals build up a list of already explored hexagons. To select a new site to explore, the Optimal strategy first picks a seed site from the list of already explored hexagons. This seed hexagon is selected probabilistically, based on quality. Then each of the seed hexagon's neighbors is considered for exploration. These neighbors are evaluated based both on their quality and on the number of previously explored neighbors they have. The reason for including the number of previously explored neighbors in the evaluation is that it helps keep the ranges compact. The number of explored neighbors is simply used as a coefficient for the hexagon score. Unexplored hexagons with 1, 2, 3, 4, 5, and 6 explored neighbors are assigned coefficients of 1.0, 1.2, 1.4, 1.6, 1.8, and 2.0, respectively. The most significant difference between the Greedy and Optimal strategies is that the Optimal strategy is less constrained, and so it can branch out and possible discover good habitat clusters that may be missed by the Greedy strategy. This is because while the Greedy algorithm must always expand into the best available neighboring hexagon, the Optimal strategy may expand in any direction from the cluster of already visited sites. However, new site selection in the Optimal strategy is still based on hexagon quality, so the Optimal strategy will produce better quality ranges than the Uniform strategy. INSERT SEARCH ALGORITHM FLOW CHARTS HERE •

The Range Parameters Tab

The Range Parameters tab can only be used if the Global tab's Modify Range Parameters checkbox is checked. If this checkbox is left unchecked, then the static range parameters are used. The static range parameters are those supplied in the population parameters range tab. If the Resource Exploration event's range parameters are modified, then these changes will only persist for the duration of that Resource Exploration event. The Resource Exploration event's range parameters are otherwise identical to those in the population parameters range tab, and are therefore are not discussed further in this section.

4.6 - The Aging Event The Aging event is presently very simple. The user can only select which population it applies to. A bit of additional complexity will be added soon. In future versions, the user will have to select whether the Aging event is going to apply to a probabilistic trait or an accumulator. If the user selects a probabilistic trait, then for each individual the aging event will increment that individual's trait value. For example, suppose a population had a probabilistic trait named Stage_Class, with trait values of Stage_0, Stage_1, and Stage_2. If an Aging event was applied to thie Stage_Class trait, then any individual with a trait value of Stage_0, would end up being in Stage_1. Individuals's in Stage_1 would shift to Stage_2, and Stage_2 individuals would remain in Stage_2. If the Aging event was assigned to an accumulator, then anytime the event was triggered, each individual's copy of that accumulator would be incremented by one. As soon as the accumulator is incremented, HexSim will automatically update any dependent traits. The Aging event is just a convenience, since it is really just a special case of the Transition or Accumulate events. A Transition Event matrix structure that would simply increment stage classes is illustrated below.

34

An Aging event associated with a Probabilistic trait would accomplish the same thing, but would be easier for the user to set up. The Transition event is, of course, more flexible. If instead stage class was an accumulated trait, and assuming the associated accumulator was called Age, then an Accumulate event equivalent to Aging is illustrated below.

In this case, the Accumulate event has a single updater function. That updater simply increments the Age accumulator by one. Again, the Accumulate event is more flexible than is Aging, but the Aging event is quick to set up.

4.7 - The Census Event The Census event does not presently give the user control over anything other than what population it applies to. But for each census event, a CSV (comma separated variable) file is produced that contains population size data by replicate and time step. These CSV output files are assigned a numeric index as part of their filename, that corresponds to their order in the life cycle. The Census event also writes data to the HexSim Log file, if the log file is turned on in the simulation controls. Future versions of HexSim will not automatically generate CSV files for each Census event. Instead, all Census event data will be stored in a single log file, and tools will be provided to extract data equivalent to that in

35

the CSV files directly from the log file. HexSim can store multiple HexMap tallies that are generated by events such as Survival and Reproduction. Each time a Census event is triggered, a n occupancy tally is updated. So the placement of the Census event dictates when the occupancy information is actually gathered by the model. Multiple Census events will simply increment the occupancy tally multiple times per time step.

5). HexSim Advanced Events 5.1 - The Accumulate Event The Accumulate event is really very straightforward. Accumulators are real-valued variables that can track an individuals age, resource acquisition, exposure to toxicants or disease, etc. Accumulated traits use accumulators to determine what an individual's trait value should be set to. The accumulate event is used to alter accumulator values, and anytime an accumulator is modified, its dependent traits are automatically updated. So for example, you might have an accumulator called Age that's linked to a trait called Stage Class. This could easily be set up so that as individual's age increases, so would their stage class. The Accumulator event is what you would use to increase every individuals' age. The figure below illustrates an Accumulate event with a single updater function that's set up to increment an accumulator named Age. The figure also shows the Accumulate event's context menu, which is used to add updater functions.

The Accumulate event depicted above has a single updater function that increments, and that targets the accumulator named Age. In this case, the updater function parameter window is shown below.

36

The updater function parameters are different for the different updater types. Every one requires the user to select an Accumulator Name. The Clear updater function has no other parameters; it simply sets the accumulator to zero. The Increment and Decrement updater functions have a single parameter that specifies the amount by which the accumulator should be incremented or decremented. The Current Range Mean updater function computes each individual's mean range value (the total range quality divided by the number of hexagons in the range) and assigns this value to the accumulator. If the individual is a floater, then its allocated area is used in place of a range. The Current Range Mean updater function requires the user to specify a spatial data source for use in the range mean computation. Both the Running Range Mean and Running Range Sum require that the user specify a spatial data source, and also the number of time steps to use in making the computation. The Running Range Mean and Sum compute the mean and sum of an individual's range, taken over the past N time steps, where N is the updater function parameter that the user must set. When this parameter N is set to 1, the Running Range Mean and the Current Range Mean updater functions will produce identical results. Future versions of HexSim will have an expanded list of updater functions, and will use a more informative parameter labeling scheme (e.g. replacing "Parameter" with "Increment By:". HexSim allows a single Accumulate event to have multiple updater functions, which can help to keep the life cycle compact. And as is true with other HexSim events, the user may add as many Accumulate events to the life cycle as desired.

5.2 - The Transition Event The Transition event Properties tab allows the user to specify a population and a probabilistic trait. Once these are selected, then the trait values are used to construct a matrix in the Matrices tab. The Matrices tab is where all of the other Transition event details are specified. The Transition event's functionality is analogous to that of matrix multiplication. But whereas matrix multiplication would operate on the population as a whole, altering the number of individuals in each stage class, HexSim's Transition event operates on an individual-by-individual basis, and the matrix elements must be probabilities. The matrix elements must sum to one within any given column, and to enforce this, HexSim does not let the user set the value of the diagonal elements. Take, for example, figure below, and note the To and From arrows in the upper-left corner of the matrix.

This matrix tells HexSim that Stage Class 0 individuals have 100% likelihood of becoming Stage Class 1. Stage Class 1 individuals have 100% likelihood of becoming Stage Class 2. Stage Class 2 individuals have 100% likelihood of becoming Stage Class 3. And Stage Class 3 individuals are certain to remain in Stage Class 3. A second example can be constructed assuming that a trait has been 37

constructed to capture disease status. In this example, illustrated below, the disease dynamics are simply captured with probabilities, the trait is probabilistic, and the Transition event is used to shift individuals between disease classes.

What this matrix tells HexSim is that susceptible individuals have a 10% chance of becoming exposed. The remainder will remain in the susceptible class. Exposed individuals have a 70% chance of becoming infected, with the remainder transitioning back into the susceptible class. Half of the infected individuals will recover, and half will not. All of the recovered individuals will become susceptible again, but if an individual did not recover, they are stuck in that state. The Transition event is not allowed to create or destroy individuals. This is imposed by forcing the columns to sum to one, and because the transition event just alters the traits of existing individuals. In the example above, it was necessary to create a Did Not Recover trait value, because the event could not kill individuals who didn't recover. That would be most easily handled by following this Transition event with a survival event imposed 100% mortality on individuals in the Did Not Recover class, and zero mortality on everyone else.

5.3 - The Interaction Event The Interaction event is the most complex of all HexSim events, both conceptually, and in terms of the interface. But it is flexible, and not that difficult to master. Interactions are always pair-wise, but may be between two separate populations, or between members of the same population. An example parameterization for predators and prey is displayed below. In this case, both predator and prey populations have been created, with predators having three traits, and the prey having four.

38

Everything you need to master in order to use the Interaction event appears in the Properties tab, and in the Interaction Outcomes parameterization window. The Properties tab has two rows of parallel data at the top of its interface, one for the primary, and one for all secondary populations. The New Tab button is used to create one or more secondary population tabs. The image below isolates these two parallel constructs from the Interactions event, as depicted in the figure above.

Each Interaction event defines one or more sets of pair-wise interactions, with one of each pair always being the single primary population, and one of each pair being either the primary or a secondary population. As illustrated in the image above, each population has a Zone of Influence and an Influence Rule. The Spatial Data menu is only active when the Influence Rule is set to "weighted". Each time the New Tab button (visible in the figure at the top of the page) is clicked; a new tab opens up that allows you to specify an additional pair-wise interaction. The Zone of Influence parameter indicates what spatial region will be used to determine if an interaction takes place. More specifically, the probability that a member of the primary population will interact with a member of the secondary population is derived from the two zones of influence, and their associated rules. The Zone of Influence can be set to an individual's explored or allocated area. The Influence Rule can be set to Always, Uniform, or Weighted. Always means that individuals from the corresponding population can be thought of as always present throughout its zone of influence. Uniform means that the probability that an individual is present in a portion of its zone of influence is proportional to its size. That is, if you selected a a portion of the zone of influence that was 10% of the whole, then under the Uniform rule, an individual would have a 10% chance of being found there. Weighted means that the likelihood of being in a portion of the zone of influence is proportional to area, but weighted by quality. In this case, quality is derived from the spatial data selected by the user. A couple of examples will help make this clear. Lets assume that X and Y are members of the primary and secondary population. X and Y both have zones of influence. Lets say that X's influence zone is made up of 10 hexagons, and Y's is made up of 30. Now assume that the two zones of influence have 6 hexagons in common. This means 39

that 60% of X's zone of influence overlaps with Y's, and 20% of Y's zone of influence overlaps with X's. Now lets say that both populations were assigned a Uniform influence rule. The probability that the two individuals would interact is 0.60 (the probability that X is in the overlapping region) multiplied by 0.20 (the probability that Y is in the overlapping region). So the probability that they will interact is 0.12. Now, if we take the above example, but set Y's Influence Rule to Always, then the probability that Y will be in the overlapping region becomes 1.0. Thus the probability of interaction becomes 0.6. When the Influence Rule is set to weighted, the probability that the individual is going to be in the area of overlap is equal to:

where i = [1, k] are the hexagons in the area of overlap, and i = [k + 1, n] are the hexagons outside of the area of overlap, and the Qi is the quality of the ith hexagon. The middle portion of the Interaction event Properties tab is used for trait selection. A trait selector is supplied for the Primary Population, and for the Secondary Population assigned to this interactions tab. The figure below isolates this portion of the Interaction event.

In this case the Primary Population's Fitness trait has been selected, and the Secondary Population's Stage Class trait has been selected. More than one trait can be selected simultaneously if desired. The trait selections are used to assemble an outcomes matrix. The outcome matrix's columns list the Primary Population's selected trait combinations, and the columns list those of the Secondary Population. If no traits are selected for a population, then only a single row or column will be generated in the outcomes matrix. This row or column will apply to all members of the respective population. The outcomes matrix allows users to specify what will happen if an interaction takes place between members of the primary and secondary populations, for each possible set of trait combinations. The figure below illustrates this point.

In this case, interactions have been defined for members of the predator (primary) population with medium fitness that encounter members of the prey (secondary) population of stage class 2. Also, interactions have been defined for members of the primary population with high fitness that encounter members of the secondary population of stage classes 2 and 3. Each outcome can be different, and this arrangement of outcomes might make sense if predators of low fitness were unable to hunt, if prey of stage classes 0 and 1 were not sought after by predators, and if predators of medium fitness were not able to capture prey of stage class 3. Interaction outcomes can be specified by right-clicking in one of the interaction outcomes matrix cells, or by double-clicking. Doing so brings up the Interaction

40

Outcomes parameterization window, which has separate panels for the primary and secondary populations. This parameterization window is shown below, along with the outcomes context menu, which allows users to add or delete outcomes, and to assign death as an outcome.

To define an outcome, the user must open the Interaction Outcomes dialog (shown above) and call up the context menu associated with one of the two panels. Outcomes do not have to be added for both the primary and secondary population, but doing so will be common. And multiple outcomes can be associated with either population. But if death is selected as the outcome, no other choices can be added. The death outcome has no parameters to set. Other outcomes necessitate specification of an accumulator, and accumulator updater function. Some updater functions require an additional parameter. The available accumulators are simply those supplied to the population in the Population Parameters Traits and Accumulators tab. Once an accumulator is specified, the corresponding traits are displayed in a read-only column at the right of the outcomes panel. The accumulator updater functions presently available include clear, increment, and assign. Other updater functions may be added later. The clear updater function simply sets the accumulator to zero. The increment and assign updaters both require that an additional parameter be assigned. Increment simply adds the parameter value to the selected accumulator. Assign sets the accumulator equal to the paremter value. In the predator-prey example, the interaction may cause the death of the prey, and result in a modification of a predator resource acquisition accumulator. The prey population outcome would then be set to death, and for the predator, the appropriate accumulator might be updated by an amount that signifies the resource value of the prey for the predator. The interaction outcomes matrix allows prey resource values to vary with prey characteristics. If no outcome is specified for a given interaction outcomes matrix cell, then that interaction simply will not take place.

5.4 - Persistent Generated HexMaps Persistent Generated HexMaps are just generated HexMaps that persist for a simulation time step. The mechanism for defining the generated HexMap is the same as what is available for the generated HexMaps throughout the model. However, the typical generated HexMaps only last as long as the event in which they have been invoked. The persistent generated HexMaps are invoked by an event, and they last until the event is invoked again, in the next time step, at which time they are replaced with an updated copy. But persistent generated HexMaps appear in the list of available spatial data, and thus can be used by any other event in the event sequence. The basic ideal with all generated HexMaps is that the user can select HexMaps from the available spatial data, and types of model state information that can be represented as spatial data. Each of these is assigned a variable name, and then the user constructs an equation using these variables. The equation describes the generated map. The types of model state information available is going to change, and will therefore be ignored for the time being. The Persistent Generated HexMap parameterization window is displayed below.

41

The user can supply an event name, and a name for the generated HexMap. The available map-based data that can be used to generate a HexMap are all accessed through the pull-down menu to the right of the Add button. Use this menu to select a data source, and then hit the Add button. This will assign a variable name (e.g h1, h2) to the data source, and add it to the list in the middle of the window. In the image above, the Habitat and Disturbance spatial data series have been added, and assigned the variables h1 and h2, respectively. Once all of the desired spatial data have been added, you may create a formula for the generated HexMap in the box at the bottom of the window. In the example above, the formula used is simply h1 + h2. This instructs HexSim that each hexagon in the generated HexMap will have a value equal to the sum of the corresponding hexagons in the Habitat and Disturbance spatial data. If Habitat and / or Disturbance are time series with multiple steps, the actual HexMaps that will be used in the computation are those for the time steps active at the time the generated map is constructed. Generated HexMaps are useful for simulating stressor interactions, or for facilitating inter- or intra-specific interactions. Stressor interactions can be captured by linking survival, reproduction, or dispersal events to generated HexMaps that combine multiple single-stressor HexMaps in appropriate ways. For example, if two stressors had an additive impact on mortality, a generated HexMap might sum individual HexMap representations of each stressor, and this product could be used to drive a Survival event. In addition, generated HexMaps could be used to guide potential mates to each other, or predators to prey, etc. However, some additional work will have to be done to the HexMap generation tool before some of these operations are convenient, or even possible.

42