HexSim Accessories & Programs 

Red-Yellow.pal

This color palette file can be imported into XnView's "Edit palette" tool. When displaying source-sink maps, it can be advantageous to use a color scheme that clearly distinguishes sources from sinks. This Red-Yellow color scheme does so by joining two dissimilar color gradients. Neutral sites (those with hexagon scores close to zero) will be shown in black. Sources will be shown using a gradient that shifts from green to yellow. Sinks will be shown using a gradient that shifts from blue to red. These color gradients here are nonlinear, and thus lump the worst sinks and best sources together visually. The Red-Yellow color scheme is shown below.

Bitmaps.zip

This zip file contains nine bitmaps that may be useful for getting started with HexSim. These BMP files can be opened with HexSim's Generate Hexmap tool (available under the HexSim menu). Several of the bitmap files come with a companion text file that indicates what the different image colors represent, and who to credit for the construction of the map. The four files labeled Jackson Pollock were made from images of this artist's work that can be found online. These bitmaps no longer look much like the original paintings because the images were reduced to just a handful of unique colors. These four Jackson Pollock images are intended to invoke the concept of spatial pattern without representing any actual place.

Hexagon-Facts.pdf

This PDF file contains 8 pages of useful information about hexagons and hexagon grids. This information was all captured from a website that apparently no longer exists, and the author of this material is unknown (else attribution would be given). Note that HexSim's hexagons are oriented differently than those described in this file.

For fun, here is a link to an entertaining YouTube video that discusses the importance of hexagons in nature: Hexagons are the Bestagons

Hexagon-Grid.pdf

This 1-page PDF file contains a hexagon grid that can be printed, or included in figures.

HexSimR

This R package was developed by Dr. Carlo Pacioni of Murdoch University, in Perth, Australia.

These HexSim models run within the Example Workspace. Just download (by clicking on the headings), unzip, and move to the Example Workspace's Scenarios folder.

Select Individuals

This HexSim model illustrates how users might select a fraction of a population, so these individuals could be subsequently treated in some unique fashion. The fraction to be selected is specified using a Global Variable. The population of interest is randomly assigned to two categories (Category A versus Category B), and the selection process is only performed using Category A individuals. In an actual model, Category A might (for example) be replaced by the collection of all adult males occupying some specific portion of the landscape. And, the selection process might be used as a mechanism for simulating hunting pressure. The example uses a manager population to count the number of Category A individuals, and to select them iteratively until the desired number has been reached.

The first step involves building a simple hexmap in which all hexagons are scored 1. This allows a single member of the Manager population to be added while simultaneously setting its explored area to the entire landscape. The Manager and Critters populations are then initialized. Next, every member of the Critters population is assigned a 1-hexagon explored area. An Interaction event is used to count the number of Category A critters, and this value is stored by the Manager. The Manager then computes the number of Critters to select, and stores this information in a counter. A second Interaction event is used to select individual Critters, and to decrement the Manager's counter. Finally, a Census event records how many individuals have been randomly assigned to each of the two categories, and how many of the Category A individuals were selected.

Our approach to the interpolation of survival rates is may be a bit more biologically compelling than our reproduction example. This example code generates survival rates that vary smoothly with resource acquisition. These values are stored in accumulators, and can be used directly in a Survival event (by supplying the accumulator name to the event). Conversely, our model also generates binary survival outcomes that are stored in a trait. This trait could also be used in a Survival event.

In contrast, users may prefer not to use our reproduction code, and instead utilize a Reproduction event stratified by stage class and resource class, or possibly a Propagation event utilizing a mean value that varies smoothly with resource acquisition. Nonetheless, we felt there was value in providing users with a reproduction analog to our survival code. Our reproduction example generates integer clutch sizes that are stored in an accumulator. That accumulator would be used as a mean value in a Propagation event, paired with a standard deviation of zero. (When the standard deviation is zero, Propagation events produce numbers of offspring exactly equal to the mean value.)

Example output generated by our model is displayed below. These data were generated using the global parameters shown above.

Lognormal Paths

This HexSim model illustrates how lognormally-distributed dispersal path lengths can be computed directly, and assigned to an accumulator. The user sets the lognormal mean and standard deviation using Global Variables. The model (a) translates these into a mean and standard deviation for a normal distribution, (b) draws normally-distributed random variates, and then (c) maps them back onto a lognormal distribution. For more information, see Morris, W. F., and D. F. Doak. 2002. Quantitative conservation biology: theory and practice of population viability analysis. Sinauer Associates, Sunderland, Massachusetts, USA.

