Package 'GCubeR'

Add or compute c130 and dbh columns

Description

Ensures that both c130 (circumference at 1.30 m) and dbh (diameter at 1.30 m) are present in the dataset. If one is missing, it is computed from the other.

Usage

add_c130_dbh(data, output = NULL)

Arguments

data	A data frame containing tree measurements. Must include at least one of the following columns: c130: circumference at 1.30 m (cm) dbh: diameter at 1.30 m (cm)
output	Optional file path where the resulting data frame should be exported as a CSV. If NULL (default), no file is written.

Details

• This function should be used at the very beginning of the workflow to ensure both c130 and dbh columns are available for subsequent functions.

• Conversion uses the formula: dbh = c130 / pi and c130 = dbh * pi.

• Units are centimeters (cm).

• If both columns are present, values are left unchanged.

Value

The same data frame with both c130 and dbh columns. Note: the function does not modify the input data frame in place. To update your object, you must reassign the result, e.g.: data2 <- add_c130_dbh(data2)

Examples

data <- data.frame(c130 = c(31.4, 62.8))
data <- add_c130_dbh(data)

data2 <- data.frame(dbh = c(10, 20))
data2 <- add_c130_dbh(data2)

---

Volume Estimation Using the Algan Method

Description

Computes aerial total volume (algan_vta) and merchantable volume (algan_vc22) according to the Algan method. The function validates input data, ensures required columns are present and applies formulas only to compatible species.

Usage

algan_vta_vc22(data, output = NULL)

Arguments

data	A data frame containing tree measurements. Must include: species_code: species name in uppercase Latin format (e.g. "ABIES_ALBA"). dbh: diameter at breast height (cm). htot: total tree height (m).
output	Optional file path where the resulting data frame should be exported as a CSV. If NULL (default), no file is written. Export is handled by the utility function export_output() and failures trigger warnings without interrupting execution.

Details

• Input dbh must be in centimeters (cm). The function converts it internally to meters.

• Input htot must be in meters (m).

• Formula for aerial total volume (only "ABIES_ALBA"):

  $algan_vta = 0.4 * (dbh/100)^2 * htot$

• Formula for merchantable volume (compatible species):

  $algan_vc22 = 0.33 * (dbh/100)^2 * htot$

  • Domain of application:

  • For "ABIES_ALBA" and "PICEA_ABIES", the Algan method is valid only if ⁠dbh > 15 cm⁠.

  • For other compatible species (ALNUS_GLUTINOSA, PRUNUS_AVIUM, BETULA_SP), no minimum dbh threshold is applied.

• Resulting volumes are expressed in cubic meters (m3).

• If required columns are missing or non-numeric, the function stops with an error.

• Both output columns are always created to ensure consistency for downstream functions.

Value

A data frame with the original input columns plus two new outputs:

• algan_vta: aerial total volume (m3). Computed only for "ABIES_ALBA", NA otherwise.

• algan_vc22: merchantable volume (m3). Computed only for compatible species (ABIES_ALBA, PICEA_ABIES, ALNUS_GLUTINOSA, PRUNUS_AVIUM, BETULA_SP), NA otherwise.

Examples

df <- data.frame(
  species_code = c("ABIES_ALBA", "PICEA_ABIES", "BETULA_SP", "QUERCUS_ROBUR"),
  dbh = c(30, 25, 20, 40), 
  htot = c(20, 18, 15, 22)   
)
algan_vta_vc22(df)

---

Total Biomass, Carbon and CO2 Estimation for Tree Species

Description

Computes total biomass (aboveground + root), carbon content and CO2 equivalent for tree species using CNPF (with multiple trunk volume sources) and Vallet methods.

Usage

biomass_calc(data, na_action = c("error", "omit"), output = NULL)

Arguments

data	A data frame containing volume and species information for each tree. Must include: species_code: species name in uppercase Latin format (e.g. "PICEA_ABIES"), matched against a density table. At least one volume column: For CNPF method (trunk volume): Dagnelie equations: dagnelie_vc22_2, dagnelie_vc22_1g, dagnelie_vc22_1 (priority order: dagnelie_vc22_2 > dagnelie_vc22_1g > dagnelie_vc22_1) Vallet equation: vallet_vc22 Rondeux equation: rondeux_vc22 Algan equation: algan_vc22 For Vallet method (total aboveground volume): vallet_vta If multiple trunk volumes are provided, CNPF is computed separately for each source. If only one is available, the corresponding method is applied. All volume columns must be numeric and expressed in cubic meters (m3).
na_action	How to handle missing values. "error" (default) stops if any required value is missing. "omit" removes rows with missing values.
output	Optional file path where the resulting data frame should be exported as a CSV. If NULL (default), no file is written. Export is handled by the utility function export_output() and failures trigger warnings without interrupting execution.

Details

• The density table provides:

  • density: wood density in tonnes of dry matter per cubic meter (t/m3).

  • con_broad: species group, either "conifer" or "broadleaf".

• The expansion factor feb is derived from con_broad:

  • feb = 1.3 for conifers

  • feb = 1.56 for broadleaves

• Dagnelie trunk volume (vc22_dagnelie) is automatically selected from the best available column, in the following priority: dagnelie_vc22_2 > dagnelie_vc22_1g > dagnelie_vc22_1.

• CNPF outputs are computed separately for each trunk volume source (Dagnelie, Vallet, Rondeux, Algan).

• Vallet method is applied only to a predefined list of compatible species using vallet_vta.

• If required columns are missing, the corresponding method is skipped with a warning.

• Warnings are also displayed if trunk volume columns exist but contain missing values (NA).

• All biomass values are expressed in tonnes of dry matter (t), carbon in tonnes of carbon (t C), and CO2 in tonnes of CO2 equivalent (t CO2).

