Customizing Patchworks

1. What is the syntax for the PIN file?
2. Can I use Python (or Ruby or Groovy or JavaScript) instead of BeanShell?
3. Do you have any examples of scripts that I can use to see how things work?
4. How do I create a PIN file for my project?
5. Can Patchwork be run in 'batch' mode to control the simulation?
6. What is the recommended way to use batch scripts to run scenarios?
7. What is the best way to create complicated reports?
8. How do I make my reports show up in Patchworks the next time it starts?
9. How can I modify the styling of the reports?
10. How can I add my logo so that it shows up on the reports?
11. How do I make my custom map layers show up in Patchworks the next time it starts?
12. Can I change the appearance of the Patchworks user interface?
13. How can I export data from the block table to an external application?
14. What's the significance of the 'feature.' and 'product.'terminology on the targets tab?
15. How should I name my attributes and accounts?
16. How do I set up groups and accounts to track conifer harvest in certain locations?

1.

What is the syntax for the PIN file?

The PIN file (Patchworks INput file) contains instructions that direct the start up and initialization of the Patchworks model. These instructions are in a language named BeanShell that is similar to Java. There are numerous books and online materials that describe the Java language syntax.

Documentation about differences between the BeanShell language and Java can be found at the BeanShell web site.

2.

Can I use Python (or Ruby or Groovy or JavaScript) instead of BeanShell?

Yes. There are a number of different shell languages available and they are easy to install in Patchworks. All you need to do is

  1. Copy the interpreter JAR file in to the Patchworks library folder.

  2. Invoke the interpreter from the Patchworks console.

3.

Do you have any examples of scripts that I can use to see how things work?

Yes. The Patchworks Script Library contains a number of sample scripts. These are documented in the Patchworks Script Library section of the User Guide.

4.

How do I create a PIN file for my project?

The easiest way to get started is to use the Pin Builder application. This program will quickly lead you through the steps to build a simple or complex PIN file.

5.

Can Patchwork be run in 'batch' mode to control the simulation?

Batch scripts can be written in the BeanShell language and executed in Patchworks. The easiest way to execute BeanShell batch scripts is to type your code into a file, and then invoke the script from the Patchworks console. For example, the following code starts the scheduler, allows it to run for 1,000,000 iterations:

Example 17. Batch execution

control.resume();                         1
    
control.waitForIterations(1000000);       2   
    
control.suspend();                        3  
reportWriter.saveStage("Trial1");         4  
	      

1

The control.resume() method causes the scheduler to unblock and continue execution.

2

The control.waitForIterations() method causes the current thread to wait for the specified number of iterations to be executed. After this has occurred the current thread will continue executing commands from the PIN file.

3

The control.suspend() method pauses the scheduler.

4

The reportWriter.saveStage() method will invoke the report writer to save all defined reports to the directory named Trial1.


6.

What is the recommended way to use batch scripts to run scenarios?

The previous example showed a simple mechanism to automate scenarios. Patchworks has a more comprehensive mechanism for recording scenario parameters, automating execution, controlling stopping criteria, and recording results and meta-data. ScenarioSet's are self-documenting and provide a convenient way to set up complex, repeatable analysis. See the User Guide for more details.

7.

What is the best way to create complicated reports?

The Add Report wizard simplifies the job of defining Complicated reports. To create a report you need to define the source of the data (usually the Block Table), and the format that you would like to see the data presented in. Choose a report template from the Add Report wizard list (see the User Guide for options), and then follow through the wizard to often fill in the required parameters.

The finished report will show up automatically in the Report tab.

8.

How do I make my reports show up in Patchworks the next time it starts?

When you use the Add Report wizard it will add reports to the Reports tab. Once you quit out of Patchworks these reports will disappear. To have them available the next time you start Patchworks you need to copy the report constructors to the PIN file. Do this by right-clicking on the report name in the Report tab, and choosing the Show Contstructor option. Copy the resulting code to the appropriate location in the PIN file.

9.

How can I modify the styling of the reports?

You can modify the appearance of reports by using a custom CSS file. Create a CSS file containing your style changes. Then use a command like the following to let the ReportWriter know to include the CSS file:

reportWriter.addSupportFile("my_custom.css", true);

For example, the following CSS file will set the default font to be Calibri (or the default serif is Calibri is not available):

body {
  font-family:  Calibri, serif;
}
[Note]Note

When you save a scenario the current contents of the custom CSS file will be copied in to the html folder of the scenario folder. Any subsequent changes to the original custom CSS file will not be reflected in the saved scenario.

10.

How can I add my logo so that it shows up on the reports?

You can use the custom CSS file to add your logo to the reports. First you will need to tell the Report Writer to include your logo file so that it will get saved out in to the scenario folder. Add code similar to the following in to the Patchworks_Init section of your PIN file:

reportWriter.addSupportFile("C:/logos/mylogo.png", false);

In the above we add a support file to the Report Writer, and it will be placed it into the 'html' folder of the scenario. This support file can be accessed from the internal web server and will be saved out to the scenario, but it will not show up in the index or the report tree.

