Marxan User Manual: Input Files

3.1 Introduction
To run Marxan you need a set of input files. These files contain all the data you wish to work with and the details of the conservation problem you wish Marxan to solve. Four input files are required, without them Marxan will not run. The required and optional files are summarized below;

Table 1: Marxan input files and default names.

Input File	Default Name	Required
Input Parameter File	input.dat	Yes
Conservation Feature FileWARNING: Plugin disabled TAG!6	spec.dat	Yes
Planning Unit File	pu.dat	Yes
Planning Unit versus Conservation Feature File	puvspr2.dat	Yes
Boundary Length File	bound.dat	No
Block Definition File	blockdef.dat	No

The Input Parameter File is used to set values for all the main parameters that control the way Marxan works. It is also used to tell Marxan where to find the input files containing your data and other variables and where to place the output files.

The Conservation Feature File contains information about each of the conservation features being considered, such as their name, targets and representation requirements, and the penalty that should be applied if these representation requirements are not met.

The Planning Unit File contains information about the planning units themselves, such as ID number, cost, location and status.

The Planning Unit versus Conservation Feature File contains information on the distribution of conservation features in each of the planning units.


The Boundary Length File contains information about the length or ‘effective length’ of shared boundaries between planning units. This file is necessary if you wish to use the Boundary Length Modifier to improve the compactness of reserve solutions, and while not required, is recommended.

The Block Definition File is very similar to the Conservation Feature File and can be used to set a series of default variable values for groups of conservation features.

This section describes in detail each of these six potential input files; their function, format and the variables contained therein. More information about some potential ways to generate these files can be found in the tutorials contained in Appendix C.

Symbols for variables
Very important parameters – we have attempted to carefully describe their role here.

Highly technical parameters – explanation is left predominantly to Appendix B.

Easy mistakes that can have big consequences.

WARNING: Plugin disabled TAG!6Previously known as the 'Species File'.

3.1.1 Input file types
All Marxan input files use the .dat file extension. These files can be viewed in basic text editor programs such as Windows Notepad or TextPad?. To generate a .dat file simply add the suffix ‘.dat’ after the file name when saving the file.

3.1.2 Input File management
All the input files except for the Input Parameter File, ‘input.dat’, should be stored in the same folder. This folder is generally called, ‘input’, but can have any name that you indicate. This folder should be nested within the same folder as the Marxan program executable, ‘Marxan.exe’. The Input Parameter File, ‘input.dat’, must also be stored in the same place as the Marxan program executable.


An example of how we recommend a Marxan folder should be set up.

Throughout this manual we refer to the different input files by their default names. You can give any name to the input files, provided the names match those given in the Input Parameter File, and providing you use the correct procedure for starting Marxan. Using consistent file names, however, helps simplify the organization of Marxan input files. The Input Parameter File should have the name, ‘input.dat’, as this is the name Marxan will look for unless it is told otherwise with a command line parameter.

If you give a name other than 'input.dat' to this file (for example scenario1.dat), start Marxan with a command line parameter like this to get it to recognise the Input Parameter File: "Marxan.exe scenario1.dat"

If you use the default 'input.dat' as the name for the Input Parameter File, there is no need to use a command line parameter to get Marxan to recognise the file. You can start it like this: "Marxan.exe"

3.2 Required files
If one of the four required files (see Table 1 in Section 3.1) is missing, Marxan will halt with an error message.


An example of the error message Marxan will display if it cannot find the necessary input files. In this case, the Conservation Feature File (spec.dat) is missing.

3.2.1 The Input Parameter File
Marxan is an extremely flexible program. The flipside to this, however, is that you must set certain parameters to appropriately deal with the particular problem you wish to solve. This is primarily accomplished through the Input Parameter File. This file contains the principal parameters that control the way Marxan finds solutions (i.e. which algorithm(s) are used, what parameters contribute to the objective function). It is also used to tell Marxan where to find the required input files, whether you are using either of the two optional input files, and what output files you want and where they should be placed.

Do not worry if the number of variables in this file seems a bit daunting; many of these variables will almost never need to be modified. A few, however, may be changed for nearly every scenario run.

There are two possible ways to create and modify the Input Parameter File:

1. Using the program, ‘Inedit’, that comes bundled with Marxan (recommended)
2. Directly through a text file editor (i.e. Windows Notepad, etc. – for advanced users)

When creating this file for the first time it is generally best to use Inedit. This program provides a graphical user interface that takes you through each of the parameters that need to be set in the Input Parameter File.


The Inedit program used to create the Input Parameter File (input.dat) used in Marxan.

Once you have set values for each of the parameters in Inedit, simply press ‘Save’ and the corresponding ‘input.dat’ file will be generated automatically. When you use the command, ‘Save’, the ‘input.dat’ file will be saved in the same folder as the Inedit program. If you use, ‘Save As’, you can select where the ‘input.dat’ file will be saved.

There are no universally best values for the parameters contained within the Input Parameter File. Although similar values may work well for different applications, you will need to determine the most appropriate parameter values for each project. This is best done in an iterative fashion in which the results are investigated, the parameters changed, the program run again, and the new results compared with the old ones. There are few short-cuts to this process. In sub-sections below we provide guidance on how to determine appropriate values for each of the major parameters. As with creating the file, adjusting the parameters can be done either with Inedit or directly on the file with a text editor. Once it has been created for the first time using Inedit and users have a basic familiarisation of the file, it is often faster to make parameter changes directly in the ‘input.dat’ file. To do this you simply open the file using a text editor program such as Windows Notepad or equivalent, change the relevant parameter values and resave the file. To modify an existing Input Parameter File using Inedit, simply load the existing ‘input.dat’ file using the command, ‘Load’, change the parameters in the appropriate tabs and then resave the file.

