ArcMarxan Toolbox

Overview

The ArcMarxan Toolbox is a free / open source python toolbox for ArcMap 10.2 and above that makes creating input files for Marxan simple, quick and easy. This project was made possible with the assistance of the Newfoundland and Labrador office of the Department of Fisheries and Oceans Canada.

The current version is 1.0.1. The current version fixes an issue on Japanese versions of ArcMap but is functionally identical to version 1.0.

This project provides basic use instructions and is not a replacement of knowledge of Marxan or training. For more information on Marxan training and Marxan see the PacMARA website.

A PDF version of this page is available for download here: ArcMarxan Help

Installation

If you have administrative priviledges on your computer you can use option 1. If you don't have administrative priviledges on your computer use option 2.

Option 1

  1. Download the install file here: ArcMarxan Windows Installer
  2. Run install program. If you have Python installed multiple times choose the ArcMap Python 2.7 location.
  3. Open ArcMap
  4. Open ArcToolbox
  5. Right-click at top and choose Add Toolbox...
  6. From the look in drop down list select Toolboxes and then System Toolboxes
  7. Select ArcMarxan.pyt and click open
  8. Open ArcToolbox again
  9. Right-click at top and choose Save Settings and To Default

Option 2

  1. Download the ArcMarxan Toolbox file here: ArcMarxan.pyt
  2. Copy this file to your system in a location where it won't be altered. Paths you might consider would be, C:\Python27\ArcGIS10.2\Lib\site-packages\arcmarxan\esri\toolboxes or C:\Users\<your user account>\AppData\Roaming\ESRI\Desktop10.2\ArcToolbox\My Toolboxes
  3. Open ArcMap
  4. Open ArcToolbox
  5. Right-click at top and choose Add Toolbox...
  6. From the look in drop down list select the location of your file. If you used the folders suggested above it will be in Toolboxes and then System Toolboxes or My Toolboxes
  7. Select ArcMarxan.pyt and click open
  8. Open ArcToolbox again
  9. Right-click at top and choose Save Settings and To Default

Use Overview

The ArcMarxan Toolbox has the following work-flow design:

  1. With other tools create your planning unit file and make sure to add status and cost fields.
  2. Calculate the planning unit contributions for each feature using standard ArcMap methods and join your results into a single large table.
  3. Create a folder for each scenario and within it use the Create Input File and Folders tool to make a input.dat file along with an input, output and pu folder.
  4. Use the Export Boundary File tool to create a bound.dat file in the scenario's input folder.
  5. Use the Export Feature Files tool to create the spec.dat, puvsp.dat and puvsp_sporder.dat files from your single joined table with all features.
  6. After creation edit the content of the spec.dat file to set targets using one of the three options of prop, target and targetocc.
  7. Use the Export Planning Units tool to create the pu.dat file from your planning unit layer using the cost and status fields. Make sure that all records have valid values.
  8. Run and calibrate Marxan by hand or with Zonae Cogito.
  9. Use the Report Features tool to assess the conservation feature compositions of groups of planning units as needed.

Tool Details

The ArcMarxan Toolbox consists of five tools. 

Create Input File and Folders

This tool creates a folder structure with an input, output and pu folder and an input.dat file. The input.dat file is the basic control file for a Marxan project and the input and output folders are default names for the Marxan inputs and outputs respectively.

The input value for this tool is the name of the folder you want to use for your Marxan project.

Export Boundary File

The boundary file in Marxan provides information on what planning units are next to other planning units and the weight of the boundary relationship between them.

