Skip to content

Volumetrics

Warning

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

Process forest inventory data. Adjust volumetric equations and taper functions for later use.

Class Parameters

Volumetrics(df, tree_identifier, tree_height, tree_dbh, tree_bark,
            segment_height, segment_diameter, tree_bark)
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 (Optional) The name of the column containing the heights of the cubed segments of the trees (meters). Required for fit_taper_functions() method.
segment_diameter (Optional) The name of the column containing the diameters of the cubed segments of the trees (centimeters). Required for fit_taper_functions() method.
tree_bark (Optional) The name of the column containing tree bark (centimeters).

Class Functions

functions and parameters
  Volumetrics.get_volumes()  
  Volumetrics.fit_taper_functions(models,iterator)  #(1)
  Volumetrics.fit_volumetric_functions(models, iterator, vol_column) #(2)
  Volumetrics.get_individual_diameter(hi,tree_height, tree_dbh) #(3)
  Volumetrics.get_individual_taper_volume(tree_height, tree_dbh, stump=0.1) #(4)
  Volumetrics.get_individual_volume(tree_height, tree_dbh) #(5)

  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. 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.
    vol_column = (Optional) A column name to the volume values. If vol_column == None, it uses de volumes obtained by the get_volumes() method to fit the volumetric functions.
  3. 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).
  4. tree_height = Total height of the tree (meters).
    tree_dbh = Diameter at breast height (DBH) of the tree (centimeters).
    stump = Stump height (meters). By default, uses stump = 0.1.
  5. tree_height = Total height of the tree (meters).
    tree_dbh = Diameter at breast height (DBH) 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() 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() Returns a pandas dataframe with diameter at a given hi height of the tree for each fitted taper model.
.get_individual_taper_volume() Returns a pandas DataFrame with the estimated volume for the provided height and diameter at breast height for each fitted taper function. It uses the integration of taper functions to obtain the result.
.get_individual_volume() Returns a pandas DataFrame with the estimated volume for the provided height and diameter at breast height for each fitted volumetric function.

Example Usage

taper_functions_example.py
1
2
from fptools.fit_volumetrics import Volumetrics #(1)
import pandas as pd #(2)

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

Create a variable for the Volumetrics Class

taper_functions_example.py
3
4
5
6
7
8
9
df = pd.read_csv(r'C:\Your\path\csv_tree_cubage_file.csv') #(1)
vol = Volumetrics(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)
vol.get_individual_taper_volume(30, 22.8) #(6)
vol.get_individual_volume(30, 22.8) #(7)

  1. Load your csv file.
  2. Create the variable vol containing the Volumetrics 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.
  6. Obtains the volumes calculated from the integration of taper functions for a tree with a height of 30 meters, a diameter at breast height of 22.8 centimeters, considering a stump height of 0.15 meters
  7. Obtains the volumes calculated from the fitted volumetric functions for a tree with a height of 30 meters and a diameter at breast height of 22.8 centimeters.

Available taper models

  • schoepfer

    • \[ \operatorname{d_i} =dbh\left( b_0 + b_1 \left( \frac{h_i}{H} \right) + 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} =b_0 \cdot (dbh^{b_1}) \cdot (h^{b_2}) \cdot \left(\frac{1 - \left(\frac{h_i}{h}\right)^{1/4}}{1 - \left(p^{1/3}\right)}\right)^{b_3 \cdot \left(\frac{h_i}{h}\right)^4 + b_4 \cdot \left(\frac{1}{e^{dbh/h}}\right) + b_5 \cdot \left(\frac{1 - \left(\frac{h_i}{h}\right)^{1/4}}{1 - \left(p^{1/3}\right)}\right)^{0.1} + b_6 \cdot \left(\frac{1}{dbh}\right) + b_7 \cdot \left(h^{1 - \left(\frac{h_i}{h}\right)^{1/3}}\right) + b_8 \cdot \left(\frac{1 - \left(\frac{h_i}{h}\right)^{1/4}}{1 - \left(p^{1/3}\right)}\right)} \]

  • johnson

    • \[ \operatorname{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

    • \[ \operatorname{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

    Available volumetric models

  • Spurr Model

    • \[ \operatorname{V} = b_0 + b_1 \cdot (\text{dbh}^2) \cdot H \]

  • Schumacher-Hall Model

    • \[ \operatorname{V} = b_0 \cdot (\text{dbh}^{b_1}) \cdot (H^{b_2}) \]

  • Honner Model

    • \[ \operatorname{V} = \frac{\text{dbh}^2}{b_1 \cdot \left(\frac{1}{H}\right)} \]

  • Ogaya Model

    • \[ \operatorname{V} = \frac{\text{dbh}^2}{b_1 \cdot H} \]

  • Stoate Model

    • \[ \operatorname{V} = b_0 + b_1 \cdot \text{dbh}^2 + b_2 \cdot \text{dbh}^2 \cdot H + b_3 \cdot H \]

  • Naslund Model

    • \[ \operatorname{V} = b_1 \cdot \text{dbh}^2 + b_2 \cdot \text{dbh}^2 \cdot H + b_3 \cdot \text{dbh} \cdot H^2 + b_4 \cdot H^2 \]

  • Takata Model

    • \[ \operatorname{V} = \frac{\text{dbh}^2 \cdot H}{b_0 + b_1 \cdot \text{dbh}} \]

  • Spurr Logarithmic Model

    • \[ \operatorname{V} = \exp(b_0 + b_1 \cdot \log(\text{dbh}^2 \cdot H)) \]

  • Meyer Model

    • \[ \operatorname{V} = b_0 + b_1 \cdot \text{dbh}^2 + b_2 \cdot \text{dbh} + b_3 \cdot \text{dbh} \cdot H + b_4 \cdot \text{dbh}^2 \cdot H \]

  • ann

    • Use the same ann models used for taper function.

    Notation

    • \( V \): Estimated volume (m³)
    • \( \text{dbh} \): Diameter at breast height (cm)
    • \( H \): Total height (m)

    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.