The Input Parameter File has the following appearance:

An example of the Input Parameter File (input.dat).

Each variable is given as a single word in capital letters. The value for that variable follows on the same line with just a single space between the variable name and value. Any lines that are either not valid variable names or not in capital letters will be ignored by Marxan, so it is possible to include comments or notes between variables in this file. The variables can occur in any order but Marxan will halt with an error if any are defined twice. Most of the variables in the Input Parameter File have default values that will be used if the variable is not defined. The exceptions to this are the variables that tell Marxan where to find the necessary input files, where to save the output files, and the variable, ‘RUNMODE’, which tells Marxan which method it should use to find the best reserve system (i.e. simulated annealing, heuristic, or both).

The following table contains a very brief description of each variable as well as their default values.

Table 2: Marxan names and default values.

Variable Name	Default Value	Description
VERSION	0.1	Type of input file
BLM	0	Boundary Length Modifier
PROP	0	Proportion of planning units in initial reserve system
RANDSEED	-1	Random seed number
BESTSCORE	0	Best score hint
NUMREPS	1	The number of repeat runs you wish to do
NUMITNS	0	Number of iterations for annealing
STARTTEMP	1	Starting temperature for annealing
COOLFAC	0	Cooling factor for annealing
NUMTEMP	1	Number of temperature decreases for annealing
COSTTHRESH	0	Cost threshold
THRESHPEN1	0	Size of cost threshold penalty
THRESHPEN2	0	Shape of cost threshold penalty
INPUTDIR	User Defined	Name of the folder containing input data files
SPECNAME	spec.dat	Name of Conservation Feature File
PUNAME	pu.dat	Name of Planning Unit File
PUVSPRNAME	puvspr2.dat	Name of Planning Unit versus Conservation Feature File
BOUNDNAME	bound.dat	Name of Boundary Length File
BLOCKDEFNAME	blockdef.dat	Name of Block Definition File
SCENNAME	Temp	Scenario name for the saved output files
SAVERUN	0	Save each run? (0 = no)
SAVEBEST	0	Save the best run? (0 = no)
SAVESUM	0	Save summary information? (0 = no)
SAVESCEN	0	Save scenario information? (0 = no)
SAVETARGMET	0	Save targets met information? (0 = no)
SAVESUMSOLN	0	Save summed solution information? (0 = no)
SAVELOG	0	Save log files? (0 = no)
SAVESNAPSTEPS	0	Save snapshots each n steps (0 = no)
SAVESNAPCHANGES	0	Save snapshots after every n changes (0 = no)
SAVESNAPFREQUENCY	0	Frequency of snapshots if they are being used
OUTPUTDIR	User Defined	Name of the folder in which to save output files
RUNMODE	User Defined	The method Marxan uses to find solutions
MISSLEVEL	1	Amount or target below which it is counted as ‘missing’
ITIMPTYPE	1	Iterative improvement type
HEURTYPE	1	Heuristic type
CLUMPTYPE	0	Clumping penalty type
VERBOSITY	1	Amount of output displayed on the program screen

In the sub-sections below each of these variables are described. We have divided the variables into groups based on which tab of the Inedit program they are modified on. The name of the tab is the same as the sub-section heading.

3.2.1.1 Problem

The ‘Problem’ tab of Inedit.

3.2.1.1.1 Repeat Runs
Variable – ‘NUMREPS’
Required: Yes

Description: The number of repeat runs you want Marxan to perform; effectively, the number of solutions to the reserve problem you want Marxan to generate. Each new run is independent of the previous one, but they will all use the same parameter and variable values. The frequency with which planning units are selected in multiple runs, gives an indication of the importance of that planning unit for efficiently meeting your reserve targets (see Section 5.3.7).

Getting Started: When running a new scenario for the first time it is always advisable to begin with a very small number of runs (e.g. 5) so you can check the program is performing as desired (i.e. the solutions are meeting the required targets) without having to wait a long time. In order to get an idea of selection frequency, however, you will generally need to do many runs. One hundred runs is probably a minimal value to start with and is an intuitive value from which to calculate selection frequency. Adding more runs will sample more of the solution space, but will of course increase the processing time. The final number you decide on must be a balance between the time taken and the information gained. The MGPH provides some useful suggestions about determining the optimal number of runs.

3.2.1.1.2 Boundary Length Modifier
Variable – ‘BLM’
Required: No

Description: The variable, ‘BLM’ (Boundary Length Modifier), is used to determine how much emphasis should be placed on minimising the overall reserve system boundary length. Minimising this length will produce a more compact reserve system, which may be desirable for a variety of pragmatic reasons. Emphasising the importance of a compact network will mean that your targets are likely to be met in a smaller number of large reserves, generally resulting in on overall larger and more expensive reserve system. Thus, the BLM works counter to the other major goal of Marxan, to minimise the overall cost of the solution. BLM can be thought of as a relative sliding scale, ranging from cheaper fragmented solutions (low BLM) to a more compact expensive ones (high BLM). Because this will have a large influence on the final solutions, some work is needed to ensure an appropriate value (or range of values) is found.

