Skip to content

Forest Report

Generate a forest report based on estimated heights and volumes using the other modules of ForestPyTools. Obtain volume values and tree types per hectare at various specific levels of the forest stand, along with other metrics. Get the report in xlsx (Excel) or json format.

Class Parameters

ForestReport(df, plot_id, plot_size, tree_type, tree_dbh,
             tree_height,group_levels = None, tree_vol_with_bark = None 
             tree_vol_withou_bark = None, iterator=None)
Parameters Description
df The dataframe containing the processed forest inventory data.
plot_id Name of the column that contains the unique identifier for each plot.
plot_size Numeric value indicating the plot size in square meters or the name of the column that contains the size of each plot in square meters.
tree_type Name of the column that contains the id of the tree types present in the forest inventory. The id must be included in tree_types_df.
tree_dbh Name of the column that contains the diameter at breast height (DBH) values.
tree_height Name of the column that contains the tree height values.
group_levels (Optional) List with the names of grouping levels that the user wants to create. A summary will be generated for each group. Example of groups: Farm, stand, soil type.
tree_vol_with_bark (Optional) Name of the column that contains the tree volume values with bark.
tree_vol_without_bark (Optional) Name of the column that contains the tree volume values without bark.
iterator (Optional) Name of an iterator that will be used to group the data. Example of an iterator: Stratum.

Class Methods

methods and parameters
  ForestReport.update_tree_types(df)#(1)!
  ForestReport.view_tree_types()
  ForestReport.get_report(dir, format="xlsx")#(2)!

  1. df = DataFrame containing the tree types present in the forest inventory. If None, the library's default DataFrame is used.
  2. dir = Directory where the report will be saved.
    format = Format in which the report will be saved. Could be xlsx(Excel) or json.
Methods Description
.update_tree_types() Updates the tree_types_df -> DataFrame that contains the ids of tree types, names, and description.
.view_tree_types() Displays the tree_types_df that the class is currently using.
.get_report() Saves the forest report in xlsx or json format in the specified dir.

Example of tree types table

id name description commercial_volume missing_stems
0 normal Tree without significant distortions or defects 1 0
1 dead Dead tree 0 0
2 bifurcated above DBH Tree bifurcated above diameter at breast height (DBH) 1 0
3 bifurcated below DBH Tree bifurcated below diameter at breast height (DBH) 1 0
4 burned Burned tree 0 0
5 missing Missing tree (planting line failure) 0 1

The column order must be followed.

Attention

  • The commercial_volume column is a binary flag that indicates whether the tree type represented by the id should be included in the commercial volume calculation. A value of 1 means the tree contributes to commercial volume; 0 means it is excluded from the calculation.

  • The missing_stems column is also a binary flag, used to identify the absence of trees in the expected planting location. Unlike dead trees, these cases represent gaps in spacing, which may result from mortality followed by tree fall, thinning operations, or planting omissions.

Column Descriptions

  • id: Represents a unique identifier for each tree type in the classification. It is used to distinguish records and can serve as a reference key in other datasets.

  • name: Indicates the name of the tree based on its condition or specific characteristics. This name acts as a short label for quick identification.

  • description: Provides a detailed explanation of the tree's condition, including information about structure, health status, or defects that may impact its commercial value.

  • commercial_volume: Indicates whether the tree's volume is considered commercially usable. A value of 1 means the tree has commercial volume and will be used; a value of 0 means it will not be used.

  • missing_stems: Used to identify missing trees in the expected planting line. Unlike dead trees, these are gaps in spacing, which may result from fallen dead trees, thinning, or unplanted spots.

Usage Example

To illustrate how the forest report module works, we use inventory data adapted from Arce and Dobner Jr. (2024).
The inventory was carried out across 19 different farms, with Eucalyptus dunnii plantations ranging from 8 to 9 years of age.
In total, 1,954 trees were measured.
The volume was calculated using a form factor of 0.45 and a bark factor of 0.91.

Download the file.

First 5 rows of the file:

ID parcela area_parcela Idade ID_Regiao ID Fazenda ID talhao Espécie Coluna Árvore Fuste Tipo arvore dap (cm) ht ht_calculada (m) Vol (m³) Vol SC (m³)
14-401-109002-1 300 8 14 14-401 14-401-109002 Eucalyptus dunnii 4 26 1 2 23.5 18.1 17.57 0.342933476 0.329216137
14-401-109002-1 300 8 14 14-401 14-401-109002 Eucalyptus dunnii 3 21 1 1 20.6 17.4 17.25 0.258717577 0.248368874
14-401-109002-1 300 8 14 14-401 14-401-109002 Eucalyptus dunnii 1 5 1 1 20.3 17.21 0.250654405 0.240628229
14-401-109002-1 300 8 14 14-401 14-401-109002 Eucalyptus dunnii 2 12 1 1 20.3 17.6 17.21 0.250654405 0.240628229
14-401-109002-1 300 8 14 14-401 14-401-109002 Eucalyptus dunnii 2 15 1 1 20.0 17.0 17.17 0.242735156 0.233025750

