Name

XMLWoodstock — Woodstock to ForestModel XML conversion wizard.

Synopsis

Synopsis

ca.spatial.tracks.woodstock.XMLWoodstock {inFilename} {OutFilename} {startYear} {periodWidth}
      

Arguments

NameDescriptionDefault
startYearThe start year of the simulationNone
periodWidth None
resolveActionsA method choice to resolve duplicate actionsFirst outcome
inFilenameThe name of the Woodstock input file (*.pri)None
useHintsFileUse a Patchworks hints file to customize conversionFalse
hintsFilenameSpecify the location of the Patchworks hints fileNone
outFilename None
yieldCurves.useIgnoreAttribute curves to be used or ignored (*Y and *YC)All/true
yieldCurves.interpolateConversion method for periodic values to annualized values. Use to set the annualized X value of the attribute curves) (Middle, End, Square, -3, -2, -2.5, -1).Middle
yieldCurves.attributeNameDefine new label for yield curves that are compatible with Patchworks.%f.attr.%m.OriginalYieldCurveName
yieldCurves.startZeroSpecifies whether translator should force the curve to start at 0,0 (all other values ignored).False
areaThemes.useIgnoreSelect themes to be added automatically as area attributesAll/True
areaThemes.prefixSpecify a label that will be used for the 'prefix' of the area attribute names that is compatible with Patchworks.%f.THEME_NAME.%m.
inventory.blockIDSpecify the column name from the spatial dataset that identifies the block labels. This will be translated to the proper XML define statement and used during the Matrix Builder process.None
inventory.AgeSpecify an expression that identifies the age of each stand.AGE
inventory.AreaSpecify an expression that defines the area of each stand.AREA
inventory.ExcludeSpecify an expression that will identify those stands that are excluded from the analysis.true

Description

The XMLWoodstock program is a translator that converts a Woodstock *.pri input file into the ForestModel XML format. The program is automated and will prompt you for the input parameters specified above in a wizard format (see the section called “ Converting the Aspatial Model to the Forest Model ” for more dialog and examples from the sample dataset). The Woodstock PRI file can either a complete model within a single file, or a reference to separate Woodstock components. The Patchworks HINTS' file can also be used to streamline the conversion process and eliminate any XML customization that may be required after the translation. The hints file is a TXT file that requires specific formatting and arguments. The hints file is discussed and defined in more detail below.

Background

There are several important differences between the modelling habits of Patchworks and Woodstock that are useful to understand when carrying out a conversion.

  1. Patchworks is an annual model and Woodstock is a periodic model. Patchworks performs actions and calculations on an annual basis. Woodstock carries out all actions on a periodic basis, with periods being typically 5 or 10 years.

  2. Patchworks is a 'cut then grow' type of model and Woodstock is a 'grow then cut'. This difference has subtle implications for differences in operable growing stock, operability, volumes harvested, etc.

  3. Patchworks includes a "period 0" to represent the initial conditions of the forest. Woodstock does not.

  4. Yields are assigned the same value for a 5 year period in a Woodstock model, but assigned a different yield for each year in Patchworks. Yield curve translation parameters can be used to specify the interpolation of the yield curves to allow for more control over interpolated values.

  5. In Woodstock, when a regeneration delay is imposed for 5 years (1 period) a stand is harvested in period 1, removed from the harvestable landbase in period 2, and then allowed back into the harvestable landbase in period 3. In Patchworks, if a stand is harvested in year 1, the delay applies to years 2 through 6, then the stand is available for harvest in year 7, which would be within period 2.

  6. Woodstock allows multiple response outcomes for each treatment. Patchworks allows only a single response for each treatment. Where multiple responses occur Patchworks can automatically choose the first outcome and ignore the rest, or multiple new strata can be defined to hold a single response rule. New strata and responses need to be defined in the Woodstock model.

  7. Woodstock allows operability limits to be defined on volume, age and timing criteria. Patchworks cannot use the timing restrictions. All other operability criteria can be included if the Woodstock constants appear at the beginning of the PRI file (in a complete model PRI file). Patchworks interprets the treatment operability using the 'lookupCurve' function in the ForestModel.

Processing Notes - Patchworks Hints File

The Patchworks hints file helps to streamline the conversion process, reduce repetition and eliminate the need to customize the resulting XML file to match the spatial dataset. During the model preparation phase several adjustments are made to both the Woodstock model and resulting XML to add features, attributes or improve the representation of the spatial dataset. The hints file saves the custom adjustments you have made to attribute names, curve conversions and selections as well as appends custom XML code verbatim to the end of the resulting XML file. In this way, making small adjustments to the Woodstock model (actions, yield curves, complex curves, transitions) to improve the model is effecient and consistent.

The following sections, arguments and formatting should be followed when creating a Woodstock hints file. The Woodstock hints file follows formatting rules similar to Woodstock models. More information and dialog is available in the section called “ Converting the Aspatial Model to the Forest Model ”. The sample dataset also includes a working 'hints' file (Patchworks/sample/tracks/Woodstock/C5_hints.txt).