Value

A data frame with one row per tree, including:

• species_code: species name in uppercase Latin format.

• dagnelie_vc22_1, dagnelie_vc22_1g, dagnelie_vc22_2, vallet_vc22, rondeux_vc22,algan_vc22: optional trunk volume inputs (in m3).

• vallet_vta: optional total aboveground volume (in m3) for Vallet method.

• vc22_dagnelie: selected trunk volume used for CNPF (Dagnelie), based on priority.

• vc22_source: name of the Dagnelie column used to populate vc22.

CNPF method outputs:

• From Dagnelie (priority selection):

  • cnpf_dagnelie_bag, cnpf_dagnelie_bbg, cnpf_dagnelie_btot, cnpf_dagnelie_c, cnpf_dagnelie_co2

• From Vallet trunk volume (vallet_vc22):

  • cnpf_vallet_bag, cnpf_vallet_bbg, cnpf_vallet_btot, cnpf_vallet_c, cnpf_vallet_co2

• From Rondeux trunk volume (rondeux_vc22):

  • cnpf_rondeux_bag, cnpf_rondeux_bbg, cnpf_rondeux_btot, cnpf_rondeux_c, cnpf_rondeux_co2

• From Algan trunk volume (algan_vc22):

  • cnpf_algan_bag, cnpf_algan_bbg, cnpf_algan_btot, cnpf_algan_c, cnpf_algan_co2

Vallet method outputs (if vallet_vta is available and species is compatible):

• vallet_bag, vallet_bbg, vallet_btot, vallet_c, vallet_co2

Examples

data <- data.frame(
  species_code = c("PICEA_ABIES", "QUERCUS_ROBUR", "FAGUS_SYLVATICA"),
  dagnelie_vc22_2 = c(1.1, NA, NA),
  dagnelie_vc22_1g = c(NA, NA, NA),
  dagnelie_vc22_1 = c(NA, 0.9, NA),
  vallet_vc22 = c(NA, 1.2, NA),
  rondeux_vc22 = c(NA, NA, 1.0),
  algan_vc22 = c(NA,0.8,NA),
  vallet_vta = c(1.5, NA, 1.3)
)

output_path <- tempfile(fileext = ".csv")
results <- biomass_calc(data, output = output_path)
if (file.exists(output_path)) {
  message("CSV file successfully created.")
} else {
  warning("CSV file was not created.")
}

---

Volume Estimation Using the Bouvard Method

Description

Computes aerial total volume (bouvard_vta) according to the Bouvard method. The function validates input data, ensures required columns are present, and applies the formula only to species "QUERCUS_SP".

Usage

bouvard_vta(data, output = NULL)

Arguments

data	A data frame containing tree measurements. Must include: species_code: species name in uppercase Latin format (e.g. "QUERCUS_SP"). dbh: diameter at breast height (cm). htot: total tree height (m).
output	Optional file path where the resulting data frame should be exported as a CSV. If NULL (default), no file is written. Export is handled by the utility function export_output() and failures trigger warnings without interrupting execution.

Details

• Input dbh must be in centimeters (cm). The function converts it internally to meters.

• Input htot must be in meters (m).

• Formula for aerial total volume (only "QUERCUS_SP"):

  $bouvard_vta = 0.5 * (dbh/100)^2 * htot$

• Resulting volumes are expressed in cubic meters (m3).

• If required columns are missing or non-numeric, the function stops with an error.

• The output column is created only if at least one "QUERCUS_SP" row is present, otherwise a warning message is displayed and no column is added.

Value

A data frame with the original input columns plus one new output:

• bouvard_vta: aerial total volume (m3). Computed only for "QUERCUS_SP", otherwise not created.

Examples

df <- data.frame(
  species_code = c("QUERCUS_SP", "PICEA_ABIES", "FAGUS_SYLVATICA"),
  dbh = c(30, 25, 40),   
  htot = c(20, 18, 22)   
)
bouvard_vta(df)

---

Convert circumference between 1.50 m and 1.30 m

Description

Computes stem circumference at 1.30 m (c130, in cm) from circumference at 1.50 m (c150, in cm) using species-specific linear coefficients stored in the reference table c150_c130_coeff. If only c130 is available, the function back-computes c150 using the inverse of the same equation.

Usage

c150_c130(data, output = NULL)

Arguments

data	A data.frame containing at least: species_code: tree species code, c150: stem circumference at 1.50 m (cm), or c130: stem circumference at 1.30 m (cm).
output	Optional file path where the resulting data frame should be exported as a CSV. If NULL (default), no file is written. Export is handled by the utility function export_output() and failures trigger warnings without interrupting execution.

Details

The conversion equation is:

$c130 = a \cdot c150 + b$

where $a$ and $b$ are species-specific coefficients.

The function performs the following steps:

• checks that the input data frame contains the required variables species_code and at least one of c150 or c130,

• validates that numeric values are provided,

• verifies that all species are available in the c150_c130_coeff reference table and issues a warning otherwise,

• merges the input with c150_c130_coeff to retrieve coefficients and species-specific validity ranges (min_c150, max_c150),

• warns when circumference values fall outside the recommended range,

• computes missing c130 from c150, or missing c150 from c130,

• returns the augmented data frame with both columns completed.

Value

A data.frame identical to the input but augmented with:

• species-specific coefficients and validity ranges,

• both c150 and c130 columns completed whenever possible.

Supported species

The following species codes are supported by c150_c130:

• "QUERCUS_SP", "QUERCUS_ROBUR", "QUERCUS_PETRAEA", "QUERCUS_PUBESCENS", "QUERCUS_RUBRA"

• "FAGUS_SYLVATICA", "ACER_PSEUDOPLATANUS", "FRAXINUS_EXCELSIOR", "ULMUS_SP", "PRUNUS_AVIUM"

