plot.ZG_output: Plot method for zero-growth output

In dendRoAnalyst: A Tool for Processing and Analyzing Dendrometer Data

Plot method for zero-growth output

Description

Unified S3 plotting method for objects returned by phase.zg(). It supports time-series views of GRO and TWD, phase ribbons and transitions, TWD-only plots, ABr summaries, phase-balance views, and boxplots of phase-level statistics. For boxplots, phase summaries are first assembled to the requested daily or monthly time scale, and rows with missing x-axis grouping labels are removed before plotting.

The plotting method operates on the two tables returned by phase.zg():

• ZG_phase: point-level time series with TIME, dm, Phases, TWD, and GRO;

• ZG_cycle: phase-level summaries including max.twd, AUC.load, AUC.total, and ABr.value.

Usage

## S3 method for class 'ZG_output'
plot(
  x,
  y = NULL,
  DOY = NULL,
  Year = NULL,
  view = NULL,
  type = c("gro_twd", "phase_ribbon", "transition", "twd", "abr", "phase_summary",
    "balance", "boxplot"),
  temporal = c("raw", "daily", "monthly"),
  x_axis = c("time", "doy"),
  stat = c("Duration_h", "Magnitude", "rate", "max.twd", "Avg.twd", "STD.twd",
    "AUC.load", "AUC.total", "ABr.value"),
  phase = c("auto", "TWD", "GRO", "all"),
  box_group = c("period", "month_of_year", "doy"),
  twd_fun = c("mean", "max"),
  gro_fun = c("max", "mean"),
  transition_linetype = "dashed",
  transition_alpha = 0.55,
  cols = c(TWD = "red", GRO = "blue"),
  singleton_as_points = TRUE,
  balance_mode = c("time_of_day", "duration"),
  balance_gap = c("carry_forward", "observed_only"),
  ...
)

Arguments

x	Object of class "ZG_output" returned by phase.zg().
y	Unused.
DOY	Optional numeric vector of length 2 giving start and end day-of-year for truncating the plotting window.
Year	Optional numeric year used together with DOY.
view	Optional backward-compatible argument. Use "boxplot" to force boxplot mode.
type	Plot type. One of "gro_twd", "phase_ribbon", "transition", "twd", "abr", "phase_summary", "balance", or "boxplot".
temporal	Temporal scale. One of "raw", "daily", or "monthly".
x_axis	X-axis style for time-based plots. One of "time" or "doy". When "doy" is used, timestamps are converted to day-of-year. For temporal = "monthly", "doy" is not meaningful and time is used instead.
stat	For type = "boxplot", one of "Duration_h", "Magnitude", "rate", "max.twd", "Avg.twd", "STD.twd", "AUC.load", "AUC.total", or "ABr.value".
phase	For type = "boxplot", one of "auto", "TWD", "GRO", or "all".
box_group	For type = "boxplot", grouping mode: "period", "month_of_year", or "doy". "period" uses exact dates/months from the already aggregated daily or monthly phase summaries; the other two pool values across repeated seasonal positions. Rows with missing grouping labels are removed before plotting.
twd_fun	Aggregation function for point-level TWD when temporal != "raw". One of "mean" or "max".
gro_fun	Aggregation function for point-level GRO when temporal != "raw". One of "max" or "mean".
transition_linetype	Line type used for transition markers.
transition_alpha	Transparency of transition markers.
cols	Vector of two colours for TWD and GRO. It may be named (c(TWD = "red", GRO = "blue")) or unnamed length 2.
singleton_as_points	Logical. If TRUE, the boxplot panel falls back to a point plot when every group contains only one value.
balance_mode	For type = "balance", one of "time_of_day" or "duration". "time_of_day" draws continuous TWD/GRO intervals along the y-axis from 0 to 24 h, preserving when phases occurred within each day. "duration" draws stacked bars of total hours spent in each phase per day or month.
balance_gap	For type = "balance", one of "carry_forward" or "observed_only". "carry_forward" assigns gaps to the previous observed phase; "observed_only" counts only observed intervals.
...	Unused.

Details

ABr formula shown by this plot method.

When type = "abr" or when stat = "ABr.value" is used in boxplots, the displayed values come directly from phase.zg():

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

where

AUC_{load} = \int_{t_{start}}^{t_{max}} TWD(t)\,dt

and

AUC_{total} = \int_{t_{start}}^{t_{end}} TWD(t)\,dt.

This function does not recompute ABr or AUC values; it only visualizes the values already stored in the ZG_output object.

Aggregation behavior.

For temporal = "daily" or "monthly", point-level series are aggregated before plotting. TWD and GRO can be summarized using "mean" or "max", depending on twd_fun and gro_fun.

For phase-level summaries in ZG_cycle, the plot method aggregates statistics by daily or monthly period. In those aggregated summaries:

• Duration_h, Magnitude, AUC.load, AUC.total, and ABr.value are summed;

• max.twd is taken as the maximum;

• Avg.twd and STD.twd are averaged;

• rate is recalculated from aggregated magnitude and duration.

Phase balance.

For type = "balance", two balance styles are available through balance_mode. With balance_mode = "time_of_day", the plot draws TWD and GRO intervals on a 0–24 hour y-axis, preserving the order in which phases occurred within each day, similar to the balance option in plot.SC_output(). With balance_mode = "duration", the plot draws stacked bars showing the total number of hours spent in each phase. Missing or irregular intervals can be handled with balance_gap.

Boxplot statistics.

The following phase-level variables can be visualized in type = "boxplot". For box_group = "period", boxplots are drawn on a continuous date axis spanning the selected multi-annual data window, so empty days or months remain visible as gaps rather than being removed from the x-axis:

• "Duration_h"

• "Magnitude"

• "rate"

• "max.twd"

• "Avg.twd"

• "STD.twd"

• "AUC.load"

• "AUC.total"

• "ABr.value"

Phase handling.

For phase = "auto", TWD-specific statistics (max.twd, Avg.twd, STD.twd, AUC.load, AUC.total, ABr.value) automatically select TWD phases, whereas GRO-specific variables (Magnitude, rate) select GRO phases.

Value

A ggplot2 object, returned invisibly.

Examples

# data(gf_nepa17)
# zg <- phase.zg(df = gf_nepa17[1:500, ], TreeNum = 1, beta = 0.1)

# Raw GRO and TWD time series
# plot(zg)

# Daily aggregated series
# plot(zg, temporal = "daily")

# Monthly TWD plot
# plot(zg, temporal = "monthly", type = "twd")

# ABr bar plot
# plot(zg, temporal = "monthly", type = "abr")

# Daily phase timing, similar to plot.SC_output balance
# plot(zg, type = "balance", temporal = "daily",
#      balance_mode = "time_of_day")

# Stacked phase-duration balance
# plot(zg, type = "balance", temporal = "daily",
#      balance_mode = "duration")

# Transition plot in day-of-year coordinates
# plot(zg, type = "transition", x_axis = "doy",
#      DOY = c(50, 100), Year = 2017)

# Boxplots of peak TWD
# plot(zg, type = "boxplot", stat = "max.twd",
#      temporal = "daily", box_group = "doy")

# Boxplots of AUC.load
# plot(zg, type = "boxplot", stat = "AUC.load",
#      temporal = "monthly", box_group = "month_of_year")

# Boxplots of ABr.value
# plot(zg, type = "boxplot", stat = "ABr.value",
#      temporal = "monthly", box_group = "month_of_year")
# plot(zg, view = "boxplot", stat = "ABr.value", temporal = "monthly")

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