Title:	Age Band Decomposition Method for Tree Ring Standardization
Version:	1.0.1
Description:	Implements the Age Band Decomposition (ABD) method for standardizing tree ring width data while preserving both low and high frequency variability. Unlike traditional detrending approaches that can distort long term growth trends, ABD decomposes ring width series into multiple age classes, detrends each class separately, and then recombines them to create standardized chronologies. This approach improves the detection of growth signals linked to past climatic and environmental factors, making it particularly valuable for dendroecological and dendroclimatological studies. The package provides functions to perform ABD-based standardization, compare results with other common methods (e.g., BAI, C method, RCS), and facilitate the interpretation of growth patterns under current and future climate variability.
URL:	https://gitlab.com/Puletti/agebanddecomposition_rpackage
Language:	en-US
License:	GPL (≥ 3)
Encoding:	UTF-8
RoxygenNote:	7.3.2
LazyData:	true
Imports:	dplyr, tidyr, tibble, readxl, ggplot2, patchwork
Suggests:	testthat (≥ 3.0.0)
Config/testthat/edition:	3
Depends:	R (≥ 4.1.0)
NeedsCompilation:	no
Packaged:	2025-07-25 05:42:47 UTC; nicolapuletti
Author:	Nicola Puletti [aut, cre], Gianluigi Mazza [aut]
Maintainer:	Nicola Puletti <nicola.puletti@crea.gov.it>
Repository:	CRAN
Date/Publication:	2025-07-28 18:30:12 UTC

ABD - Age Band Decomposition

Description

ABD - Age Band Decomposition. This function calculates standardized tree-ring width chronologies by decomposing tree-ring width (stdTRW) data into age bands, detrending each age band separately, and then recombining them to produce the mean standardized chronology. Specifically, ABD standardizes each series within its age band (e.g., each ring width is divided by the corresponding age-specific expected value from the stdTRW). Then, standardized values from all age bands are merged and averaged to produce a composite chronology, preserving both inter-annual and low-frequency climate signals.

Usage

ABD(inTRW, min_nTrees_year = 3, pct_stdTRW_th = 0.5, pct_Trees_th = 0.3)

Arguments

Details

The function performs age-band decomposition on stdTRW data by filtering out age classes with insufficient observations (min_nTrees_year) or excessive within-class variation.

The stdTRW_th value is particularly important in small datasets: too strict a threshold may exclude valid data. If working with approximately 20 trees or fewer, a threshold of 0.5 is suggested.

Please, see the Examples section below for a demonstration using a typical input tibble obtained with TRW_readExcel().

Value

A tibble with the following columns: year, N_ageBands, ABD, and ABDsd.

See Also

TRW_readExcel, stdTRW, plotABD

Other ABD functions: TRW_readExcel(), stdTRW()

Examples

ABD(inTRW)

AgeBandDecomposition test data

Description

A tiny test dataset including example, the basic reference for AgeBandDecomposition package.

Usage

ABD_test_data1

Format

A tibble with 85 rows and 16 variables, as derived from the Excel file.

TRW_readExcel

Description

This function supports the first step of data import from an Excel file and arranges the dataset properly for ABD analysis.

Usage

TRW_readExcel(path, sheet, ageBands, limitFirst20y, verbose = TRUE)

Arguments

Details

The provided Excel .xlsx file contains tree-ring width (TRW) chronologies organized by year. Each column represents an individual tree (e.g., tree01, tree02, tree03, etc.), with rows corresponding to calendar years. Missing values within the ring-width series (e.g., due to measurement gaps or broken sections) and the estimated number of rings to the pith for incomplete cores must be explicitly coded as -999.

An example .xlsx file formatted accordingly is available on the package's GitLab page.

https://gitlab.com/Puletti/agebanddecomposition_rpackage

This example can be used to test the functions or as a template for preparing your own data.

Value

A list of two objects. The first object is a tibble representing the imported dataset in long format. In this tibble the last two columns are an identification number (id_by_years) and two grouping variables (age_class and ageBands). The second object in the list is a lookup table (tibble), useful for further steps.

See Also

stdTRW, ABD

Other ABD functions: ABD(), stdTRW()

Examples

# Download the 'ABD_example.xlsx' file from the GitLab page of the package
package_gitlab_site <- 'https://gitlab.com/Puletti/agebanddecomposition_rpackage'
xls_url <- "/-/raw/main/studio/dati/TRW_example.xlsx"
url <- paste0(package_gitlab_site,xls_url)

tmpfile <- tempfile(fileext = ".xlsx")
download.file(url,
              tmpfile,
              mode = "wb")

inTRW_example <- TRW_readExcel(tmpfile, sheet = "Example", ageBands = '1010', limitFirst20y = FALSE)
inTRW_example

stdTRW test data

Description

