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 = 1,
  abr_adaptive_beta = FALSE,
  abr_duration_reference_h = 24,
  twd_reference = 1,
  max_twd_reference = NULL,
  twd_max_reference = NULL,
  slope_load_reference = NULL,
  slope_recovery_reference = NULL,
  drought_indices = TRUE,
  predawn_hours = c(0, 6),
  midday_hours = c(10, 16),
  season_months = 5:10,
  mds_probability = 0.99,
  min_mds_n = 30
)

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 duration exponent for the peak-weighted event-burden ABr formula. Defaults to 1. In the current formulation this is used as a fixed exponent for direct TWD phase duration.
abr_adaptive_beta	Logical retained for backward compatibility. The current peak-weighted formulation does not use slope-adaptive beta for ABr.value.raw; loading/recovery slope variables are returned only as diagnostics. If TRUE, a warning is issued and the fixed beta is still used.
abr_duration_reference_h	Positive numeric scalar used to scale direct phase duration Duration_h before applying beta. The default 24 expresses event duration in days.
twd_reference	Reference used to standardize Avg.twd and to report max.twd.std. The default is 1, which means twd.average.standardized = Avg.twd / 1 and preserves absolute TWD-amplitude differences among trees, species, and sites. Use NULL or "tree_mean" to divide by the mean Avg.twd of all TWD phases in the analysed series. Use "tree_max" to divide by the maximum Avg.twd observed in the analysed tree. Alternatively, provide another single positive numeric value as a common reference for several trees.
max_twd_reference	Deprecated alias for twd_reference; kept for backward compatibility.
twd_max_reference	Deprecated alias for twd_reference; kept for backward compatibility.
slope_load_reference	Optional positive numeric scalar used to standardize slope.load.twd. If NULL, the mean loading slope of all TWD phases in the analysed series is used.
slope_recovery_reference	Optional positive numeric scalar used to standardize slope.recovery.twd. If NULL, the mean recovery slope of all TWD phases in the analysed series is used.
drought_indices	Logical. If TRUE, calculate and return the daily drought-index table ZG_drought. Defaults to TRUE.
predawn_hours	Numeric vector of length two giving the pre-dawn hour window used for TWDpredawn and the pre-dawn maximum stem radius used in MDS. Defaults to c(0, 6).
midday_hours	Numeric vector of length two giving the midday hour window used for the midday minimum stem radius in MDS and TWDmidday. Defaults to c(10, 16).
season_months	Integer vector giving the months used to estimate MDSmax. Defaults to May-October, 5:10.
mds_probability	Numeric probability used to calculate MDSmax from vegetation-season MDS values. Defaults to 0.99.
min_mds_n	Integer. Minimum number of valid seasonal MDS values expected for a stable MDSmax estimate. A warning is issued below this value. Defaults to 30.

Details

The compressed event index is ABr.value = log10(1 + ABr.value.raw / 0.01). The fixed scale 0.01 is shared across trees and sites. ABr.value.log1p remains an alias of this new value; ABr.value.pct remains 100 times the raw value. Recompute older saved results to obtain the new columns.

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)

• AUC.recovery (mm*h): post-peak residual deficit area, calculated as AUC.total - AUC.load (TWD only)

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

• ABr.value.raw: peak-weighted event-burden index for TWD phases, calculated as

  ABr = twd.average.standardized \times max.twd \times duration.twd.days^{beta}

  where twd.average.standardized = Avg.twd / twd_reference and duration.twd.days = Duration_h / abr_duration_reference_h. With the defaults twd_reference = 1, beta = 1, and abr_duration_reference_h = 24, the index is an average-intensity and peak-weighted mm day burden. Returned as NA for GRO phases.

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.

Daily drought-index output (ZG_drought). If drought_indices = TRUE, the returned list also contains ZG_drought, a daily table with maximum daily shrinkage (MDS), reference maximum daily shrinkage (MDSmax), normalized maximum daily shrinkage (MDSnorm), pre-dawn tree water deficit (TWDpredawn), and normalized pre-dawn tree water deficit (TWDnorm). These variables follow the definitions used by Peters et al. (2025), where MDSmax is calculated by default as the 99th percentile of vegetation-season MDS values. The function calculates these parameters only; it does not reproduce the full physiological threshold modelling workflow of Peters et al. (2025).

Peak-weighted event-burden ABr output. The returned phase table uses a peak-weighted ABr by default. Mean TWD is standardized by a generic TWD reference. The default reference is fixed at 1, so twd.average.standardized = Avg.twd / 1; this preserves absolute amplitude differences among trees, species, and sites. The main index is returned as ABr.value.raw:

ABr.value.raw = twd.average.standardized \times max.twd \times (Duration_h / abr_duration_reference_h)^{beta}

where twd.average.standardized = Avg.twd / twd_reference. With the default twd_reference = 1, abr_duration_reference_h = 24, and beta = 1, the index is expressed as mm day and gives high values only to events that combine sustained average TWD, high maximum TWD, and long duration. Setting twd_reference = NULL or "tree_mean" standardizes by the tree-level mean Avg.twd.

The AUC-derived columns AUC.total, duration.twd.equiv_h, and duration.twd.equiv_days are still returned as diagnostics, but they no longer control ABr.value.raw. Loading and recovery slope columns are also retained as diagnostic descriptors.

The percentage output ABr.value.pct is calculated as 100 * ABr.value.raw, and ABr.value.log1p is log10(1 + ABr.value.pct).

Value

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

