Background

Overview

HexSim is a spatially-explicit, individual-based computer model designed for simulating wildlife and plant population dynamics and interactions. HexSim is a framework in which users can develop simulation models without writing computer code.

Space in HexSim may represent as a two-dimensional grid, and as a system of branching networks. Simulated individuals must be specified as living within a grid, or within a network, and cannot have both properties. However, a single simulation can include both population types. At present, there are limited tools available through which the grid- and network-based populations may interact.

HexSim includes a sophisticated graphical user interface (GUI). The model uses spatial data to capture landscape structure, habitat quality, stressor distribution, and other types of information. HexSim can work with real or fabricated landscapes. HexSim’s design makes it ideal for exploring the cumulative impacts to wildlife and plant populations of multiple interacting stressors.

HexSim also includes a flexible genetics sub-model, and is an excellent platform for developing eco-evolutionary (eco-evo) simulation models. In particular, HexSim life history traits link the model's demographic and genetic components. In HexSim, for example, selective pressure can be applied to a genetic trait by linking it to a behavior or vital rate. And demographic and genetic traits can be coupled, making it easy to develop a model in which fitness is partly inherited and partly a consequence of an individual's success at capturing resources, or exposure to stress or disease.

Examples of evaluations that HexSim is suited for include:

Features built into the HexSim model include the ability to:

HexSim simulations are built around a user-defined life cycle. This life cycle is the principal mechanism driving all other model processing and data needs. Users develop the life cycle when initially setting up a simulation. The life cycle consists of a sequence of life-history events that the user selects from a list. This event list includes survival, reproduction, movement, resource acquisition, species interactions, and many other actions. Through the creative use of events, the user can impose yearly, seasonal, daily, or other time cycles on the simulated population. Each event can work with all, or just a segment of a population, and events can be linked to static or dynamic spatial data layers. Each life-cycle event has its own data requirements.

Model Design

HexSim is a collection of executable and other files that are integrated through a modern graphical user interface (GUI). Conceptually, HexSim consists of an interface, a model engine that conducts simulations, and a series of output processors. But HexSim also contains a wide array of tools for creating and editing spatial data, constructing and maintaining workspaces (the model’s external data structures), data import and export, scenario construction, event parameterization, visualization, and so on (see figure below).

HexSim scenarios (simulation files) include descriptions of one or more populations, spatial data needs, life cycle definitions and event parameterization, and basic simulation criteria such as the number of time steps. Each population is composed of individuals, and individuals have traits that can change probabilistically, or based on age, resource availability, disturbance, competition, etc. HexSim also includes optional genetics and heritable traits. The use of traits allows individuals to have unique properties that change in time and space. Traits also allow populations to be segregated into classes, such as males and females, fitness categories, disease categories, etc. Combinations of trait values can be used to stratify events such as survival, reproduction, movement, etc.

The HexSim life cycle consists of events that are drawn from an event list. The event list has a wide array of event types, each of which can be parameterized in many different ways. Simple scenarios may use few events with minimal parameterization and little spatial data. But when more complexity is warranted, HexSim allows a great deal of data and behavior to be added to its simulations.

HexSim Workspaces

HexSim organizes projects into "workspaces". Each HexSim workspace contains a grid file, plus Analysis, Spatial Data, Scenarios, and Results folders. The Analysis folder is a place for users to add their own content. The Spatial Data folder contains additional sub-folders. Users should not alter the workspace structure. The critical elements of the HexSim workspace structure are displayed below. 

The model creates and maintains the workspace structure for the user. The model interface’s Workspace tab provides a view into the workspace structure. Workspaces contain input files called scenarios, spatial data, results, and other items. The scenarios and spatial data are displayed in the workspace tab. When scenarios are opened, they come up in their own tabbed windows. The HexSim menu includes options for opening multiple workspaces, creating new workspaces, build new spatial data, construct new scenarios, and many other useful operations. Scenario and spatial data context menus provide additional functionality.

HexSim Scenarios