• "BETULA_SP", "ALNUS_GLUTINOSA", "LARIX_SP", "PINUS_SYLVESTRIS", "CRATAEGUS_SP"

• "PRUNUS_SP", "CARPINUS_SP", "CASTANEA_SATIVA", "CORYLUS_AVELLANA", "MALUS_SP"

• "PYRUS_SP", "SORBUS_ARIA", "SAMBUCUS_SP", "RHAMNUS_FRANGULA", "PRUNUS_CERASUS"

• "ALNUS_INCANA", "POPULUSxCANADENSIS", "POPULUS_TREMULA", "PINUS_NIGRA", "PINUS_LARICIO"

• "TAXUS_BACCATA", "ACER_PLATANOIDES", "ACER_CAMPESTRE", "SORBUS_AUCUPARIA", "JUNGLANS_SP"

• "TILLIA_SP", "AESCULUS_HIPPOCASTANUM", "ROBINIA_PSEUDOACACIA", "SALIX_SP"

See Also

c150_c130_coeff for species-specific coefficients.

Examples

df <- data.frame(
  species_code = c("PINUS_SYLVESTRIS", "QUERCUS_RUBRA"),
  c150 = c(145, NA),
  c130 = c(NA, 156)
)
c150_c130(df)

---

Coefficients for circumference conversion (1.50 m <-> 1.30 m)

Description

Species-specific linear coefficients used to convert stem circumference between 1.50 m (c150) and 1.30 m (c130). These coefficients are used internally by c150_c130.

Usage

data(c150_c130_coeff)

Format

A data frame with columns:

species_code

Tree species code (character)

coeff_a

Slope coefficient a (numeric)

coeff_b

Intercept coefficient b (numeric)

min_c150

Minimum valid circumference at 1.50 m (cm)

max_c150

Maximum valid circumference at 1.50 m (cm)

Source

Internal CSV file data-raw/c150_c130_coeff.csv

---

Single-entry Dagnelie branch volume (tarif "br")

Description

Computes the branch volume $v_{br}$ (in cubic metres per tree) using Dagnelie's single-entry "br" equations. The branch volume is derived from the stem circumference at 1.30 m (c130, in cm) and the tree species, using species-specific polynomial coefficients stored in the reference table danbr.

Usage

dagnelie_br(data, output = NULL)

Arguments

data	A data.frame containing at least: c130: stem circumference at 1.30 m (cm), species_code: tree species code.
output	Optional file path where the resulting data frame should be exported as a CSV. If NULL (default), no file is written. Export is handled by the utility function export_output() and failures trigger warnings without interrupting execution.

Details

The "br" tarif branch volume is calculated as:

$v_{br} = a + b\,c130 + c\,c130^2 + d\,c130^3$

where $a$, $b$, $c$, and $d$ are species-specific coefficients.

The function performs the following steps:

• checks that the input data frame contains the required variables c130 and species_code,

• validates that c130 is numeric,

• verifies that all species are available in the danbr reference table and issues a warning otherwise,

• merges the input with danbr to retrieve coefficients and species-specific validity ranges (min_c130, max_c130),

• warns when c130 values fall outside the recommended range,

• computes tarif-"br" branch volume and returns the augmented data frame.

If one or more species codes are not found in danbr, the function issues a warning and returns NA-values for missing coefficients and volumes. Trees with c130 values outside the recommended species-specific range produce a warning but still receive a computed branch volume.

Value

A data.frame identical to the input data but augmented with:

• species-specific coefficients and validity ranges,

• dagnelie_br: the computed Dagnelie tarif-"br" branch volume (m$^3$ per tree).

Supported species

The following species codes are supported by dagnelie_br:

• "QUERCUS_SP",

• "QUERCUS_ROBUR",

• "QUERCUS_PETRAEA",

• "QUERCUS_PUBESCENS",

• "QUERCUS_RUBRA"

• "FAGUS_SYLVATICA",

• "ACER_PSEUDOPLATANUS",

• "FRAXINUS_EXCELSIOR",

• "ULMUS_SP",

• "PRUNUS_AVIUM"

• "BETULA_SP",

• "ALNUS_GLUTINOSA",

• "LARIX_SP",

• "PINUS_SYLVESTRIS",

• "CRATAEGUS_SP"

• "PRUNUS_SP",

• "CARPINUS_SP",

• "CASTANEA_SATIVA",

• "CORYLUS_AVELLANA",

• "MALUS_SP"

• "PYRUS_SP",

• "SORBUS_ARIA",

• "SAMBUCUS_SP",

• "RHAMNUS_FRANGULA",

• "PRUNUS_CERASUS"

• "ALNUS_INCANA",

• "POPULUSxCANADENSIS",

• "POPULUS_TREMULA",

• "PINUS_NIGRA",

• "PINUS_LARICIO"

• "TAXUS_BACCATA",

• "ACER_PLATANOIDES",

• "ACER_CAMPESTRE",

• "SORBUS_AUCUPARIA",

• "JUNGLANS_SP"

• "TILLIA_SP",

• "AESCULUS_HIPPOCASTANUM",

• "ROBINIA_PSEUDOACACIA",

• "SALIX_SP"

See Also

danbr for species-specific coefficients.

Examples

df <- data.frame(
  c130         = c(145, 156, 234, 233),
  species_code = c("PINUS_SYLVESTRIS", "QUERCUS_RUBRA",
                   "QUERCUS_SP", "FAGUS_SYLVATICA")
)
dagnelie_br(df)

---

Single-entry Dagnelie volume (tarif 1)

Description

