% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/clim.twd.R
\name{clim.twd}
\alias{clim.twd}
\title{Calculate relative dendrometer change during adverse climate periods and the following normal phase}
\usage{
clim.twd(
  df,
  Clim,
  dailyValue = "max",
  thresholdClim = "<10",
  thresholdDays = ">5",
  showPlot = TRUE
)
}
\arguments{
\item{df}{A data frame with the first column containing date-time stamps
(\code{yyyy-mm-dd HH:MM:SS}, convertible to \code{POSIXct}) and subsequent
columns containing dendrometer series.}

\item{Clim}{A data frame with the first column containing dates and the second
column containing the climate variable of interest.}

\item{dailyValue}{Character. Daily aggregation statistic used when resampling
dendrometer data. One of \code{"max"}, \code{"min"}, \code{"mean"}, or
\code{"sum"}. Default is \code{"max"}.}

\item{thresholdClim}{Character string defining the climate threshold.
Supported forms are:
\itemize{
  \item \code{"<5"}, \code{"<=5"}, \code{">5"}, \code{">=5"}, \code{"==5"}
  \item \code{"between(5,10)"}
  \item \code{"5:10"}
}}

\item{thresholdDays}{Character string defining the minimum duration threshold
for consecutive adverse days. Must use a single-threshold form such as
\code{">5"} or \code{">=3"}.}

\item{showPlot}{Logical. If \code{TRUE}, diagnostic plots are produced and the
user can interactively choose IDs and phase type (\code{"adverse"},
\code{"normal"}, or \code{"both"}). Default is \code{TRUE}.}
}
\value{
A list of class \code{"clim_twd_output"} containing:
\describe{
  \item{adverse_change}{A data frame of relative dendrometer change during
  adverse phases only.}
  \item{normal_change}{A data frame of relative dendrometer change during the
  following normal phases only.}
  \item{full_period_change}{A data frame of relative dendrometer change across
  adverse + following normal phase, reset to 0 at each adverse start.}
  \item{continuous_full_period_change}{A data frame similar to
  \code{full_period_change}, but values continue from the end of the previous
  full period instead of resetting to 0.}
  \item{period_info}{A data frame with one row per ID and tree, containing
  adverse and normal phase boundaries, the date and magnitude of maximum
  adverse decline during the adverse phase, lags to first drop below zero, lags
  to maximum adverse decline, and lags to return to zero.}
  \item{phase_table}{A data frame with adverse and normal phase boundaries for
  each ID.}
}
}
\description{
Identifies adverse climate periods from a climate time series and calculates
relative dendrometer change from the start of each adverse phase.

In addition to the adverse phase itself, the function also defines a
\emph{complete period} for each event ID:
\itemize{
  \item the adverse climate phase, and
  \item the following normal climate phase until the next adverse phase starts
  (or until the end of the common series).
}

Relative dendrometer change is always calculated from the first day of the
adverse phase for that ID.

The function returns:
\itemize{
  \item \code{adverse_change}: relative change only during adverse phases,
  \item \code{normal_change}: relative change only during the following normal phases,
  \item \code{full_period_change}: relative change across adverse + following normal phase,
  \item \code{continuous_full_period_change}: same as \code{full_period_change},
  but values do not reset to 0 at the next adverse phase and instead continue
  from the end of the previous full period,
  \item \code{period_info}: per-ID and per-tree summary metrics.
}
}
\details{
The algorithm works as follows:
\enumerate{
  \item Climate data are thresholded to identify adverse days.
  \item Consecutive adverse days are grouped into candidate adverse runs.
  \item Only runs satisfying \code{thresholdDays} are retained as true adverse events.
  \item For each retained adverse event, the following normal period is defined
  as all non-adverse days until the next adverse event starts (or the end of
  the series).
  \item Dendrometer data are resampled to daily resolution using
  \code{\link[dendRoAnalyst:dendro.resample]{dendro.resample}}.
  \item Relative dendrometer change is calculated from the first day of the
  adverse phase for each ID.
}

\strong{Threshold syntax:}
\itemize{
  \item single-threshold forms such as \code{"<5"}, \code{"<=10"},
  \code{">3"}, \code{">=0"}, \code{"==0"},
  \item range forms for \code{thresholdClim} such as \code{"between(5,10)"}
  or \code{"5:10"}, both interpreted inclusively.
}

\code{thresholdDays} must use a single-threshold form such as \code{">5"}.
}
\note{
If the dendrometer and climate datasets have different time spans, analysis is
automatically restricted to their common overlap.
}
\examples{
\donttest{
data(gf_nepa17)
data(ktm_rain17)

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

head(rel_out$adverse_change)
head(rel_out$normal_change)
head(rel_out$full_period_change)
head(rel_out$continuous_full_period_change)
head(rel_out$period_info)

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

}
\references{
Raffelsbauer V, Spannl S, Peña K, Pucha-Cofrep D, Steppe K, Bräuning A (2019).
Tree Circumference Changes and Species-Specific Growth Recovery After Extreme Dry Events
in a Montane Rainforest in Southern Ecuador.
\emph{Frontiers in Plant Science}, 10, 342.
\doi{10.3389/fpls.2019.00342}
}
\seealso{
\code{\link[dendRoAnalyst:dendro.resample]{dendro.resample}},
\code{\link{phase.zg}},
\code{\link{phase.sc}}
}
