Getting Started with the ForestModel XML

To start, we will examine a few of the simple standard elements and attributes that are required in any ForestModel XML. This section will look at an example to illustrate possible syntax and uses, however reviewing the XML reference pages (see ForestModel References) will give a far more detailed and complete picture of each individual element.

In this first example Example 9, “ Define input inventory fields and feature attributes ”, various mandatory elements are included that are necessary at the beginning of each ForestModel document to identify the type of document, and how it will relate to the inventory it will be applied to. Next, fields and columns need to be defined to link the XML file with the original forest inventory, so that column and field names correspond and can be referred to throughout the file. Select queries will be used to assign attributes that describe the growth and yield of the specific strata (feature attributes) to specific inventory records. This is as far as this example will take us for now. We will add more as we progress through this chapter.

Example 9.  Define input inventory fields and feature attributes

1  <?xml version="1.0"?> 
2  <!DOCTYPE ForestModel SYSTEM "ForestModel.dtd">
3  <ForestModel description="C5 Dataset" horizon="200" year="2002" match="multi">

      <input block="GRIDCODE" area="AREAHA" age="F_AGE" exclude="GRIDCODE=0" />       

4    <!--Identify columns of interest from the input inventory file. -->

5    <define field="theme1" column="THEME1" />
      <define field="theme2" column="THEME2" />
      <define field="theme3" column="THEME3" />
      <define field="theme4" column="THEME4" />
      <define field="theme5" column="THEME5" />

      <!-- Block attributes
         Include attributes that describe the development characterics
         of this block.  The following describes the Y4 yield strata on
         available forest land. -->

6    <select statement="theme2 eq 'Y4' and theme3 eq 'N'">
7      <features>
8        <attribute label="feature.Yield.managed.Decid">
9          <curve>
10            <point x="5.0" y="0.0" />
              <point x="20.0" y="0.17" />
              <point x="30.0" y="0.85" />
              <point x="35.0" y="1.47" />
              <point x="45.0" y="3.29" />
              <point x="70.0" y="9.37" />
              <point x="80.0" y="11.38" />
              <point x="90.0" y="12.73" />
              <point x="95.0" y="13.13" />
              <point x="105.0" y="13.39" />
              <point x="115.0" y="13.03" />
              <point x="125.0" y="12.19" />
              <point x="180.0" y="5.18" />
              <point x="195.0" y="3.71" />
              <point x="215.0" y="2.27" />
              <point x="235.0" y="1.32" />
              <point x="260.0" y="0.64" />
              <point x="290.0" y="0.25" />
              <point x="325.0" y="0.18" />
            </curve>
          </attribute>
   
          <attribute label="feature.Yield.managed.Conif">
            <curve>
              <point x="5.0" y="8.85" />
              <point x="40.0" y="111.33" />
              <point x="65.0" y="169.93" />
              <point x="90.0" y="207.76" />
              <point x="105.0" y="221.41" />
              <point x="120.0" y="229.31" />
              <point x="145.0" y="232.14" />
              <point x="175.0" y="223.18" />
              <point x="215.0" y="198.99" />
              <point x="300.0" y="134.96" />
            </curve>
          </attribute>
        </features>
      </select>
    </ForestModel> 
          


1

<?xml version="1.0"?>

This is a standard element identifying the XML standard being used. This tag must be included verbatim at the beginning of every model. This is a special element and does not contain a closing tag.

2

<!DOCTYPE ForestModel SYSTEM "ForestModel.dtd">

This <DOCTYPE> element must also appear at the beginning of every model. This element tells the parser what DTD (Document Type Definition) is dictating syntax. Without this statement the XML file cannot be parsed correctly. It is a good habit to include these first two elements right away (cut and paste from previous XML documents to save time!).

3

<ForestModel>

The ForestModel element is the main enclosing element in this DTD, and contains all other elements. This element contains 3 attributes (description, horizon and year) which provide meta-data to describe how this particular model applies to the target dataset.

The ForestModel element can only contain elements that are allowed in this context (see ForestModel). The ForestModel element must be opened with all required attributes and closed at the very end of the document with the </ForestModel> tag. The description attribute provides a descriptive comment and is presently unused. The horizon attribute provides a cue to the Matrix Builder about how many years the simulation is expected to cover. This will help the Builder in determining how many linked tracks it needs to create. The year attribute provides a starting point for the analysis.

4

<!-- comments -->

Author comments can be placed anywhere in the document so long as they are wrapped in <!-- and -->. Anything wrapped in these tags is ignored completely by the parser. Sections of code can be commented out to change the ForestModel temporarily or detailed comments can be included to document the basis for the model.

5

<define>

The <define> element creates a link between the database attribute values of the original forest inventory and the variable names used in the ForestModel. Once the attribute values have been defined to the ForestModel they can be used in various select statements throughout the document. The <define> element has 3 attributes, however only one is required (field).

The <define> element is an EMPTY tag (meaning is does not wrap any other elements, no children are allowed). The field attribute is required, and provides the name that will reference this column in the remainder of the ForestModel. The column and constant attributes are optional and mutually exclusive. If neither attribute is specifed, the defined field will be a new helper variable that can be assigned arbitrary values in <assign> statements. The "column" attribute is an expression that specifies columns of interest from the input inventory. The field will automatically be filled in with these record values as the Matrix Builder operates. The "constant" tag specifies a constant value that can be used later on where ever expressions are used. Constant values can be strings or numbers.

