# TreeList Report

Text-file report containing stand and tree measures for each cycle in the simulation.

Outputs

TreeList

FilePath - Report file path

Format - Report format option: TABLE | CSV

Separator - Value separator option: COMMA | TAB

SpeciesCodes - Species code type you want to report: PLANT | FIA | VARIANT

Units - Unit system to report results in: METRIC | USA

MinDBH - Minimum tree record DBH reported

StartYear - Year to start reporting; default = 0 (all cycle start years reported)

YearInterval - Reporting interval in years; default = 1 (all cycle start years reported)

CutList - If set to TRUE (default = FALSE), additional tree records are written to the report

that represent the cut tree proportions when harvest occurs in the cycle.

When this is set to TRUE, make sure to report the ‘Cut’ column – see ‘SetStandColumns’

To be able to identify trees cut from uncut trees.

SetStandColumns - Stand variables you want to report

SetVaraintStandColumns - Varaint-specific stand variables you want to report

SetTreeColumns - Tree variables you want to report

TopDiameterSample - Number of trees per hectare included in stand-level top DBH (thickest or tallest) calculations. Default = 100 trees per hectare. If less than the sample number of trees are present, then all trees are used.

TopHeightSample - Number of trees per hectare included in stand-level top height (thickest or tallest) calculations. Default = 100 trees per hectare. If less than the sample number of trees are present, then all trees are used.

## FilePath

Absolute or relative report file path to create and write simulation results to. When set, if the file exists, it will be deleted immediately. Simulation results are continually written to this file immediately following each simulation cycle.

Surround your path with double quotes if it contains spaces.

## Format

Specifies the report format. Choose between:

· TABLE [Default] – character separated (delimited) values. This file format can be easily opened in Excel or imported into Access.

· COMPUTER – Use this report format if you will read the report from a custom third party application. Stand information is stored in a header line prefaced by a single character (~). Tree records follow this header for each stand cycle written. This report is designed to minimize report write and read times between OSM and third-party applications, as well as minimize hard disk space required to store the reports.

## Separator

Specifies the character delimiter to use for separating values in report lines.

· COMMA [Default]

· TAB

## MinDBH

Minimum DBH limit on trees reported. This limit also influences some stand summary statistics reported, such as Crown Closure (CC).

## SpeciesCodes

Reported species code options:

· VARIANT [Default] – Comma separated values. This file format can be easily opened in Excel or imported into Access. These species codes are set by the regional variant model and are therefore subject to change.

· PLANT [Recommended] – USDA For. Serv. Plant Database codes. Very unlikely to change.

· FIA – USDA For. Serv. Forest Inventory and Analysis numeric species codes. Unlikely to change.

## Units

Determines the units that report will be written in. Options:

· METRIC [Default]

· USA – English / Imperial

## YearInterval

Determines the year interval that will be reported, expressed in years. The following would report tree lists for cycles: 0, 2, 4, 6, 8 and 10; or in years: 0, 10,20,30,40, and 50. Setting YPC to 1 or 10 would still produce the same reporting intervals. Interval needs to be evenly divisible by YPC.

Simulation

YPC 5

Years 55

Outputs.TreeList.YearInterval 10

Important! Tree record properties that report tree dynamics to be applied before the next simulated cycle; e.g., ToCut, ToDie, DBHI, HTI, ToIngrow will only reflect the changes that are to occur before the next simulation cycle starts, not cumulative average cycle changes between reporting intervals. In other words, if simulating 5 YPC and reporting every 10 years, then each 10-year reported cycle would report tree list dynamics (e.g., DBHI mm/yr) for only the next five years, not the next ten.

## CutList

If set to TRUE (default = FALSE), additional tree records are written to the report that represent the cut tree proportions when harvest occurs in the cycle.

When this is set to TRUE, make sure to report the ‘Cut’ column – see ‘SetStandColumns’. The Cut column outputs to TRUE if the record represents a tree in the cut list.

This feature is useful for simplifying reporting both pre-cut and cut tree records in the same simulation cycle. This feature is also useful for developing Woodstock Regimes, as the output format when summarised at the stand-level matches closely with the ‘pre-cut’ and ‘cut’ Regime row format used by Woodstock.

Example Tree List Report commands:

OUTPUTS

TreeList

FilePath “C:\...\MyTreeListProjectionReport.csv”

CutList True

SetStandColumns Scenario SurveyID Cycle Year Age RD HT_Tallest DBH_Thickest History Cut

SetTreeColumns TreeID List Species DBH HT Stems ToCut ToDie

## SetStandColumns

This command sets specific stand properties or measures that are to be reported.

If this property is not set, all variables in the table below will be written and their order may not be the same as shown in the table rows.

