Skip to content

Volumetrics

Warning

This library is under development, none of the presented solutions are available for download.

Obtain tree volumes from forest inventory data and fit taper functions to capture tree shape and estimate diameters at different heights. Obtain reports on the total volume produced, as well as assortments generated by the forest.

Class Parameters

VolEstimation(df, tree_identifier, tree_height, tree_dbh, tree_bark, segment_height, segment_diameter)
Parameters Description
df The dataframe containing the cubage data.
tree_identifier The name of the column that contains the unique identifiers of the trees.
tree_height The name of the column that contains the total heights of the trees (meters).
tree_dbh The name of the column containing the diameter at breast height (DBH) values of the trees (centimeters).
tree_bark (Optional) The name of the column containing the bark thickness values of the trees (centimeters). If tree_bark == None return only volumes with bark on 'get_volumes()' method.
segment_height The name of the column containing the heights of the cubed segments of the trees (meters).
segment_diameter The name of the column containing the diameters of the cubed segments of the trees (centimeters).

Class Functions

functions and parameters
  VolEstimation.get_volumes()  
  VolEstimation.fit_taper_functions(models,iterator)  #(1) 
  VolEstimation.get_individual_diameter(hi,tree_height, tree_dbh) #(2)

  1. models = (Optional) List of models to be fitted! If models == None uses all available models.
    iterator = (Optional) A column name string. Defines wich column will be used as a iterator. Could be a farm name, plot name, code or any unique identification tag.
  2. hi = Fraction of height from which you want to obtain the diameter (meters).
    tree_height = Total height of the tree (meters).
    tree_dbh = Diameter at breast height (DBH) value of the tree (centimeters).
Parameters Description
.get_volumes() Returns the volume of each cubed segment and the total volume of each tree separated by tree_identifier. If tree_bark == None, it returns only the volume with bark; otherwise, it returns the volume with and without bark.
.fit_taper_functions(models, iterator) Fits the available taper function models. Saves a .json file with the coefficients for each fitted model and a .pkl file for the fitted ANN's.
.get_individual_diameter(hi, tree_height, tree_dbh) Returns a diameter at a hi height of the tree.

Example Usage

taper_functions_example.py
1
2
from fptools.taper_functions import VolEstimation #(1)
import pandas as pd #(2)

  1. Import VolEstimation class.
  2. Import pandas for data manipulation.

Create a variable for the VolEstimation Class

taper_functions_example.py
3
4
5
6
7
df = pd.read_csv(r'C:\Your\path\csv_tree_cubage_file.csv') #(1)
vol = VolEstimation(df=df,tree_identifier= 'arvore_id', tree_height='HT',tree_dbh = 'DAP', segment_height='HT segmento', segment_diameter= 'Dsegmento',tree_bark='Casca') #(2)
calculated_volumes_df = vol.get_volumes() #(3) 
metrics = vol.fit_taper_functions() #(4) 
vol.get_individual_diameter(1.3,25,30) #(5)

  1. Load your csv file.
  2. Create the variable vol containing the VolEstimation class.
  3. Calculate volumes for each tree and segments em save the results on calculated_volumes_df variable.
  4. Fit the taper functions and save the performance metris in metrics variable. It will create a .json file with the models coefficients and a .pkl files for the fitted ann models.
  5. Get the diameter at 1.3 meters of a tree with a total height of 25 meters and a diameter at breast height (DBH) of 30 centimeters.

