Help for package rTG

Type:

Package

Title:

Methods to Analyse Seasonal Radial Tree Growth Data

Version:

1.0.4

Author:

Jernej Jevsenak [aut, cre]

Maintainer:

Jernej Jevsenak <jernej.jevsenak@gmail.com>

Description:

Methods for comparing different regression algorithms for describing the temporal dynamics of secondary tree growth (xylem and phloem). Users can compare the accuracy of the most common fitting methods usually used to analyse xylem and phloem data, i.e., Gompertz function, Double Gompertz function, General Additive Models (GAMs); and an algorithm newly introduced to the field, i.e., Bayesian Regularised Neural Networks (brnn). The core function of the package is XPSgrowth(), while the results can be interpreted using implemented generic S3 methods, such as plot() and summary().

License:

GPL-3

Encoding:

UTF-8

LazyData:

true

Suggests:

testthat (≥ 3.0.0)

Imports:

ggplot2(≥ 2.2.0), mgcv (≥ 1.8-34), knitr(≥ 1.19), dplyr(≥ 0.1.0), magrittr(≥ 1.5), methods

Depends:

R(≥ 3.5), brnn(≥ 0.6), minpack.lm (≥ 1.2-4)

URL:

https://github.com/jernejjevsenak/rTG

BugReports:

https://github.com/jernejjevsenak/rTG/issues

NeedsCompilation:

Repository:

CRAN

RoxygenNote:

7.3.2

Config/testthat/edition:

Packaged:

2025-02-28 18:37:05 UTC; JernejJ

Date/Publication:

2025-02-28 18:50:02 UTC

XPSgrowth

Description

XylemPhloemSeasonalGrowth: This Function fits and compares the selected methods for modeling seasonal xylem and phloem data.

Usage

XPSgrowth(
  data_trees,
  parameters = NULL,
  search_initial_gom = TRUE,
  search_initial_double_gom = TRUE,
  fitting_method = c("gompertz", "GAM", "brnn", "double_gompertz"),
  ID_vars = NULL,
  fitted_save = FALSE,
  add_zeros = TRUE,
  add_zeros_before = "min",
  post_process = TRUE,
  unified_parameters = FALSE,
  gom_a = NA,
  gom_b = NA,
  gom_k = NA,
  d_gom_a1 = NA,
  d_gom_a2 = NA,
  d_gom_b1 = NA,
  d_gom_b2 = NA,
  d_gom_k1 = NA,
  d_gom_k2 = NA,
  brnn_neurons = NA,
  gam_k = NA,
  gam_sp = NA,
  gom_a_range = seq(0, 3000, by = 500),
  gom_b_range = seq(0.01, 1000, by = 50),
  gom_k_range = seq(0, 500, by = 2),
  d_gom_a1_range = seq(0, 1, by = 0.001),
  d_gom_a2_range = seq(0, 5, by = 0.01),
  d_gom_b1_range = seq(0, 5, by = 0.001),
  d_gom_b2_range = seq(0, 10, by = 0.1),
  d_gom_k1_range = seq(0, 1, by = 0.001),
  d_gom_k2_range = seq(0, 1, by = 0.001)
)

Arguments

data_trees

a data frame with ID variables and wood formation data with columns doy and width

parameters

a data frame with ID variables and initial parameter values for the selected methods

search_initial_gom

logical, should the algorithm to search initial Gompertz parameters be applied? This argument also overwrites manually defined Gompertz parameter values

search_initial_double_gom

logical, should the algorithm to search initial parameters for double Gompertz function be applied? This argument also overwrites manually defined parameter values for double Gompertz

fitting_method

vector of one or more methods to be compared: "gompertz", "double_gompertz", "gam", "brnn"

ID_vars

character vector of variables which indicate column names of ID variables

fitted_save

logical, should the fitted curves be saved in current working directory?

add_zeros

logical, should zero observations at the beginning of growing season be added?

add_zeros_before

if 'min' (character) then zeros will be added prior to the first observation in each year. Alternatively, users can specify absolute doy prior which zeros will be added.

post_process

logical, should the post-process algorithm be applied?

unified_parameters

logical, if TRUE, the algorithm will use only manually selected function parameters. See the arguments 'gom_a', 'gom_b', 'd_gom_k', 'd_gom_a1', 'd_gom_a2', 'd_gom_b1', 'd_gom_b2', 'd_gom_k1', 'd_gom_k2', 'brnn_neurons', 'gam_k' and 'gam_sp'. Default is FALSE

gom_a

numeric, the parameter a for the Gompertz function

gom_b

numeric, the parameter b for the Gompertz function

gom_k

numeric, the parameter k for the Gompertz function

d_gom_a1

numeric, the parameter a1 for the double Gompertz function

d_gom_a2

numeric, the parameter a2 for the double Gompertz function

d_gom_b1

numeric, the parameter b1 for the double Gompertz function

d_gom_b2

numeric, the parameter b2 for the double Gompertz function

d_gom_k1

numeric, the parameter k1 for the double Gompertz function

d_gom_k2

numeric, the parameter k2 for the double Gompertz function

brnn_neurons

positive integer, the number of neurons to be used by the BRNN method

gam_k

numeric, the parameter k for General Additive Model (GAM)

gam_sp

numeric, the parameter sp for General Additive Model (GAM)

gom_a_range

a numerical vector of the possible values of the parameter a, which is considered in the search for the initial Gompertz parameter values

gom_b_range

a numerical vector of the possible values of the parameter b, which is considered in the search for the initial Gompertz parameter values

gom_k_range

a numerical vector of the possible values of the parameter k, which is considered in the search for the initial Gompertz parameter values

d_gom_a1_range