Getting Started: The BLM should be either ‘0’ or a positive number. It is permissible for the BLM to include decimal points (e.g. 0.1). Setting the BLM to ‘0’ will remove boundary length from consideration altogether. There is no universally good value for the BLM, as it works in relation to the costs and geometry of the study region/planning units. With a small BLM Marxan will concentrate on minimizing overall reserve cost and will only aim for compactness when little extra cost will be incurred. Alternatively, a large BLM will place a high emphasis on minimizing the boundary length, even if it means a more costly solution. The user must explore the effects of different BLM values to determine an appropriate BLM for the project’s objectives.

Although the ‘correct’ level of spatial compactness is a rather subjective value, the box below provides some tips. As a very rough guide, a good starting place for the BLM is to scale it such that the largest boundary between planning units becomes a similar order of magnitude to the most expensive planning unit. For instance, if your highest planning unit cost is 100 and your longest boundary is 1000, you may want to start the BLM at 0.1. Note that it is usually best to explore a range of values that are separated using a fixed multiplier; e.g., 0.04, 0.2, 1, 5, 25 – where in this example, these values are each multiplied by 5. Typically, the values are increased exponentially or by orders of magnitude in order to sample a range of values and choose one that balances the order of magnitude of competing terms of the objective function.



More information about the impact of spatial compactness and determining an efficient level of it can be found in Stewart and Possingham (2005). See Appendix B-1.2 for a detailed description of its role in the objective function. Also, more information on the application of the BLM can be found in the MGPH.

3.2.1.1.3 Input file type
Variable – ‘VERSION’
Required: Yes

Description: This variable is only provided to allow backwards compatibility with SPEXAN (a precursor to Marxan) files. The difference between the two file types is that Marxan can read variable values based on their name whereas SPEXAN used their position in the file, requiring strict formatting.

Getting Started: Always select ‘New Freeform Style’ in Inedit, or ‘0.1’ in the ‘input.dat’ fileWARNING: Plugin disabled TAG!7

WARNING: Plugin disabled TAG!7As Marxan has a number of improvements over SPEXAN, there is no benefit in using SPEXAN, unless replicating work that used it in the past.

3.2.1.2 Run Options

The ‘Run Options’ tab of Inedit.

3.2.1.2.1 Run Options
Variable – ‘RUNMODE’
Required: Yes

Description: This is an essential variable that defines the method Marxan will use to locate good reserve solutions. As discussed in the introduction, the real strength of Marxan lies in its use of Simulated Annealing to find solutions to the reserve selection problem. Marxan, however, is also capable of using simpler, but more rapid, methods to locate potential solutions, such as heuristic rules and iterative improvement (see Appendix B-2.2 for more details on these methods). Because heuristic rules can be applied extremely quickly and produce reasonable results they are included for use on extremely large data sets. Modern computers are now so powerful that heuristics are less necessary as a time saving device, although they are still useful as research tools. Running Iterative Improvement on its own gives very poor solutions. As well as using any of these three methods on their own, Marxan can also use them in concert with each. If more than one are selected they will be applied in the following order: Simulated Annealing, Heuristic, Iterative Improvement. This means that there are seven different run options:

0	Apply Simulated Annealing followed by a Heuristic
1	Apply Simulated Annealing followed by Iterative Improvement
2	Apply Simulated Annealing followed by a Heuristic, followed by Iterative Improvement
3	Use only a Heuristic
4	Use only Iterative Improvement
5	Use a Heuristic followed by Iterative Improvement
6	Use only Simulated Annealing

Although each of the above running combinations can be set with a single number in the ‘input.dat’ file, all three fields on the ‘Run Options’ tab of Inedit are needed to define it. For instance, if you wanted to select Simulated Annealing followed by Iterative Improvement, you need to first tick the ‘Simulated Annealing’ box, ensure the ‘Heuristic’ box is blank, and then tick the ‘Iterative Improvement’ box.

Getting Started: Of these combinations, the most useful is Simulated Annealing followed only by Iterative Improvement (variable value, ‘1’). This is because Simulated Annealing searches the solution space effectively, and the Iterative Improvement then ensures that the solution represents the best option in the immediate area of the decision space (known as a ‘local minimum’). For most applications this will be the best and you will rarely need to change it.
''
3.2.1.2.2 Iterative Improvement''
Variable – ‘ITIMPTYPE’
Required: No

Description: If Iterative Improvement is being used to help find solutions, this variable defines what type of Iterative Improvement will be applied. There are four different options, details of which can be found in Appendix B-2.2:

0	Normal Iterative Improvement
1	Two Step Iterative Improvement
2	‘Swap’ Iterative Improvement
3	Normal Improvement followed by Two Step Iterative Improvement

Getting Started: To specify these in Inedit you use the drop down box labelled ‘Iterative Improvement’. The default for this variable is Two Step Iterative Improvement, and for most scenarios this will be fine.

3.2.1.2.3 Heuristic
Variable – ‘HEURTYPE’
Required: No

Description: If you are using an optional heuristic to find reserve solutions, this variable defines what type of heuristic algorithm will be applied. Details of the different Heuristics listed below are given in Appendix B-2.3.

0	Richness
1	Greedy
2	Max Rarity
3	Best Rarity
4	Average Rarity
5	Sum Rarity
6	Product Irreplaceability
7	Summation Irreplaceability

Getting Started: To specify these in Inedit you use the drop down box labelled ‘Heuristic’. However, we recommend that beginners use simulated annealing initially.