Computes the standing volume $v_{c,22}$ (in cubic metres per tree) using Dagnelie's single-entry tarif-1 equations. The volume is derived from the stem circumference at 1.30 m (c130, in cm) and the tree species, using species-specific polynomial coefficients stored in the reference table dan1.

Usage

dagnelie_vc22_1(data, output = NULL)

Arguments

data	A data.frame containing at least: c130: stem circumference at 1.30 m (cm), species_code: tree species code.
output	Optional file path where the resulting data frame should be exported as a CSV. If NULL (default), no file is written. Export is handled by the utility function export_output() and failures trigger warnings without interrupting execution.

Details

The tarif-1 volume is calculated as:

$v_{c,22} = coeff\_a + coeff\_b \cdot c130 + coeff\_c \cdot c130^2 + coeff\_d \cdot c130^3$

where $a$, $b$, $c$, and $d$ are species-specific coefficients.

The function performs the following steps:

• checks that the input data frame contains the required variables c130 and species_code,

• validates that c130 is numeric,

• verifies that all species are available in the dan1 reference table and issues a warning otherwise,

• merges the input with dan1 to retrieve coefficients and species-specific validity ranges (min_c130, max_c130),

• warns when c130 values fall outside the recommended range,

• computes tarif-1 volume and returns the augmented data frame.

If one or more species codes are not found in dan1, the function issues a warning and returns NA-values for missing coefficients and volumes. Trees with c130 values outside the recommended species-specific range produce a warning but still receive a computed volume.

Value

A data.frame identical to the input data but augmented with:

• species-specific coefficients and validity ranges,

• dagnelie_vc22_1: the computed Dagnelie tarif-1 volume (m$^3$ per tree).

Supported species

The following species codes are supported by dagnelie_vc22_1:

• "QUERCUS_SP"

• "QUERCUS_ROBUR"

• "QUERCUS_PETRAEA"

• "QUERCUS_PUBESCENS"

• "QUERCUS_RUBRA"

• "FAGUS_SYLVATICA"

• "ACER_PSEUDOPLATANUS"

• "FRAXINUS_EXCELSIOR"

• "ULMUS_SP"

• "PRUNUS_AVIUM"

• "BETULA_SP"

• "ALNUS_GLUTINOSA"

• "PICEA_ABIES"

• "PSEUDOTSUGA_MENZIESII"

• "LARIX_SP"

• "PINUS_SYLVESTRIS"

• "CRATAEGUS_SP"

• "PRUNUS_SP"

• "CARPINUS_SP"

• "CASTANEA_SATIVA"

• "CORYLUS_AVELLANA"

• "MALUS_SP"

• "PYRUS_SP"

• "SORBUS_ARIA"

• "SAMBUCUS_SP"

• "RHAMNUS_FRANGULA"

• "PRUNUS_CERASUS"

• "ALNUS_INCANA"

• "POPULUSxCANADENSIS"

• "POPULUS_TREMULA"

• "PINUS_NIGRA"

• "PINUS_LARICIO"

• "TAXUS_BACCATA"

• "ACER_PLATANOIDES"

• "ACER_CAMPESTRE"

• "SORBUS_AUCUPARIA"

• "JUNGLANS_SP"

• "TILLIA_SP"

• "PICEA_SITCHENSIS"

• "ABIES_ALBA"

• "TSUGA_CANADENSIS"

• "ABIES_GRANDIS"

• "CUPRESSUS_SP"

• "THUJA_PLICATA"

• "AESCULUS_HIPPOCASTANUM"

• "ROBINIA_PSEUDOACACIA"

• "SALIX_SP"

See Also

dan1 for species-specific coefficients.

Examples

df <- data.frame(
  c130         = c(145, 156, 234, 233),
  species_code = c("PINUS_SYLVESTRIS", "QUERCUS_RUBRA",
                   "QUERCUS_SP", "FAGUS_SYLVATICA")
)
dagnelie_vc22_1(df)

---

Graduated single-entry Dagnelie volume (tarif 1g)

Description

Computes the standing volume $v_{c,22}$ (in cubic metres per tree) using Dagnelie's tarif 1g equations. The volume is calculated from the stem circumference at 1.30 m (c130, in cm), the dominant height (hdom, in m), and the tree species, using species-specific polynomial coefficients stored in dan1g.

Usage

dagnelie_vc22_1g(data, output = NULL)

Arguments

data	A data.frame containing the columns: c130 (stem circumference at 1.30 m, in cm) hdom (dominant height, in m) species_code (character code of the tree species)
output	Optional file path where the resulting data frame should be exported as a CSV. If NULL (default), no file is written. Export is handled by the utility function export_output().

Details

The function:

• checks that the input data frame contains the required columns c130, hdom and species_code,

• validates that all species codes are present in the dan1g table,

• merges the input data with dan1g to retrieve: coeff_a, coeff_b, coeff_c, coeff_d, coeff_e, coeff_f, as well as the species-specific valid ranges min_c130, max_c130, min_hdom, max_hdom,

• issues a warning for trees whose c130 is outside the valid range [min_c130, max_c130],

• issues a warning for trees whose hdom is outside the valid range [min_hdom, max_hdom],

• computes the tarif 1g volume using the species-specific polynomial:

  $v_{c,22} = coeff_a + coeff_b \cdot c130 + coeff_c \cdot c130^2 + coeff_d \cdot c130^3 + coeff_e \cdot hdom + coeff_f \cdot c130^2 \cdot hdom$

Species codes must match those available in the dan1g table. If one or more species are not found, the function issues a warning.

If a tree's c130 or hdom falls outside the species-specific validity ranges [min_c130, max_c130] or [min_hdom, max_hdom], a warning is issued, but the volume is still computed.

Value

A data.frame identical to data, augmented with:

