% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/stats.clim.twd.R
\name{clim.twd.stats}
\alias{clim.twd.stats}
\title{Calculate tree-, species-, or site-level statistics from clim.twd output}
\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{
\item{x}{An object of class \code{"clim_twd_output"} returned by
\code{clim.twd()}.}

\item{tree_info}{Optional metadata table describing trees. It must contain a
column named \code{tree}, and may additionally contain \code{species} and
\code{site}. A named character vector is also accepted for species-only
mapping, where names are trees and values are species.}

\item{response}{Character. Which response table from \code{clim.twd()} should
be summarized:
\describe{
  \item{`"adverse_change"`}{Only the adverse phase.}
  \item{`"normal_change"`}{Only the following normal phase.}
  \item{`"full_period_change"`}{Adverse + following normal phase, reset to 0
  at each adverse start.}
  \item{`"continuous_full_period_change"`}{Adverse + following normal phase,
  continuing from the previous full period instead of resetting to 0.}
}}

\item{group_by}{Character. Grouping level for trajectory summaries. One of
\code{"tree"}, \code{"species"}, \code{"site"}, or \code{"species_site"}.}

\item{center}{Character. Central tendency used for grouped trajectories and
grouped period metrics. One of \code{"mean"} or \code{"median"}.}

\item{conf_level}{Numeric confidence/limit level. Default is \code{0.95}.
Empirical limits are returned as the lower and upper quantiles corresponding
to this level.}

\item{months}{Optional numeric vector of months (1--12). Only IDs whose
adverse-phase start falls in these months are retained.}

\item{years}{Optional numeric vector of years. Only IDs whose adverse-phase
start year falls in these years are retained.}

\item{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 \code{c(300, 50)}.}

\item{year_window}{Optional numeric vector of length 2 defining the allowed
year range for adverse-phase start.}

\item{include_tree_series}{Logical. If \code{TRUE}, the filtered long-format
tree-level data are stored in the output.}
}
\value{
A list of class \code{"clim_twd_stats"} with:
\describe{
  \item{trajectory_summary}{Grouped time-series summary for each ID and date,
  including central tendency, SD bands, and empirical 95\% limits.}
  \item{id_summary}{Grouped per-ID summary derived from
  \code{x$period_info}.}
  \item{selected_ids}{IDs retained after temporal filtering.}
  \item{phase_table}{Filtered phase table.}
  \item{tree_info}{Metadata table used for grouping.}
  \item{long_data}{Filtered long-format tree-level response table, if
  \code{include_tree_series = TRUE}.}
  \item{settings}{List of settings used to generate the summaries.}
}
}
\description{
Calculates grouped statistics from the output of \code{clim.twd()}.

The function can summarize relative dendrometer change trajectories and
event-level metrics:
\itemize{
  \item by tree,
  \item by species,
  \item by site,
  \item 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.
}
\details{
\strong{Temporal filtering} is based on the \code{adverse_start} date in
\code{x$phase_table}. Multiple filters are combined, so for example users can
simultaneously restrict to:
\itemize{
  \item specific months,
  \item specific years,
  \item a day-of-year window,
  \item and a year range.
}

If \code{group_by = "species"}, \code{"site"}, or \code{"species_site"},
\code{tree_info} must provide the required columns.
}
\examples{
\donttest{
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)
)
}

}
