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 (m²/ha or ft²/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.