HexSim Movement events provide an option for drawing path lengths from a lognormal distribution. But if users wish to carefully examine the resulting distribution of path lengths, it is more convenient to make those assignments directly via accumulators. The accumulator values can then be written out using a Data Probe. However, while the Accumulator Expression updater function includes a standard normal distribution (GasDev), it doesn't include a lognormal distribution. This model shows how to map random numbers obtained from a standard normal distribution onto a lognormal distribution.

In addition, this model allows users to establish dispersal minimum and maximum values. When lognormally-distributed random draws fall outside the proscribed range, they are rejected and another selection is made. This work is performed within an iterating Event Group.

More generally, Data Lookup events make it possible for users to incorporate any arbitrary distribution into a HexSim simulation. First, a large collection of random draws from the desired distribution must be assembled into a CSV file, outside of HexSim. Then whenever needed, a Data Lookup event can access this file, assigning individuals values drawn from the table at random.

Quasi-Gradient Paths

This HexSim model implements a dispersal scheme in which movements are partly random and partly up-gradient. Purely random movements will not exhibit taxis, whereas purely up-gradient movements tend to be unrealistically deterministic. The hybrid movement paths that emerge from this model can balance these concerns. Users specify a total movement distance, and step lengths for both the random and up-gradient components of dispersal. This is done using Global Variables. Then, as the simulation runs, individuals take one random step, followed by one up-gradient step, and repeat until the total movement distance has been traversed.

Event Colors

This HexSim model was designed to serve as a small library of event colors. Users who like one or more colors can copy them into their own models.

Some of these construct HexSim input data, while others manipulate simulation output. The code is all written in the C programming language, and may be immediately compiled and run within a Unix / Linux environment like Cygwin. These programs are provided with no assurance that they are free from design or coding errors.

assign-patch-id

This program converts a categorical patch map into a non-categorical patch map. It does this by assigning a unique ID to every patch in the input patch map. In the context of this program, a distinct patch is a collection of pixels that (a) have the same value, and are (b) not adjacent to any other nonzero pixels of the same value. Distinct output patches can result from input patches that are isolated by zero-valued hexagons, or from adjacent hexagon clusters, when the clusters have different scores.

barriers-divide-patches

HexSim users will frequently employ patch maps for process sampling at scales larger than an atomic hexagon. For example, occupancy rates or source-sink values can be gathered on a patch-by-patch basis if simulated individuals consistently identify which patch they are in. However, when patches are bisected by barriers, these sampling schemes will produce meaningless results. This program reads a patch map (stored as a CSV file) and a HexSim Barrier Map (a HBF file), and generates a new map in which every patch bisected by a barrier is divided up into multiple separate patches. Doing this manually is completely impractical for all but the smallest landscapes.

barriers-merge-patches

When the barriers_divide_patches program is used to a break patches along barriers, small patch fragments will often be generated. This program can be used to remove these small fragments by aggregating adjacent patches that are not completely separated by a barrier. Users specify a patch map (stored as a CSV file), a HexSim Barrier Map (a HBF file), and a maximum patch area that cannot be exceeded during the aggregation process. The program generates a new patch map in which some or all of the small patch fragments are incorporated into other adjacent patches.

bin-hexmap

This program rescores the nonzero hexagons in a hexmap. It does this by grouping them into bins, with the number of bins being supplied by the user on the command line. The program attempts to keep the number of hexagons in each bin constant, but it can not do this perfectly. Note that the program can't be used with hexmaps containing negative scores, and it will abort if passed such a file. However, it is OK to use the program with hexmaps that have real-numbered scores.

This program is primarily useful for improving the contrast in dispersal flux hexmaps. In such cases, the original dispersal flux hexmap would typically be binned, and then converted into an 8-bit raster image in which each bin is assigned a unique color. If this conversion to raster is performed by HexSim, the maximum number of nonzero colors will be 100. Otherwise, the number of colors (including zeros) could be as large as 256. However, the program does not limit the number of bins.

build-gradient

This program reads a Hexmap (stored as a CSV file), and writes a new Hexmap (also a CSV file) that contains a smooth gradient of integer values intended to be used by Dispersal's Walk Up Gradient algorithm.

The input Hexmap must be composed strictly of hexagons scored 0, 1, or 2. The smoothed image will ignore the zero-valued input hexagons. The input hexagons scored 1 define the region to be smoothed. The input hexagons scored 2 are the starting sites. The starting sites will be assigned the largest values in the output map (each starting site will have the same final value). Each smoothed hexagon will be assigned a value equal to this maximum minus the steps it's removed from the nearest starting site. Starting sites that are not adjacent to hexagons scored 1 will have no affect on the output, but such values also do not create problems for the algorithm.

