diff --git a/NAMESPACE b/NAMESPACE
index 2e1ebdc..1233ea3 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -21,6 +21,8 @@ export(silv_dominant_height)
export(silv_lorey_height)
export(silv_ntrees_ha)
export(silv_predict_biomass)
+export(silv_predict_biomass_auto)
+export(silv_predict_biomass_components)
export(silv_predict_carbon)
export(silv_predict_carbon_auto)
export(silv_predict_biomass_auto)
diff --git a/R/predict-biomass.R b/R/predict-biomass.R
index b14b2fe..e971aff 100644
--- a/R/predict-biomass.R
+++ b/R/predict-biomass.R
@@ -37,7 +37,7 @@ ModelBiomass <- S7::new_class(
#' \emph{Evergreen broadleaves}).
#' @param quiet A logical value. If \code{TRUE}, suppresses any informational messages.
#'
-#' @return A numeric vector
+#' @return A numeric vector with predicted tree biomass (kg).
#'
#' @export
#'
@@ -66,12 +66,48 @@ ModelBiomass <- S7::new_class(
#' [eq_biomass_menendez_2022()], [eq_biomass_cudjoe_2024()]
#'
#' @examples
-#' # Calculate biomass for a single tree
-#' silv_predict_biomass(
-#' diameter = 45,
-#' height = 22,
-#' model = eq_biomass_ruiz_peinado_2011("Pinus pinaster")
+#' # 1. Vector-based calculation: predict stem/tree biomass for Pinus pinaster
+#' model <- eq_biomass_ruiz_peinado_2011("Pinus pinaster")
+#' predicted_biomass <- silv_predict_biomass(
+#' diameter = c(20, 25, 30),
+#' height = c(15, 17, 18),
+#' model = model
#' )
+#' print(predicted_biomass)
+#'
+#' # 2. Dataset-based tutorial: apply to a forest inventory data frame
+#' inventory <- data.frame(
+#' tree_id = 1:3,
+#' species = c("Pinus pinaster", "Pinus pinaster", "Pinus pinaster"),
+#' dbh_cm = c(18.5, 22.1, 29.4),
+#' height_m = c(14.0, 16.5, 19.0)
+#' )
+#'
+#' # Apply prediction and append a new column to the dataset
+#' inventory$biomass_kg <- silv_predict_biomass(
+#' diameter = inventory$dbh_cm,
+#' height = inventory$height_m,
+#' model = model
+#' )
+#' print(inventory)
+#'
+#' # 3. Young plantation example (Menendez 2022 model) using rcd and bp
+#' # Menendez 2022 equations use root collar diameter (rcd) and/or biomass packing (bp)
+#' model_menendez <- eq_biomass_menendez_2022("Pinus pinaster")
+#' predicted_young_pinaster <- silv_predict_biomass(
+#' rcd = c(5.2, 7.1, 9.4), # Root collar diameter in cm
+#' height = c(2.1, 3.2, 4.5), # Height in m
+#' model = model_menendez
+#' )
+#' print(predicted_young_pinaster)
+#'
+#' # For Pinus halepensis, Menendez 2022 requires biomass packing (bp)
+#' model_halepensis <- eq_biomass_menendez_2022("Pinus halepensis")
+#' predicted_young_halepensis <- silv_predict_biomass(
+#' bp = c(0.005, 0.012), # Biomass packing in m3
+#' model = model_halepensis
+#' )
+#' print(predicted_young_halepensis)
silv_predict_biomass <- function(
diameter = NULL,
height = NULL,
@@ -82,12 +118,24 @@ silv_predict_biomass <- function(
quiet = FALSE) {
# 0. Handle errors and setup
+ ## 0.0. Determine vector length based on inputs
+ n <- if (!is.null(diameter)) {
+ length(diameter)
+ } else if (!is.null(rcd)) {
+ length(rcd)
+ } else if (!is.null(bp)) {
+ length(bp)
+ } else {
+ 0
+ }
+
+ if (is.null(diameter)) diameter <- rep(NA_real_, n)
## 0.1. Default rcd to diameter if not provided
if (is.null(rcd)) rcd <- diameter
## 0.2. Ensure ntrees = 1 when ntrees = NULL
- if (is.null(ntrees)) ntrees <- rep(1, length(diameter))
+ if (is.null(ntrees)) ntrees <- rep(1, n)
## 0.3. Default height to NA_real_ if NULL
- if (is.null(height)) height <- rep(NA_real_, length(diameter))
+ if (is.null(height)) height <- rep(NA_real_, n)
# 1. Define a helper function to calculate biomass for a single tree
calc_biomass <- function(d, h, n, sp, rcd_val, bp_val) {
@@ -179,7 +227,7 @@ silv_predict_biomass <- function(
#' @param return_rmse A logical value. If TRUE, the function returns the root
#' mean squared error (RMSE) of the selected model instead of the biomass value.
#'
-#' @return A S7 list of parameters
+#' @return A ModelBiomass object containing the configured model parameters and expressions.
#'
#' @export
#'
@@ -291,7 +339,7 @@ eq_biomass_ruiz_peinado_2011 <- function(species, component = "stem", return_rms
#' @param return_rmse A logical value. If TRUE, the function returns the root
#' mean squared error (RMSE) of the selected model instead of the biomass value.
#'
-#' @return A S7 list of parameters
+#' @return A ModelBiomass object containing the configured model parameters and expressions.
#'
#' @export
#'
@@ -411,7 +459,7 @@ eq_biomass_ruiz_peinado_2012 <- function(species, component = "stem", return_rms
#' @param return_rmse A logical value. If TRUE, the function returns the root
#' mean squared error (RMSE) of the selected model instead of the biomass value.
#'
-#' @return A S7 list of parameters
+#' @return A ModelBiomass object containing the configured model parameters and expressions.
#'
#' @export
#'
@@ -534,7 +582,7 @@ eq_biomass_dieguez_aranda_2009 <- function(species, component = "stem", return_r
#' @param return_r2 A logical value. If TRUE, the function returns the root
#' mean squared error (RMSE) of the selected model instead of the biomass value.
#'
-#' @return A S7 list of parameters
+#' @return A ModelBiomass object containing the configured model parameters and expressions.
#'
#' @export
#'
@@ -667,7 +715,7 @@ eq_biomass_montero_2005 <- function(species, component = "stem", return_r2 = FAL
#' @param return_rmse A logical value. If TRUE, the function returns the root
#' mean squared error (RMSE) of the selected model instead of the biomass value.
#'
-#' @return A S7 list of parameters
+#' @return A ModelBiomass object containing the configured model parameters and expressions.
#'
#' @export
#'
@@ -775,7 +823,7 @@ eq_biomass_manrique_2017 <- function(species, component = "AGB", return_r2 = FAL
#' @param return_rmse A logical value. If TRUE, the function returns the root
#' mean squared error (RMSE) of the selected model instead of the biomass value.
#'
-#' @return A S7 list of parameters
+#' @return A ModelBiomass object containing the configured model parameters and expressions.
#'
#' @export
#'
@@ -873,7 +921,7 @@ eq_biomass_menendez_2022 <- function(species, return_r2 = FALSE, return_rmse = F
#' @param return_rmse A logical value. If TRUE, the function returns the root
#' mean squared error (RMSE) of the selected model instead of the biomass value.
#'
-#' @return A S7 list of parameters
+#' @return A ModelBiomass object containing the configured model parameters and expressions.
#'
#' @export
#'
@@ -998,14 +1046,34 @@ eq_biomass_cudjoe_2024 <- function(species, component = "AGB", return_rmse = FAL
#' @export
#'
#' @examples
-#' # Predict biomass using default priorities
+#' # 1. Vector-based calculation: automatic model selection for mixed species
#' species_vec <- c("Pinus pinaster", "Quercus petraea")
#' d_vec <- c(20, 25)
#' h_vec <- c(12, 14)
-#' silv_predict_biomass_auto(species_vec, d_vec, h_vec)
+#' auto_results <- silv_predict_biomass_auto(species_vec, d_vec, h_vec)
+#' print(auto_results)
#'
-#' # Fallback to Montero 2005 when height is missing
-#' silv_predict_biomass_auto(species_vec, d_vec, height = NULL)
+#' # 2. Vector-based calculation: fallback to Montero 2005 when height is missing
+#' fallback_results <- silv_predict_biomass_auto(species_vec, d_vec, height = NULL)
+#' print(fallback_results)
+#'
+#' # 3. Dataset-based tutorial: apply to a mixed-species forest inventory data frame
+#' inventory <- data.frame(
+#' tree_id = 1:3,
+#' species = c("Pinus pinaster", "Quercus petraea", "Pinus sylvestris"),
+#' dbh_cm = c(22.5, 18.0, 31.2),
+#' height_m = c(15.0, 11.5, 18.0)
+#' )
+#'
+#' # Run auto-selection and bind the results directly
+#' biomass_data <- silv_predict_biomass_auto(
+#' species = inventory$species,
+#' diameter = inventory$dbh_cm,
+#' height = inventory$height_m
+#' )
+#'
+#' inventory_with_biomass <- cbind(inventory, biomass_data)
+#' print(inventory_with_biomass)
silv_predict_biomass_auto <- function(
species,
diameter,
@@ -1167,20 +1235,44 @@ silv_predict_biomass_auto <- function(
#' @param bp An optional numeric vector of biomass packing values (in m\ifelse{html}{\out{3}}{$^3$}).
#' @param quiet A logical value. If \code{TRUE}, suppresses any informational messages.
#'
-#' @return A \code{data.frame} with the columns \code{species}, \code{diameter},
-#' \code{height} (if provided), and one additional column for each individual biomass
-#' component available for the selected species and model.
+#' @return A \code{data.frame} with the columns \code{species}, \code{diameter} (cm),
+#' \code{height} (m, if provided), and one additional numeric column (in kg) for each
+#' individual biomass component available for the selected species and model.
#'
#' @export
#'
#' @examples
-#' # Predict all components using Ruiz-Peinado 2011
-#' silv_predict_biomass_components(
-#' species = "Pinus pinaster",
-#' diameter = 25,
-#' height = 15,
+#' # 1. Vector-based calculation: predict all components for Pinus pinaster
+#' comp_results <- silv_predict_biomass_components(
+#' species = c("Pinus pinaster", "Pinus pinaster"),
+#' diameter = c(20, 25),
+#' height = c(12, 15),
#' model_fn = eq_biomass_ruiz_peinado_2011
#' )
+#' print(comp_results)
+#'
+#' # 2. Dataset-based tutorial: apply to a forest inventory data frame
+#' inventory <- data.frame(
+#' tree_id = 1:3,
+#' species = c("Pinus pinaster", "Pinus pinaster", "Pinus pinaster"),
+#' dbh_cm = c(18.5, 22.1, 29.4),
+#' height_m = c(14.0, 16.5, 19.0)
+#' )
+#'
+#' # Predict components for the entire dataset
+#' comp_df <- silv_predict_biomass_components(
+#' species = inventory$species,
+#' diameter = inventory$dbh_cm,
+#' height = inventory$height_m,
+#' model_fn = "ruiz-peinado-2011"
+#' )
+#'
+#' # Combine and display results (excluding repeated identifier columns)
+#' inventory_with_components <- cbind(
+#' inventory,
+#' comp_df[, -(1:3)]
+#' )
+#' print(inventory_with_components)
silv_predict_biomass_components <- function(
species,
diameter,
diff --git a/R/predict-carbon.R b/R/predict-carbon.R
index c1336b6..4f065dc 100644
--- a/R/predict-carbon.R
+++ b/R/predict-carbon.R
@@ -29,6 +29,46 @@
#' - `carbon_model`: The model and species level used (e.g., `"montero-2005"` or `"montero-2005 (genus fallback)"`).
#'
#' @name predict_carbon
+#'
+#' @examples
+#' # 1. Vector-based calculation: calculate stem carbon for Pinus pinaster
+#' biomass_vector <- c(120.5, 230.1, 85.4)
+#' species_vector <- c("Pinus pinaster", "Pinus pinaster", "Pinus pinaster")
+#'
+#' carbon_vector <- silv_predict_carbon(
+#' biomass = biomass_vector,
+#' species = species_vector,
+#' component = "stem",
+#' model = "montero-2005"
+#' )
+#' print(carbon_vector)
+#'
+#' # 2. Vector-based calculation with row-wise auto-selection & genus fallback
+#' carbon_df <- silv_predict_carbon_auto(
+#' biomass = c(120.5, 95.0),
+#' species = c("Pinus pinaster", "Pinus radiata"), # Pinus radiata triggers genus fallback
+#' component = c("stem", "roots")
+#' )
+#' print(carbon_df)
+#'
+#' # 3. Dataset-based tutorial: apply to a forest inventory data frame
+#' inventory <- data.frame(
+#' tree_id = 1:3,
+#' species = c("Pinus pinaster", "Pinus sylvestris", "Quercus robur"),
+#' biomass_kg = c(150.0, 180.5, 220.0),
+#' component = c("stem", "roots", "stem")
+#' )
+#'
+#' # Apply row-wise auto-selection to the entire dataset
+#' carbon_results <- silv_predict_carbon_auto(
+#' biomass = inventory$biomass_kg,
+#' species = inventory$species,
+#' component = inventory$component
+#' )
+#'
+#' # Combine and display results
+#' inventory_with_carbon <- cbind(inventory, carbon_results)
+#' print(inventory_with_carbon)
NULL
#' @rdname predict_carbon
diff --git a/R/predict-height.R b/R/predict-height.R
index cb5dc41..4e07a00 100644
--- a/R/predict-height.R
+++ b/R/predict-height.R
@@ -15,15 +15,14 @@ ModelHD <- S7::new_class(
-#' Estimates tree height from DBH
+#' Estimates tree height (m) from DBH (cm)
#'
-#' Estimates total tree height using height-diameter (h-d) equations. Currently, only models developed
+#' Estimates total tree height (m) using height-diameter (h-d) equations. Currently, only models developed
#' for Spain are available.
#'
-#' @param diameter Numeric vector with diameters in cm
-#' @param model A function. A function with the structure \code{eq_hd_*()} with
-#' additional arguments depending on the specific model. Currently only [eq_hd_vazquez_veloso_2025()]
-#' is available.
+#' @param diameter Numeric vector with diameters in cm (DBH).
+#' @param model A ModelHD object. An object configured via the \code{eq_hd_*()} family of functions.
+#' Defaults to \code{eq_hd_vazquez_veloso_2025("All the species")}.
#' @param quiet A logical value. If TRUE, suppresses any informational messages.
#'
#' @details
@@ -37,13 +36,37 @@ ModelHD <- S7::new_class(
#'
#' @seealso [eq_hd_vazquez_veloso_2025()]
#'
-#' @return A numeric vector with predicted heights
+#' @return A numeric vector with predicted heights (m).
#' @export
#'
#' @examples
-#' 1 + 1 #TODO
+#' # 1. Predict height using the default model (Vázquez-Veloso 2025 generic model)
+#' predicted_heights_default <- silv_predict_height(diameter = c(20, 25, 30))
+#' print(predicted_heights_default)
+#'
+#' # 2. Load the S7 ModelHD object for Pinus pinaster
+#' model <- eq_hd_vazquez_veloso_2025("Pinus pinaster")
+#'
+#' # 3. Vector-based calculation: predict tree heights from diameters
+#' diameters <- c(20, 25, 30)
+#' predicted_heights <- silv_predict_height(diameter = diameters, model = model)
+#' print(predicted_heights)
+#'
+#' # 4. Dataset-based tutorial: apply to a forest inventory data frame
+#' inventory <- data.frame(
+#' tree_id = 1:3,
+#' species = c("Pinus pinaster", "Pinus pinaster", "Pinus pinaster"),
+#' dbh_cm = c(18.5, 22.1, 29.4)
+#' )
+#'
+#' # Apply prediction and append a new column to the dataset
+#' inventory$height_m <- silv_predict_height(
+#' diameter = inventory$dbh_cm,
+#' model = model
+#' )
+#' print(inventory)
silv_predict_height <- function(diameter,
- model,
+ model = eq_hd_vazquez_veloso_2025("All the species"),
quiet = FALSE) {
# 0. Handle errors
@@ -76,7 +99,7 @@ silv_predict_height <- function(diameter,
-#' Estimates tree height from DBH
+#' Height-diameter equations from Vázquez-Veloso et al. (2025)
#'
#' This function is intended to be used in [silv_predict_height()]. It implements the h-d equations
#' developed in Vázquez-Veloso et al. (2025). These equations have been developed using the Spanish
@@ -110,7 +133,7 @@ silv_predict_height <- function(diameter,
#'
#' @seealso [silv_predict_height()]
#'
-#' @return A numeric vector with predicted height
+#' @return A ModelHD object containing the configured model parameters and metadata.
#' @export
#'
#' @examples
diff --git a/R/predict-snfi-volume.R b/R/predict-snfi-volume.R
index 5bb3638..385441b 100644
--- a/R/predict-snfi-volume.R
+++ b/R/predict-snfi-volume.R
@@ -255,23 +255,46 @@
#' @export
#'
#' @examples
-#' # Single tree: Pinus radiata in Alava (province 1), code 28
-#' silv_predict_snfi_volume(
+#' # 1. Vector-based calculation: single tree (Pinus radiata in Alava, province 1, code 28)
+#' single_tree <- silv_predict_snfi_volume(
#' province = 1,
#' species = 28,
#' dbh = 20,
#' h = 15,
#' dnm = 23
#' )
+#' print(single_tree)
#'
-#' # Mixed inputs: province and species by name
-#' silv_predict_snfi_volume(
-#' province = c(1, 39),
+#' # 2. Vector-based calculation: multiple trees with province and species by name
+#' multi_trees <- silv_predict_snfi_volume(
+#' province = c("Araba/Álava", "Cantabria"),
#' species = c("Pinus radiata", "Pinus radiata"),
#' dbh = c(20, 25),
#' h = c(15, 18),
#' dnm = c(23, 26)
#' )
+#' print(multi_trees)
+#'
+#' # 3. Dataset-based tutorial: apply to a forest inventory data frame
+#' inventory <- data.frame(
+#' tree_id = 1:3,
+#' province = c("Cantabria", "Cantabria", "Araba/Álava"),
+#' species = c("Pinus radiata", "Pinus radiata", "Pinus sylvestris"),
+#' dbh_cm = c(20.5, 28.0, 18.2),
+#' height_m = c(15.2, 18.5, 12.0)
+#' )
+#'
+#' # Apply the SNFI volume estimation functions row-wise across the dataset
+#' volume_results <- silv_predict_snfi_volume(
+#' province = inventory$province,
+#' species = inventory$species,
+#' dbh = inventory$dbh_cm,
+#' h = inventory$height_m
+#' )
+#'
+#' # Combine and display results
+#' inventory_with_volume <- cbind(inventory, volume_results)
+#' print(inventory_with_volume)
silv_predict_snfi_volume <- function(
province,
species,
diff --git a/R/sample-size.R b/R/sample-size.R
index e7f7b60..260153d 100644
--- a/R/sample-size.R
+++ b/R/sample-size.R
@@ -538,16 +538,20 @@ silv_sample_size_simple <- function(
#'
#' @param x Object to plot.
#' @param ... Other arguments passed to methods.
+#' @param min_error A numeric value specifying the minimum relative error to consider (default is 0.01).
+#' @param max_error A numeric value specifying the maximum relative error to consider (default is 0.5).
#'
#' @return Usually called for side-effects (producing a plot).
#' @export
-plot <- S7::new_generic("plot", "x")
+plot <- S7::new_generic("plot", "x", function(x, ..., min_error = .01, max_error = .5) {
+ S7::S7_dispatch()
+})
-#' @describeIn plot Plot a `SimpleSampleSize` object showing how sample size
-#' varies with the maximum allowed relative error.
+#' @rdname plot
+#'
#' @param min_error A numeric value specifying the minimum relative error to consider (default is 0.01).
#' @param max_error A numeric value specifying the maximum relative error to consider (default is 0.5).
#'
diff --git a/_pkgdown.yml b/_pkgdown.yml
index d75a5ff..2b7b908 100644
--- a/_pkgdown.yml
+++ b/_pkgdown.yml
@@ -23,6 +23,8 @@ reference:
desc: Functions for estimating forest variables from models or equations
contents:
- silv_predict_biomass
+ - silv_predict_biomass_auto
+ - silv_predict_biomass_components
- silv_predict_carbon
- silv_predict_carbon_auto
- silv_predict_biomass_auto
@@ -84,7 +86,6 @@ reference:
- silv_sample_size_simple
- silv_sample_size_stratified
- silv_sample_size
- - plot_SimpleSampleSize
- title: "Treatments"
desc: Functions for forest treatments
diff --git a/man/SimpleSampleSize.Rd b/man/SimpleSampleSize.Rd
deleted file mode 100644
index 271085f..0000000
--- a/man/SimpleSampleSize.Rd
+++ /dev/null
@@ -1,18 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/sample-size.R
-\name{plot_SimpleSampleSize}
-\alias{plot_SimpleSampleSize}
-\title{Plot Sample Size vs Error}
-\arguments{
-\item{x}{An object of class \code{SimpleSampleSize} containing sampling options and results.}
-
-\item{min_error}{A numeric value specifying the minimum relative error to consider (default is 0.01).}
-
-\item{max_error}{A numeric value specifying the maximum relative error to consider (default is 0.5).}
-}
-\value{
-A \code{ggplot} object representing the relationship between error and sample size.
-}
-\description{
-This method generates a plot showing how the required sample size varies with the maximum allowed relative error.
-}
diff --git a/man/eq_biomass_cudjoe_2024.Rd b/man/eq_biomass_cudjoe_2024.Rd
index d85c8c3..00431fa 100644
--- a/man/eq_biomass_cudjoe_2024.Rd
+++ b/man/eq_biomass_cudjoe_2024.Rd
@@ -18,7 +18,7 @@ calculation (e.g., "stem", "branches"). See Details.}
mean squared error (RMSE) of the selected model instead of the biomass value.}
}
\value{
-A S7 list of parameters
+A ModelBiomass object containing the configured model parameters and expressions.
}
\description{
Allometric equations adjusted for \emph{Quercus petraea}, and \emph{Pinus sylvestris}
diff --git a/man/eq_biomass_dieguez_aranda_2009.Rd b/man/eq_biomass_dieguez_aranda_2009.Rd
index 1768b66..a919e77 100644
--- a/man/eq_biomass_dieguez_aranda_2009.Rd
+++ b/man/eq_biomass_dieguez_aranda_2009.Rd
@@ -26,7 +26,7 @@ mean squared error (RMSE) of the selected model instead of the biomass value.}
mean squared error (RMSE) of the selected model instead of the biomass value.}
}
\value{
-A S7 list of parameters
+A ModelBiomass object containing the configured model parameters and expressions.
}
\description{
Allometric equations adjusted for Galician (Spain) species
diff --git a/man/eq_biomass_manrique_2017.Rd b/man/eq_biomass_manrique_2017.Rd
index a254960..4a06130 100644
--- a/man/eq_biomass_manrique_2017.Rd
+++ b/man/eq_biomass_manrique_2017.Rd
@@ -26,7 +26,7 @@ mean squared error (RMSE) of the selected model instead of the biomass value.}
mean squared error (RMSE) of the selected model instead of the biomass value.}
}
\value{
-A S7 list of parameters
+A ModelBiomass object containing the configured model parameters and expressions.
}
\description{
Allometric equations adjusted for \emph{Quercus petraea} and \emph{Quercus pyrenaica}
diff --git a/man/eq_biomass_menendez_2022.Rd b/man/eq_biomass_menendez_2022.Rd
index 3f5592a..03dccfb 100644
--- a/man/eq_biomass_menendez_2022.Rd
+++ b/man/eq_biomass_menendez_2022.Rd
@@ -18,7 +18,7 @@ mean squared error (RMSE) of the selected model instead of the biomass value.}
mean squared error (RMSE) of the selected model instead of the biomass value.}
}
\value{
-A S7 list of parameters
+A ModelBiomass object containing the configured model parameters and expressions.
}
\description{
Allometric equations for young (<30) plantations of 18 Spanish species including
diff --git a/man/eq_biomass_montero_2005.Rd b/man/eq_biomass_montero_2005.Rd
index 8e455b8..7642668 100644
--- a/man/eq_biomass_montero_2005.Rd
+++ b/man/eq_biomass_montero_2005.Rd
@@ -18,7 +18,7 @@ calculation (e.g., "tree", "stem", "branches"). See Details.}
mean squared error (RMSE) of the selected model instead of the biomass value.}
}
\value{
-A S7 list of parameters
+A ModelBiomass object containing the configured model parameters and expressions.
}
\description{
Allometric equations adjusted for Spanish species
diff --git a/man/eq_biomass_ruiz_peinado_2011.Rd b/man/eq_biomass_ruiz_peinado_2011.Rd
index 94e0023..0b4702c 100644
--- a/man/eq_biomass_ruiz_peinado_2011.Rd
+++ b/man/eq_biomass_ruiz_peinado_2011.Rd
@@ -18,7 +18,7 @@ calculation (e.g., "tree", "stem", "branches"). See Details.}
mean squared error (RMSE) of the selected model instead of the biomass value.}
}
\value{
-A S7 list of parameters
+A ModelBiomass object containing the configured model parameters and expressions.
}
\description{
Allometric equations adjusted for Spanish softwood species
diff --git a/man/eq_biomass_ruiz_peinado_2012.Rd b/man/eq_biomass_ruiz_peinado_2012.Rd
index fcf9509..5768ed4 100644
--- a/man/eq_biomass_ruiz_peinado_2012.Rd
+++ b/man/eq_biomass_ruiz_peinado_2012.Rd
@@ -18,7 +18,7 @@ calculation (e.g., "tree", "stem", "branches"). See Details.}
mean squared error (RMSE) of the selected model instead of the biomass value.}
}
\value{
-A S7 list of parameters
+A ModelBiomass object containing the configured model parameters and expressions.
}
\description{
Allometric equations adjusted for Spanish hardwood species
diff --git a/man/eq_hd_vazquez_veloso_2025.Rd b/man/eq_hd_vazquez_veloso_2025.Rd
index 66c7256..53d63e7 100644
--- a/man/eq_hd_vazquez_veloso_2025.Rd
+++ b/man/eq_hd_vazquez_veloso_2025.Rd
@@ -2,7 +2,7 @@
% Please edit documentation in R/predict-height.R
\name{eq_hd_vazquez_veloso_2025}
\alias{eq_hd_vazquez_veloso_2025}
-\title{Estimates tree height from DBH}
+\title{Height-diameter equations from Vázquez-Veloso et al. (2025)}
\usage{
eq_hd_vazquez_veloso_2025(
species,
@@ -33,7 +33,7 @@ greater than 15\% of the total. It does not matter which species is accompanying
If not specified, it takes the value \code{pure}, which is the most common condition in Spain.}
}
\value{
-A numeric vector with predicted height
+A ModelHD object containing the configured model parameters and metadata.
}
\description{
This function is intended to be used in \code{\link[=silv_predict_height]{silv_predict_height()}}. It implements the h-d equations
diff --git a/man/plot.Rd b/man/plot.Rd
index 4d6d2ae..caa27e1 100644
--- a/man/plot.Rd
+++ b/man/plot.Rd
@@ -2,14 +2,22 @@
% Please edit documentation in R/sample-size.R
\name{plot}
\alias{plot}
+\alias{plot,silviculture::SampleSize-method}
\title{Plot an object}
\usage{
-plot(x, ...)
+plot(x, ..., min_error = 0.01, max_error = 0.5)
+
+## S7 method for class
+plot(x, ..., min_error = 0.01, max_error = 0.5)
}
\arguments{
\item{x}{Object to plot.}
\item{...}{Other arguments passed to methods.}
+
+\item{min_error}{A numeric value specifying the minimum relative error to consider (default is 0.01).}
+
+\item{max_error}{A numeric value specifying the maximum relative error to consider (default is 0.5).}
}
\value{
Usually called for side-effects (producing a plot).
diff --git a/man/predict_carbon.Rd b/man/predict_carbon.Rd
index 6c5a8ac..ee5ed16 100644
--- a/man/predict_carbon.Rd
+++ b/man/predict_carbon.Rd
@@ -58,3 +58,43 @@ from the package's internal \code{carbon_models} database.
the best available carbon model for each row based on a provided priority list.
If the exact species is not found, it attempts a genus-level fallback (e.g., "Pinus spp.").
}
+\examples{
+# 1. Vector-based calculation: calculate stem carbon for Pinus pinaster
+biomass_vector <- c(120.5, 230.1, 85.4)
+species_vector <- c("Pinus pinaster", "Pinus pinaster", "Pinus pinaster")
+
+carbon_vector <- silv_predict_carbon(
+ biomass = biomass_vector,
+ species = species_vector,
+ component = "stem",
+ model = "montero-2005"
+)
+print(carbon_vector)
+
+# 2. Vector-based calculation with row-wise auto-selection & genus fallback
+carbon_df <- silv_predict_carbon_auto(
+ biomass = c(120.5, 95.0),
+ species = c("Pinus pinaster", "Pinus radiata"), # Pinus radiata triggers genus fallback
+ component = c("stem", "roots")
+)
+print(carbon_df)
+
+# 3. Dataset-based tutorial: apply to a forest inventory data frame
+inventory <- data.frame(
+ tree_id = 1:3,
+ species = c("Pinus pinaster", "Pinus sylvestris", "Quercus robur"),
+ biomass_kg = c(150.0, 180.5, 220.0),
+ component = c("stem", "roots", "stem")
+)
+
+# Apply row-wise auto-selection to the entire dataset
+carbon_results <- silv_predict_carbon_auto(
+ biomass = inventory$biomass_kg,
+ species = inventory$species,
+ component = inventory$component
+)
+
+# Combine and display results
+inventory_with_carbon <- cbind(inventory, carbon_results)
+print(inventory_with_carbon)
+}
diff --git a/man/silv_predict_biomass.Rd b/man/silv_predict_biomass.Rd
index 090592b..cd1e9d0 100644
--- a/man/silv_predict_biomass.Rd
+++ b/man/silv_predict_biomass.Rd
@@ -37,7 +37,7 @@ for a subset of species in \code{\link{eq_biomass_menendez_2022}} (e.g.
\item{quiet}{A logical value. If \code{TRUE}, suppresses any informational messages.}
}
\value{
-A numeric vector
+A numeric vector with predicted tree biomass (kg).
}
\description{
Computes the biomass of a tree species using species-specific allometric
@@ -65,12 +65,48 @@ in \link{biomass_models}.
If you would like to suggest additional models, please open a new issue on GitHub.
}
\examples{
-# Calculate biomass for a single tree
-silv_predict_biomass(
- diameter = 45,
- height = 22,
- model = eq_biomass_ruiz_peinado_2011("Pinus pinaster")
+# 1. Vector-based calculation: predict stem/tree biomass for Pinus pinaster
+model <- eq_biomass_ruiz_peinado_2011("Pinus pinaster")
+predicted_biomass <- silv_predict_biomass(
+ diameter = c(20, 25, 30),
+ height = c(15, 17, 18),
+ model = model
+)
+print(predicted_biomass)
+
+# 2. Dataset-based tutorial: apply to a forest inventory data frame
+inventory <- data.frame(
+ tree_id = 1:3,
+ species = c("Pinus pinaster", "Pinus pinaster", "Pinus pinaster"),
+ dbh_cm = c(18.5, 22.1, 29.4),
+ height_m = c(14.0, 16.5, 19.0)
+)
+
+# Apply prediction and append a new column to the dataset
+inventory$biomass_kg <- silv_predict_biomass(
+ diameter = inventory$dbh_cm,
+ height = inventory$height_m,
+ model = model
+)
+print(inventory)
+
+# 3. Young plantation example (Menendez 2022 model) using rcd and bp
+# Menendez 2022 equations use root collar diameter (rcd) and/or biomass packing (bp)
+model_menendez <- eq_biomass_menendez_2022("Pinus pinaster")
+predicted_young_pinaster <- silv_predict_biomass(
+ rcd = c(5.2, 7.1, 9.4), # Root collar diameter in cm
+ height = c(2.1, 3.2, 4.5), # Height in m
+ model = model_menendez
+)
+print(predicted_young_pinaster)
+
+# For Pinus halepensis, Menendez 2022 requires biomass packing (bp)
+model_halepensis <- eq_biomass_menendez_2022("Pinus halepensis")
+predicted_young_halepensis <- silv_predict_biomass(
+ bp = c(0.005, 0.012), # Biomass packing in m3
+ model = model_halepensis
)
+print(predicted_young_halepensis)
}
\seealso{
\link{biomass_models}, \code{\link[=eq_biomass_montero_2005]{eq_biomass_montero_2005()}}, \code{\link[=eq_biomass_dieguez_aranda_2009]{eq_biomass_dieguez_aranda_2009()}},
diff --git a/man/silv_predict_biomass_auto.Rd b/man/silv_predict_biomass_auto.Rd
index 6313500..00c1faf 100644
--- a/man/silv_predict_biomass_auto.Rd
+++ b/man/silv_predict_biomass_auto.Rd
@@ -55,12 +55,32 @@ If tree height is not provided, is NA, or is 0, the function automatically
falls back to the \code{\link{eq_biomass_montero_2005}} model.
}
\examples{
-# Predict biomass using default priorities
+# 1. Vector-based calculation: automatic model selection for mixed species
species_vec <- c("Pinus pinaster", "Quercus petraea")
d_vec <- c(20, 25)
h_vec <- c(12, 14)
-silv_predict_biomass_auto(species_vec, d_vec, h_vec)
+auto_results <- silv_predict_biomass_auto(species_vec, d_vec, h_vec)
+print(auto_results)
-# Fallback to Montero 2005 when height is missing
-silv_predict_biomass_auto(species_vec, d_vec, height = NULL)
+# 2. Vector-based calculation: fallback to Montero 2005 when height is missing
+fallback_results <- silv_predict_biomass_auto(species_vec, d_vec, height = NULL)
+print(fallback_results)
+
+# 3. Dataset-based tutorial: apply to a mixed-species forest inventory data frame
+inventory <- data.frame(
+ tree_id = 1:3,
+ species = c("Pinus pinaster", "Quercus petraea", "Pinus sylvestris"),
+ dbh_cm = c(22.5, 18.0, 31.2),
+ height_m = c(15.0, 11.5, 18.0)
+)
+
+# Run auto-selection and bind the results directly
+biomass_data <- silv_predict_biomass_auto(
+ species = inventory$species,
+ diameter = inventory$dbh_cm,
+ height = inventory$height_m
+)
+
+inventory_with_biomass <- cbind(inventory, biomass_data)
+print(inventory_with_biomass)
}
diff --git a/man/silv_predict_biomass_components.Rd b/man/silv_predict_biomass_components.Rd
index 8b07915..daeb325 100644
--- a/man/silv_predict_biomass_components.Rd
+++ b/man/silv_predict_biomass_components.Rd
@@ -35,20 +35,44 @@ each class. Defaults to \code{NULL}.}
\item{quiet}{A logical value. If \code{TRUE}, suppresses any informational messages.}
}
\value{
-A \code{data.frame} with the columns \code{species}, \code{diameter},
-\code{height} (if provided), and one additional column for each individual biomass
-component available for the selected species and model.
+A \code{data.frame} with the columns \code{species}, \code{diameter} (cm),
+\code{height} (m, if provided), and one additional numeric column (in kg) for each
+individual biomass component available for the selected species and model.
}
\description{
Predicts all available individual biomass components (e.g., stem, bark, branches,
roots) for the given trees in a single call, returning a wide data frame.
}
\examples{
-# Predict all components using Ruiz-Peinado 2011
-silv_predict_biomass_components(
- species = "Pinus pinaster",
- diameter = 25,
- height = 15,
+# 1. Vector-based calculation: predict all components for Pinus pinaster
+comp_results <- silv_predict_biomass_components(
+ species = c("Pinus pinaster", "Pinus pinaster"),
+ diameter = c(20, 25),
+ height = c(12, 15),
model_fn = eq_biomass_ruiz_peinado_2011
)
+print(comp_results)
+
+# 2. Dataset-based tutorial: apply to a forest inventory data frame
+inventory <- data.frame(
+ tree_id = 1:3,
+ species = c("Pinus pinaster", "Pinus pinaster", "Pinus pinaster"),
+ dbh_cm = c(18.5, 22.1, 29.4),
+ height_m = c(14.0, 16.5, 19.0)
+)
+
+# Predict components for the entire dataset
+comp_df <- silv_predict_biomass_components(
+ species = inventory$species,
+ diameter = inventory$dbh_cm,
+ height = inventory$height_m,
+ model_fn = "ruiz-peinado-2011"
+)
+
+# Combine and display results (excluding repeated identifier columns)
+inventory_with_components <- cbind(
+ inventory,
+ comp_df[, -(1:3)]
+)
+print(inventory_with_components)
}
diff --git a/man/silv_predict_height.Rd b/man/silv_predict_height.Rd
index 7f654d2..752fc30 100644
--- a/man/silv_predict_height.Rd
+++ b/man/silv_predict_height.Rd
@@ -2,24 +2,27 @@
% Please edit documentation in R/predict-height.R
\name{silv_predict_height}
\alias{silv_predict_height}
-\title{Estimates tree height from DBH}
+\title{Estimates tree height (m) from DBH (cm)}
\usage{
-silv_predict_height(diameter, model, quiet = FALSE)
+silv_predict_height(
+ diameter,
+ model = eq_hd_vazquez_veloso_2025("All the species"),
+ quiet = FALSE
+)
}
\arguments{
-\item{diameter}{Numeric vector with diameters in cm}
+\item{diameter}{Numeric vector with diameters in cm (DBH).}
-\item{model}{A function. A function with the structure \code{eq_hd_*()} with
-additional arguments depending on the specific model. Currently only \code{\link[=eq_hd_vazquez_veloso_2025]{eq_hd_vazquez_veloso_2025()}}
-is available.}
+\item{model}{A ModelHD object. An object configured via the \code{eq_hd_*()} family of functions.
+Defaults to \code{eq_hd_vazquez_veloso_2025("All the species")}.}
\item{quiet}{A logical value. If TRUE, suppresses any informational messages.}
}
\value{
-A numeric vector with predicted heights
+A numeric vector with predicted heights (m).
}
\description{
-Estimates total tree height using height-diameter (h-d) equations. Currently, only models developed
+Estimates total tree height (m) using height-diameter (h-d) equations. Currently, only models developed
for Spain are available.
}
\details{
@@ -27,7 +30,31 @@ The function estimates total tree height (in meters) using diameter at breast he
and may require additional information depending on the specific model. See each model’s documentation for details.
}
\examples{
-1 + 1 #TODO
+# 1. Predict height using the default model (Vázquez-Veloso 2025 generic model)
+predicted_heights_default <- silv_predict_height(diameter = c(20, 25, 30))
+print(predicted_heights_default)
+
+# 2. Load the S7 ModelHD object for Pinus pinaster
+model <- eq_hd_vazquez_veloso_2025("Pinus pinaster")
+
+# 3. Vector-based calculation: predict tree heights from diameters
+diameters <- c(20, 25, 30)
+predicted_heights <- silv_predict_height(diameter = diameters, model = model)
+print(predicted_heights)
+
+# 4. Dataset-based tutorial: apply to a forest inventory data frame
+inventory <- data.frame(
+ tree_id = 1:3,
+ species = c("Pinus pinaster", "Pinus pinaster", "Pinus pinaster"),
+ dbh_cm = c(18.5, 22.1, 29.4)
+)
+
+# Apply prediction and append a new column to the dataset
+inventory$height_m <- silv_predict_height(
+ diameter = inventory$dbh_cm,
+ model = model
+)
+print(inventory)
}
\references{
References for the models available:
diff --git a/man/silv_predict_snfi_volume.Rd b/man/silv_predict_snfi_volume.Rd
index e5d1a24..7540008 100644
--- a/man/silv_predict_snfi_volume.Rd
+++ b/man/silv_predict_snfi_volume.Rd
@@ -82,23 +82,46 @@ Inputs: \code{dbh} and \code{dnm} in \strong{cm} (converted to mm internally),
}
}
\examples{
-# Single tree: Pinus radiata in Alava (province 1), code 28
-silv_predict_snfi_volume(
+# 1. Vector-based calculation: single tree (Pinus radiata in Alava, province 1, code 28)
+single_tree <- silv_predict_snfi_volume(
province = 1,
species = 28,
dbh = 20,
h = 15,
dnm = 23
)
+print(single_tree)
-# Mixed inputs: province and species by name
-silv_predict_snfi_volume(
- province = c(1, 39),
+# 2. Vector-based calculation: multiple trees with province and species by name
+multi_trees <- silv_predict_snfi_volume(
+ province = c("Araba/Álava", "Cantabria"),
species = c("Pinus radiata", "Pinus radiata"),
dbh = c(20, 25),
h = c(15, 18),
dnm = c(23, 26)
)
+print(multi_trees)
+
+# 3. Dataset-based tutorial: apply to a forest inventory data frame
+inventory <- data.frame(
+ tree_id = 1:3,
+ province = c("Cantabria", "Cantabria", "Araba/Álava"),
+ species = c("Pinus radiata", "Pinus radiata", "Pinus sylvestris"),
+ dbh_cm = c(20.5, 28.0, 18.2),
+ height_m = c(15.2, 18.5, 12.0)
+)
+
+# Apply the SNFI volume estimation functions row-wise across the dataset
+volume_results <- silv_predict_snfi_volume(
+ province = inventory$province,
+ species = inventory$species,
+ dbh = inventory$dbh_cm,
+ h = inventory$height_m
+)
+
+# Combine and display results
+inventory_with_volume <- cbind(inventory, volume_results)
+print(inventory_with_volume)
}
\references{
MITECO. 4th Spanish National Forest Inventory - SIG database codes.
diff --git a/man/snfi3_volume_coefficients.Rd b/man/snfi3_volume_coefficients.Rd
index a302542..4fdb20c 100644
--- a/man/snfi3_volume_coefficients.Rd
+++ b/man/snfi3_volume_coefficients.Rd
@@ -12,7 +12,7 @@ A \code{tibble} with 37,730 rows and 16 variables:
\item{Codigo_especie}{Integer. Species numeric code.}
\item{Especie}{Character. Species scientific name.}
\item{Parametro}{Character. Volume component: VCC (merchantable volume with bark), VSC (merchantable volume without bark), IAVC (annual volume increment with bark), or VLE (coarse firewood volume).}
-\item{F.c.}{Integer. Tree quality class (forma de copa), from 1 (healthy and straight tree) to 6 (dead tree).}
+\item{F.c.}{Integer. Tree quality class (calidad del árbol), from 1 (healthy and straight tree) to 6 (dead tree).}
\item{Par_esp}{Character. Special parameter metadata.}
\item{Modelo}{Integer. Equation model index.}
\item{a, b, c, d, p, q, r}{Numeric. Equation coefficients (NA where not applicable).}
diff --git a/man/snfi4_volume_coefficients.Rd b/man/snfi4_volume_coefficients.Rd
index e2ea2f8..008bf50 100644
--- a/man/snfi4_volume_coefficients.Rd
+++ b/man/snfi4_volume_coefficients.Rd
@@ -12,7 +12,7 @@ A \code{tibble} with 20,925 rows and 15 variables:
\item{Codigo_especie}{Integer. Species numeric code.}
\item{Especie}{Character. Species scientific name.}
\item{Parametro}{Character. Volume component: VCC (merchantable volume with bark), VSC (merchantable volume without bark), IAVC (annual volume increment with bark), or VLE (coarse firewood volume).}
-\item{F.c.}{Integer. Tree quality class (forma de copa), from 1 (healthy and straight tree) to 6 (dead tree).}
+\item{F.c.}{Integer. Tree quality class (calidad del árbol), from 1 (healthy and straight tree) to 6 (dead tree).}
\item{Modelo}{Integer. Equation model index.}
\item{a, b, c, d, p, q, r}{Numeric. Equation coefficients (NA where not applicable).}
\item{D.n.m.}{Character. Mean plot diameter metadata (diámetro normal medio), required for IAVC equation model 13.}