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
Volumetrics.get_volumes()
Volumetrics.fit_taper_functions(models, iterator, save_dir = None)#(1)!
Volumetrics.fit_volumetric_functions(models, iterator, vol_column,
save_dir = None)#(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)!
- 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.
save_dir = (Optional) A directory to save the fitted function parameters and ann model. - 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. Ifvol_column == None
, it uses de volumes obtained by theget_volumes()
method to fit the volumetric functions.
save_dir = (Optional) A directory to save the fitted function parameters and ann model. - 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). - 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, usesstump = 0.1
. - tree_height = Total height of the tree (meters).
tree_dbh = Diameter at breast height (DBH) of the tree (centimeters).
Methods | 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
Consider a volume dataset composed of 50 Eucalyptus trees, in which diameters were measured at heights of 0.1 meter, 0.6 meter, 1.30 meters, and, from that point onward, at 2-meter intervals along the stem.
First 5 rows of the file:
Fazenda | arvore_n | dap (cm) | altura_total (m) | seção (m) | diametro_c_casca (cm) | diametro_s_casca (cm) | casca (cm) |
---|---|---|---|---|---|---|---|
Fazenda 1 | 1 | 24,8 | 28,0 | 0,1 | 30,05 | 26,51 | 1,74 |
Fazenda 1 | 1 | 24,8 | 28,0 | 0,6 | 26,55 | 23,15 | 1,96 |
Fazenda 1 | 1 | 24,8 | 28,0 | 1,3 | 24,75 | 21,93 | 1,94 |
Fazenda 1 | 1 | 24,8 | 28,0 | 2,0 | 23,85 | 21,48 | 1,90 |
Fazenda 1 | 1 | 24,8 | 28,0 | 4,0 | 21,40 | 19,30 | 1,11 |
taper_functions_example.py | |
---|---|
- Import
Volumetrics
class. - Import
pandas
for data manipulation.
- Load your
.xlsx
file. - Create the variable
vol
containing theVolumetrics
class. - Calculate the volumes for each tree and segment, grouped by
iterator
, and save the results in the variablecalculated_volumes_df
. The original DataFrame will be returned with the following additional columns:segment_vol_with_bark
,segment_vol_without_bark
,tree_vol_with_bark
,tree_vol_without_bark
,bark_factor
, andmean_bark_factor
. - Save the DataFrame with the calculated volumes as
exemplo_volumetrics_with_vol.xlsx
. - Fit taper functions and artificial neural networks for each
iterator
, saving the performance metrics in the variablemetrics_taper
. This will create a.json
file with the model coefficients and.pkl
files for the trained ANN models, storing all generated files insave_dir
. - Get the diameter at 10 meters for a tree with a total height of 31 meters and a diameter at breast height (DBH) of 30 centimeters using the fitted models, saving it in the variable
individual_diameter
. - Get the volumes calculated by integrating the taper functions for a tree with a height of 35 meters and DBH of 32 centimeters, considering a stump height of 0.15 meters, and save it in the variable
taper_volume
. - Fit all volumetric functions for each
iterator
and save the results insave_dir
, storing the metrics in the variablemetrics_vol
. Since novol_column
was provided, it will use the volume obtained through theget_volumes
method to fit the models. - Calculate the volume of a tree with a height of 21.8 meters and a DBH of 19 centimeters using all volumetric functions and save it in the variable
individual_volume
.
Output
Tables
calculated_volumes_df
(1)
- Initial DataFrame with the following additional columns:
segment_vol_with_bark
,segment_vol_without_bark
,tree_vol_with_bark
,tree_vol_without_bark
,bark_factor
,mean_bark_factor
Fazenda | arvore_n | dap (cm) | altura_total (m) | seção (m) | diametro_c_casca (cm) | diametro_s_casca (cm) | casca (cm) | segment_vol_with_bark | segment_vol_without_bark | tree_vol_with_bark | tree_vol_without_bark | bark_factor | mean_bark_factor |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Fazenda 1 | 1 | 24,84076433 | 28 | 0,1 | 30,05 | 26,51 | 1,74 | 0,007092165 | 0,005544635 | 0,559879936 | 0,387477996 | 0,692073373 | 0,682430303 |
Fazenda 1 | 1 | 24,84076433 | 28 | 0,6 | 26,55 | 23,15 | 1,96 | 0,031450877 | 0,023341421 | 0,559879936 | 0,387477996 | 0,692073373 | 0,682430303 |
Fazenda 1 | 1 | 24,84076433 | 28 | 1,3 | 24,75 | 21,93 | 1,94 | 0,036171179 | 0,026055822 | 0,559879936 | 0,387477996 | 0,692073373 | 0,682430303 |
Fazenda 1 | 1 | 24,84076433 | 28 | 2,0 | 23,85 | 21,48 | 1,90 | 0,032463883 | 0,02310445 | 0,559879936 | 0,387477996 | 0,692073373 | 0,682430303 |
Fazenda 1 | 1 | 24,84076433 | 28 | 4,0 | 21,40 | 19,30 | 1,11 | 0,080407591 | 0,065402308 | 0,559879936 | 0,387477996 | 0,692073373 | 0,682430303 |
Fazenda 1 | 1 | 24,84076433 | 28 | 6,0 | 20,50 | 19,17 | 1,81 | 0,068942643 | 0,047175553 | 0,559879936 | 0,387477996 | 0,692073373 | 0,682430303 |
About the generated columns
segment_vol_with_bark
: Stem segment with bark volume, calculated between two consecutive measurement sections.segment_vol_without_bark
: Stem segment without bark volume, calculated between two consecutive measurement sections.tree_vol_with_bark
: Total tree with bark volume, obtained by summing all segment volumes with bark.tree_vol_without_bark
: Total tree without bark volume, obtained by summing all segment volumes without bark.bark_factor
: Bark factor of the segment, calculated as the ratio between the volume with bark and the volume without bark for that segment.mean_bark_factor
: Average bark factor of the tree, calculated as the mean of the bark factors from all segments.
metrics_taper
(1)
- DataFrame with evaluation metrics generated for each
iterator
and taper model and artificial neural network, including the score assigned to each model based on its performance.
iterator | model | MAE | MAPE | MSE | RMSE | R squared | Explained Var | Mean Error | score |
---|---|---|---|---|---|---|---|---|---|
Fazenda 1 | kozak | 0,580666 | 5,718699 | 0,572843 | 0,756864 | 0,994621 | 0,994621 | -0,000167 | 10 |
Fazenda 1 | bi | 0,635942 | 5,972947 | 0,643045 | 0,801901 | 0,993962 | 0,994016 | -0,075560 | 9 |
Fazenda 1 | ann | 0,576319 | 5,651187 | 0,560707 | 0,748804 | 0,994735 | 0,994739 | 0,020658 | 8 |
Fazenda 1 | schoepfer | 0,769151 | 7,532993 | 1,033545 | 1,016634 | 0,990295 | 0,990356 | -0,080168 | 7 |
Fazenda 1 | johnson | 1,078775 | 10,108434 | 1,978243 | 1,406500 | 0,981425 | 0,981571 | -0,124507 | 6 |
Fazenda 1 | matte | 1,424262 | 14,718423 | 3,337336 | 1,826838 | 0,968664 | 0,969344 | 0,269282 | 5 |
Fazenda 2 | ann | 1,342497 | 7,238220 | 3,318417 | 1,821652 | 0,988023 | 0,988023 | 0,001891 | 10 |
Fazenda 2 | kozak | 1,350729 | 7,357823 | 3,468079 | 1,862278 | 0,987483 | 0,987483 | -0,002186 | 9 |
Fazenda 2 | bi | 1,374535 | 7,880664 | 3,483492 | 1,866412 | 0,987427 | 0,987435 | -0,045863 | 8 |
Fazenda 2 | schoepfer | 1,678529 | 8,785657 | 4,895865 | 2,212660 | 0,982329 | 0,982373 | 0,110280 | 7 |
Fazenda 2 | matte | 2,180025 | 13,928099 | 7,414827 | 2,723018 | 0,973238 | 0,974475 | 0,585444 | 6 |
Fazenda 2 | johnson | 2,216439 | 12,099970 | 9,165003 | 3,027376 | 0,966921 | 0,966956 | 0,097858 | 5 |
individual_diameter
(1)
- DataFrame with the individual diameters estimated by the taper functions and artificial neural networks for each
iterator
and taper model, for a tree with a height of 31 meters, a DBH of 30 centimeters, at a height of 10 meters.
iterator | model | Predicted_diameter (cm) |
---|---|---|
Fazenda 1 | schoepfer | 22,75296935 |
Fazenda 1 | bi | 22,35954058 |
Fazenda 1 | kozak | 22,45146956 |
Fazenda 1 | johnson | 23,41945889 |
Fazenda 1 | matte | 22,83651908 |
Fazenda 1 | ann | 23,33443805 |
Fazenda 2 | schoepfer | 21,48912862 |
Fazenda 2 | bi | 23,08526645 |
Fazenda 2 | kozak | 22,40805692 |
Fazenda 2 | johnson | 22,46401882 |
Fazenda 2 | matte | 21,43830806 |
Fazenda 2 | ann | 23,71472482 |
taper_volume
(1)
- DataFrame with the volumes estimated by integrating the taper functions and artificial neural networks for each
iterator
and taper model, for a tree with a height of 35 meters and a DBH of 32 centimeters.
iterator | model | Predicted_volume (m³) |
---|---|---|
Fazenda 1 | schoepfer | 1,166056704 |
Fazenda 1 | bi | 1,143061281 |
Fazenda 1 | kozak | 1,165284829 |
Fazenda 1 | johnson | 1,201758409 |
Fazenda 1 | matte | 1,150231088 |
Fazenda 1 | ann | 1,326654958 |
Fazenda 2 | schoepfer | 1,055148596 |
Fazenda 2 | bi | 1,179288353 |
Fazenda 2 | kozak | 1,147756782 |
Fazenda 2 | johnson | 1,108690858 |
Fazenda 2 | matte | 1,066598472 |
Fazenda 2 | ann | 1,178903371 |
metrics_vol
(1)
- DataFrame with evaluation metrics generated for each
iterator
, volumetric model, and artificial neural network, including the score assigned to each model based on its performance.
iterator | model | MAE | MAPE | MSE | RMSE | R squared | Explained Var | Mean Error | score |
---|---|---|---|---|---|---|---|---|---|
Fazenda 1 | honner | 0,028987 | 6,510184 | 0,001409 | 0,037535 | 0,998022 | 0,998143 | -0,009291 | 10 |
Fazenda 1 | ann | 0,020789 | 5,362507 | 0,000713 | 0,026703 | 0,998999 | 0,998999 | -0,000569 | 9 |
Fazenda 1 | takata | 0,027501 | 5,250705 | 0,001291 | 0,035934 | 0,998187 | 0,998214 | -0,004318 | 8 |
Fazenda 1 | spurr_log | 0,026612 | 4,438766 | 0,001235 | 0,035137 | 0,998267 | 0,998277 | -0,002731 | 7 |
Fazenda 1 | schumacher_hall | 0,027584 | 4,649301 | 0,001203 | 0,034683 | 0,998311 | 0,998321 | -0,002636 | 6 |
Fazenda 1 | meyer | 0,025136 | 6,229777 | 0,001112 | 0,033346 | 0,998439 | 0,998439 | 0,000000 | 5 |
Fazenda 1 | stoate | 0,026301 | 6,530368 | 0,001158 | 0,034029 | 0,998374 | 0,998374 | 0,000000 | 4 |
Fazenda 1 | spurr | 0,026008 | 9,348743 | 0,001177 | 0,034306 | 0,998348 | 0,998348 | 0,000000 | 3 |
Fazenda 1 | naslund | 0,024859 | 11,898225 | 0,001020 | 0,031930 | 0,998569 | 0,998571 | 0,001263 | 2 |
Fazenda 1 | ogaya | 0,410646 | 151,1923 | 0,213968 | 0,462567 | 0,699650 | 0,719168 | -0,117918 | 1 |
Fazenda 2 | naslund | 0,153069 | 6,603060 | 0,048230 | 0,219612 | 0,974528 | 0,974529 | -0,001349 | 10 |
Fazenda 2 | schumacher_hall | 0,160824 | 9,781453 | 0,048410 | 0,220023 | 0,974433 | 0,974447 | -0,005183 | 9 |
Fazenda 2 | spurr_log | 0,160540 | 9,932109 | 0,048446 | 0,220105 | 0,974414 | 0,974428 | -0,005270 | 8 |
Fazenda 2 | takata | 0,159037 | 6,922203 | 0,049057 | 0,221488 | 0,974091 | 0,974091 | -0,000386 | 7 |
Fazenda 2 | ann | 0,150892 | 5,508166 | 0,043498 | 0,208562 | 0,977027 | 0,977053 | 0,007015 | 6 |
Fazenda 2 | meyer | 0,155147 | 8,411204 | 0,047824 | 0,218687 | 0,974742 | 0,974742 | 0,000000 | 5 |
Fazenda 2 | stoate | 0,161432 | 14,918844 | 0,048986 | 0,221328 | 0,974129 | 0,974129 | 0,000000 | 4 |
Fazenda 2 | spurr | 0,181962 | 28,583026 | 0,055897 | 0,236425 | 0,970479 | 0,970479 | 0,000000 | 3 |
Fazenda 2 | honner | 0,189541 | 6,829942 | 0,062964 | 0,250927 | 0,966746 | 0,967397 | 0,035110 | 2 |
Fazenda 2 | ogaya | 0,430466 | 40,223791 | 0,284181 | 0,533086 | 0,849913 | 0,850523 | 0,034001 | 1 |
individual_volume
(1)
- DataFrame with the volumes estimated by the volumetric functions and artificial neural networks for each
iterator
, for a tree with a height of 21.8 meters and a DBH of 19 centimeters.
iterator | model | Predicted_volume (m³) |
---|---|---|
Fazenda 1 | spurr | 0,241827831 |
Fazenda 1 | schumacher_hall | 0,248607044 |
Fazenda 1 | honner | 0,262977386 |
Fazenda 1 | ogaya | 0,860375777 |
Fazenda 1 | naslund | 0,245824632 |
Fazenda 1 | takata | 0,255820523 |
Fazenda 1 | spurr_log | 0,251481659 |
Fazenda 1 | meyer | 0,228396501 |
Fazenda 1 | stoate | 0,241410100 |
Fazenda 1 | ann | 0,271805848 |
Fazenda 2 | spurr | 0,421606899 |
Fazenda 2 | schumacher_hall | 0,332105882 |
Fazenda 2 | honner | 0,232727813 |
Fazenda 2 | ogaya | 0,939382897 |
Fazenda 2 | naslund | 0,324612548 |
Fazenda 2 | takata | 0,287273333 |
Fazenda 2 | spurr_log | 0,336234242 |
Fazenda 2 | meyer | 0,200621992 |
Fazenda 2 | stoate | 0,242861095 |
Fazenda 2 | ann | 0,284503571 |
.json
Files
For each taper and volumetric function, .json
files are generated containing the estimated coefficients of each model. An individual .json
file is created for each iterator, named according to its respective identifier.
- taper_functions_coefficients_Fazenda 1.json
- taper_functions_coefficients_Fazenda 2.json
- volumetrics_functions_coefficients_Fazenda 1.json
- volumetrics_functions_coefficients_Fazenda 2.json
.pkl
Files
Similarly, for each artificial neural network trained for tapering or volume prediction, a .pkl
file is generated containing the trained model, named according to the respective iterator.
- taper_model_ann_Fazenda 1.pkl
- taper_model_ann_Fazenda 2.pkl
- volumetric_ann_Fazenda 1.pkl
- volumetric_ann_Fazenda 2.pkl
Although this type of file cannot be viewed directly, it stores the neural network parameters and internal configurations, which will be used later in the generation of assortments.
Available taper models
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, 6 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.
Available volumetric models
Use the same ann models used for taper function.
Notation
- \( b_n \): Fitted parameters
- \( 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) \) |
Notation
- \( y_i \): Observed value for the i-th observation
- \( \hat{y}_i \): Estimated (predicted) value for the i-th observation
- \( n \): Total number of observations
- \( \bar{y} \): Mean of the observed values
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.
References
BI, H. (2000). Trigonometric variable-form taper equations for Australian eucalypts. Forest Science, 46(3), 397–409.
JOHNSON, T. (1911). Taxatariska undersökringar om skogsträdens form. Skgsvardsföreningens tiedskrifle. Häfte, Berlim, 9(10), 285–329.
KOZAK, A. (2004). My last words on taper equations. The Forestry Chronicle, 80(4), 507–515.
MATTE, L. (1949). The taper of coniferous species with special reference to Loblolly Pine. Forestry Chronicle, Mattawa, 25(1), 21–31.
MEYER, H. A. (1940). A mathematical expression for height curves. Journal of Forestry, 38, 415–420. https://doi.org/10.1093/jof/38.5.415
NÄSLUND, M. (1936). Skogsförsöksanstaltens gallringsförsök i tallskog. Meddelanden från Statens Skogsförsöksanstalt, Swedish Institute of Experimental Forestry, 29: 169.
SCHÖEPFER, W. (1966). Automatisierung des Massen-, Sorten- und Wertberechnung stehender Waldbestände. Schriftenreihe Bad. Wurtt-Forstl.
SCHUMACHER, F. X.; HALL, F. S. (1933). Logarithmic expression of timber tree volume. Journal of Agricultural Research, Washington, 47(9), 719–734.
SCOLFORO, J. R. S. (2005). Biometria Florestal: Parte I: Modelos de regressão linear e não-linear; Parte II: Modelos para relação hipsométrica, volume, afilamento e preso de matéria seca. Lavras: UFLA/FAEPE, pp. 224–226.
SPURR, S. R. (1952). Forest inventory. New York: Ronald Press, 476 p.
STOATE, I. N. (1945). The use of a volume equation in pine stands. Australian Forestry, Canberra, 9, 48–52.