The library provides a default example of a tree types DataFrame to be used.
However, each forestry engineer or company may have their own methodology and coding for tree types.
In this case, we use the tree type classification defined by Arce and Dobner Jr. (2024).

Download the file.

Below is the DataFrame that we will use.

id name description commercial_volume missing_stems
1 Normal Healthy tree, without significant distortions or visible defects. 1 0
2 Dominante Tree that stands out in height and vigor compared to neighboring trees. 1 0
3 Seco Dead tree, without leaves and with no signs of physiological activity. 0 0
4 Quebrado Tree with damaged or broken parts of the trunk or crown. 0 0
5 Rebrotado Tree originated from sprouts after cutting or damage to the main stem. 1 0
6 Falta Absence of a tree in the expected planting line position. 0 1
7 Bifurcado Tree with the main stem divided into two or more main branches. 1 0
8 Inclinado Tree growing significantly tilted in relation to the vertical axis. 1 0
9 Apice Seco Tree with the upper part (apex) dry or dead. 1 0
10 Fuste Curvo Tree with a curved trunk, lacking straight alignment. 1 0
11 Suprimido Tree suppressed by shading or competition from neighboring trees. 1 0

forest_report_example.py
1
2
3
from fptools.forest_report import ForestReport#(1)!

import pandas as pd#(2)!

  1. Import the ForestReport class.
  2. Import the pandas library for data manipulation.

forest_report_example.py
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
inventory_data = pd.read_excel(
                              r'C:\seu\caminho\exemplo_forest_report.xlsx'
                              )#(1)!

tree_df_types = pd.read_excel(r'C:\seu\caminho\tree_types.xlsx')#(2)!

report = ForestReport(inventory_data, plot_id="ID parcela",
                      plot_size='area_parcela',tree_type='Tipo arvore',
                      group_levels=['ID_Regiao','ID Fazenda','ID talhao'],
                      tree_height="ht_calculada (m)", tree_dbh="dap (cm)",
                      tree_vol_with_bark="Vol (m³)",
                      tree_vol_without_bark="Vol SC (m³)")#(3)!

report.view_tree_types()#(4)!

report.update_tree_types(tree_df_types)#(5)!

report.get_report(r'C:\seu\caminho\para\salvar', format="xlsx")#(6)!

  1. Load the inventory_data DataFrame from an xlsx file.
  2. Load the tree_types_df DataFrame from an xlsx file.
  3. Create the report variable containing the ForestReport class using the inventory_data DataFrame.
    Set the ID parcela column to identify each plot.
    Set the area_parcela column to provide the plot size in square meters.
    Set the Tipo arvore column to identify the ID of each tree present in tree_types_df.
    Set the columns ID_Regiao, ID Fazenda, and ID talhao as subgroup levels for which reports will be generated.
    Set the ht_calculada (m) column as the one containing tree heights in meters.
    Set the dap (cm) column as the one containing tree diameters at breast height in centimeters.
    Set the Vol (m³) column as the one containing total tree volume with bark.
    Set the Vol SC (m³) column as the one containing total tree volume without bark.
  4. Display the current tree_types_df DataFrame (the default DataFrame that should be customized).
  5. Update the tree_types_df using the tree_df_types DataFrame.
  6. Save the report in xlsx format.

Attention: Unique Identifiers in Groupings

When using the group_levels parameter, it is essential that the defined groups contain unique combinations of values across the specified columns. This avoids ambiguity in the summaries generated by grouping.

For example, when grouping by ID_Regiao and ID Fazenda, do not use generic identifiers like "A", "B", or "C" if they are reused across different regions. See the examples below:

✅ Correct Example

ID_Regiao ID Fazenda
14 14-A
14 14-B
15 15-A
15 15-B

Each combination of ID_Regiao and ID Fazenda is unique, ensuring consistent groupings with no overlap.

❌ Incorrect Example

ID_Regiao ID Fazenda
14 A
14 B
15 A
15 B

In this incorrect example, the identifier "A" appears in two different regions. If grouping is done only by ID Fazenda, the summaries for "A" will include data from both regions, leading to interpretation errors.

💡 Recommendation

Use composite identifiers that include full context, such as "14-A", "15-B", etc., ensuring that each group is unique.

References

ARCE, JULIO EDUARDO; DOBNER JR., MARIO. (2024). Manejo e planejamento de florestas plantadas: com ênfase nos gêneros Pinus e Eucalyptus. Curitiba, PR: Ed. dos Autores, 419p.