A list of two test datasets derived from TRW_readExcel function. The first list-object is a tibble that can be used as the argument of stdTRW function.

Usage

inTRW

Format

A list of two tibbles

plotABD

Description

Function for plotting ABD values from inTRW object using the two tibble objects produced by the function TRW_readExcel.

Usage

plotABD(
  inTRW,
  min_nTrees_year = 3,
  pct_stdTRW_th = 0.5,
  pct_Trees_th = 0.3,
  linewidth_TRW = 0.7,
  linewidth_Ntrees = 1,
  byYears = 20,
  xlim = NULL,
  ylimABD = NULL,
  ...
)

Arguments

Details

This function produces a multi-panel plot with three graphs: the first displays standardized values by age band; the second shows the final mean chronology (ABD), adjusted for age-related effects; and the third depicts the corresponding number of trees.

Value

None. A multipanel plot.

See Also

plotBAI, plotTRW, ABD

Other tree ring plotting: plotBAI(), plotTRW()

Examples

plotABD(inTRW, 
   min_nTrees_year = 3, 
   pct_stdTRW_th = .5,
   pct_Trees_th = .3,
   byYears = 50)

plotBAI

Description

Function for plotting basal area increment (BAI) values derived from inTRW object using the first tibble produced by the function TRW_readExcel.

Usage

plotBAI(
  inTRW,
  linewidth_BAI = 1,
  linewidth_Ntrees = 1,
  byYears = 20,
  xlim = NULL,
  ylim = NULL,
  ...
)

Arguments

Details

This function generates a basic plot displaying the mean chronology +/- standard error of raw basal area increments (in squared cm) alongside the corresponding number of trees.

Value

None. A plot is produced.

See Also

plotTRW, plotABD

Other tree ring plotting: plotABD(), plotTRW()

Examples

plotBAI(inTRW
    , linewidth_BAI = .5
    , linewidth_Ntrees = 1
    )

plotTRW

Description

Function for plotting TRW values from inTRW object using the first tibble produced by the function TRW_readExcel.

Usage

plotTRW(
  inTRW,
  linewidth_TRW = 1,
  linewidth_Ntrees = 1,
  byYears = 20,
  xlim = NULL,
  ylim = NULL,
  ...
)

Arguments

Details

This function generates a basic plot displaying the mean chronology +/- standard error of raw tree-ring widths (in mm) alongside the corresponding number of trees.

Value

None. A plot is produced.

See Also

plotBAI, plotABD

Other tree ring plotting: plotABD(), plotBAI()

Examples

plotTRW(inTRW)

stdTRW

Description

To remove the influences of local site characteristics on tree growth, this function standardizes the tree-ring width series by dividing each tree-ring width of a particular series by the mean width of that series. In dendroclimatic studies, it is advisable to exclude the initial years or decades of growth (the first “age bands”, i.e., 1-10 and 11-20) as they are less likely to contain climatic signals rather than the influence of strong early-year growth competition within the tree stand (Mazza and Sarris, 2021; Sarris et al., 2007).

Usage

stdTRW(inTRW)

Arguments

Details

To export a tibble like the one below to an .xlsx file, you can use the writexl package:

mytibble <- stdTRW_df |>
  dplyr::group_by(year) |>
  dplyr::summarise(
    N_trees = dplyr::n(),
    mean_stdTRW = mean(stdTRW, na.rm = TRUE)
  )

writexl::write_xlsx(mytibble, path = "my_stdTRW_df.xlsx")

This will create an Excel file named my_stdTRW_df.xlsx in your current working directory. Please, check also the Examples section below for how to obtain stdTRW_df object.

Value

A tibble with the following columns: year, tree_code, TRW, meanTRW, and stdTRW. Together with additional columns of grouping variables based on age class.

References

Mazza, G., Sarris, D., 2021. Identifying the full spectrum of climatic signals controlling a tree species' growth and adaptation to climate change. Ecol. Indic. 130, 108109. https://doi.org/10.1016/j.ecolind.2021.108109.

Sarris, D., Christodoulakis, D., Körner, C., 2007. Recent decline in precipitation and tree growth in the eastern Mediterranean. Glob. Chang. Biol. 13 (6), 1187–1200. https://doi.org/10.1111/j.1365-2486.2007.01348.x.

See Also

TRW_readExcel, ABD

Other ABD functions: ABD(), TRW_readExcel()

Examples

inTRW_1 <- inTRW[[1]]

stdTRW_df <- stdTRW(inTRW_1)

stdTRW_df |>
dplyr::group_by(year) |>
dplyr::summarise(N_trees = dplyr::n(),
       mean_stdTRW = mean(stdTRW, na.rm = TRUE)) |>
       ggplot2::ggplot(ggplot2::aes(year, N_trees)) +
       ggplot2::geom_line()