3.2.1.3 Annealing
3.2.1.3.1 Number of Iterations, Temperature Decreases, Initial Temperature and Cooling Factor
Variables – ‘NUMITNS’, ‘STARTTEMP’, ‘COOLFAC’, and ‘NUMTEMP’
Required: yes (when using Simulated Annealing)

Description: These four variables control the way the Simulated Annealing algorithm proceeds. They will come into play when Simulated Annealing is chosen in the ‘RUNMODE’ (see Section 3.2.1.2.1). As they are quite technical and a detailed understanding is not necessary to successfully use Marxan, their explanation is left to Appendix B-2.1.



Getting Started: In practice you will rarely need to adjust most of these. The variables, ‘STARTTEMP’ and ‘COOLFAC’, will be set appropriately for you simply by ticking the Inedit box labelled ‘Adaptive Annealing’, and for almost all applications it is quite reasonable to leave the number of temperature decreases (variable, ‘NUMTEMP’) set at 10 000. The number of iterations set (variable, ‘NUMITNS’) has a substantial bearing on how long each run takes. In general, the number of iterations determines how close Marxan gets to the optimal solution (or at least a very good solution). The number should start high (e.g. 1 000 000) and then be increased (e.g. 10 million or more is commonly applied on large scale datasets) until there is no substantial improvement in score as iterations continues to increase. At some point, the extra time required by a higher number of iterations will be better spent doing more runs than spending a long time on each run. Choose an acceptable trade-off between solution efficiency (score, or number of planning units) and execution time (number of iterations).

3.2.1.4 Input
3.2.1.4.1 Species File Name, Planning Unit File Name, Planning Unit versus Species, Block Definitions, Boundary Length and Input Folder
Variables – ‘INPUTDIR’, ‘SPECNAME’, ‘PUNAME’, ‘PUVSPRNAME’, ‘BOUNDNAME’, and ‘BLOCKDEFNAME’
Required: Yes


Description and Getting Started: These variables are reasonably self explanatory and their protocols for naming and storage have been discussed previously (see Section 3.1.2). Although on the Inedit screen you have a chance to specify the location of each file using the ‘Browse’ buttons, the files must still be in the correct folder in order for Marxan to run.

3.2.1.5 Output
3.2.1.5.1 Screen Output
Variable – ‘VERBOSITY’
Required: Yes
Description: This variable controls how much information Marxan displays on the screen while it is running. In Inedit it is set using the drop down box labelled, ‘Screen Output’. Users can specify how much information Marxan prints to the screen (the verbosity).



There are four different options for screen display:

0	Silent Running – Only the title of the program is displayed.
1	Results Only – Marxan will display which run it is up to, the basic results of each run and the total run time.
2	General Progress – In addition to the information about each run, Marxan will display information on the data that has been read in as well as details on any conservation features whose targets and requirements are such that they cannot be adequately reserved in the system.
3	Detailed Progress – Shows exactly where the program is up to and gives the value of the system each time the temperature changes.

Getting Started: The default for this variable is ‘General Progress’ and in most cases this will be the best choice. Printing results to the screen does not increase Marxan’s run time substantially unless 'Detailed Progress' is used. It is generally worthwhile to use at least ‘Results Only’ so that you have some idea of how many runs have been completed. ‘Detailed Progress’ is useful for seeing how the process of annealing works, and can also help identify problems Marxan runs (e.g. if the numbers do not change and it is “stalled”). For this reason, some users always use this setting, to visually check that the program appears to be running OK. Only apply ‘Silent Running’ if you are confident in Marxan’s execution and you are saving all necessary outputs.

3.2.1.5.2 Save Files and Save File Name
Variables – ‘SAVERUN’, ‘SAVEBEST’, ‘SAVESUM’, ‘SAVESCEN’, ‘SAVETARGETMET’, ‘SAVESUMSOLN’, ‘SAVELOG’, ‘SAVESNAPSTEPS’, ‘SAVESNAPCHANGES’, ‘SAVESNAPFREQUENCY’, and ‘SCENNAME’
Required: No

Description and Getting Started: With the exception of ‘SCENNAME’ and ‘SAVESNAPFREQUENCY’, these variables are all used to tell Marxan what results it should save as output. When using Inedit you can tell Marxan to save any of these files simply by ticking the corresponding box. In the ‘input.dat’ file, set the value to ‘1’ for each output you want Marxan to save. If you wish to display the results in a GIS, tab delimited output should be used in preference to comma delimited. This can be done in Inedit by ticking the box labelled ‘ArcView Format’, and it is done directly in the ‘input.dat’ by setting the values for these variables to ‘2’. The different outputs and their uses are all described in detail in the next section.

If either SAVESNAPSTEPS (‘Save each n steps’ in Inedit) or SAVESNAPCHANGES (‘Save each n changes’ in Inedit) are selected then a SAVESNAPFREQUENCY (‘Frequency’ in Inedit) value must also be specified. This is the predetermined number of either system iterations (SAVESNAPSTEPS) or system changes (SAVESNAPCHANGES) at which the solution progress of the optimisation procedure is saved.

Beware: saving snapshots can create enormous amounts of output files which swamp your output folder and drastically slow down the running of Marxan. They are for advanced diagnoses and should only be used by expert users. If you use them, make sure the snap frequency is large enough so that you are not left with tens of thousands of output files. The actual number you choose will depend on how many iterations you are using (see Section 3.2.1.3.1). For 1 million iterations, a snap frequency of 100,000 will give 10 output files.

