Creating patch account definitions using the PIN Builder

Patch targets are defined to the model in the PIN file like the route accounts. The required PIN file code can be generated easily and error free using the PIN Builder.

Adding the topology file

Patch accounts require explicit definition of topological relationships. The topological adjacency relationships required can be defined using either the raster or vector Proximal Topology (Proximal Topology (raster)) tool. Once this file has been created it can be referred to in the PIN Builder.

We have already created our topology file in the section called “Creating Block Topology” of this Quick Tour. We will use this topology file to define the block relationships required for the patch accounts (better go back if you skipped that step!).

  1. From the 'Optional PIN File Elements' window in the PIN Builder chose the 'Add Topology' button from the left hand side. This will open the 'Topology File' dialog (see Figure 173, “PIN Builder 'Add topology' dialog”).

  2. In the 'Toplogy File' dialog navigate to the previously defined proximal topology file (QuickTourIII/tracks/blocks_topology_200.csv).

  3. Adjust the threshold search distance in meters. The threshold search distance can be filtered from the original threshold search distance that was used to create the topology file (less than or equal to the original search distance). For example, if a distance of 500m was used to search for neighbour relationships in the topology file a threshold of 200m could be used in the model to search for disturbance patch members.

    We will use the original search distance of 200m.

  4. Click 'Finish' when a valid topology file has been selected.


The PIN Builder only allows definition of a single topology file. Once a topology file has been added in the PIN Builder the 'Add Topology' button will be inactive. Multiple topology files can be used (to allow different definitions of proximal distance for different patch accounts), but these need to be defined manually using PIN file commands.

Figure 173. PIN Builder 'Add topology' dialog

Define patch account name and size classes

Patch accounts are created by specifying the criteria account and the upper and lower limits of the size range. When you define a patch account the model will create a set of six sub-accounts (see the section called “Patch Sub-Account Types”). The names for these accounts will be created using a user specified prefix, and a user specified size class label, and a system specified sub-account name. All patch accounts using the same criteria must be given the same prefix. The size labels are arbitrary but should meaningfully describe the account.

  1. Click 'Add patch target' from the 'Optional PIN Elements' window of the PIN Builder to open the 'Patch Account' dialog.

  2. From the drop down list select the predefined patch criteria summary account (the list will include all accounts in the accounts.csv file). Choose product.Treated.CC from the list.

  3. Define a name prefix in the 'Patch account name prefix' box. By default the string 'patch.' is displayed. Edit the prefix by clicking in the box and typing the remaining text. For example, if you are defining disturbance patches you may wish to add 'patch.disturbance.' or if you are defining harvest patches you may add 'patch.harvest.'. Patchworks will create account names by appending the size class label and the sub account type to the prefix.

    Since we are using a harvest criteria we will define our patch account prefix as patch.harvest.

Figure 174. PIN Builder 'Patch account' dialog

  1. Create patch size categories by editing the 'Low' and 'High' size class ranges and providing a label for each range defined. The range label will be appended to the patch prefix for each category defined.

  2. Add new categories by using the '+' button at the bottom of the dialog and edit the range and label as required.

  3. To remove a category select the row and use the '-' button at the bottom of the window.

  4. We will define the following size classes:

    • Low: 0 High: 10 Label: 0_10

    • Low: 10 High: 50 Label: 10_50

    • Low: 50 High: 999999 Label: 50+

Add patch account code to the PIN file

The PIN Builder will translate the patch account size class categories into the properly formatted Beanshell code that can be copied and pasted into the PIN file. After the patch account definitions are added to the PIN file, these accounts will be created everytime the model loads.


The PIN Builder will automatically generate commands for other patch related features:

  • map layers displaying patch locations

  • area and frequency reports by patch size class

These other features are optional, and this section concentrates on the patch account code. You can refer to the section called “The PIN file” for more general PIN file information or the section called “Patch Report” for more information on patch reports.

  1. Click the 'Show Code' button in the Patch Account dialog to translate the patch account definitions into Beanshell code.

  2. A seperate window will appear with the required code. This code can be cut and pasted into an existing PIN file in the appropriate places.

  3. If you click 'Finish' in the 'Patch Account' dialog to return to the 'Optional PIN Elements' window you can also click 'Show Code' from the left-hand side. This will generate a complete PIN file with the elements you have defined thus far, including the patch accounts, topology, maps and reports.

We can look at an example of the code that would be generated by the PIN Builder and added to the PIN file in the Target Initialization section of the PIN file (reference PIN file section image).

int Patchworks_TargetInit() {                                1

control.inputTopology(new File("topology.csv"), 50d);        2

   if (usePatching) {                                        3 

       * Create the patch accounts
      control.addPatchTarget("patch.disturbance.young",      4
                             "patch.disturbance.0_50",       5
                             0.0f, 50.0f);                   6
                             50.0f, 150.0f);
                             150.0f, 250.0f);
                             250.0f, 2500.0f);
                             2500.0f, 50000000.0f);
   return 1;



This is the start of the Target Initialization section of the PIN file. Paste the patch account and topology references within this section.


Reference to the location of the topology file and the threshold distance that was specified in the PIN Builder.


This is a reference to the boolean flag created at the beginning of the PIN file that can easily turn on (true) or off (false) the patching accounts. The variable is typically defined at the beginning of the PIN file:

   boolean usePatching = true;

Enclosing patch specific code in the PIN file in this type of 'if' statement allows you turn on/off the patches by changing the flag in one place at the beginning of the file. This saves you from hunting through the PIN file to comment out or remove patch account references if you do not wish to use patching in some scenarios.


The first argument is the reference to the patch criteria summary account.


The second argument is the account name for the specific size class category. The PIN Builder has concatenated the patch account prefix and the patch size categories labels.


The third argument is the lower range limit and the fourth argument is the upper range limit for the category. The 'f' signifies that this value is a floating point.


Inclusion in the patch size class is determined by the sum of the patch criteria value being:

  • Greater than the lower range limit and

  • Less than or equal to the upper range limit

Note that this is the opposite for other ranges in Patchworks (e.g. numeric map ranges, ranges for category reports). Inclusion in these types of ranges is greater than or equal to the lower limit and less than the upper limit.

The reason for the difference is to exclude zero values from patch size category starting at 0 ha. if zero values were included, then all non-patch polygons would also be included in this category.