phase.zg: Apply the Zero-Growth (ZG) approach to segment dendrometer...

In dendRoAnalyst: A Tool for Processing and Analyzing Dendrometer Data

Apply the Zero-Growth (ZG) approach to segment dendrometer data into TWD/GRO phases

Description

Implements the Zero-Growth approach (Zweifel et al., 2016) on a single dendrometer series to (i) classify each timestamp into tree water deficit (TWD; reversible shrinkage/expansion) or 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.

Usage

phase.zg(df, TreeNum, smoothing = NULL, beta = 0.1)

Arguments

df	A data frame with the first column containing date-time (character, POSIXct, or Date convertible to POSIXct using lubridate::ymd_hms) and the subsequent columns containing one or more dendrometer series (mm) at constant temporal resolution.
TreeNum	Integer index of the dendrometer series column to analyze. For example, TreeNum = 1 refers to df[[2]] (the first dm column after the time column).
smoothing	NULL (default) for no smoothing, or a numeric value between 1 and 24 specifying the smoothing window in hours used by smooth_dm(method = "median_mean") for phase labeling.
beta	Numeric scalar giving the exponent applied to the effective loading duration in the ABr formula. Defaults to 0.1. Set beta = 0 to make ABr depend only on max.twd.

Details

Phase assignment. Let y_t be the dendrometer measurement (raw or smoothed). The growth line is g_t=\max_{s\le t}(y_s). Points with y_t = g_t are labeled GRO (phase = 2). Points with y_t < g_t are labeled TWD (phase = 1). Contiguous runs of identical labels are summarized into individual phases.

Summaries per phase (ZG_cycle). For each phase, the function returns:

• Phases (1 = TWD, 2 = GRO)

• Start, End (POSIXct)

• Duration_h (hours)

• Magnitude (mm): for GRO only, computed from the growth line as \Delta g = g_{\mathrm{end}}-g_{\mathrm{start}}; NA for TWD

• rate (\mum/h): Magnitude * 1000 / Duration_h (GRO only)

• max.twd (mm), Max.twd.time (POSIXct): peak TWD and its time (TWD only)

• Avg.twd (mm), STD.twd (mm): mean and SD of TWD within the phase (TWD only)

• AUC.load (mm*h): area under the TWD curve from phase start to Max.twd.time (TWD only)

• AUC.total (mm*h): area under the full TWD curve across the phase (TWD only)

• DOY: day-of-year of the phase start

• ABr.value: Absolut Baumreaktion (ABr) for TWD phases, defined here as

  \mathrm{ABr} = \max(\mathrm{TWD}) \times \left(\frac{AUC_{load}}{\max(\mathrm{TWD})}\right)^{\beta}

  returned as NA for GRO phases. This metric anchors severity on the event peak while allowing the loading duration to contribute with exponent beta.

Point-level output (ZG_phase). The second element returns the input time series augmented with:

• Phases (1/2), TWD (= GRO - dm), and GRO (growth line).

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

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).

Notes & caveats.

• Negative Magnitude values in GRO phases indicate residual noise or insufficient smoothing; a warning is issued.

• Very short phases may occur around local extrema; consider smoothing or post-filtering minimal run lengths upstream if needed.

• Ensure timestamps are regular (or nearly regular) for best results.

Value

A named list of class "ZG_output" with two tibbles:

• ZG_cycle: one row per contiguous phase with columns Phases, Start, End, Duration_h, Magnitude, rate, max.twd, Max.twd.time, AUC.load, AUC.total, ABr.value, Avg.twd, STD.twd, DOY.

• ZG_phase: point-level data with columns TIME, dm, Phases, TWD, GRO.

Column definitions (ZG_cycle)

Phases

Integer; 1 = TWD (reversible shrinkage/expansion), 2 = GRO (irreversible expansion).

Start, End

POSIXct; phase boundaries.

Duration_h

Numeric; phase duration in hours.

Magnitude

Numeric; GRO-only millimeter change of growth line across the phase. NA for TWD.

rate

Numeric; GRO-only rate in (Magnitude*1000/Duration_h).

max.twd

Numeric; peak TWD within the TWD phase.

Max.twd.time

POSIXct; time of max.twd within the TWD phase.

AUC.load

Numeric; pre-peak area under the TWD curve in mm*h, integrated from phase start to Max.twd.time.

AUC.total

Numeric; total area under the TWD curve in mm*h across the full TWD phase.

ABr.value

Numeric; Absolut Baumreaktion value for TWD phases,

\max(\mathrm{TWD}) \times \left(\frac{AUC_{load}}{\max(\mathrm{TWD})}\right)^{\beta}

NA for GRO.

Avg.twd, STD.twd

Numeric; mean and standard deviation of TWD in the phase.

DOY

Integer; day-of-year for the phase start.

References

Zweifel R, Haeni M, Buchmann N, Eugster W (2016) Are trees able to grow in periods of stem shrinkage? New Phytologist, 211:839–849. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1111/nph.13995")}

Examples

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")]

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