• the joined columns from dan1g (coeff_a, coeff_b, coeff_c, coeff_d, coeff_e, coeff_f, min_c130, max_c130, min_hdom, max_hdom)

• dagnelie_vc22_1g: the computed volume (m$^3$ per tree)

See Also

dan1g for the species-specific coefficients and ranges.

Examples

df <- data.frame(
  c130         = c(145, 156, 234, 233),
  hdom         = c(25, 23, 45, 34),
  species_code = c("PINUS_SYLVESTRIS", "QUERCUS_RUBRA",
                   "QUERCUS_SP", "FAGUS_SYLVATICA")
)
dagnelie_vc22_1g(data = df)

---

Two-entry Dagnelie volume (tarif 2)

Description

Computes the standing volume $v_{c,22}$ (in cubic metres) using Dagnelie's two-entry tarif 2 equations. The volume is calculated from the stem circumference at 1.30 m (c130, in cm), the total height of the tree (htot, in m), and the tree species, using species-specific polynomial coefficients stored in dan2.

Usage

dagnelie_vc22_2(data, output = NULL)

Arguments

data	A data.frame containing at least the columns c130 (stem circumference at 1.30 m, in cm), htot (height of the tree, in m), and species_code (character code of the tree species).
output	Optional file path where the resulting data frame should be exported as a CSV. If NULL (default), no file is written. Export is handled by the utility function export_output() and failures trigger warnings without interrupting execution.

Details

The function:

• checks that the input data frame contains the required columns c130, htot and species_code,

• validates that all species codes are present in the dan2 table,

• merges the input data with dan2 to retrieve: coeff_a, coeff_b, coeff_c, coeff_d, coeff_e, coeff_f, as well as the species-specific valid ranges: min_c130, max_c130, min_htot, max_htot,

• issues a warning for trees whose c130 is outside the valid range [min_c130, max_c130],

• issues a warning for trees whose htot is outside the valid range [min_htot, max_htot],

• computes the tarif 2 volume using the species-specific polynomial:

  $v_{c,22} = coeff_a + coeff_b \cdot c130 + coeff_c \cdot c130^2 + coeff_d \cdot c130^3 + coeff_e \cdot htot + coeff_f \cdot c130^2 \cdot htot$

Species codes must match those available in the dan2 reference table. If one or more species are not found, the function issues a warning.

For trees where c130 or htot is outside the species-specific validity ranges [min_c130, max_c130] and [min_htot, max_htot], warnings are issued, but the volume is still computed.

Value

A data.frame identical to data but augmented with:

• the joined columns from dan2 (coeff_a, coeff_b, coeff_c, coeff_d, coeff_e, coeff_f, min_c130, max_c130, min_htot, max_htot),

• tarif2: the Dagnelie two-entry volume $v_{c,22}$ in m$^3$ per tree.

Supported species

The following species codes are currently supported by dagnelie_vc22_2:

• "QUERCUS_SP"

• "QUERCUS_ROBUR"

• "QUERCUS_PETRAEA"

• "QUERCUS_PUBESCENS"

• "QUERCUS_RUBRA"

• "FAGUS_SYLVATICA"

• "ACER_PSEUDOPLATANUS"

• "FRAXINUS_EXCELSIOR"

• "ULMUS_SP"

• "PRUNUS_AVIUM"

• "BETULA_SP"

• "ALNUS_GLUTINOSA"

• "PICEA_ABIES"

• "PSEUDOTSUGA_MENZIESII"

• "LARIX_SP"

• "PINUS_SYLVESTRIS"

• "CRATAEGUS_SP"

• "PRUNUS_SP"

• "CARPINUS_SP"

• "CASTANEA_SATIVA"

• "CORYLUS_AVELLANA"

• "MALUS_SP"

• "PYRUS_SP"

• "SORBUS_ARIA"

• "SAMBUCUS_SP"

• "RHAMNUS_FRANGULA"

• "PRUNUS_CERASUS"

• "ALNUS_INCANA"

• "POPULUSxCANADENSIS"

• "POPULUS_TREMULA"

• "PINUS_NIGRA"

• "PINUS_LARICIO"

• "TAXUS_BACCATA"

• "ACER_PLATANOIDES"

• "ACER_CAMPESTRE"

• "SORBUS_AUCUPARIA"

• "JUNGLANS_SP"

• "TILLIA_SP"

• "PICEA_SITCHENSIS"

• "ABIES_ALBA"

• "TSUGA_CANADENSIS"

• "ABIES_GRANDIS"

• "CUPRESSUS_SP"

• "THUJA_PLICATA"

• "AESCULUS_HIPPOCASTANUM"

• "ROBINIA_PSEUDOACACIA"

• "SALIX_SP"

See Also

dan2 for the species-specific coefficients and ranges.

Examples

df <- data.frame(
  c130         = c(145, 156, 234, 233),
  htot         = c(25, 23, 45, 34),
  species_code = c("PINUS_SYLVESTRIS", "QUERCUS_RUBRA",
                   "QUERCUS_SP", "FAGUS_SYLVATICA")
)
dagnelie_vc22_2(data = df)

---

Dagnelie coefficients (tarif 1)

Description

Species-specific polynomial coefficients for the Dagnelie single-entry tarif-1 volume equations used by dagnelie_vc22_1.

Usage

data(dan1)

Format

A data frame with columns:

species_code

Tree species code (character)

coeff_a

Coefficient a (numeric)

coeff_b

Coefficient b (numeric)

coeff_c

Coefficient c (numeric)

coeff_d

Coefficient d (numeric)

min_c130

Minimum circumference at 1.30 m (cm)

max_c130

Maximum circumference at 1.30 m (cm)

Source

Internal CSV file data-raw/dan1.csv

---

Dagnelie coefficients (tarif 1g)

Description