Stand Columns | Data Type | Description
Scenario | String | Name of scenario. Set using SIMULATION.Scenario or from input tables.
SurveyID | String | Stand or plot ID. Defined on input.
SurveyYear | Int16 | Year of survey. Default set to current year by OSM if not defined on input.
SurveyAge | Int16 | Age of survey. Default set to zero by OSM if not defined on input.
Plots | Int16 | Number of plots in stand. Default set to 1 by OSM if not defined on input.
Stockable | Single | Ratio of total sample area (all plots) that supports productive tree growth. Default set to 1 by OSM if not defined on input.
X | Double | Longitude. Default set to zero by OSM if not defined on input.
Y | Double | Latitude. Default set to zero by OSM if not defined on input.
Cycle | Int16 | Simulation Cycle. Always starts at 0 and incremented by OSM each cycle.
YPC | Byte | Years per Cycle. Set using SIMULATION.YPC command. YPC can vary in the first couple cycles if SIMULATION.CurrentYear is set and >= SurveyYear, as OSM will first grow the stand to exactly match the current year (inventory alignment).
Year | Int16 | Calendar year at beginning of each simulation Cycle. Updated each cycle by OSM.
Age | Int16 | Stand age at beginning of each simulation Cycle. Updated each cycle by OSM.
History | String | Text describing treatment history in current Cycle. Set via Action commands.
RD | Single | Relative density ratio of stand at beginning of each Cycle. Depends on Variant stocking (self-thinning) relationship.
STK | Single | Stocking ratio of stand at beginning of Cycle. Depends on Variant stocking (self-thinning) relationship.
CC | Single | Crown closure percent of stand at beginning of Cycle. Depends on Variant crown width models.
HT_Thickest* | Single | Average height (m or feet) of X thickest trees in stand at beginning of Cycle.
HT_Tallest* | Single | Average height (m or feet) of X tallest trees in stand at beginning of Cycle.
DBH_Thickest* | Single | Average DBH (cm or inches) of X thickest trees in stand at beginning of Cycle.
DBH_Tallest* | Single | Average DBH (cm or inches) of X tallest trees in stand at beginning of Cycle.
Cut | Boolean | If included in this report, the trees cut during the cycle will be inserted as additional tree records in the report. Care must be taken to separate cut tree records (true) and existing tree records (false) when post processing tree list report results.

* Use TopDiameterSample & TopHeightSample to set number of trees considered in average. Default = 100.

To explicitly order and define which columns should be reported, set only those you wish to report, as shown in the example commands below:

Outputs

TreeList

SetStandColumns Scenario SurveyID Cycle YPC

Column order in the report will match the order of columns listed.

## SetVariantStandColumns

This command sets Variant-specific stand properties or measures that should be reported. These properties are handled separately from the base OSM properties as they require significantly different code logic to process.

If this property is not set, no Variant-specific variables will be written.

For example, in the Acadian-Variant, we could state:

Outputs

TreeList

SetStandColumns Scenario SurveyID Cycle YPC

SetVaraintStandColumns Zone BGI Management PoorSite

Following from above, the resulting report stand header would write like this:

Scenario, SurveyID, Cycle, YPC, Zone, BGI, Management, PoorSite

Variant columns are always printed after base OSM columns. Column order in the report will match the order of columns listed.

To limit columns reported, set only those you wish to report, but you do need to state at least one column if using this command.

For a list of reportable Variant-specific columns, see Variant input documentation; e.g.,

· Acadian Variant stand columns

· Newfoundland and Labrador Variant stand columns

## SetTreeColumns

This command sets specific tree properties or measures that should be reported. If not set, all variables available will be written.

Tree Columns | Data Type | Description
TreeID | Int64 | Unique ID for each tree throughout the simulation.
List | Byte | Internal OSM Tree List this tree currently resides in: 1 = Live Seedlings; 2 = Live Trees; 3 = Dead Standing Trees (snags).
Species | String | Variant Code (default), USDA FIA ID, or USDA Plant code
Born | Int16 | Year tree was born.
Died | Int16 | Year tree died. Zero for live trees.
Origin | String | Mode of regeneration.
DBH | Single | Diameter at breast height (cm or inches) at beginning of Cycle.
DBHI | Single | Diameter increment at breast height (cm/yr or inches/yr).
HT | Single | Height (m or ft) at beginning of Cycle.
HTI | Single | Height increment (m/yr or ft/yr).
HTK | Single | Height of top kill (m or ft). NaN for trees with no top kill.
BAL | Single | Basal area of larger (thicker) trees (m2/ha or ft2/ac).
Risk | Byte | Risk of mortality class. User defined in tree list. Not predicted by base model.
Grade | Byte | Bole form / quality class.
CR | Single | Crown ratio at beginning of Cycle.
CW | Single | Largest forest grown crown diameter (m or ft).
HCBI | Single | Height to live crown base increment (m or ft).
CCF | Single | Crown competition factor at beginning of Cycle.
GMV | Single | Gross merchantable volume (m3/ha or ft3/ac) for trees >= 8cm at beginning of Cycle.
GTV | Single | Gross total volume (m3/ha or ft3/ac) at beginning of Cycle.
Stems | Single | Total number of trees (#/ha or #/ac) at beginning of Cycle.
ToCut | Single | Total number of trees (#/ha or #/ac) scheduled to be cut at start of Cycle.
ToDie | Single | Total number of trees (#/ha or #/ac) scheduled to die at end of Cycle.

To limit columns reported, set only those you wish to report, e.g.:

Outputs

TreeList

SetStandColumns Scenario SurveyID Cycle YPC

SetTreeColumns Species DBH HT Stems

Column order in the report will match the order of columns listed. Stand columns are always written first.