The variable, ‘SCENNAME’ (or ‘Save File Name’ in Inedit), is the name you wish Marxan to append to all output files it saves (e.g. ‘scenario1_ssoln.dat’ would be the name given the summed solution output). The name should be something you can use to identify the scenario that generated the outputs.

3.2.1.5.3 Output Directory
Variable – ‘OUTPUTDIR’
Required: Yes

Description and Getting Started: The variable is used to tell Marxan the name of the folder (called directory or DIR in Marxan) it should save the output files in. The naming and location protocols for this folder are discussed in Section 5.1) and as with the input folder, it is critical this is correct or Marxan will not run.

3.2.1.5.4 Species missing proportion
Variable – ‘MISSLEVEL’
Required: No

Description: This is the proportion of the target a conservation feature must reach in order for it to be reported as met. Using Inedit, it is specified in the box labelled ‘Species missing if proportion of target lower than’. There are situations where Marxan can get extremely close to the target (e.g. 99% of the desired level) without actually meeting the target. You can specify a level for which you are pragmatically satisfied that the amount of representation is close enough to the target to report it as met.

Getting Started: This value should always be high, i.e. greater than or equal to 0.95, if you are setting it lower than this you should probably think about changing your targets. As a guide, it is often useful to run Marxan with the ‘MISSLEVEL’ set at ‘1’ and then re-run with it set at a slightly lower value and see if there is much of a difference in system cost. Setting this variable does not change the way the Marxan algorithm works, it merely changes the way target achievement is reported in screen and file output.


3.2.1.6 Cost Threshold
3.2.1.6.1 Threshold, Penalty Factor A and Penalty Factor B
Variables – ‘COSTTHRESH’, ‘THRESHPEN1’, and ‘THRESHPEN2’
Required: No.

Note: When using this variable, some users have reported, that the total cost of resulting reserve networks exceeds the cost threshold specified. It is apparent from the output tables if this problem manifests. Marxan is currently being redesigned for improved reliability with regard to this variable. If you obtain resulting reserve networks that exceed the threshold specified, disregard these results.

Description: These variables can be included if you want Marxan to find reserve solutions below a total cost. As discussed in the introduction, Marxan is designed to solve a ‘minimum set’ problem, its goal being to meet all our conservation targets for the least cost. Another class of conservation problem is known as the ‘maximum coverage’ problem where the goal is to achieve the best conservation outcomes for a given fixed budget. In many cases, this is more representative of how conservation actions operate. Although including a cost threshold does not make Marxan solve the strict ‘maximum coverage’ problem, it is comparable and can be used in cases where you have conservation targets you hope to meet and cannot exceed a predetermined budget. The actual way this cost threshold is applied within the algorithm is described in detail in Appendix B-1.4

Getting Started: Setting this variable to ‘0’ in the ‘input.dat’ file will disable it.
Be careful using this function as it can affect Marxan’s ability to find efficient solutions.

3.2.1.7 Misc
3.2.1.7.1 Starting Prop
Variable – ‘PROP’
Required: No

Description: When Marxan starts a run it must generate an initial reserve system. This variable defines the proportion of planning units to be included in the initial reserve system at the start of each run.

Getting Started: The variable ‘PROP’ must be a number between 0 and 1, and in Inedit it is set using the box labelled ‘Starting Prop’. If zero is chosen then no planning units will be included in the initial reserve, a value of 1 means all planning units will be included, and a value of 0.5 means 50% of planning units will be randomly included. In practice, the setting has no effect on the operation of simulated annealing, provided a sufficient number of iterations is used.

This will only be applied to those planning units whose status does not lock them in or out of solutions (see Section 3.2.3.3).

3.2.1.7.2 Random Seed
Variable – ‘RANDSEED’
Required: No

Description: Do not worry too much about this variable. It controls whether the same ‘random’ selection of planning units is included in the initial reserve system each run. Using a constant positive integer for this variable will make Marxan use the same random seed each time it is run.

Getting Started: Except for debugging purposes, it should be not checked in Inedit (i.e. set to ‘-1’ in the input file).

3.2.1.7.3 Clumping Rule
Variable – ‘CLUMPTYPE’
Required: No

Note: When using this variable, some users have reported resulting reserve configurations do not meet the clumping requirements specified. It is apparent from the output tables if this problem manifests, and we recommend you disregard any results that do not meet your clumping requirements (see Section 3.2.2.5 for more information).

Description: This variable is useful if some conservation features have a minimum clump size set (target2, see Section 3.2.2.5). It tells Marxan if occurrences smaller than the minimum clump size should contribute towards the overall target, and if so, how. Be aware that this will slow down Marxan by an order of magnitude.

Getting Started: The ‘CLUMPTYPE’ is set in Inedit using the options in the drop down box labelled ‘Clumping Rule’. There are three options for this variable:

0	Partial clumps do not count – Clumps smaller than the target score nothing.
1	Partial clumps count half – Clumps smaller than the target score half their amount.
3	Graduated penalty – Score is proportional to the size of the clump.

3.2.1.7.4 Best Score Speedup
Variable – ‘BESTSCORE’
Required: No

Description: This variable tells Marxan not to keep track of the best score until it reaches a specified minimum level. It is set in Inedit using the box labelled ‘Best Score Speedup’. It was intended to be a time saving measure, but is seldom required.

Getting Started: It should always be set to ‘-1’.

3.2.2 The Conservation Feature File
The Conservation Feature File contains information about each of the conservation features being considered, such as their name, target representation, and the penalty if the representation target is not met. It has the default name ‘spec.dat’. Because of this name it is sometimes referred to as the Species File, although conservation features will often be surrogates such as habitat type rather than actual species. Importantly, this file does not contain information on the distribution of conservation features across planning units. This information is held in the Planning Unit versus Conservation Feature File.

