Skip to content

Clutter Forecast

Warning

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

Use continuous forest inventory databases to predict forest growth and production. Utilize traditional method Clutter model. With this module, you will be able to estimate volume and basal area.

Class Parameters

Clutter Trainer

ClutterTrainer(df, age1, age2, ba1, ba2, site, vol, iterator=None)
Parameters Description
df The dataframe containing the continous processed forest inventory data.
age1 Name of the column containing the age of the previously sampled plot.
age2 Name of the column containing the age of the subsequently sampled plot.
ba1 Name of the column containing the basal area of the previously sampled plot.
ba2 Name of the column containing the basal area of the subsequently sampled plot.
site Name of the column containing the site index of the stand.
vol Name of the column containing the volume of the subsequently sampled plot.
iterator (Optional) Name of an iterator that will be used to group the data. Example of an iterator: Genetic material, Stratum.
Example of clutter input
Iterator Plot age1 age2 ba1 ba2 site vol
GM 1 1 2.5 3.5 7.57 8.42 7.83 44.04
GM 1 1 3.5 4.5 8.42 14 8.73 51.42
GM 1 2 2.1 3.1 4.94 5.51 6.98 38.06
GM 1 2 3.1 4.33 5.51 6.45 7.45 39.26
GM 2 1 2 3 7.3 8.25 11.37 74.63
GM 2 1 3 4 8.25 9.13 11.69 68.27
GM 2 1 4 5 9.13 12.79 12.83 72.76
GM 2 1 5 6 12.79 15.63 14 73.87

Class Methods

methods and parameters
  ClutterTrainer.fit_model(save_dir=None)#(1)!

  1. save_dir = Directory where the coefficients and parameters of the trained models will be saved.
Methods Description
.fit_model() Adjust the models for predicting basal area and volume.

Clutter Models

  • Basal area prediction

    • \[ \ln G_2 = \ln G_1 \left( \frac{t_1}{t_2} \right) + \alpha_0 \left( 1 - \frac{t_1}{t_2} \right) + \alpha_1 \left( 1 - \frac{t_1}{t_2} \right) S \]

  • Volume prediction

    • \[ \ln V_2 = \beta_0 + \beta_1 \cdot \frac{1}{t_2} + \beta_2 \cdot S + \beta_3 \cdot \ln G_2 \]
    Notation
    • \( G_1 \): Initial basal area (at age \( t_1 \)) in m²·ha⁻¹
    • \( G_2 \): Final basal area (at age \( t_2 \)) in m²·ha⁻¹
    • \( t_1 \): Initial age in months or years
    • \( t_2 \): Final age in months or years
    • \( S \): Site index, dimensionless, \( f(\text{site age}, t_i) \)
    • \( \alpha_0, \alpha_1 \): Coefficients to be estimated
    • \( V_2 \): Final volume (at age \( t_2 \)) in m³·ha⁻¹
    • \( \beta_i \): Coefficients to be estimated

    Class Parameters

    Clutter Predictor

    ClutterPredictor(coefs_file, age1, site, ba1, iterator=None)
    Parameters Description
    coefs_file Directory of the json file containing the coefficients and parameters of the fitted models.
    age1 Name of the column containing the age of the previously sampled plot.
    ba1 Name of the column containing the basal area of the previously sampled plot.
    site Name of the column containing the site index of the stand.
    iterator (Optional) Name of an iterator that will be used for predictions.
    Class Methods
    Methods Description
    .predict() Predicts future basal area and volume using the coefficients fitted in ClutterTrainer for a specific age.
    .get_coefs() Displays the coefficients loaded from the coefs_file.
    .predict_range() Predicts future basal area and volume using the coefficients fitted in ClutterTrainer for a predefined age range.

    methods and parameters
      ClutterTrainer.get_coefs()#(1)!
  ClutterTrainer.predict(age2)#(2)!
  ClutterTrainer.predict_range(age_range=(2, 10),show_plots=False)#(3)!

    1. Returns the loaded coefficients from coefs_file.
    2. Returns the prediction made for age2.
    3. Returns the prediction made for a specified age range in age_range as a tuple.
      If show_plots=True, displays the plots of the performed predictions.

    Example Usage

    As an example, we will use an adapted dataset from Arce and Dobner Jr. (2024) for Eucalyptus dunnii. The dataset consists of 81 permanent plots, with ages ranging from 3 to 9 years, measured continuously over time.

    Download file.

    First 5 rows of the file:

    Estrato Parcela I1 I2 G1 G2 IS V2_observ
    Estrato-2 1220117_P7005 3 4 8.88 11.98 14.42 36.05
    Estrato-2 1220117_P7005 4 5 11.98 13.53 14.42 51.90
    Estrato-2 1220117_P7005 5 6 13.53 17.24 14.42 81.22
    Estrato-2 1220117_P7005 6 7 17.24 22.47 14.42 144.45
    Estrato-2 1220117_P7005 7 8 22.47 22.20 14.42 150.15

    clutter_forecast_example.py
    1
