Title:	Age Band Decomposition Method for Tree Ring Standardization
Version:	2.0.0
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, dplR, patchwork
Suggests:	testthat (≥ 3.0.0)
Config/testthat/edition:	3
Depends:	R (≥ 4.1.0)
NeedsCompilation:	no
Packaged:	2026-02-04 14:38:41 UTC; nicolapuletti
Author:	Nicola Puletti [aut, cre], Gianluigi Mazza [aut], Dimitrios Sarris [ctb]
Maintainer:	Nicola Puletti <nicola.puletti@crea.gov.it>
Repository:	CRAN
Date/Publication:	2026-02-04 15:20:08 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 import_rwl().

Value

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

See Also

import_rwl, stdTRW, plotABD

Other ABD functions: import_rwl(), stdTRW()

Examples

ABD(inTRW)

TRW_readExcel (Deprecated)

Description

This function is deprecated and will be removed in a future version. Please use import_rwl instead after converting your data to RWL format.

Usage

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

Arguments

Value

A list of two objects (see original documentation).

See Also

import_rwl

import_rwl

Description

This function imports tree-ring width data from RWL (Tucson format) files and pith offset information, then arranges the dataset for ABD analysis.

Usage

import_rwl(
  rwl_path,
  po_path,
  ageBands,
  first_age_class = NULL,
  zero_as_na = TRUE,
  verbose = TRUE
)

Arguments

Details

The RWL file must be in Tucson format (readable by dplR::read.rwl). The pith offset file must be a tab-delimited text file with header containing columns 'tree_code' and 'pith.offset', where pith.offset indicates the number of missing rings between the pith and the first measured ring. are available on the package's GitLab page. https://gitlab.com/Puletti/agebanddecomposition_rpackage and can be used to test the package's functions.

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 example files from the package's GitLab page
package_gitlab_site <- 'https://gitlab.com/Puletti/agebanddecomposition_rpackage'
rwl_url <- "/-/raw/main/studio/dati/TRW_example.rwl"
po_url <- "/-/raw/main/studio/dati/pith.offset.txt"

# Create temporary files
tmpfile_rwl <- tempfile(fileext = ".rwl")
tmpfile_po <- tempfile(fileext = ".txt")

# Download the files
download.file(paste0(package_gitlab_site, rwl_url),
              tmpfile_rwl,
              mode = "wb")

download.file(paste0(package_gitlab_site, po_url),
              tmpfile_po,
              mode = "wb")

# Import the data
inData <- import_rwl(rwl_path = tmpfile_rwl, 
                             po_path = tmpfile_po, 
                             ageBands = '1010', 
                             first_age_class = 3,
                             zero_as_na = TRUE,
                             verbose = TRUE)

# View the result
inData

AgeBandDecomposition test data

Description

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

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

inTRW

Format

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

A list of two tibbles

plotABD

Description

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

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 import_rwl.

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 import_rwl.

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

import_rwl, ABD

Other ABD functions: ABD(), import_rwl()

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()