Species-specific coefficients for the Dagnelie vc22 model (variant 1g). Loaded from data-raw/dan1g.csv.

Usage

data(dan1g)

Format

A data frame with columns:

species_code

Tree species code (character)

coeff_a

Coefficient a (numeric)

coeff_b

Coefficient b (numeric)

coeff_c

Coefficient c (numeric)

coeff_d

Coefficient d (numeric)

coeff_e

Coefficient e (numeric)

coeff_f

Coefficient f (numeric)

min_c130

Minimum circumference at 1.30m (cm)

max_c130

Maximum circumference at 1.30m (cm)

min_hdom

Minimum dominant height (m)

max_hdom

Maximum dominant height (m)

Source

Internal CSV file data-raw/dan1g.csv

---

Dagnelie coefficients (tarif 2)

Description

Species-specific polynomial coefficients for the Dagnelie two-entry tarif-2 volume equations used by dagnelie_vc22_2.

Usage

data(dan2)

Format

A data frame with columns:

species_code

Tree species code (character)

coeff_a

Coefficient a (numeric)

coeff_b

Coefficient b (numeric)

coeff_c

Coefficient c (numeric)

coeff_d

Coefficient d (numeric)

coeff_e

Coefficient e (numeric)

coeff_f

Coefficient f (numeric)

min_c130

Minimum circumference at 1.30 m (cm)

max_c130

Maximum circumference at 1.30 m (cm)

min_htot

Minimum total height (m)

max_htot

Maximum total height (m)

Source

Internal CSV file data-raw/dan2.csv

---

Dagnelie branch coefficients (tarif "br")

Description

Species-specific polynomial coefficients for the Dagnelie branch volume model (tarif "br"). Loaded from data-raw/danbr.csv.

Usage

data(danbr)

Format

A data frame with columns:

species_code

Tree species code (character)

coeff_a

Coefficient a (numeric)

coeff_b

Coefficient b (numeric)

coeff_c

Coefficient c (numeric)

coeff_d

Coefficient d (numeric)

min_c130

Minimum circumference at 1.30 m (cm)

max_c130

Maximum circumference at 1.30 m (cm)

Source

Internal CSV file data-raw/danbr.csv

---

Wood density table for biomass calculation

Description

Provides species-specific wood density values (t/m3) and species group classification (conifer vs broadleaf) used in CNPF and Vallet biomass estimation methods.

Usage

data(density_table)

Format

A data frame with columns:

species_code

Tree species code (character, uppercase Latin format)

density

Wood density in tonnes of dry matter per cubic meter (numeric)

con_broad

Species group: "conifer" or "broadleaf"

Source

Internal CSV file data-raw/density_table.csv

---

Equations metadata for GCubeR

Description

A reference table compiling metadata about allometric equations used in GCubeR (Vallet, Dagnelie, Algan, Rondeux, CNPF, etc.). This dataset is provided for information purposes only and is not directly used by package functions.

Usage

data(equations_GCubeR)

Format

A data frame with columns:

eq_id

Equation identifier (character)

method

Method family (Vallet, Dagnelie, Algan, Rondeux, CNPF...)

predicted_variable

Predicted variable (volume, biomass, carbon...)

output_unit

Unit of the output (m3, kg, tdm...)

species_id

Numeric species identifier (integer)

species_name_fr

Species name in French (character)

species_code

Species code (uppercase Latin name)

validity_region

Region of validity (text)

validity_range

Range of validity (text)

input_variable

Input variables required (e.g. c130, htot, dbh)

input_unit

Units of input variables (e.g. cm, m)

formula_type

Equation type (e.g. polynomial, exponential)

explicit_formula

Explicit formula as text

coeff_a

Equation coefficient a (numeric)

coeff_b

Equation coefficient b (numeric)

coeff_c

Equation coefficient c (numeric)

coeff_d

Equation coefficient d (numeric)

coeff_e

Equation coefficient e (numeric)

coeff_f

Equation coefficient f (numeric)

remarks

Additional notes

reference_source

Bibliographic source

Source

Internal CSV file data-raw/equations_GCubeR.csv

---

Export data frame to CSV with warnings instead of errors

Description

This function exports a data.frame to a CSV file. If output is NULL, nothing is done. If the path is invalid or the export fails, a warning is issued but the function does not stop, and still returns (invisibly) a logical value indicating success.

Usage

export_output(data, output, verbose = FALSE)

Arguments

data	A data.frame to export.
output	Character string: path to the CSV file. If NULL, nothing is done.
verbose	Logical. If TRUE, prints diagnostic messages. Default: FALSE.

Value

Invisibly returns TRUE if the export succeeded, FALSE otherwise.

Examples

df <- data.frame(
  id = 1:3,
  volume = c(10.5, 12.3, 9.8)
)

export_output(df, file.path(tempdir(), "volumes.csv"))

---

GCubeR main workflow

Description

This function takes a dataframe containing tree measurements (circumference, diameter, height, species code) and enriches it by:

1. Converting circumference at 1.50 m (c150) to circumference at 1.30 m (c130).

2. Adding diameter at breast height (dbh) if missing, or converting back to c130.

3. Applying a suite of allometric equations for volume, biomass, and carbon stock estimation.

Usage

GCubeR(data, output = NULL, volume_col = NULL)

Arguments

data	A data.frame with at least: species_code: tree species identifier (character), c150, c130, or dbh: stem circumference or diameter, optionally htot (total height) and hdom (dominant height).
output	Optional file path where the resulting data frame should be exported as a CSV. If NULL (default), no file is written. Export is handled by the utility function export_output() and failures trigger warnings without interrupting execution.
volume_col	Optional character string naming the column of volume to use for plotting in plot_by_class. If NULL (default), the function will automatically select the first available column among: dagnelie_vc22_1, dagnelie_vc22_1g, dagnelie_vc22_2, dagnelie_br, vallet_vta, vallet_vc22, bouvard_vta, rondeux_vc22, rondeux_vtot, algan_vta, or algan_vc22.

