% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/phase.zg.R
\name{phase.zg}
\alias{phase.zg}
\title{Apply the Zero-Growth (ZG) approach to segment dendrometer data into TWD/GRO phases}
\usage{
phase.zg(df, TreeNum, smoothing = NULL, beta = 0.1)
}
\arguments{
\item{df}{A data frame with the \strong{first column} containing date-time
(character, \code{POSIXct}, or \code{Date} convertible to \code{POSIXct} using
\code{lubridate::ymd_hms}) and the \strong{subsequent columns} containing one or
more dendrometer series (mm) at constant temporal resolution.}

\item{TreeNum}{Integer index of the dendrometer series column to analyze.
For example, \code{TreeNum = 1} refers to \code{df[[2]]} (the first dm column after
the time column).}

\item{smoothing}{\code{NULL} (default) for no smoothing, or a numeric value
between 1 and 24 specifying the smoothing window in \strong{hours} used by
\code{smooth_dm(method = "median_mean")} for phase labeling.}

\item{beta}{Numeric scalar giving the exponent applied to the effective loading
duration in the ABr formula. Defaults to \code{0.1}. Set \code{beta = 0} to
make ABr depend only on \code{max.twd}.}
}
\value{
A named list of class \code{"ZG_output"} with two tibbles:
\itemize{
  \item \code{ZG_cycle}: one row per contiguous phase with columns
        \code{Phases}, \code{Start}, \code{End}, \code{Duration_h}, \code{Magnitude}, \code{rate},
        \code{max.twd}, \code{Max.twd.time}, \code{AUC.load}, \code{AUC.total}, \code{ABr.value},
        \code{Avg.twd}, \code{STD.twd}, \code{DOY}.
  \item \code{ZG_phase}: point-level data with columns
        \code{TIME}, \code{dm}, \code{Phases}, \code{TWD}, \code{GRO}.
}
}
\description{
Implements the Zero-Growth approach (Zweifel et al., 2016) on a single
dendrometer series to (i) classify each timestamp into \strong{tree water deficit}
(TWD; reversible shrinkage/expansion) or \strong{growth} (GRO; irreversible
expansion), (ii) summarize each contiguous phase (start/end, duration,
magnitude, rates, TWD statistics), and (iii) optionally smooth the raw
series prior to phase assignment to reduce spurious phase flips.

The growth line is computed as the running cumulative maximum of the
(raw or smoothed) dendrometer series. TWD is defined as the vertical
distance between the growth line and the observed measurement.
}
\details{
\strong{Phase assignment.}
Let \eqn{y_t} be the dendrometer measurement (raw or smoothed). The growth
line is \eqn{g_t=\max_{s\le t}(y_s)}. Points with \eqn{y_t = g_t} are labeled
\strong{GRO} (phase = 2). Points with \eqn{y_t < g_t} are labeled \strong{TWD}
(phase = 1). Contiguous runs of identical labels are summarized into
individual phases.

\strong{Summaries per phase (ZG_cycle).}
For each phase, the function returns:
\itemize{
  \item \code{Phases} (1 = TWD, 2 = GRO)
  \item \code{Start}, \code{End} (\code{POSIXct})
  \item \code{Duration_h} (hours)
  \item \code{Magnitude} (mm): for GRO only, computed from the \emph{growth line}
        as \eqn{\Delta g = g_{\mathrm{end}}-g_{\mathrm{start}}}; \code{NA} for TWD
  \item \code{rate} (\eqn{\mu}m/h): \code{Magnitude * 1000 / Duration_h} (GRO only)
  \item \code{max.twd} (mm), \code{Max.twd.time} (\code{POSIXct}): peak TWD and its time (TWD only)
  \item \code{Avg.twd} (mm), \code{STD.twd} (mm): mean and SD of TWD within the phase (TWD only)
  \item \code{AUC.load} (mm*h): area under the TWD curve from phase start to \code{Max.twd.time} (TWD only)
  \item \code{AUC.total} (mm*h): area under the full TWD curve across the phase (TWD only)
  \item \code{DOY}: day-of-year of the phase start
  \item \code{ABr.value}: \emph{Absolut Baumreaktion (ABr)} for TWD phases, defined here as
        \deqn{\mathrm{ABr} = \max(\mathrm{TWD}) \times \left(\frac{AUC_{load}}{\max(\mathrm{TWD})}\right)^{\beta}}
        returned as \code{NA} for GRO phases. This metric anchors severity on the event peak while
        allowing the loading duration to contribute with exponent \code{beta}.
}

\strong{Point-level output (ZG_phase).}
The second element returns the input time series augmented with:
\itemize{
  \item \code{Phases} (1/2), \code{TWD} (= \code{GRO - dm}), and \code{GRO} (growth line).
}

\strong{Smoothing (optional).}
If \code{smoothing} is provided (hours), the function uses
\code{smooth_dm(..., method = "median_mean", window_hours = smoothing)} to create a
smoothed series used \emph{only} for phase assignment; all magnitudes and TWD
statistics are still computed against the \emph{original} \code{dm}. This reduces
short-lived phase flips due to noise. Valid range is 1–24 hours.

\strong{Temporal resolution.}
The function auto-detects the median sampling interval (in minutes) to
parameterize smoothing. If multiple distinct intervals are detected, a
warning is emitted (results may be degraded if resolution is inconsistent).

\strong{Notes & caveats.}
\itemize{
  \item Negative \code{Magnitude} values in GRO phases indicate residual noise or
        insufficient smoothing; a warning is issued.
  \item Very short phases may occur around local extrema; consider smoothing
        or post-filtering minimal run lengths upstream if needed.
  \item Ensure timestamps are regular (or nearly regular) for best results.
}
}
\section{Column definitions (ZG_cycle)}{

\describe{
  \item{Phases}{Integer; 1 = TWD (reversible shrinkage/expansion),
  2 = GRO (irreversible expansion).}
  \item{Start, End}{\code{POSIXct}; phase boundaries.}
  \item{Duration_h}{Numeric; phase duration in hours.}
  \item{Magnitude}{Numeric; GRO-only millimeter change of growth line across the phase. \code{NA} for TWD.}
  \item{rate}{Numeric; GRO-only rate in (\code{Magnitude*1000/Duration_h}).}
  \item{max.twd}{Numeric; peak TWD within the TWD phase.}
  \item{Max.twd.time}{\code{POSIXct}; time of \code{max.twd} within the TWD phase.}
  \item{AUC.load}{Numeric; pre-peak area under the TWD curve in mm*h, integrated from
  phase start to \code{Max.twd.time}.}
  \item{AUC.total}{Numeric; total area under the TWD curve in mm*h across the full TWD phase.}
  \item{ABr.value}{Numeric; Absolut Baumreaktion value for TWD phases,
  \deqn{\max(\mathrm{TWD}) \times \left(\frac{AUC_{load}}{\max(\mathrm{TWD})}\right)^{\beta}} \code{NA} for GRO.}
  \item{Avg.twd, STD.twd}{Numeric; mean and standard deviation of TWD in the phase.}
  \item{DOY}{Integer; day-of-year for the phase start.}
}
}

\examples{
\donttest{
library(dendRoAnalyst)
data(gf_nepa17)

# Minimal example (no smoothing)
zg <- phase.zg(df = gf_nepa17[1:600, ], TreeNum = 1)
head(zg$ZG_cycle, 5)
head(zg$ZG_phase, 5)

# With smoothing (e.g., 6 hours) to reduce short flips
zg6 <- phase.zg(df = gf_nepa17[1:600, ], TreeNum = 1, smoothing = 6, beta = 0.1)
subset(zg6$ZG_cycle, Phases == 1L)[1:5, c("Start","End","max.twd","ABr.value")]
}

}
\references{
Zweifel R, Haeni M, Buchmann N, Eugster W (2016) Are trees able to grow in periods of stem shrinkage?
\emph{New Phytologist}, 211:839–849. \doi{10.1111/nph.13995}
}