The program is passed an existing hexmap (in CSV format), plus the grid dimensions (number of rows, min-cols, and max-cols).

build-hexmap-blocks

This program is used to create a CSV file that can be imported into HexSim as a Hexmap. The new Hexmap will be comprised of a collection of rectangular blocks. A number of command-line options are described in the file header. An analogous tool exists within the HexSimCommandLine tool, which is bundled with HexSim, and documented in the User's Guide under Utilities / Command Line Options.

build-hexmap-hexagons

This program is used to create a CSV file that can be imported into HexSim as a Hexmap. The new Hexmap will be comprised of a collection of hexagon-shaped patches. A number of command-line options are described in the file header. An analogous tool exists within the HexSimCommandLine tool, which is bundled with HexSim, and documented in the User's Guide under Utilities / Command Line Options.

build-histogram

HexSim users will often find it useful to represent some simulation output as frequency plots (histograms). Graphing packages use bar plots to display frequency data, but when the number of bins becomes large, point or line plots can become a nice alternative to bar plots. This program generates a frequency table from a file of data values. Users must pass the program the bin size and data file (in that order). The data file must be a single column of numbers, with no header. The program's output will contain three separate columns giving the midpoint of each bin, the number of records in each bin, and the percent of the data found in each bin.

build-patch-barriers

This program reads a HexSim CSV patch map, and creates a HexSim HBF barrier map. The resulting barrier map will include a barrier located along the edge of every patch present in the patch map. The program must be passed the patch map name, followed by the number of rows, minimum columns, and maximum columns. Results are written to the standard output.

clip-hexmap

This program can be used to clip a Hexmap data file using a Hexmap mask. Both files must be in CSV format. A common use-case for this program will be to clip a patch map using a collection of nonzero hexagons extracted from a habitat map.

csv2sun

This program converts a hexmap in CSV format into a Sun rasterfile. Sun rasterfiles are typically associated with a ".sun" or ".ras" extension. The free application XnView (www.xnview.com) can read a Sun rasterfile and convert it into a more modern format. The Sun rasterfile format is used here for coding simplicity.

csv2png

This Python program converts a hexmap in CSV format into a PNG file.

fix-barriers

This program repairs HexSim barrier files. First, it will remove any negative signs from barrier categories. Next, the program will remove any barrier segments at the workspace edge. Then, it will remove any barriers that are only one segment in length. It will also remove barrier spurs that are just one edge long. Lastly, the program will remove barrier loops surrounding a single hexagon. Loops are only altered if there are 0, 1, or 2 connections to them. An illustration of the barrier repair process can be seen here.

get-dispersal-flux

This program builds a dispersal flux hexmap identical to the one constructed by the HexSim Tally of the same name. There is, however, a significant difference between the two routines. HexSim's Dispersal Flux Tally builds separate hexmaps for each population. This routine builds a single dispersal flux hexmap that combines the data from all populations.

get-hexmap-means

This program reads a collection of HexSim Hexmap (*.hxn) files. For each hexagon, the program computes the mean value taken over the collection, and then it writes a new Hexmap that records these means. The number of Hexmaps in the collection does not need to be specified -- this program may be passed an argument such as '*.hxn'. The output hexmaps will be in CSV format.

get-hexmap-maximums

This program reads a collection of HexSim Hexmap (*.hxn) files. For each hexagon, the program computes the maximum value taken over the collection, and then it writes a new Hexmap that records these means. The number of Hexmaps in the collection does not need to be specified -- this program may be passed an argument such as '*.hxn'. The output hexmaps will be in CSV format.

get-hexmap-occurrence

This program reads a collection of HexSim Hexmap (*.hxn) files. Each of these files is first converted into a binary (0 vs 1) map. If a hexagon's score exceeds zero, it is set to one. Otherwise, it is set to zero. Next, for each hexagon, the program computes the mean value taken over the collection, and then it writes a new Hexmap that records these means. The number of Hexmaps in the collection does not need to be specified -- this program may be passed an argument such as '*.hxn'. The output hexmaps will be in CSV format.

get-patch-areas

This program reads a patch map that has been exported as a CSV file. It tallies up the area of each patch, in hexagons.

get-ss-value

