HexSim Accessories & Utilities

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: https://www.youtube.com/watch?v=thOifuHs6eY

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.

The programs below are being provided with no assurance that they are free from design or coding errors. Some of these utilities construct HexSim input data, while others manipulate simulation output. The utilities are all written in the C programming language, and may be compiled and run within a Unix / Linux environment like Cygwin. Compiling these utilities for Windows will probably involve making a few changes to the source code.

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 utility 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 utility is used to a break patches along barriers, small patch fragments will often be generated. This utility 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 utility generates a new patch map in which some or all of the small patch fragments are incorporated into other adjacent patches.

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 utility 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 utility 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 utility 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 utility 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 utility 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 utility'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.

clip-hexmap

This utility 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.

get-patch-areas

This utility 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 utility:

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 utility 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 utility 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 utility, users need only pass the Data Probe output CSV file, and one of the strings: 'sum' or 'mean'.

read-hexmap

This utility 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 utility 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.

read-replicates

This utility 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 utility 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 utility along with the number of the column that the statistics should be generated for (the first column is numbered 1, not 0). The utility 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 utility will renumber such a patch map, to ensure that the patch IDs are sequential. The Hexmap used must be stored in CSV format.