A HexSim scenario is an XML file that contains all of the information necessary to run a HexSim simulation. Scenarios include population definitions, spatial data requirements, an event list, and event parametrization. Populations and events have sophisticated parameterization windows, but most of the model’s complexity can be ignored if desired. Events can be set up to trigger once, only within a temporal window, periodically, or randomly. The model has tools for building in environmental stochasticity and for controlling density dependence. Individuals from the same, or from different populations can interact, compete for resources, share diseases, and so on. Because all of this information is stored in a single scenario file, it can be quickly retrieved and used to run a new simulation. Scenario files are small in size and easily shared. Users interact with scenarios in HexSim scenario tabs (see figure to the right).

HexSim Populations

HexSim simulations must include at least one population. When multiple populations are present, individuals from the different populations may interact with each other, and they may compete for resources. HexSim populations are of two types - grid or network. All events that are assembled into a scenario for each population must match the population type. Events names contain "Network" if they are specific to a Network population. For example, the life history event that relocates individuals within a network is called Network Movement.

In HexSim, all individuals are placed into one of two categories -- floaters or group members. This scheme is useful for simulating territorial species, but it can also be effectively ignored when working with non-territorial animals. Group members are territory-holders, and only group members are allowed to reproduce.

The first step in building a HexSim model is adding a population. A new population is created by right-clicking in the Populations panel of a scenario tab. Users then select either Terrestrial or Network population types. The Population Parameter’s Properties tab is used to establish some initial conditions. For grid-based populations, a Range Data tab is used to define group and range properties, use of space, resource needs and priorities, and other information. Also specific to grid-based populations, an Affinities tab is used to define affinity structures. Affinities are collections of hexagons that may be revisited at some later time. HexSim has four types of affinities: natal, reproduction, resource, and group movement. Finally, the Traits tab is where users define population traits. Every population must have at least one trait that contains at least two trait values. Trait builders have been provided to automate the creation of some of the most common trait types.

Traits are a fundamental part of HexSim scenarios. HexSim traits are defined at the population level, but they are implemented on an individual basis. What makes HexSim’s traits particularly valuable is that users can set them up any way they see fit. And the traits can then be used to control most life cycle events. Traits can influence events because events can be stratified by trait combinations. For example, a movement event might be set up to operate only on a fledgling stage class. Or a survival event might assign mortality based on the values of a trait that reflects resource acquisition. In addition, one trait’s values can also be influenced by multiple other traits, which makes it possible to set up stressor interactions and complex feedback loops. Traits can also be used to capture interactions such as parasitism, competition, mutualism, breeding, and so on.

HexSim traits can be probabilistic or accumulated (changing with time or exposure, etc.). HexSim also has a genetics module and heritable traits, though these are not available to network-based populations. Accumulated traits change based on individual experience, which is captured in a series of variables called accumulators. Events called updater functions modify accumulators, which in-turn alter accumulated traits. Transition events are used to modify probabilistic traits. Interaction events change trait values based on intra- and inter-specific interactions. Trait builders automate the process of setting up the most common trait types. Heritable traits are based on an individual's genotype, which is created at birth from its parents genotypes. HexSim genetics also include mutation, which can further impact an individual's heritable traits.

HexSim Life Cycles

HexSim simulations consist of one or more replicates, with each replicate having a fixed number of time steps. The number of replicates to use is specified at run-time (replicates is not a scenario parameter). A time step is one complete pass through a user-defined life cycle. The life cycle is made up from a sequence of events, and each event operates on one or more populations. A time step will often correspond to a year, but it does not have to. Users construct life cycles by selecting events from a list. Each event has a corresponding parameterization window that allows its behavior to be specified. The complete set of parameters associated with a simulation are stored in a file referred to as a "scenario".The model interface provides the user with a list of the scenarios available within a workspace. Scenarios can be quickly retrieved, edited, used to launch new simulations.

HexSim Input and Output Files

HexSim is a collection of files, including multiple executables. One of the executable files is the main Graphical User Interface (GUI), and another is the model engine. The role of the GUI is to construct an XML scenario file that can be passed to the engine at run-time. The scenario file holds the absolute path to the workspace being used, a list of the requisite spatial data, a description of the simulation being run, and the full set of simulation parameters.