The Conservation Feature File can contain up to seven variables, although not all of these are required. When included, each of these variables is presented in a column with the name of that variable as the column header.

An example of the Conservation Feature File (spec.dat) used in Marxan.

Note: It is essential that the header names are exact. Note that all letters are lower case. For all variables except ‘id’ and ‘name’, the default value is 0. If data are missing from these variables Marxan will still be able to run, but the conservation features will take on the default values for missing attributes.


3.2.2.1 Conservation Feature ID
Variable – ‘id’
Required: Yes

Description: A unique numerical identifier for each conservation feature. Be careful not to duplicate id numbers as Marxan will ignore all but the last one.

Getting Started: It is useful to establish a logical system of numbering for features. Then you can have an idea about what they are at a glance. For example, all birds might have a 1 in the fourth placeholder; e.g. 1003. The fifth placeholder could represent regions if features are treated differently across regions; e.g. 21003 would mean bird 3 in region 2. Whatever system you decide upon, document it and be consistent in its usage.

3.2.2.2 Conservation Feature Type
Variable – ‘type’
Required: No

Description: Used to define groups of conservation features for which a number of umbrella attributes can be set for all features within the specified group (or “type”). Each group of features must have a unique numerical identifier. This variable is used in conjunction with the Block Definition File (see Section 3.3.2) which will contain the attributes to be assigned to a particular group of conservation features.

Getting Started: All variables you wish to take on Block Definition attributes should have their value entered as -1 in the Conservation Feature File (see Section 3.3.2 for example). Otherwise, the value in the Conservation Feature File will override the block definition. We recommend using the Conservation Feature Type in conjunction with the Block Definition File, whenever feasible, because it streamlines changes, avoids typographic mistakes, and allows for the easy setting of proportional (percentage) targets. It is the only mechanism for setting proportional targets in this and prior versions of Marxan.


3.2.2.3 Feature Representation Target
Variable – ‘target’
Required: Yes

Description: The target amount of each conservation feature to be included in the solutions. These values represent constraints on potential solutions to the reserve selection problem. That is, for a reserve solution to be feasible it must include at least this amount of each feature. The target value is expressed in the same units used to define the amount of each feature in each planning unit, contained in the Planning Unit versus Conservation Feature File (see Section 3.2.4). However, units from different conservation features can vary (e.g. hectares of habitat for one feature and number of occurrences for another, nests for a third and length of stream for a fourth).

Getting Started: Targets are user defined and can take any value from 0 to the total sum of that feature found in all planning units. You must be careful not to set a higher target than can possibly be achieved given the occurrence of a feature in the planning units as these targets will not be achievable. The selection of appropriate conservation feature targets may reflect goals for representation in protected area networks set out in either legislation or convention (e.g. 20%). Targets do not, however, have to be uniform values for all species (i.e. always 20%). They may instead reflect the perceived importance of conservation for that feature, for instance you may wish that rarer or more threatened conservation features have higher targets than very common ones. Whatever the chosen targets, it is important that they are well justified as they will have an enormous bearing on the character of potential reserve systems. The higher the target the fewer the number of different possible solutions Marxan will be able to find. This is discussed further in the MGPH.

If Block Definition File is being used for this feature, then the Feature Representation Target should be set to -1 here.

3.2.2.4 Conservation Feature Penalty Factor
Variable – ‘spf’
Required: Yes

Description: The letters ‘spf’ stands for Species Penalty Factor. This variable is more correctly referred to as the Conservation Feature Penalty Factor. The penalty factor is a multiplier that determines the size of the penalty that will be added to the objective function if the target for a conservation feature is not met in the current reserve scenario (see Appendix B-1.4 for details of how this penalty is calculated and applied). The higher the value, the greater the relative penalty, and the more emphasis Marxan will place on ensuring that feature’s target is met. The SPF thus serves as a way of distinguishing the relative importance of different conservation features. Features of high conservation value, for example highly threatened features or those of significant social or economic importance, should have higher SPF values than less important features. This signifies that you are less willing to compromise their representation in the reserve system. Choosing a suitable value for this variable is essential to achieving good solutions in Marxan. If it is too low, the representation of conservation features may fall short of the targets. If it is too high, Marxan’s ability to find good solutions will be impaired (i.e. it will sacrifice other system properties such as lower cost and greater compactness in an effort to fully meet the conservation feature targets).

Getting Started: It will often require some experimentation to determine appropriate SPFs. This should be done in an iterative fashion. A good place to start is to choose the lowest value that is of the same order of magnitude as the number of conservation features, e.g. if you have 30 features, start with test SPFs of, say, 10 for all features. Do a number of repeat of runs (perhaps 10) and see if your targets are being met in the solutions. If not all targets are being met try increasing the SPF by a factor of two and doing the repeat runs again. When you get to a point where all targets are being met, decrease the SPFs slightly and see if they are still being met. After test runs are sorted out, then differing relative values can be applied, based on considerations such as rarity, ecological significance, etc., as outlined above.

Even if all your targets are being met, always try lower values. By trying to achieve the lowest SPF that produces satisfactory solutions, Marxan has the greatest flexibility to find good solutions. In general, unless you have some a priori reason to weight the inclusion of features in your reserve system, you should start all features with the same SPF. If however, the targets for one or two features are consistently being missed even when all other features are adequately represented, it may be appropriate to raise the SPF for these features. Once again, see the MGPH for more detail on setting SPFs.