This program reads a patch map, a productivity report, and a count-based projection matrix report. The program writes a CSV output table that contains patch-by-patch data. It also writes 5 separate CSV files that can be imported into HexSim as Hexmaps. The productivity and projection matrix reports must have been stratified by the same location-based trait.

The program will skip the productivity report if the filename given for it on the command line is the dash character "-". Similarly, the program will skip the projection report if the filename given for it on the command line is the dash character "-". The collection of output files generated by the program will be smaller if an input file is not provided.

When this program is run, it must be passed an output file name in addition to the inputs mentioned above. If this name is set to "Test", and if both productivity and projection matrix reports are supplied, then the following files will be generated by the program:

• Test.csv

This file summarizes patch-by-patch data, and includes the following information: 

Births-Deaths ; Non-Migrants ; Emigrants ; Immigrants ; Emigrants-Immigrants.

• Test_patch-flux.csv

This file displays the number of individuals that moved between each pair of patches, with direction explicitly addressed. Fluxes of zero individuals are not printed.

• Test_births-deaths.csv

This output is a Hexmap in CSV format. This file contains observed source-sink values, measured as the number of births minus deaths. This data is tabulated per-patch.

• Test_emigrants-immigrants.csv

This output is a Hexmap in CSV format. This file contains observed source-sink values, measured as the number of emigrants minus immigrants. This data is tabulated per-patch.

• Test_emigrants.csv

This output is a Hexmap in CSV format. This file contains observed number of emigrants. This data is tabulated per-patch.

• Test_immigrants.csv

This output is a Hexmap in CSV format. This file contains observed number of immigrants. This data is tabulated per-patch.

• Test_non-migrants.csv

This output is a Hexmap in CSV format. This file contains observed number of non-migrants. Non-migrants are the individuals represented by the matrix diagonal. These individuals were in the same patch in two adjacent time steps. This data is tabulated per-patch.

hxn2csv

This program reads a HexSim Hexmap (HXN) file, and converts the content to a comma-separated variable format. This type of conversion can be performed efficiently within HexSim, but if the content of many Hexmaps need to be processed at the same time, then using an external routine like this can greatly reduce the effort involved. And this code could be modified to read multiple Hexmaps and merge their content into a single custom image. The resulting CSV file could then be imported into HexSim, or converted to a raster file using the Display Spatial Data tool.

LINK

Program LINK reads a HexSim log file, and uses that (and other) information to quantify and visualize landscape connectivity. The use of program LINK is discussed in detail here.

locate-barrier-loops

This program reads a barrier map, and it then writes a hexmap in CSV format. The output file will identify any hexagons that are completely surrounded by barriers. This is useful for finding locations where use of the barrier map will trap dispersers into a single hexagon. Once these locations have been identified, then the barrier map can be edited to correct these issues.

map-patch-counts

This program converts a CSV file with patch-by-patch count data into a CSV file that can be imported into HexSim as a Hexmap. The program must be passed CSV version of a patch map, and a 2-column file with patch counts data corresponding to the same collection of patches. The patch count data might represent productivity values or occupancy rates, etc. Both input files are assumed to have single-line headers.

randomize-patches

Patch maps composed of ordered arrays of patches can be difficult to visualize because adjacent patches end up being displayed using identical or nearly-identical colors. This program will randomize the patch IDs, so that the map will be easier to visualize. The patch map used must be stored in CSV format.

read-data-probe

This program will generate the sum or mean values, taken over all individuals, for Data Probe event output files. This is useful because Data Probe event output includes a separate row for each individual, and users will often want to summarize this information for each time step. Since the number of individuals will typically change each time step (and replicate), computing these sums and means in a spreadsheet can be awkward. To use the program, users need only pass the Data Probe output CSV file, and one of the strings: 'sum' or 'mean'.

read-replicates

This program will generate a few useful statistics from a concatenation of HexSim Census event output files. Users will often run multiple replicates of the same simulation, and then want to obtain means, or other metrics from the collection of replicates. This program simplifies that task. First, users must collect the Census event output files into one CSV file containing a single header line. The Unix 'cat' command is ideal for this (but it will produce a file with multiple header lines). The concatenated file is passed to the program along with the number of the column that the statistics should be generated for (the first column is numbered 1, not 0). The program will write out the minimum, mean, maximum, number of zeros, and P(0) values for each time step, corresponding to the selected data column. P(0) here refers to the probability of extinction.

renumber-patches

When patch maps are altered (e.g. clipped to a mask file), the total number of patches can change. This program will renumber such a patch map, to ensure that the patch IDs are sequential. The Hexmap used must be stored in CSV format.