Simulations are typically launched from the model interface, but they can also be started directly from a command window by invoking the model engine executable, and passing it a scenario file. The other executable files included with HexSim are used for a number of different tasks. Some of these can be launched directly from a command window (with specific command-line parameters), and others cannot. But every one is accessible through the main HexSim interface.

When a simulation is launched, a sub-folder is created within the workspace Results folder. This new folder is used to store the simulation output. HexSim Census and Data Probe events create comma-separated-variable (CSV) files that track various measures of population size and individual properties by time step. HexSim also stores simulation results in a log file that can be used later to generate a variety of reports, maps, and animations that illustrate the model dynamics. Interface menu options provide access to modules that automate the generation of these reports, maps, and other simulation products. HexSim also includes a dynamic simulation viewer that uses log file data to generate animated movies illustrating simulation dynamics. The use of log files as the principal repository of simulation output means that users need not anticipate what analyses they will want to perform prior to running a simulation. HexSim's log files are simply text documents with well-defined internal structure. Users have control over what data will be saved to log files. But all logging parameters are turned on by default, and users should be cautious as log files can easily grow to many gigabytes in size.

Reanimation Events

Reanimation events make it possible for users to begin one simulation using ending conditions obtained from another simulation run previously. The Reanimation event can operate in one of two modes, determined by an Import vs. Export setting (see below). When used to export data, the Reanimation event will write an XML file to the workspace's Cache folder (if necessary, this folder will be created). When used to import data, the Reanimation event will read an XML cache file, and use the information it contains to recreate the population it describes.

Reanimation events will be useful when multiple replicates are to be run using a model that takes a long time to achieve steady-state. In such cases, Reanimation allows users to run a single simulation to steady-state, at which time a Reanimation cache file would be exported. Then all subsequent simulations can begin by importing the cache file. The replicates would then all begin with identical initial conditions, and subsequently diverge due to model stochasticity. This strategy can save enormous amounts of computing time.

HexSim Landscape -- Grid or Network

HexSim simulations are built around a user-defined landscape that can be either a 2-dimensional grid of hexagons, or a branching, directional network consisting of segments and nodes. In either case, the landscape represents the topology within which individuals interact with space, such as through movement or resource acquisition. The grid-based landscape is the most general, and thus most powerful way in which space can be represented. However, there are specific properties of networks, such as directionality and branching order, that are commonly used in landscape ecology. These features could be approximated within a grid-based system, but are much more efficient when performed on a true network. We have therefore added a complete network sub-model to HexSim. The work-flow for developing population simulations on grid vs. network landscapes are fundamentally the same, though the details differ sufficiently that a user should carefully weigh the pros and cons of the two approaches prior to initiating the workspace and scenario construction process. Any specific HexSim workspace can include both grid and network topologies.

Populations must be defined as living either on a grid or a network. However, a single HexSim scenario can include populations of both forms, and individuals with different topologies may interact to a limited extent. Individuals from two populations using the same topology can interact in many ways, making it straightforward to simulate competition, predation, parasitism, etc. At present, interactions between grid- and network-based populations must be mediated through their landscapes. Specifically, grid-based individuals can alter the properties of network segments they encounter, which might have consequences for network-based individuals. And network-based individuals can alter the scores of the hexagons their network traverses. HexSim performs these tasks using the Network-Hexmap Interaction life history event. In time, additional features will be developed to help users simulate cross-topology interactions. Note also that HexSim's Switch Population life history event can move individuals between populations even when those populations exist within different topologies. This event makes it possible, for example, to simulate an amphibian that begins life as an aquatic organism, but later morphs into a terrestrial organism.

Grid based populations operate on a 2-dimensional array of hexagons, while network based populations must contend with a fractal environment having a dimension somewhere between 1 and 2. Of course, the fractal-dimensional property of networks means only 1-dimensional movement is possible, while in grid-based populations, 2-dimensional movement is typical. In some cases, the choice of grid versus network will be straightforward. A wide ranging ungulate that fully exploits the two-dimensional nature of its landscape will be best simulated using a gridded landscape. In contrast, a stream dwelling fish may appear an obvious candidate for HexSim's network-based topology. But if the 2-dimensional nature of the streams in which it resides are important (if conditions or resources vary along a cross-section), then both topologies should be considered. Users must decide if the large-scale network structure is more important than the fine scale, but higher-dimensional structure, or visa-versa. If the network structure dominates, then a network-based population and associated network-based events and tools would be the best option. If, on the other hand, the two dimensional nature of river habitat is an essential component of the simulation, then a network-like array of grid cells (hexagons) can be developed.