2
    fptools.forecast import ClutterTrainer, ClutterPredictor#(1)!
import pandas as pd#(2)!

    1. Import ClutterTrainer and ClutterPredictor class from forecast module.
    2. Import pandas for data manipulation.

    clutter_forecast_example.py
     3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
    df = pd.read_csv(r'C:\Your\Directory\dados_clutter.xlsx')#(1)!

clutter = ClutterTrainer(dados, "I1","I2", "G1","G2",'IS',"V2_observ")#(2)!

metrics = clutter.fit_model(save_dir = r"C:\Your\Directory\to\save")#(3)!

predictor = ClutterPredictor("C:\Your\Directory\to\save\all_coefficients.json",
                             7,14.41,17.23)#(4)!

ba_vol_predicted = predictor.predict(10)#(5)!

coef = predictor.get_coefs()#(6)!

ba_vol_range_predicted = predictor.predict_range((2,12), show_plots=True)#(7)!

    1. Load your continuous forest inventory data file in xlsx format.
    2. Create the clutter variable containing the ClutterTrainer class, defining the corresponding columns.
    3. Fit the Clutter model, saving the coefficients and parameters to the folder C:\Your\Directory\to\save\the\metrics, and the training metrics to the variable metrics.
    4. Create a variable containing the predictor. This predictor will use the saved model C:\Your\Directory\to\save\all_coefficients.json to apply an inventory with age 7 years, a site index of 14.41, and a basal area of 17.23, in order to predict future volume and basal area production.
    5. Make the prediction for this stand at age 10 and save the results in ba_vol_predicted.
    6. Retrieve the model coefficients and store them in the variable coef.
    7. Make a prediction for this stand from age 2 to 12, generating a plot that shows the evolution of basal area and volume over this period, along with the confidence level.

    Outputs

    Tables

    metrics(1)

    1. Metric values from the model fitting for each model used by iterator (when applicable).
    Iterator Model MSE RMSE MAE MAPE R² Explained Variance Max Error
    Not used ln_ba2_est 2.70 1.64 1.32 2.35 0.92 0.94 4.41
    Not used ln_vol2_est 280.92 16.76 12.34 2.06 0.94 0.94 76.58

    ba_vol_predicted(1)

    1. Estimated future basal area and volume values for age 10.
    BA2 Volume
    17.23 159.03

    coef(1)

    1. Dictionary with coefficients for each model and iterator (when used).
    {
  "lnb2_model": {
    "b0": 0.03818795042386813,
    "b1": 3.465183897074305,
    "b2": 0.016174627316697623,
    "num_rows": 402,
    "min_age": 3,
    "max_age": 9,
    "mape": 2.3528810455777904,
    "r2": 0.923524025998693
  },
  "lnv2_model": {
    "b0": 1.3927682912732822,
    "b1": -4.364287014356091,
    "b2": 0.04215217322729903,
    "b3": 1.1299750378626658,
    "num_rows": 402,
    "min_age": 3,
    "max_age": 9,
    "mape": 2.0563064467361003,
    "r2": 0.9414308873440383
  }
}

    ba_vol_range_predicted(1)

    1. Data frame containing future basal area and volume estimates for a predefined age range.
    Age BA2 Volume BA2_max_error BA2_min_error Volume_max_error Volume_min_error
    2.00 2.05 1.88 2.10 2.00 1.91 1.84
    2.50 3.72 5.69 3.81 3.63 5.81 5.57
    3.00 5.54 11.93 5.67 5.41 12.17 11.68
    3.50 7.35 20.24 7.53 7.18 20.65 19.82
    4.00 9.10 30.09 9.31 8.88 30.70 29.47
    4.50 10.74 40.95 10.99 10.48 41.79 40.11
    5.00 12.26 52.41 12.54 11.97 53.49 51.33
    5.50 13.66 64.13 13.98 13.34 65.45 62.81
    6.00 14.95 75.87 15.30 14.60 77.43 74.31
    6.50 16.14 87.48 16.52 15.76 89.28 85.68
    7.00 17.23 98.83 17.64 16.82 100.86 96.79
    7.50 18.24 109.85 18.67 17.81 112.10 107.59
    8.00 19.17 120.49 19.62 18.71 122.97 118.01
    8.50 20.02 130.74 20.50 19.55 133.43 128.05
    9.00 20.82 140.58 21.31 20.33 143.47 137.69
    9.50 21.56 150.00 22.07 21.05 153.09 146.92
    10.00 22.25 159.03 22.77 21.72 162.30 155.76
    10.50 22.89 167.66 23.42 22.35 171.11 164.21
    11.00 23.48 175.91 24.04 22.93 179.53 172.30
    11.50 24.04 183.80 24.61 23.48 187.58 180.03
    12.00 24.57 191.35 25.15 23.99 195.28 187.41
    Example of Output Forecast Chart

    References

    CLUTTER, J. L.; FORTSON, J. C.; PIENAAR, L. V.; BRISTER, G. H.; BAILEY, R. L. (1983). Timber management: a quantitative approach. New York: John Wiley & Sons, 333p.

    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.