clim.twd.stats: Calculate tree-, species-, or site-level statistics from...

In dendRoAnalyst: A Tool for Processing and Analyzing Dendrometer Data

Calculate tree-, species-, or site-level statistics from clim.twd output

Description

Calculates grouped statistics from the output of clim.twd().

The function can summarize relative dendrometer change trajectories and event-level metrics:

• by tree,

• by species,

• by site,

• or by species within site.

It can also restrict IDs to specific months, years, or custom day-of-year windows based on the adverse-phase start date of each ID.

Usage

clim.twd.stats(
  x,
  tree_info = NULL,
  response = c("adverse_change", "normal_change", "full_period_change",
    "continuous_full_period_change"),
  group_by = c("tree", "species", "site", "species_site"),
  center = c("mean", "median"),
  conf_level = 0.95,
  months = NULL,
  years = NULL,
  doy_window = NULL,
  year_window = NULL,
  include_tree_series = TRUE
)

Arguments

x	An object of class "clim_twd_output" returned by clim.twd().
tree_info	Optional metadata table describing trees. It must contain a column named tree, and may additionally contain species and site. A named character vector is also accepted for species-only mapping, where names are trees and values are species.
response	Character. Which response table from clim.twd() should be summarized: '"adverse_change"' Only the adverse phase. '"normal_change"' Only the following normal phase. '"full_period_change"' Adverse + following normal phase, reset to 0 at each adverse start. '"continuous_full_period_change"' Adverse + following normal phase, continuing from the previous full period instead of resetting to 0.
group_by	Character. Grouping level for trajectory summaries. One of "tree", "species", "site", or "species_site".
center	Character. Central tendency used for grouped trajectories and grouped period metrics. One of "mean" or "median".
conf_level	Numeric confidence/limit level. Default is 0.95. Empirical limits are returned as the lower and upper quantiles corresponding to this level.
months	Optional numeric vector of months (1–12). Only IDs whose adverse-phase start falls in these months are retained.
years	Optional numeric vector of years. Only IDs whose adverse-phase start year falls in these years are retained.
doy_window	Optional numeric vector of length 2 defining the allowed day-of-year window for adverse-phase start. Wrapped windows are supported, for example c(300, 50).
year_window	Optional numeric vector of length 2 defining the allowed year range for adverse-phase start.
include_tree_series	Logical. If TRUE, the filtered long-format tree-level data are stored in the output.

Details

Temporal filtering is based on the adverse_start date in x$phase_table. Multiple filters are combined, so for example users can simultaneously restrict to:

• specific months,

• specific years,

• a day-of-year window,

• and a year range.

If group_by = "species", "site", or "species_site", tree_info must provide the required columns.

Value

A list of class "clim_twd_stats" with:

trajectory_summary

Grouped time-series summary for each ID and date, including central tendency, SD bands, and empirical 95% limits.

id_summary

Grouped per-ID summary derived from x$period_info.

selected_ids

IDs retained after temporal filtering.

phase_table

Filtered phase table.

tree_info

Metadata table used for grouping.

long_data

Filtered long-format tree-level response table, if include_tree_series = TRUE.

settings

List of settings used to generate the summaries.

Examples

rel_out <- clim.twd(
  df = gf_nepa17,
  Clim = ktm_rain17,
  thresholdClim = "<10",
  thresholdDays = ">5",
  showPlot = FALSE
)

# tree-level statistics
st1 <- clim.twd.stats(
  rel_out,
  response = "full_period_change",
  group_by = "tree"
)

summary(st1)
plot(st1, type = "trajectory")

# species metadata
tree_info <- data.frame(
  tree = c("T2", "T3"),
  species = c("Pinus", "Pinus"),
  site = c("Ktm", "Ktm")
)

# species-level summaries restricted to IDs starting in months 6 to 8
st2 <- clim.twd.stats(
  rel_out,
  tree_info = tree_info,
  response = "full_period_change",
  group_by = "species",
  center = "median",
  months = 6:8
)

summary(st2)
plot(st2, type = "trajectory", band = "limit95")

# species within site
st3 <- clim.twd.stats(
  rel_out,
  tree_info = tree_info,
  response = "continuous_full_period_change",
  group_by = "species_site",
  doy_window = c(150, 250),
  year_window = c(2017, 2018)
)

dendRoAnalyst documentation built on May 20, 2026, 5:07 p.m.