A numerical vector representing the range of potential values for the 'a1' parameter within the double Gompertz function.

d_gom_a2_range

A numerical vector representing the range of potential values for the 'a2' parameter within the double Gompertz function.

d_gom_b1_range

A numerical vector representing the range of potential values for the 'b1' parameter within the double Gompertz function.

d_gom_b2_range

A numerical vector representing the range of potential values for the 'b2' parameter within the double Gompertz function.

d_gom_k1_range

A numerical vector representing the range of potential values for the 'k1' parameter within the double Gompertz function.

d_gom_k2_range

A numerical vector representing the range of potential values for the 'k2' parameter within the double Gompertz function.

Value

a list with the following elements:

$fitted - a data frame with fitted values
$gompertz_initial_parameters - a data frame that contains a curated selection of initial parameter values for the Gompertz function.
$gompertz_model_parameters - a data frame with final model coefficients for the Gompertz function.
$gompertz_initial_parameters_errors - a data frame with unsuccessful cases of Gompertz grid search.
$double_gompertz_initial_parameters - a data frame that contains a curated selection of initial parameter values for the double Gompertz function.
$double_gompertz_initial_parameters_errors - a data frame with unsuccessful cases of double Gompertz grid search.
$doble_gompertz_model_parameters - a data frame with final model coefficients for the double Gompertz function.

Examples

library(rTG)

# 1 Example on xylem and phloem data
data(parameters)
data(data_trees)

# subset data_trees
data_trees <- data_trees[c(1:27),]

# 1a Example using neural network
simulation_1a <- XPSgrowth(data_trees = data_trees,
     parameters = parameters,
     ID_vars = c("Species", "Tissue", "Site", "Year", "Tree"),
     fitting_method = c("brnn"),
     fitted_save = FALSE,
     search_initial_gom = FALSE,
     add_zeros = TRUE,
     add_zeros_before = 'min',
     post_process = TRUE)

## Not run: 
#' # 1b Example on double Gompertz function
simulation_1b <- XPSgrowth(data_trees = data_trees,
     parameters = parameters,
     ID_vars = c("Species", "Tissue", "Site", "Year"),
     fitting_method = c("double_gompertz"),
     fitted_save = FALSE,
     search_initial_double_gom = TRUE,
     add_zeros = TRUE)

 plot(simulation_1b)

# Obtain model parameters
simulation_1b$double_gompertz_model_parameters


## End(Not run)

# 2 Example on dendrometer data
data("data_dendrometers")

simulation_2 <- XPSgrowth(data_dendrometers, unified_parameters = TRUE,
                  ID_vars = c("site", "species", "year", "tree"),
                  fitting_method = c("brnn", "gam"),
                  brnn_neurons = 2, gam_k = 9, gam_sp = 0.5,
                  search_initial_gom = TRUE, add_zeros = FALSE,
                  post_process = TRUE)

plot(simulation_2)

data_dendrometers

Description

A data set with dendrometer data from sugar maple and black spruce from Simoncouche site, Canada.

Usage

data_dendrometers

Format

A data frame with 718 rows and 6 variables:

site: Simoncouche
species: sugar maple and black spruce
tree: tree identifier
year: 2017, 2020
doy: day Of a Year
width: width expressed in relative terms

Source

Data belongs to Sergio Rossi

data_trees

Description

A dataset with intra-seasonal radial tree growth data. It was collected in three different years, at three sites, each with six trees. Please see references for details.

Usage

data_trees

Format

A data frame with 945 rows and 7 variables:

Tissue: XYLEM or PHLOEM
Species: Fagus sylvatica (FASY), Picea abies (PIAB), Quercus pubescens (QUPE)
Site: Panska reka (PAN), Karst (KRAS)
Year: 2011, 2017
Tree: Tree ID indicators ranging from 1 to 6
doy: Day Of a Year
width: The total number of radial cells / the total ring width

Source

Gričar, J., Prislan, P., De Luis, M., Gryc, V., Hacurová, J., Vavrčík, H., Čufar, K., 2015. Plasticity in variation of xylem and phloem cell characteristics of Norway spruce under different local conditions. Frontiers in plant science 6, 730. Gričar, J., Zavadlav, S., Jyske, T., Lavrič, M., Laakso, T., Hafner, P., Eler, K., Vodnik, D., 2019. Effect of soil water availability on intra-annual xylem and phloem formation and non-structural carbohydrate pools in stem of Quercus pubescens. Tree Physiol. 39, 222-233. Prislan, P., Gričar, J., Čufar, K., de Luis, M., Merela, M., Rossi, S., 2019. Growing season and radial growth predicted for Fagus sylvatica under climate change. Clim. Change 153, 181-197.

double_gompertz

Description

A method to fit the double Gompertz function

Usage

double_gompertz(x, a1, b1, k1, a2, b2, k2)

Arguments

x

independent variable

a1

parameter a1

b1

parameter b1

k1

parameter k1

a2

parameter a2

b2

parameter b2

k2

parameter k2

Value

a nls object with the function fit

parameters

Description

data frame with model fitting parameters for different regression methods.

Usage

parameters

Format

A data frame with 79 rows and 2 variables:

Tissue: XYLEM or PHLOEM
Species: Fagus sylvatica (FASY), Picea abies (PIAB), Quercus pubescens (QUPE)
Site: Panska reka (PAN), Karst (KRAS)
Year: 2011, 2017
Tree: Tree ID indicators ranging from 1 to 6
gom_a: The initial value for the Gompertz parameter a
gom_b: The initial value for the Gompertz parameter b
gom_k: The initial value for the Gompertz parameter c
brnn_neurons: The number of neurons for BRNN method
gam_k: The k parameter value for GAM method
gam_sp: The sp parameter value for GAM method