Networks, due to their inherent efficiencies, may also be the best choice for terrestrial populations having a very large spatial extent. For example, species with life cycles dominated by long distance migrations such as birds or insects utilizing distinct fly-ways, or ungulates moving between seasonal habitats, might be represented as network populations. Doing so could simplify the spatial representation of their domain, and make the movement processes easier to simulate.

HexSim's network features are only visible when the <aquatic> tag is set to true, in the HexSimPreferences.xml file.

The HexSimPreferences.xml file is part of the HexSim package contained in the downloadable zip file. This file can be modified using a text editor. The two examples below illustrate how the network features can be turned off or on:

Network Tools Visible

<?xml version="1.0" encoding="utf-8"?>

<preferences>

  <main>

    <aquatic>

      <use>true</use>

    </aquatic>

Network Tools Invisible

<?xml version="1.0" encoding="utf-8"?>

<preferences>

  <main>

    <aquatic>

      <use>false</use>

    </aquatic>

HexSim Spatial Data for Grids

For populations that are simulated on a grid, the HexSim workspace will contain a single grid file, and one or more spatial data time series. Grid files describe the basic landscape geometry, such as the number, size, and arrangement of hexagons. The spatial data time series are organized into themes. Each such theme is composed of one or more time steps. A time step is a single file, and a spatial data time series is a collection of such files all having a similar title. HexSim grid spatial data can come in the form of HexMaps and Barrier maps. HexMaps capture land cover information such as habitat quality. Barrier maps can capture the influence of linear features such as roads.

HexSim can construct grid spatial data time steps from comma-separated-variable (CSV) files, Shapefiles (an ESRI file format), and from 8-bit (256 color) uncompressed raster files in a Microsoft Bitmap (BMP) format. Shapefile and CSV data are imported directly, while bitmap data are intersected with the workspace grid and sampled using a tool called the HexMap Constructor. When the HexSim constructs spatial data from a bitmap, it places a copy of the bitmap file in the Spatial Data / Bitmaps folder. The HexMaps themselves are stored in the Spatial Data / Hexagons folder, and Barrier maps are found in the Spatial Data / Barriers folder. HexMaps and Barrier maps are arranged by theme. Each theme is assigned its own sub-folder. The theme folders house one or more spatial data time steps. A HexMap time series 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 and maintain these structures automatically.

There are two concepts to keep in mind when working with HexSim grid spatial data. The first is that you may use as much or as little grid spatial data as you like. A single HexMap is adequate for running a simulation. A more complex simulation may make use of many spatial data themes, each represented by multiple time steps. And these themes might be quite diverse, with some representing habitat, others capturing stressors, and some representing landscape barriers. The second concept to remember is that all HexSim grid spatial data are inherently time series. Each spatial data theme must have a HexMap representing time step one. The use of subsequent time steps is optional. When spatial data include multiple time steps, HexSim automatically inserts the correct data at the appropriate time. When no additional time step-specific Hexmaps have been provided, the data from the last time step will be used in all subsequent time steps.

HexSim Spatial Data for Networks

For populations that are to be simulated on a network, the HexSim workspace will contain a single network file, and one or more spatial data time step update files. Network files describe the basic landscape topology, such as the size of network reaches, and the spatial arrangement of reaches relative to a designated "upstream" or "downstream" location. The CSV property files that can accompany HexSim networks each define properties, and their values for a specific range of time steps. There can be more than one such property file, but their time step ranges must be non-overlapping.

Interface Idiosyncrasies

When a computer's display size is set to a value other than 100%, this can cause the HexSim interface objects to appear crowded together, or not fully resolved on the screen. Any such GUI problems should go away if the display resolution is set back to 100%.

In most parts of the HexSim GUI, the TAB character is used to accept a value and move on to the next interface widget. The RETURN key will be ignored in these situations.