% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/stats.clim.twd.R
\name{clim.twd.test}
\alias{clim.twd.test}
\title{Statistical testing for clim.twd output}
\usage{
clim.twd.test(
  x,
  tree_info = NULL,
  parameter = c("lag_to_below_zero", "lag_to_max_adverse_decline", "lag_to_return_zero",
    "max_adverse_decline_value", "change_end_adverse", "change_end_full_period",
    "continuous_end_full_period"),
  compare_by = c("tree", "species", "site", "species_site"),
  within = c("all", "year", "ID"),
  test_method = c("auto", "t_test", "welch_t", "wilcox", "anova", "kruskal"),
  ids = NULL,
  years = NULL,
  months = NULL,
  doy_window = NULL,
  year_window = NULL,
  pairwise = TRUE,
  p_adjust_method = "BH",
  min_n_per_group = 2
)
}
\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{parameter}{Character. Parameter from \code{x$period_info} to test.
Supported examples include:
\describe{
  \item{`"lag_to_below_zero"`}{Lag from adverse start until relative change
  first drops below zero.}
  \item{`"lag_to_max_adverse_decline"`}{Lag from adverse start until maximum
  adverse decline is reached.}
  \item{`"lag_to_return_zero"`}{Lag from adverse start until relative change
  returns to zero or above.}
  \item{`"max_adverse_decline_value"`}{Most negative relative change during
  the adverse phase.}
  \item{`"change_end_adverse"`}{Relative change at the end of the adverse phase.}
  \item{`"change_end_full_period"`}{Relative change at the end of the full period.}
  \item{`"continuous_end_full_period"`}{Continuous end value across periods.}
}}

\item{compare_by}{Character. Grouping variable to compare. One of
\code{"tree"}, \code{"species"}, \code{"site"}, or \code{"species_site"}.}

\item{within}{Character. Defines the comparison scenario:
\describe{
  \item{`"all"`}{Compare groups across all retained IDs.}
  \item{`"year"`}{Compare groups separately within each adverse-start year.}
  \item{`"ID"`}{Compare groups separately within each ID.}
}}

\item{test_method}{Character. One of \code{"auto"}, \code{"t_test"},
\code{"welch_t"}, \code{"wilcox"}, \code{"anova"}, or \code{"kruskal"}.
With \code{"auto"}, the function uses:
\itemize{
  \item Welch t-test or one-way ANOVA when group distributions look
  approximately normal,
  \item Wilcoxon or Kruskal-Wallis otherwise.
}}

\item{ids}{Optional numeric vector of IDs to retain before testing.}

\item{years}{Optional numeric vector of years to retain based on
\code{adverse_start}.}

\item{months}{Optional numeric vector of months (1--12) to retain based on
\code{adverse_start}.}

\item{doy_window}{Optional numeric vector of length 2 defining the allowed
day-of-year window of \code{adverse_start}. Wrapped windows such as
\code{c(300, 50)} are supported.}

\item{year_window}{Optional numeric vector of length 2 defining the allowed
year range for \code{adverse_start}.}

\item{pairwise}{Logical. If \code{TRUE}, pairwise post-hoc tests are computed
for strata with more than two groups when applicable.}

\item{p_adjust_method}{Character. P-value adjustment method for pairwise tests.
Default is \code{"BH"}.}

\item{min_n_per_group}{Minimum number of non-missing observations required per
group before testing. Default is \code{2}.}
}
\value{
A list of class \code{"clim_twd_test"} containing:
\describe{
  \item{data_used}{Filtered test data used for the analyses.}
  \item{test_results}{Main test results by stratum.}
  \item{pairwise_results}{Pairwise comparison table where available.}
  \item{group_summary}{Descriptive summaries by stratum and group.}
  \item{settings}{Settings used for the analysis.}
}
}
\description{
Performs hypothesis tests on parameters derived from \code{clim.twd()} output.

This function is designed for scenarios such as:
\itemize{
  \item species comparison as a whole,
  \item species comparison by year,
  \item site comparison as a whole,
  \item site comparison by year,
  \item species-within-site comparison,
  \item ID-wise comparisons.
}

The function uses the \code{period_info} table from \code{clim.twd()} and
tests selected parameters across groups such as trees, species, sites, or
species-site combinations.
}
\examples{
\donttest{
rel_out <- clim.twd(
  df = gf_nepa17,
  Clim = ktm_rain17,
  thresholdClim = "<10",
  thresholdDays = ">5",
  showPlot = FALSE
)

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

# species comparison across all retained IDs
tst1 <- clim.twd.test(
  rel_out,
  tree_info = tree_info,
  parameter = "max_adverse_decline_value",
  compare_by = "species",
  within = "all"
)

summary(tst1)
plot(tst1)

# species comparison by year
tst2 <- clim.twd.test(
  rel_out,
  tree_info = tree_info,
  parameter = "lag_to_return_zero",
  compare_by = "species",
  within = "year"
)

# site comparison by year
tst3 <- clim.twd.test(
  rel_out,
  tree_info = tree_info,
  parameter = "change_end_full_period",
  compare_by = "site",
  within = "year",
  test_method = "kruskal"
)
}

}