Input values for this tool are:

  • Planning unit layer - For a Marxan analysis you must create a planning unit layer which will divide the study area into planning units. Planning units are usually of regularly shaped areas and they must be numbered with a unique id. This is the correct layer to choose for this input value.
  • Planning unit id field - The name of the field with the planning unit id is selected here.
  • Boundary method - The boundary length between planning units can be set in multiple ways. If you have no specific concerns about wanting to impact how areas are selected except by their adjacency to other areas then the first option, using a single value for all planning units, is appropriate. If you want to use the actual length of the boundaries then use the measured option. If you want to use some weighted value of the measured length times a field value choose weighted. If you want to use a field value only choose the field option.
  • Boundary treatment - Some Marxan practitioners suggests there is merit is excluding or assigning half values to planning unit boundaries at the perimeter of the planning area. This option enables this choice. Best empirical evidence suggests that using a consistent value on all boundaries gives the least biased result if all planning units are the same size.
  • Single value - If you are using the Single Value method which assigns a single value to al boundaries enter that value into this field.
  • Calculation field name - If you are using the Weighted or Field methods, select your calculating field here.
  • Calculation method - If you are using a weighted or field method, it is possible that the values from one PU's field will not match the values of the adjacent PU. You can choose three options of how to process these differences which are to use the mean, maximum or minimum.
  • Marxan input folder - This folder is where the bound.dat file will be written. This file does not need to be edited after creation unless a new planning unit layer is created or the planning unit layer is altered.

Export Feature Files

There are three files in Marxan that tell Marxan about your features of interest and their targets. These files are the spec.dat file, pusvsp.dat and puvsp_sporder.dat. This tool creates all three in a single step, with the understanding that you will need to manually edit the spec.dat file in a text editor or spreadsheet program to set target and species penalty factor values. For users unfamiliar with the puvsp_sporder.dat file, it has the same contents as the puvsp.dat file, but in species order and this saves processing time when running Marxan.

Input values for this tool are:

  • Planning unit layer - The planning unit layer or table with all the calculated values for each feature is selected here. This might be a shapefile or a table or a geodatabase feature class. What is important is that all the calculated values are available in a single file and that it has a planning unit id field.
  • Planning unit id field - The name of the field with the planning unit id is selected here.
  • Feature fields - Select fields for inclusion as features in your project by marking the check box beside them
  • Marxan input folder - This folder is where the spec.dat, puvsp.dat and pusvsp_sporder.dat files will be written. The puvsp.data and pusvsp_sporder.dat describe how much of each feature exists in each planning unit. Although only the puvsp.dat file is required, creating both files speeds the initialization process for Marxan. These two files do not need to be edited after creation unless features are added, removed or recalculated. The spec.dat file will need to be altered after creation to set targets using the prop, target or targetocc fields. The prop field is a proportional target field with values ranging from 0 to 1. The target field is used to set targets in the units of the measured feature. The targetocc field allows users to set targets based on the number of occurrences of a feature. Please note that only one file can be used for each feature. Please refer to the Marxan user documentation for more details.

Export Planning Units File

The planning units file describes what planning units exist, their status and the cost associated with selecting them.

Input values for this tool are:

  • Planning unit layer - The planning unit layer with the id, cost and status values as fields.
  • Planning unit id field - The name of the field with the planning unit id is selected here.
  • Planning unit cost field - The name of the field with planning unit cost values for each planning unit is selected here.
  • Planning unit status field - The name of the field with the planning unit status values for each planning unit is selected here.
  • Marxan input folder - This folder is where the pu.dat file will be written.

Report Features for Selected Planning Units

This tool lets you look at the feature contents of arbitrary selections of planning units. To use this tool select the planning units of interest using ArcMap and then open this tool and run it.

Input values for this tool are:

  • Planning unit layer - The planning unit layer with the planning unit id field 
  • Planning unit id field - The name of the field with the planning unit id is selected here.
  • Marxan input folder - The Marxan input folder is selected here. This tool reads the puvsp.dat and spec.dat files to generate the report.
  • Report output file name - Assign a name and location for your report name here.

This tool will create a comma separated file you can open in an spreadsheet program to look at the results. The file will contain the following values:

  1. Marxan Feature Id - Each feature is assigned a numerical id in the spec.dat file.
  2. Marxan Feature Name - Each feature is assigned a name in the spec.dat file. When using the ArcMarxan Toolbox this name is the field name in the source planning unit layer.
  3. Feature Count - The number of times this feature was recorded in the selected planning units.
  4. Selected Planning Unit Count - The number of selected planning units.
  5. Occurrence Percent - The percent occurrence of the feature in the selected planning units.
  6. Feature Value Total (sum) - The total amount of the feature in the selected planning units in the units provided to Marxan.