plot.SC_output: Plot method for stem-cycle output

In dendRoAnalyst: A Tool for Processing and Analyzing Dendrometer Data

Plot method for stem-cycle output

Description

Unified S3 plotting method for objects returned by phase.sc(). Supports raw phase timelines, phase ribbons, transition diagnostics, daily/monthly phase balance, cumulative increment, event frequency, phase heatmaps, and daily/monthly boxplots of phase statistics.

For type = "balance", two plotting modes are available. With balance_mode = "time_of_day", phases are drawn as continuous within-day intervals, and the y-axis represents hour of day from 0 to 24. This makes the timing of shrinkage, expansion, and increment visible. For example, if shrinkage occurs from 00:00 to 05:00, expansion from 05:00 to 15:00, and shrinkage again from 15:00 to 24:00, these intervals are shown as continuous coloured blocks along the y-axis.

With balance_mode = "duration", the older stacked-bar behaviour is used. In that case, the y-axis represents the amount of time spent in each phase. With temporal = "daily", the y-axis is hours per day. With temporal = "monthly", the y-axis is hours per month.

Usage

## S3 method for class 'SC_output'
plot(
  x,
  y = NULL,
  DOY = NULL,
  Year = NULL,
  type = c("points", "ribbon", "transition", "balance", "increment", "frequency",
    "heatmap", "boxplot"),
  temporal = c("raw", "daily", "monthly"),
  x_axis = c("time", "doy"),
  balance_mode = c("time_of_day", "duration"),
  stat = c("Duration_h", "Duration_m", "Magnitude", "rate"),
  phase = c("all", "Shrinkage", "Expansion", "Increment"),
  cols = c("#fee8c8", "#fdbb84", "#e34a33"),
  phNames = c("Shrinkage", "Expansion", "Increment"),
  transition_linetype = "dashed",
  transition_alpha = 0.55,
  singleton_as_points = TRUE,
  ...
)

Arguments

x	Object of class "SC_output" returned by phase.sc().
y	Unused.
DOY	Optional numeric vector of length 2 giving start and end day-of-year.
Year	Optional numeric year used together with DOY.
type	Plot type. One of "points", "ribbon", "transition", "balance", "increment", "frequency", "heatmap", or "boxplot".
temporal	Temporal scale: "raw", "daily", or "monthly". For type = "boxplot", use "daily" or "monthly". For type = "balance", "frequency", and "heatmap", "raw" is internally treated as daily summary and a warning is emitted.
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 on the x-axis. For temporal = "monthly", "doy" is not meaningful and time is used instead.
balance_mode	For type = "balance", controls how phase balance is drawn. One of "time_of_day" or "duration". "time_of_day" draws continuous phase intervals along the y-axis from 0 to 24 h, preserving when phases occurred within each day. "duration" draws stacked bars showing total time spent in each phase per day or month.
stat	For type = "boxplot", one of "Duration_h", "Duration_m", "Magnitude", or "rate".
phase	For type = "boxplot", one of "all", "Shrinkage", "Expansion", or "Increment".
cols	Vector of three colours for Shrinkage, Expansion, and Increment.
phNames	Vector of three labels for the three phase names.
transition_linetype	Line type used for transition markers in type = "transition".
transition_alpha	Transparency of transition markers.
singleton_as_points	Logical. If TRUE, the boxplot panel falls back to a point plot when every group contains only one value.
...	Unused.

Details

Plot types:

• "points": dendrometer series with points coloured by phase.

• "ribbon": dendrometer series with background ribbons for contiguous phases.

• "transition": dendrometer series with vertical lines at phase changes.

• "balance": phase balance through time. With balance_mode = "time_of_day", phase intervals are drawn continuously along the y-axis from 0 to 24 h, so the timing of shrinkage, expansion, and increment within each day is visible. With balance_mode = "duration", stacked bars show total time spent in each phase per day or month.

• "increment": cumulative increment, phase 3, over time.

• "frequency": number of phase events starting per day or month.

• "heatmap": dominant phase by hour-of-day across dates or months.

• "boxplot": distribution of selected cycle statistics after assembling cycle summaries to the chosen daily or monthly time scale.

The "frequency" plot uses SC_cycle. The "heatmap" plot uses SC_phase. The "transition" plot is especially useful for checking whether smoothing reduced spurious phase switching.

Value

A ggplot2 object, returned invisibly.

Examples

# data(gf_nepa17)
# sc <- phase.sc(df = gf_nepa17, TreeNum = 1, smoothing = 12)

# plot(sc)
# plot(sc, type = "ribbon")
# plot(sc, type = "transition")

# Daily within-day phase timing
# plot(sc, type = "balance", temporal = "daily")

# Daily within-day phase timing for selected DOY range
# plot(sc, type = "balance", temporal = "daily",
#      DOY = c(150, 160), Year = 2023)

# Old stacked-duration balance plot
# plot(sc, type = "balance", temporal = "daily",
#      balance_mode = "duration")

# Monthly stacked duration
# plot(sc, type = "balance", temporal = "monthly",
#      balance_mode = "duration")

# Boxplots
# plot(sc, type = "boxplot", stat = "Magnitude", temporal = "monthly")
# plot(sc, type = "boxplot", stat = "Duration_h",
#      temporal = "daily", phase = "Shrinkage")

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