Details

Orchestrates the GCubeR pipeline by sequentially applying allometric conversion and biomass/volume functions to a user-provided dataset.

The following functions are called in order:

1. c150_to_c130

2. add_c130_dbh

3. dagnelie_vc22_1

4. dagnelie_vc22_1g

5. dagnelie_vc22_2

6. dagnelie_br

7. vallet_vta

8. vallet_vc22

9. algan_vta_vc22

10. rondeux_vc22_vtot

11. bouvard_vta

12. biomass_calc

Value

A data.frame identical to the input but augmented with:

• c130 and dbh (ensured to be present),

• outputs from Dagnelie, Vallet, Algan, Rondeux, Bouvard functions,

• biomass and carbon stock estimates.

Examples

data <- data.frame(
  tree_id = 1:3,
  species_code = c("PINUS_SYLVESTRIS", "QUERCUS_RUBRA", "FAGUS_SYLVATICA"),
  c150 = c(145, NA, NA),
  c130 = c(NA, 156, NA),
  dbh  = c(NA, NA, 40),
  htot = c(25, 30, 28),
  hdom = c(NA, 32, NA)
)
GCubeR(data)

---

Summarise and plot standing volume by c130 class and species

Description

This function builds a cross-tabulated volume table by species and c130 classes, adds a TOTAL row per class, optionally exports the table as a CSV, and returns a ggplot object showing the volume distribution by c130 class.

Usage

plot_by_class(
  data,
  volume_col = "dagnelie_vc22_2",
  breaks = seq(30, 230, by = 25),
  small_limit = 60,
  medium_limit = 120,
  output = NULL,
  make_plot = TRUE
)

Arguments

data	A data frame containing at least: c130: stem circumference at 1.30 m (cm), species_code: species identifier, a volume column (defaults to "dagnelie_vc22_2").
volume_col	Name of the column containing tree volume (string). Defaults to "dagnelie_vc22_2".
breaks	Numeric vector defining c130 class boundaries (cm). Default is seq(30, 230, by = 25).
small_limit	Threshold between small and medium wood (cm of c130). A vertical dashed line is drawn at this value in the plot. Default is 60.
medium_limit	Threshold between medium and large wood (cm of c130). A vertical dashed line is drawn at this value in the plot. Default is 120.
output	Optional file path where the cross-tabulated table should be exported as a CSV. If NULL (default), no file is written. Export is handled by the utility function export_output().
make_plot	Logical; if TRUE (default), a ggplot object is created and returned alongside the table.

Details

The table has:

• rows = species (plus a "TOTAL" row),

• columns = c130 classes (e.g. [30,55), [55,80), ...),

• cells = summed volume per species and c130 class.

The plot shows a volume-weighted histogram (or barchart) by c130 class, stacked by species, with a trend line for total volume per class and dashed vertical lines marking small, medium and large wood thresholds.

The c130 classes are built with cut() using breaks as class boundaries and an open-ended last class (using Inf as the upper bound). The resulting factor labels (e.g. "[30,55)") are used as column names in the cross-tabulated table.

For the plot, volume is used as a weight so that bar heights represent total volume per c130 class. A trend line is computed from total volume per class midpoint using the same binning scheme.

Value

A list with two components:

• table: data frame with species as rows and c130 classes as columns, plus a TOTAL row.

• plot: a ggplot2 object (or NULL if make_plot = FALSE).

Examples

set.seed(123)
n <- 150
c130 <- runif(n, 30, 230)
htot <- 0.25 * c130 + rnorm(n, 0, 3)
htot <- pmax(5, pmin(htot, 45))

species_list <- c(
  "PINUS_SYLVESTRIS", "PICEA_ABIES",
  "QUERCUS_ROBUR", "FAGUS_SYLVATICA", "BETULA_SP"
)
species_code <- sample(species_list, n, replace = TRUE)

df <- data.frame(
  c130 = round(c130, 1),
  htot = round(htot, 1),
  species_code = species_code
)

df <- dagnelie_vc22_2(df)
res <- plot_by_class(df, volume_col = "dagnelie_vc22_2")

res$table

print(res$plot)

---

Calculate Total and Commercial Stem Volume (Rondeux, larch)

Description

Computes the total stem volume (rondeux_vtot) and the commercial stem volume at 22 cm (rondeux_vc22) for larch trees according to Rondeux equations, based on the circumference at 1.30 m (c130, in cm) and the total height (htot, in meters).

Usage

rondeux_vc22_vtot(data, na_action = c("error", "omit"), output = NULL)

Arguments

data	A data frame containing tree measurements. Must include: species_code (uppercase character), c130 (circumference at 1.30 m, in cm), htot (total height, in m).
na_action	How to handle missing essential values (c130, htot). "error" (default) stops if missing values are detected. "omit" removes rows with missing essential fields.
output	Optional file path where the resulting data frame should be exported as a CSV. If NULL (default), no file is written. Export is handled by the utility function export_output() and failures trigger warnings without interrupting execution.

Details

The implemented equations are:

$v_{\mathrm{tot}} = a_{\mathrm{vtot}} \cdot c_{130}^2 \cdot h_{\mathrm{tot}}$

where $a_{\mathrm{vtot}} = 0.406780 \times 10^{-5}$.

$v_{c22} = a_{\mathrm{vc22}} + b_{\mathrm{vc22}} \cdot c_{130}^2 \cdot h_{\mathrm{tot}}$

where $a_{\mathrm{vc22}} = -0.008877$ and $b_{\mathrm{vc22}} = 0.412411 \times 10^{-5}$.