If Block Definition File is being used for this feature, then the Conservation Feature Penalty Factor should be set to -1 here.

3.2.2.5 Minimum Clump Size
Variable – ‘target2’
Required: No
Note: When using this variable, some users have reported resulting reserve configurations do not meet the clumping requirements specified. It is apparent from the output tables if this problem manifests, and we recommend you disregard any results that do not meet your clumping requirements.

Description: This variable specifies a minimum clump size for the representation of conservation features in the reserve system. If the amount of a conservation feature found in a clump is less that this value, then it does not count towards meeting the conservation target (the variable – ‘target’) for that feature. This is useful in cases where small or isolated patches or populations are of lower conservation value than larger, well connected patches or populations.

Getting Started: It is best, when getting started, to not use this variable, and see how the features clump without it. If then, some particular features require further clumping, this variable can be applied.

As with the conservation target, the value of ‘target2’ must be in the same units used to define the amount of each feature in each Planning Unit, contained in the Planning Unit versus Conservation Feature File (see Section 3.2.4). For instance, if you have included data on the area of different habitat types within planning units, then ‘target2’ specifies a minimum area (which may in fact be met in a single planning unit). In the case of presence absence data then the ‘target2’ value indicates the number of occurrences in contiguous planning units that must occur before the clump contributes to meeting targets (which also may be met in a single planning unit).

Care must be taken when setting the minimum clump size as targets for some features will have little choice but to be met in small, isolated occurrences.



3.2.2.6 Target for Feature Occurrences
Variable – ‘targetocc’
Required: No

Description: This variable specifies the minimum number of occurrences of a conservation feature required in a reserve system. This value can be used in situations where even though your conservation target may be met in one planning unit, you would like it to be represented in a greater number of planning units, possibly for risk spreading.

Getting Started: This is a rather specialised feature that is only sometimes used. Unlike ‘target’ and ‘target2’, the value of ‘targetocc’ is not related to the units used to describe the occurrence of conservation features, it is simply the number of planning units the feature must occur in for a viable reserve solution. This variable can be used in conjunction with or instead of ‘target’.

If Block Definition File is being used for this feature, then the Target for Feature Occurrences should be set to -1 here.

3.2.2.7 Conservation Feature Name
Variable – ‘name’
Required: No

Description: The alphabetical (no numbers!) name of each conservation feature (e.g. cloud forest). This variable is unusual in that it can include spaces. If you want to include spaces in the name, use words not numbers to allow Marxan to read a series of words as a single variable. You can also use numbers with no spaces as the name if you want.

3.2.2.8 Target for Separated Feature Occurrences
Variable – ‘sepnum’
Required: No

Note: When using this variable, some users have reported resulting reserve configurations do not meet the clumping requirements specified. It is apparent from the output tables if this problem manifests, and we recommend you disregard any results that do not meet your clumping requirements (see Section 3.2.2.5 for more information).

Description: The number of mutually separated occurrences of a feature required in the reserve system. This is similar to ‘targetocc’, except that if you wish to include multiple feature occurrences for the purpose of risk spreading then you may desire that the planning units holding these occurrences are not adjacent to each other. Where a minimum clump size has been set using ‘target2’, the variable ‘sepnum’ refers to the required number of mutually separated occurrences in valid clumps.

Getting Started: This is an advanced feature addressing replication. Marxan should first be run without it, and then later runs can be done with it applied.

This feature slows down Marxan by an order of magnitude.
If Block Definition File is being used for this feature, then the Target for Separated Feature Occurrences should be set to -1 here.

3.2.2.9 Minimum Separation Distance
Variable – ‘sepdistance’
Required: No

Note: When using this variable, some users have reported resulting reserve configurations do not meet the clumping requirements specified. It is apparent from the output tables if this problem manifests, and we recommend you disregard any results that do not meet your clumping requirements (see Section 3.2.2.5 for more information).

Description: Used in conjunction with ‘sepnum’ (above), this variable specifies the minimum distance at which planning units holding a conservation feature are considered to be separate. This may be useful in situations where multiple occurrences are desired because of the threat of large-scale events such as hurricanes or fires. For example, if hurricanes typically damage habitat over a known distance we may wish that two occurrences of the same feature are separated by a greater distance. Separation distance may also relate to the dispersal capacity of invasive species.

Getting Started: In order to use this variable, the geographic location of each planning unit must be specified in the Planning Unit File (see Section 3.2.3.4).

This feature can slow down Marxan considerably.
If Block Definition File is being used for this feature, then the Minimum Separation Distance should be set to -1 here.

3.2.3 The Planning Unit File
The Planning Unit File contains all the information related to planning units, except for the distribution of conservation features across planning units (which is held in the Planning Unit versus Conservation Feature File). The default name for this file is ‘pu.dat’. The Planning Unit File can contain up to five variables, although only one of these (‘id’) is required. When included, each of these variables is presented in a column with the name of that variable as the column header.


An example of the Planning Unit File (pu.dat) used in Marxan.

It is essential that header names are exact. All are lower case and contain no punctuation, spaces or numeric characters. The order headers are presented in does not matter.

3.2.3.1 Planning Unit ID
Variable – ‘id’
Required: Yes

Description: A unique numerical identifier for each planning unit. Values for the variable ‘id’ can be any number (i.e. there is no requirement to start at number 1) but they must not contain spaces, letters or punctuation. There is an upper limit of around 20 000 to 30 000 on the number of planning units that basic Marxan can handle, though the optimised version has no such restrictions (see Section 1.87.1).

