Contents:


 Utilities 

HexSim Utilities


Important Disclaimer:

The programs below are being provided with no assurance that they are free from coding or conceptual errors. Use them at your own risk. Some of these utilities construct HexSim input data, and others manipulate simulation products. The source below should be replaced with more modern code, probably written in Python.

Clicking on the links below will open the files in a separate window.

The utilities below can be compiled and executed within Cygwin (www.cygwin.com), or other analogous environments. Cygwin runs on Windows, so it can be used side-by-side with HexSim.


Program: build_hexmap_blocks.c

This utility is used to create a CSV file that can be imported into HexSim as a Hexmap. The Hexmap generated 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. HexSimCommandLine is documented in the User's Guide under Utilities / Command Line Options.


Program: build_hexmap_hexagons.c

This utility is used to create a CSV file that can be imported into HexSim as a Hexmap. The Hexmap generated 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. HexSimCommandLine is documented in the User's Guide under Utilities / Command Line Options.


Program: clip_hexmap.c

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.


Program: renumber_patches.c

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 a CSV format.


Program: randomize_patches.c

Patch maps composed of many sequentially increasing or decreasing patches can be difficult to visualize. Adjacent patches end up being displayed using identical or nearly-identical colors, becoming hard to distinguish from each other. This utility will randomize the ID values used in a patch map, so that the map will be easier to visualize in HexSim. The Hexmap used must be stored in a CSV format.


Program: get_patch_areas.c

This utility reads a patch map, which must be a CSV version of a Hexmap, exported from HexSim. It tallies up the area in hexagons of each patch.


Program: map_productivity_report.c

This utility reads a patch map and a location-stratified productivity report, and constructs a Hexmap showing the productivity (birth - death) values. The patch map must be stored in a CSV format, and it must be the map used to generate the productivity report. Users also supply a minimum value, below which productivity will be set to zero.


Program: map_projection_counts.c

This utility reads a patch map and a location-stratified, count-based, projection matrix report. The patch map must be stored in a CSV format, and it must be the map used to generate the production matrix report. It computes each patch's source-sink quality as emigration minus immigration (E - I), and writes three Hexmaps. The Hexmaps produced include: patch occupancy rates, per-patch E - I, and per-hexagon E - I. The utility also produces a CSV file that contains per-patch values for area, occupancy, E - I, and E - I scaled by patch size.


Program: net_flux.c

This utility reads a pair of location-stratified, count-based, projection matrix reports (a rate-based report and a count-based report, in that order), and it writes a CSV file that quantifies the flux and net flux rates between each pair of patches. The program also computes the change in lambda associated with the loss of each possible connection between patches. For more information on the net flux metric, see Schumaker et. al. 2014.


Program: read_hexmap.c

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. For example, 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.


Program: read_replicates.c

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 representative values for census output obtained across the collection of replicates. This utility simplifies that task. First, users must collect the Census event output files into a single 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.


Program: read_data_probe.c

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


Program: build_histogram.c

HexSim users will often find it useful to represent 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 nicer than bar plots. This utility generates a frequency table from a file of data values. To use the utility, users must pass it the bin size and the 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. Generating a frequency plot for the data then becomes trivial.