Expected units:

• c130: cm

• htot: m

• output volumes: m3

These equations are valid only for larch. Rows with other species are returned with NA volumes and a warning is issued.

Value

A data frame identical to data, with two added columns:

• rondeux_vtot: total stem volume (m3)

• rondeux_vc22: commercial stem volume at 22 cm (m3)

Examples

df <- data.frame(
  species_code = c("LARIX_DECIDUA", "LARIX_DECIDUA", "LARIX_DECIDUA"),
  c130 = c(60, 65, 55),
  htot = c(15, 18, 20)
)

rondeux_vc22_vtot(df)

---

Vallet coefficients for merchantable volume (vc22)

Description

Species-specific polynomial coefficients (a, b, c) used in the Vallet model to compute commercial wood volume (vc22) up to a 7 cm top diameter.

Usage

data(val_vc22)

Format

A data frame with columns:

species_code

Tree species code (character)

coeff_a

Coefficient a (numeric)

coeff_b

Coefficient b (numeric)

coeff_c

Coefficient c (numeric)

Source

Internal CSV file data-raw/vallet_vc22.csv

---

Vallet coefficients for total aboveground volume (VTA)

Description

Species-specific polynomial coefficients (a, b, c, d) used in the Vallet form factor model to compute total aboveground volume (VTA).

Usage

data(val_vta)

Format

A data frame with columns:

species_code

Tree species code (character)

coeff_a

Coefficient a (numeric)

coeff_b

Coefficient b (numeric)

coeff_c

Coefficient c (numeric)

coeff_d

Coefficient d (numeric)

Source

Internal CSV file data-raw/vallet_vta.csv

---

Calculate Commercial Volume (vc22) up to 7cm Diameter at Breast Height (dbh)

Description

Computes the commercial wood volume (vc22, over bark, up to a 7 cm top-diameter) using the Vallet polynomial model, based on dbh (cm) and htot (m).

Usage

vallet_vc22(data, na_action = c("error", "omit"), output = NULL)

Arguments

data	A data frame containing tree measurements. Must include the columns: species_code, dbh (diameter at 1.30m, in cm), and htot (total height, in m).
na_action	How to handle missing input values. "error" (default) stops if core required values are explicitly NA. "omit" removes rows with missing core data.
output	Optional file path where the resulting data frame should be exported as a CSV. If NULL (default), no file is written. Export is handled by the utility function export_output() and failures trigger warnings without interrupting execution.

Details

The model is valid only for trees with a diameter at 1.30m (dbh) greater than or equal to 7 cm.

The polynomial formula used is:

$VC22_{dm^3} = a \cdot \frac{h_{tot}}{dbh} + (b + c \cdot dbh) \cdot \frac{\pi \cdot dbh^2 \cdot h_{tot}}{40}$

Coefficients a, b, c are species-specific and loaded from the vallet_vc22.csv file.

Value

The resulting data frame with the new column vallet_vc22 (Commercial Volume in m3).

Examples

data_test_vc22 <- data.frame(
  species_code = c("PICEA_ABIES", "FAGUS_SYLVATICA", "UNKNOWN_SPECIES", "QUERCUS_ROBUR"),
  dbh = c(19.1, 25.5, 15.9, 6.4), 
  htot = c(25, 18, 20, 22)
)

results_console <- vallet_vc22(data_test_vc22)
print(results_console)

---

Calculate Total Aboveground Volume (VTA) Vallet Method

Description

Computes the total aboveground volume (VTA) for trees based on the circumference at 1.30m (c130) and total height (htot) using the Vallet form factor method.

Usage

vallet_vta(data, na_action = c("error", "omit"), output = NULL)

Arguments

data	A data frame containing tree measurements. Must include the columns: species_code (in uppercase Latin format), c130 (circumference at 1.30m, in cm), and htot (total height, in m).
na_action	How to handle missing input values. "error" (default) stops if core required values are explicitly NA. "omit" removes rows with missing core data. Note: Model constraint violation (c130 < 45 cm) and unknown species are always handled by setting VTA and Form Factor to NA, preserving input values.
output	Optional file path (string). If provided, the resulting data frame will be written to this file using semicolon (;) as a delimiter. NA values are written as empty strings (""). Defaults to NULL.

Details

The model is only valid for trees with a circumference at 1.30m (c130) of at least 45 cm. For non-compliant trees or unknown species, results are set to NA.

The Form Factor (form) is calculated as:

$form = (a + b \cdot c_{130} + c \cdot \frac{\sqrt{c_{130}}}{h_{tot}}) \cdot \left(1 + \frac{d}{c_{130}^2}\right)$

The Total Aboveground Volume (VTA) is then:

$VTA = form \cdot \frac{1}{\pi \cdot 40000} \cdot c_{130}^2 \cdot h_{tot}$

Coefficients a, b, c, d are loaded from the vallet_vta.csv file.

Value

The resulting data frame (same as the printed data) with the new columns and vallet_vta (Total Aboveground Volume in m3)..

Supported species

The Vallet VTA method is currently implemented for the following species (via their species_code):

• "PICEA_ABIES"

• "QUERCUS_ROBUR"

• "FAGUS_SYLVATICA"

• "PINUS_SYLVESTRIS"

• "PINUS_PINASTER"

• "ABIES_ALBA"

• "PSEUDOTSUGA_MENZIESII"

Examples

data_test <- data.frame(
  species_code = c("PICEA_ABIES", "FAGUS_SYLVATICA", "UNKNOWN_SPECIES", "QUERCUS_ROBUR"),
  c130 = c(60, 80, 50, 40), 
  htot = c(25, 18, 20, 22)
)

results_console <- vallet_vta(data_test)

---