Available models

  • schoepfer

    • \[ \operatorname{d_i} =dbh\left( b_0 + b_1 \frac{h_i}{H} + b_2 \left( \frac{h_i}{H} \right)^2 + b_3 \left( \frac{h_i}{H} \right)^3 + b_4 \left( \frac{h_i}{H} \right)^4 + b_5 \left( \frac{h_i}{H} \right)^5 \right) \]

  • bi

    • \[ \operatorname{d_i}=dbh\left[ \left( \frac{log\;sin \left( \frac{\pi}{2} \frac{h_i}{H} \right)} {log\;sin \left( \frac{\pi}{2} \frac{1.3}{H} \right)} \right) ^{\beta_0+\beta_1sin\left(\frac{\pi}{2}\frac{h_i}{H}\right)+\beta_2sin\left(\frac{3\pi}{2}\frac{h_i}{H}\right)+\beta_3sin\left(\frac{\pi}{2}\frac{h_i}{H}\right)/\frac{h_i}{H}+\beta_4dbh+\beta_5\frac{h_i}{H}\sqrt{dbh}+\beta_6\frac{h_i}{H}\sqrt{H}} \right] \]

  • kozak

    • \[ \operatorname{d_i} = \beta_0dbh^{\beta_1}\left[\frac{1-\left(\frac{h_i}{H}\right)^{1/4}}{1-p^{1/4}}\right]^{\beta_2+\beta_3\left(\frac{1}{e^{dbh/H}}\right)+\beta_4dbh^{\left[\frac{1-\left(\frac{h_i}{H}\right)^{1/4}}{1-p^{1/4}}\right]}+\beta_5\left[\frac{1-\left(\frac{h_i}{ht}\right)^{1/4}}{1-p^{1/4}}\right]^{dbh/H}} \]

  • johnson

    • \[ d_i = dbh \cdot \left( b_0 \cdot \log\left( \frac{b_1 + \frac{(H - h_i)}{(H - 1.3)}}{b_2} \right) \right) \]

  • matte

    • \[ d_i = dbh \cdot \left( b_0 \cdot \left( \frac{H - h_i}{H - 1.30} \right)^2 + b_1 \cdot \left( \frac{H - h_i}{H - 1.30} \right)^3 + b_2 \cdot \left( \frac{H - h_i}{H - 1.30} \right)^4 \right) \]

  • ann

    • Notation

    • \( β_n \): Fitted parameters
    • \( d_i \): Diameter (cm)
    • \( \text{dbh} \): Diameter at breast height (cm)
    • \( H \): Total height (m)
    • \( h_i \): Segment height (m)

    Artificial Neural Network

    When selecting the 'ann' model, 5 different structures of artificial neural networks will be tested. Only the result from 1 model will be returned. The model returned will be selected by the ranking function.
    For the 'ann' model, the module sklearn.neural_network.MLPRegressor is used.

    --- title: ANN Parameters --- classDiagram direction LR class MLPRegressor { Epochs: 3000 Activation: logistic Solver Mode: lbfgs Batch size: dynamic Learning rate init: 0.1 Learning rate mode: adaptive } class Model-0 { Hidden layer sizes: (4,5) 'relogisticlu' activation } class Model-1 { Hidden layer sizes: (4,2) 'logistic' activation } class Model-2 { Hidden layer sizes: (3,2) 'logistic' activation } class Model-3 { Hidden layer sizes: (4,4) 'logistic' activation } class Model-4 { Hidden layer sizes: (4,4) 'relu' activation } MLPRegressor <|-- Model-0 MLPRegressor <|-- Model-1 MLPRegressor <|-- Model-2 MLPRegressor <|-- Model-3 MLPRegressor <|-- Model-4

    Ranking function

    To select the best-performing models and rank them accordingly, the following metrics are obtained:

    Métric name Structure
    Mean Absolute Error (MAE) \( MAE = \frac{1}{n} \sum_{i=1}^{n} \|y_i - \hat{y}_i\| \)
    Mean Absolute Percentage Error (MAPE) \( MAPE = \frac{100}{n} \sum_{i=1}^{n} \left\|\frac{y_i - \hat{y}_i}{y_i}\right\| \)
    Mean Squared Error (MSE) \( MSE = \frac{1}{n} \sum_{i=1}^{n} (y_i - \hat{y}_i)^2 \)
    Root Mean Squared Error (RMSE) \( RMSE = \sqrt{\frac{1}{n} \sum_{i=1}^{n} (y_i - \hat{y}_i)^2} \)
    R Squared (Coefficient of Determination) \( R^2 = 1 - \frac{\sum_{i=1}^{n} (y_i - \hat{y}_i)^2}{\sum_{i=1}^{n} (y_i - \bar{y})^2} \)
    Explained Variance (EV) \( EV = 1 - \frac{Var(y - \hat{y})}{Var(y)} \)
    Mean Error \( Mean\ Error = \frac{1}{n} \sum_{i=1}^{n} (y_i - \hat{y}_i) \)

    After obtaining the metrics for each tested model, the best model receives a score of 10, while the others receive scores of 9, 8, and so on.