% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plot_SC_output.R
\name{plot.SC_output}
\alias{plot.SC_output}
\title{Plot method for stem-cycle output}
\usage{
\method{plot}{SC_output}(
  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{
\item{x}{Object of class \code{"SC_output"} returned by \code{phase.sc()}.}

\item{y}{Unused.}

\item{DOY}{Optional numeric vector of length 2 giving start and end
day-of-year.}

\item{Year}{Optional numeric year used together with \code{DOY}.}

\item{type}{Plot type. One of
\code{"points"}, \code{"ribbon"}, \code{"transition"},
\code{"balance"}, \code{"increment"}, \code{"frequency"},
\code{"heatmap"}, or \code{"boxplot"}.}

\item{temporal}{Temporal scale: \code{"raw"}, \code{"daily"}, or
\code{"monthly"}. For \code{type = "boxplot"}, use \code{"daily"} or
\code{"monthly"}. For \code{type = "balance"}, \code{"frequency"}, and
\code{"heatmap"}, \code{"raw"} is internally treated as daily summary and
a warning is emitted.}

\item{x_axis}{X-axis style for time-based plots. One of \code{"time"} or
\code{"doy"}. When \code{"doy"} is used, timestamps are converted to
day-of-year on the x-axis. For \code{temporal = "monthly"}, \code{"doy"}
is not meaningful and time is used instead.}

\item{balance_mode}{For \code{type = "balance"}, controls how phase balance
is drawn. One of \code{"time_of_day"} or \code{"duration"}.
\code{"time_of_day"} draws continuous phase intervals along the y-axis
from 0 to 24 h, preserving when phases occurred within each day.
\code{"duration"} draws stacked bars showing total time spent in each
phase per day or month.}

\item{stat}{For \code{type = "boxplot"}, one of
\code{"Duration_h"}, \code{"Duration_m"}, \code{"Magnitude"}, or
\code{"rate"}.}

\item{phase}{For \code{type = "boxplot"}, one of
\code{"all"}, \code{"Shrinkage"}, \code{"Expansion"}, or
\code{"Increment"}.}

\item{cols}{Vector of three colours for Shrinkage, Expansion, and Increment.}

\item{phNames}{Vector of three labels for the three phase names.}

\item{transition_linetype}{Line type used for transition markers in
\code{type = "transition"}.}

\item{transition_alpha}{Transparency of transition markers.}

\item{singleton_as_points}{Logical. If \code{TRUE}, the boxplot panel falls
back to a point plot when every group contains only one value.}

\item{...}{Unused.}
}
\value{
A \code{ggplot2} object, returned invisibly.
}
\description{
Unified S3 plotting method for objects returned by \code{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 \code{type = "balance"}, two plotting modes are available. With
\code{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 \code{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 \code{temporal = "daily"}, the y-axis is hours per day. With
\code{temporal = "monthly"}, the y-axis is hours per month.
}
\details{
Plot types:
\itemize{
  \item \code{"points"}: dendrometer series with points coloured by phase.
  \item \code{"ribbon"}: dendrometer series with background ribbons for
        contiguous phases.
  \item \code{"transition"}: dendrometer series with vertical lines at phase
        changes.
  \item \code{"balance"}: phase balance through time. With
        \code{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 \code{balance_mode = "duration"}, stacked bars show total time
        spent in each phase per day or month.
  \item \code{"increment"}: cumulative increment, phase 3, over time.
  \item \code{"frequency"}: number of phase events starting per day or month.
  \item \code{"heatmap"}: dominant phase by hour-of-day across dates or months.
  \item \code{"boxplot"}: distribution of selected cycle statistics after
        assembling cycle summaries to the chosen daily or monthly time scale.
}

The \code{"frequency"} plot uses \code{SC_cycle}.
The \code{"heatmap"} plot uses \code{SC_phase}.
The \code{"transition"} plot is especially useful for checking whether
smoothing reduced spurious phase switching.
}
\examples{
\donttest{
# 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")
}

}