A helper variable is a defined variable that does not exist in the original inventory, essentially creating another blank field in the records that can be used later in the file when necessary. One of the most common examples of this is seen later when we explore various management treatments. If a helper variable 'treatment' is defined now, different treatment types can be assigned later to distinguish the products that would result from these unique treatments. To define a helper variable simple specify the field name (<define field="treatment"/>).

6

<select>

<select> is one of the most important ForestModel elements, as it has the ability to define eligibility of an input stratum. A select statement can be thought of as the questions the ForestModel asks the input inventory.

The only attribute of the <select> element is a statement. The default statement is blank (" ") if none is specified. Select statements must follow the general SQL-like syntax (see Patchworks Query Language).

Select statements can be used for a series of features, products, and tracks or to express the retention and sucession of various strata. A statement attribute would take the form of an SQL-like expression that each inventory stratum could be evaluated against. In our simple example above, only one select statement was used to identify features:

    <select statement="theme2 eq 'Y4' and theme3 eq 'N'">
	      

This is a question asked to each of the inventory records. Does the value in the theme2 field equal 'Y4' and the value in the theme3 field equal 'N'? If the answer is yes, the <features> enclosed in the <select> element apply to that particular stratum. If the answer is no, the inventory record is tested against the next possible select statement (in sequential order) until a match is found. If no match is found for the stratum, no features (products, treatments, etc.) are assigned and a message is written to the messages.csv file.

7

<features>

Feature sets describe the change in forest conditions over time, usually resulting from growth and natural processes. Feature sets are made up of <attribute> and <attributes> elements, collectively describing a set of curves. Features may describe changes in volume of certain species or species groups, habitat changes, visual disturbance characteristics or seral stages. Features attributes describe 'what is on the ground' and how those characteristics change over time. Feature attributes are generally distinguished by names beginning with the prefix feature as opposed to product. The <features> element goes hand in hand with select statements, as one features element is associated with a specific select statement. A features element may contain a long list of attributes, but that collection relates only to the strata that have met the requirements of the select statement.

8

<attribute>

An <attribute> is essentially a curve that describes either a feature or product. Be aware that there is an <attribute> and <attributes> element, each with distinct syntax and meaning.

An attribute has 5 attributes associated with it. Only label is mandatory (#REQUIRED). The label is a string that identifies the attribute and will appear as either a feature or product attribute in the Patchworks model, therefore be sure to use a consistent nomeclature scheme (feature for feature attributes and product for product attributes).

The <attribute> element contains a number of important parameters that allow the user to define how certain characteristics should behave over time (meaning should the attribute continue to cycle on the same curve, should it end at the maximum x value or should it succeed to something else?). An attribute can also use curve shapes that have been used by other attributes, but scale them back to create a new and unique attribute and curve (factor) but save space and time in the XML file.

9

<curve>

Curves are typically made up of one or more points. Curves are defined by inflection points, which are specified as x,y coordinate pairs. The values between points are filled in using a linear interpolation process. A straight-line extrapolation will be used for points below the minimum or above the maximum x value.

As stated earlier, curves are typically made of one or more points. However, the <curve> element has two optional attributes that allow for defining an identifier (id) and referring to other curve identifiers (idref). Both of these attributes are optional and no default is defined (#IMPLIED). In our example above, no attributes have been defined in the <curve> element, however in large complex datasets various curves can be used over and over again to describe certain attributes, features and products by referring to an idref.

10

<point>

The <point> element contains two required attributes: x and y. These attribute values represent inflection points on the curve. This is an EMPTY element and is therefore represented by <point x=" " y=" "/>. Points are always contained inside a <curve> element, as they describe the shape of the curve.

Example Block

With a <ForestModel> file like the one above, the Matrix Builder can use it as a RECIPE to create the necessary input files that eventually tell Patchworks about the actual forest dynamics of the planning area and the management options and responses available. To illustrate this we can take one Block from the dataset that met the SELECT statements in our example XML above.

Figure 176. Example Block from XML definition


In the above image, two curves are most apparent: feature.Yield.managed.Conif and feature.Yield.managed.Decid. These are the feature curves assigned to Block 50 , which were derived from the XML file we examined above. The original fragment from the input inventory satisfied the select statement:

    <select statement="theme2 eq 'Y4' and theme3 eq 'N'">
	  

and was therefore assigned <features>

    <attribute label="feature.Yield.managed.Decid">
    <attribute label="feature.Yield.managed.Conif">
	  

These features were then written to the features.csv input file, and the curves that describe these attributes were derived from the numerous <points> and then written to the curves.csv which Patchworks can then use to model the forest dynamics of this particular Block.

Many other Blocks in the dataset may have met our simple select statment and have been assigned the same feature attributes. These feature attributes could be represented by identical curves or they may use the same shaped curve but be scaled or factored by some appropriate value. In a more complex example, hundreds of feature select statements could exist to match many unique strata in the input inventory, with hundreds of associated curves. Although this creates a more complex and realistic ForestModel and dataset, the tools used are simply the basic elements we examined in this simple example!

The XML structure is straightforword and flexible, meaning you can create simple ForestModels like the one above or drastically more complex files using the exact same components. In the next section we will add some additional elements that would help to streamline the XML file if we had a large and complex dataset.