Woodstock Hints File Sections

  • *INPUT

    A list of name/value pairs describing the column definitions for the block, area, age and exclude parameters used in the input statement of the ForestModel.

    *INPUT
    block   Int(BLOCK)
    area    AREA/10000
    age     F_AGE
    exclude BLOCK=0
    	      

  • *DEFINE

    A list of name/value pairs describing the column definitions for the define statements of the ForestModel.

    *DEFINE
    theme1 Upper(String(THEME1))
    theme2 Upper(String(THEME2))
    theme3 Upper(String(THEME3))
    theme4 Upper(String(THEME4))
    theme5 Upper(String(THEME5))
    		

  • *ATTRIBUTE

    Used to describe the interpretation of the yield curves and complex curves from the Woodstock model. There are 5 arguments for the *ATTRIBUTE parameter:

    1. Curve Name - the name of the curve as it appears in the Woodstock model (capitalization important).

    2. Use/Ignore - boolean (true/false) whether to include this curve and it's definition in the XML or not. Can easily exclude curves or test different configurations of the model using this parameter without major alterations to the file.

    3. Period conversion - sets the X values of the curves from the Woodstock periodic values to an annual value. Accepted values include: Middle, End, Square, -3, -2.5, -2, -1. This would be interpreted as: X value = (periodwidth - 2.5). See below (REFERENCE) for a more detailed explanation of the 'Square' method.

    4. Attribute name - the name of the attribute as it will appear in the XML. This is where woodstock curves can be renamed to fit within the Patchworks hierarchial nomenclature system (see example below).

    5. Force Zero - Specify 'zero' to force the curve to start at (0,0). Patchworks uses a straightline interpolation technique from the first point and below, and the last point and above. This argument can be used to force the model to add the (0,0) point. This is often useful for yield curves so that a stand at Year 0 does not appear to have volume.

    ; Volume Curves
    *ATTRIBUTE Conif true -3 %f.Yield.%m.Conif zero
    *ATTRIBUTE Decid true -3 %f.Yield.%m.Decid zero
    
    ; Seral Stage Curves
    *ATTRIBUTE regen true Square %f.Seral.regen
    *ATTRIBUTE young true Square %f.Seral.young
    *ATTRIBUTE mature true Square %f.Seral.mature
    *ATTRIBUTE old true Square %f.Seral.old
    		

  • *THEME

    The theme tag allows you to define which themes to include as simple area attributes in the ForestModel, the attribute name (pattern prefix) and which values to include. THEME requires 3 parameters and accepts an optional list for unique values:

    1. Theme Number - The number of the THEME as it appears in the Woodstock model.

    2. Use/Ignore - boolean (true/false) argument to specify whether or not to include the theme as an area attribute.

    3. Attribute Name - specify the attribute name to be used in the ForestModel. The attribute name allows you to define Patchworks attribute labels that follow the hierarchial nomenclature pattern. The attribute name is essentially the 'pattern prefix' of the area attribute label. Including the '%f' and '%m' in the name will allow the model to create both 'feature' and 'product' attributes, for both the 'managed' and 'unmanaged' areas automatically (see XML reference for more details).

    4. Category Names (optional) - an optional list of category names can follow the THEME to specify new names for the attribute labels and which of the category values should be included. This allows you to update numeric theme values with abbreviated labels in the Patchworks model and to exclude irrelevant categories (ie. non-forest for example). If no list is provided all values will be read in and names will be unchanged.

    ; Theme area attributes
    *THEME 5 true %f.Area.%m.
    		

    *THEME 1 true  %f.Area.Strata.%m.
     1   AspenShrub
     2   AspenWhiteSpruce
     3   AspenLateMixedWhiteSpruce
     4   AspenEarlyMixedWhiteSpruce
     5   AspenMixedWhiteSpruce
     6   WspruceWhiteSpruce
     7   Pine
     8   PineBlackSpruceDeciduous
     9   DeciduousPineBlackSpruce
     10  PineWhiteSpruce
     11  BalsamPoplarShrub
     12  BlackSprucePineWhitespruce
     13  BlackSpruce
    		

  • *XML

    Any text that occurs in this section will be copied verbatim to the end of the XML file. Often custom code is added to the XML to add features to the Patchworks model. If the Woodstock model is re-translated this code would be overwritten. Adding this additional code to the hints file ensures that it is included each time the translation occurs and the resulting XML file does not require any edits.

    Often features are defined for patching criteria in the Patchworks model, operable growing stock curve definitions, or cost information.

    *XML
    
    <!-- Treatment disturbance curve.  Every treatment
           causes a disturbance -->
    
      <select>
        <products>
          <attribute label="product.disturbed">
            <curve idref="unity"/>
          </attribute>
        </products>
      </select>
    	      

    <!-- Operable growing stock Curves -->
      <select>
        <features>
          <attribute label="%f.Opgs.%m.Sftwd">
            <expression statement="operable(attribute('%f.Yield.%m.Swvol'))" />
          </attribute>
          <attribute label="%f.Opgs.%m.Hrdwd">
            <expression statement="operable(attribute('%f.Yield.%m.Hwvol'))" />
          </attribute>
        </features>
      </select>
    		

See Also

the section called “ Converting the Aspatial Model to the Forest Model ”

Examples

java -jar patchworks.jar ca.spatial.gis.woodstock.XMLWoodstock