• ZG_cycle: one row per contiguous phase with columns Tree, Phases, Start, End, Duration_h, DOY, GRO columns Magnitude and rate, TWD columns max.twd, Max.twd.time, Avg.twd, STD.twd, AUC.load, AUC.total, AUC.recovery, and optimized ABr columns duration.twd.equiv_h, duration.twd.equiv_days, duration.twd.days, max.twd.std, twd.average.standardized, loading.duration_h, recovery.duration_h, slope.load.twd, slope.recovery.twd, slope.load.twd.std, slope.recovery.twd.std, recovery.slowness.std, slope.stress.std, ABr.beta.event, ABr.value.raw, ABr.value.pct, and ABr.value.log1p.

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

• ZG_drought: daily drought-index table returned when drought_indices = TRUE. Columns include MDS, MDSmax, MDSnorm, TWDpredawn, and TWDnorm.

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.

AUC.recovery

Numeric; post-peak residual deficit area, calculated as AUC.total - AUC.load.

duration.twd.equiv_h

Numeric; equivalent duration of the event at maximum TWD, AUC.total / max.twd.

max.twd.std

Numeric; max.twd standardized by the selected TWD reference: tree mean of Avg.twd, tree maximum of Avg.twd, or a user-defined numeric value.

twd.reference

Numeric; TWD reference used to standardize Avg.twd and report max.twd.std.

twd.reference.method

Character; method used to define twd.reference.

twd.average.standardized

Numeric; Avg.twd divided by twd_reference; with the default reference of 1, this is equal to Avg.twd expressed relative to one TWD measurement unit.

duration.twd.days

Numeric; direct phase duration scaled by ABr.duration.reference_h; with the default reference of 24 h, this is duration in days.

loading.duration_h

Numeric; duration from phase start to Max.twd.time.

recovery.duration_h

Numeric; duration from Max.twd.time to phase end.

slope.load.twd

Numeric; loading slope of TWD, max.twd / loading.duration_h. Larger values indicate faster shrinkage or deficit loading.

slope.recovery.twd

Numeric; recovery slope of TWD, max.twd / recovery.duration_h. Larger values indicate faster recovery.

slope.load.twd.std

Numeric; slope.load.twd standardized by the mean loading slope, unless slope_load_reference is supplied.

slope.recovery.twd.std

Numeric; slope.recovery.twd standardized by the mean recovery slope, unless slope_recovery_reference is supplied.

recovery.slowness.std

Numeric; inverse standardized recovery slope, 1 / slope.recovery.twd.std. Larger values indicate slower recovery.

slope.stress.std

Numeric; combined stress slope, sqrt(slope.load.twd.std * recovery.slowness.std). If either separate slope cannot be estimated because the maximum occurs at the event boundary, the function falls back internally to standardized total-event slope.

ABr.beta.event

Numeric; fixed duration exponent used for ABr in the peak-weighted formulation.

ABr.duration.reference_h

Numeric; reference duration in hours used to scale direct phase duration before applying beta.

ABr.duration.factor

Numeric; duration.twd.days^ABr.beta.event.

ABr.value.raw

Numeric; peak-weighted event-level ABr burden for TWD phases, twd.average.standardized * max.twd * ABr.duration.factor. NA for GRO.

ABr.value.pct

Numeric; percentage-scaled ABr value, 100 * ABr.value.raw.

ABr.value.log1p

Numeric; log-transformed percentage-scaled ABr value, calculated as log10(1 + ABr.value.pct), useful for plotting strongly right-skewed event burdens.

Avg.twd, STD.twd

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

DOY

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

Column definitions (ZG_drought)

The ZG_drought table is returned only when drought_indices = TRUE. It contains one row per calendar day.

Tree

Character or integer; dendrometer series identifier based on TreeNum.

DATE

Date; calendar day represented by the row.

Year, Month, DOY

Integer; calendar year, month, and day-of-year.

MDS

Numeric; maximum daily shrinkage in mm, calculated as the difference between the pre-dawn maximum stem radius and the midday minimum stem radius, predawn_dm_max - midday_dm_min.

MDSmax

Numeric; reference maximum daily shrinkage in mm. By default, this is the mds_probability quantile, usually 0.99, of valid MDS values within season_months.

MDSnorm

Numeric; normalized maximum daily shrinkage, MDS / MDSmax.

TWDpredawn

Numeric; pre-dawn tree water deficit in mm, calculated from the selected predawn_hours window.

TWDnorm

Numeric; normalized pre-dawn tree water deficit, TWDpredawn / MDSmax.

TWDmidday

Numeric; midday tree water deficit in mm, calculated from the selected midday_hours window.

TWDnorm_midday

Numeric; normalized midday tree water deficit, TWDmidday / MDSmax.

TWDdaily_min, TWDdaily_max

Numeric; minimum and maximum TWD observed during the calendar day.

TWDnorm_daily_max

Numeric; maximum daily TWD normalized by MDSmax.

predawn_dm_max

Numeric; maximum dendrometer value observed within predawn_hours.

midday_dm_min

Numeric; minimum dendrometer value observed within midday_hours.

n_obs

Integer; number of valid observations available for the day.

n_predawn

Integer; number of observations within the pre-dawn window.

n_midday

Integer; number of observations within the midday window.

MDSmax_probability

Numeric; probability used to estimate MDSmax.

MDSmax_n

Integer; number of seasonal MDS values used to estimate MDSmax.

season_months

Character; comma-separated list of months used for estimating MDSmax.

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

Peters RL et al. (2025) Normalized tree water deficit: an automated dendrometer signal to quantify drought stress in trees. New Phytologist. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1111/nph.70266")}

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)
head(zg$ZG_drought, 5)

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

dendRoAnalyst documentation built on Oct. 2, 2026, 9:06 a.m.