This number should not be confused with the variable, ‘id’, in the Conservation Feature File (see Section 3.2.2).

3.2.3.2 Planning Unit Cost
Variable – ‘cost’
Required: No

Description: The cost of including each planning unit in the reserve system. The value entered for this variable will be the amount added to the objective function (see Section 1.5) when that planning unit is included in the reserve system. The cost of a planning unit can be based on any number of measures. It is a variable worth thinking carefully about as it can have a very large influence on the solutions Marxan generates.

Getting Started: Proper use of the cost function can be complicated. In its simplest form, the cost of all planning units can be set to 1. Marxan will then try and minimise the total number of planning units included in the reserve system but will judge the selection of planning units based solely on the features present and not on cost. If your planning units are not equivalent in size, an equivalent “default” measure is to use the area of the planning unit as its cost. Alternatively the MGPH describes the use of a transformed value of area). The rationale for this is based on the assumption that the larger the reserve size the more costly it will be to implement and manage, although this is not always the case, and costs are almost never linear.

A more sophisticated (and generally better) alternative is to use a measure of the actual fiscal cost of including that planning unit in a reserve system (for example see Naidoo et al. 2006). This may be the cost required to purchase that piece of land, or the opportunity cost of alternate land and sea uses that are incompatible with conservation. Cost can also be any relative social, economic or ecological measure. For instance, it may reflect the likelihood of success in different areas based on social willingness, enforceability, or the presence of uncontrollable threats.

Although only a single cost can be defined for each planning unit, this cost can be a composite of different measures, provided there is a defensible basis with which to combine them. Costs of the same currency can be combined (e.g. if both costs are monetary). Costs of a different currency can not sensible be combined without using arbitrary weightings (e.g. if one cost is monetary and one is social).

3.2.3.3 Planning Unit Status
Variable – ‘status’
Required: No

Description: This variable defines whether a planning unit (PU) is locked in or out of the initial and final reserve systems. It can take one of four values:

Table 3: Planning Unit values.

Status	Meaning
0	The PU is not guaranteed to be in the initial (or seed) reserve system, however, it still may be. Its chance of being included in the initial reserve system is determined by the ‘starting proportion’ specified in the Input Parameter File (see Section 3.2.1).
1	The PU will be included in the initial reserve system but may or may not be in the final solution.
2	The PU is fixed in the reserve system (“locked in”). It starts in the initial reserve system and cannot be removed.
3	The PU is fixed outside the reserve system (“locked out”). It is not included in the initial reserve system and cannot be added.

Getting Started: This variable is not necessary and if not included will take the default value of 0. In general, it is helpful to first run Marxan without any sites locked in or out, to provide an unbiased near-optimal solution. However, this variable can be useful to explore various scenarios where planning units have either status ‘2’ (must always be in the reserve system), or status ‘3’ (can never be included in the reserve system).

As an example, PUs located in existing protected areas could be assigned status ‘2’ because it is unlikely that areas already protected will be traded for other areas. One could conduct an analysis with all protected areas locked in and all other areas locked out to identify how close an existing protected areas system achieves the stated ecological objectives. However, care must be taken when locking areas into a reserve network as it can make a significant difference to the character of final reserve networks. In scenarios where reserve compactness is important (i.e. a boundary length modifier is used, see Section 3.2.1.1.2), Marxan is likely to use existing conservation areas as hubs, or “seeds,” around which to build the solution. This has the affect of substantially limiting the number of possible solutions. This may in fact be desirable as expanding existing protected areas is often politically and practically easier than creating new ones, but it can also lead to inefficient and possibly costly reserve solutions. It may also be appropriate to use status ‘2’ for known occurrences of rare or highly valuable features (e.g. deep sea coral reefs), which it would be irresponsible not to include in a reserve system but whose inclusion in the regular reserve selection process may unreasonably bias the results. In such situations, these features should be explicitly locked in so as not to compromise the transparency or defensibility of the planning exercise.

If a strong emphasis is being placed on compactness then as an alternative scenario, Marxan should be run with the boundary length of planning units containing these locked-in features set to zero. This will minimise their influence on the overall reserve system, and allow the most efficient system to be revealed. The same may also apply to important cultural sites that planners would like to include in a reserve system.

Status ‘3’ is useful in cases where planning units will never be available for inclusion in a reserve system.

3.2.3.4 X Planning Unit Location
Variable – ‘xloc’
Required: No

Description: The x-axis coordinate of the planning unit. This variable is only required if a minimum separation between feature occurrences has been specified in the ‘sepdistance’ column of the Conservation Feature File (see Section 3.2.2.9). The value entered reflects a point location for a planning unit, which may be its centre or some other sensible choice. This variable must be specified in conjunction with a value for the ‘yloc’ variable (below).

More information on generating this value can be found in the tutorials (Appendix C-2).

3.2.3.5 Y Planning Unit Location
Variable – ‘yloc’
Required: No

Description: The y-axis coordinate of the planning unit. This variable is only required if a minimum separation between feature occurrences has been specified in the ‘sepdistance’ column of the Conservation Feature File (see Section 3.2.2.9). The value entered reflects a point location for a planning unit, which may be its centre or some other sensible choice. This variable must be specified in conjunction with a value for the ‘xloc’ variable (above)

More information on generating this value can be found in the tutorials (Appendix C-2).

---