Next, prepare a custom CSS file as described in the previous question. Customize a style class that goes with on of the sections in the report. In this example we will add the logo to the main content section of the report, up against the right margin. Note that you will need to set the height attribute so that there is at least enough space to fit in the logo, and adjust the position so that the logo does not go off the edge of the screen:

.mainContent {
   background: url("logo.png") no-repeat right;
   background-position: calc(100% - 30px) 40px;
   min-height: 64px; /* Enough space to that the logo fits */
   background-position: fixed; /* logo does not scroll with the page */
}

In this example we copied the logo file in to the same ReportWriter folder as the previous CSS file, so we do not need to specify any additional file path information for the CSS file to find the logo.

11.

How do I make my custom map layers show up in Patchworks the next time it starts?

Right-click on a custom map layer and choose the Show Contstructor option. Copy the resulting code to the appropriate location in the PIN file.

12.

Can I change the appearance of the Patchworks user interface?

Yes, there are several ways to do this. You can add menu items that invoke your own custom commands by calling the gui.addMenuItem method from the Patchworks console or from within a script. See the Patchworks Script Library documentation for more information.

A more adventurous approach would be to install a completely different user interface. The code for the default interface is loaded from a file named startup.bsh that is located in the script library. The PIN file usually calls the classicGUI() method in this file to set up the GUI, but you can replace this call with one of your own. It is also possible to run Patchworks without a GUI, for example when run within a larger simulation ensemble.

13.

How can I export data from the block table to an external application?

The 'point and click' procedure to extract this information would be

  1. Open the table viewer for the Block table and adjust the properties to show only the necessary columns of interest.

  2. Use the Query Tool to select the appropriate records.

  3. Slide the slider bar to the first period of interest and export as a csv file.

  4. Repeat for the necessary time periods and then open the files you generated in Access to make a 'pivot table report'.

If this is a procedure you anticipate using regularly, you might want to create an automated script to do the same work. Paste the snip of code similar to the following into a file and Open the 'Patchworks Console' to run the script using a command like: source("myfile.bsh");.

/*
 * Select stand eligible for harvest in each of the 
 * first 10 planning periods.  The data for each
 * period is written to a unique file.
 */
for (int i=1; i<=10; i++) {
  blockData.setPeriod(i);
  blockData.select(null, "CURRENTTREAMENT ne ''");
  blockData.exportCSV("harvest_"+i+".csv");
} 
	    

If you would like to capture this information with each scenario that you save, consider using a TableQuery report instead.

14.

What's the significance of the 'feature.' and 'product.'terminology on the targets tab?

'features' and 'products' are the standard nomenclature used in Patchworks. We use the feature group to refer to extant features (growing stock, etc.) and the product group to refer to extractions (removals or costs of management actions).

The nomenclature for targets is entirely up to you. The Patchworks program will create an 'explorer'-style hierarchical classification based on your account names, so use your naming scheme to organize your targets into groups (each '.' will be a new branch of the hierarchy).

You can change these names to whatever you want, there is nothing 'hardcoded' about it. Just modify the appropriate lines to the 'accounts.csv' file or PIN file.

15.

How should I name my attributes and accounts?

Patchworks supports a hierarchical nomenclature for account and attribute names, but you can use whatever names you want. Attribute and account names can have a number of parts, each part is separated by a '.' character. Our common convention is that the first part of the name indicates if the value represents an extant feature (e.g. growing stock ='feature') or an extraction (e.g. harvested volume ='product').

The remainder of the hierarchy is simply pigeon-holing. For example, we would name douglas fir growing stock something like: 'feature.Yield.DF', and douglas fir harvest volumes 'product.Yield.DF'. Product values might be 'product.Value' (possibly broken down into finer categories). Harvest costs might be 'product.Cost.harvest'. Silviculture costs might be product.Cost.silv, or might be broken down into finer categories reflecting treatment intensities or planting stock types. Cavity bearing properties might be feature.Habitat.cavity, since this is tracking an extant feature.

All of these values represent attributes that are tracked for each polygon. Several tools in Patchworks make use of the hierarchical name structure to sort and display attributes using an explorer style of tree-view control. Our report writer is also geared to summing up categories that fall under part of a hierarchy (e.g. sum up all cost categories). Many of the reportWriter reports can have a column or target prefix specified which will eliminate the redundant prefix and use the unique ends as row or column headings.

16.

How do I set up groups and accounts to track conifer harvest in certain locations?

Add a column to the block dataset that identifies polygons by locations of interest, and then create a group according to the unique values in this field. For example, if the column that contains the group names is COMPART, then add a line to the Target Initialization section of the PIN file that looks like:

control.calculateGroups("COMPART"); 
	    

The next step is to add accounts for the required groups. For example:

control.addAccount("Comp1", "product.Yield.managed.conifer", "Comp1.Yield.managed.conifer");
control.addAccount("Comp2", "product.Yield.managed.conifer", "Comp2.Yield.managed.conifer");
control.addAccount("Comp3", "product.Yield.managed.conifer", "Comp3.Yield.managed.conifer");
	    

These lines state that conifer yield from the Comp1, Comp2 and Comp3 groups should be added into new accounts named Comp1.Yield.managed.conifer etc. Now that you have groups for each compartment other attributes can be summarized, such as area and treatments.