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

\item{y}{Unused.}

\item{DOY}{Optional numeric vector of length 2 giving start and end
day-of-year for truncating the plotting window.}

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

\item{view}{Optional backward-compatible argument. Use \code{"boxplot"}
to force boxplot mode.}

\item{type}{Plot type. One of \code{"gro_twd"}, \code{"phase_ribbon"},
\code{"transition"}, \code{"twd"}, \code{"abr"},
\code{"phase_summary"}, \code{"balance"}, or \code{"boxplot"}.}

\item{temporal}{Temporal scale. One of \code{"raw"}, \code{"daily"},
or \code{"monthly"}.}

\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. For \code{temporal = "monthly"}, \code{"doy"} is not
meaningful and time is used instead.}

\item{stat}{For \code{type = "boxplot"}, one of
\code{"Duration_h"}, \code{"Magnitude"}, \code{"rate"},
\code{"max.twd"}, \code{"Avg.twd"}, \code{"STD.twd"},
\code{"AUC.load"}, \code{"AUC.total"}, or \code{"ABr.value"}.}

\item{phase}{For \code{type = "boxplot"}, one of \code{"auto"},
\code{"TWD"}, \code{"GRO"}, or \code{"all"}.}

\item{box_group}{For \code{type = "boxplot"}, grouping mode:
\code{"period"}, \code{"month_of_year"}, or \code{"doy"}.
\code{"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.}

\item{twd_fun}{Aggregation function for point-level TWD when
\code{temporal != "raw"}. One of \code{"mean"} or \code{"max"}.}

\item{gro_fun}{Aggregation function for point-level GRO when
\code{temporal != "raw"}. One of \code{"max"} or \code{"mean"}.}

\item{transition_linetype}{Line type used for transition markers.}

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

\item{cols}{Vector of two colours for TWD and GRO. It may be named
(\code{c(TWD = "red", GRO = "blue")}) or unnamed length 2.}

\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{balance_mode}{For \code{type = "balance"}, one of
\code{"time_of_day"} or \code{"duration"}. \code{"time_of_day"} draws
continuous TWD/GRO intervals along the y-axis from 0 to 24 h, preserving
when phases occurred within each day. \code{"duration"} draws stacked bars
of total hours spent in each phase per day or month.}

\item{balance_gap}{For \code{type = "balance"}, one of
\code{"carry_forward"} or \code{"observed_only"}.
\code{"carry_forward"} assigns gaps to the previous observed phase;
\code{"observed_only"} counts only observed intervals.}

\item{...}{Unused.}
}
\value{
A \code{ggplot2} object, returned invisibly.
}
\description{
Unified S3 plotting method for objects returned by \code{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
\code{phase.zg()}:
\itemize{
  \item \code{ZG_phase}: point-level time series with \code{TIME},
        \code{dm}, \code{Phases}, \code{TWD}, and \code{GRO};
  \item \code{ZG_cycle}: phase-level summaries including
        \code{max.twd}, \code{AUC.load}, \code{AUC.total}, and
        \code{ABr.value}.
}
}
\details{
\strong{ABr formula shown by this plot method.}

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

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

where

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

and

\deqn{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 \code{ZG_output} object.

\strong{Aggregation behavior.}

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

For phase-level summaries in \code{ZG_cycle}, the plot method aggregates
statistics by daily or monthly period. In those aggregated summaries:
\itemize{
  \item \code{Duration_h}, \code{Magnitude}, \code{AUC.load},
        \code{AUC.total}, and \code{ABr.value} are summed;
  \item \code{max.twd} is taken as the maximum;
  \item \code{Avg.twd} and \code{STD.twd} are averaged;
  \item \code{rate} is recalculated from aggregated magnitude and duration.
}

\strong{Phase balance.}

For \code{type = "balance"}, two balance styles are available through
\code{balance_mode}. With \code{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
\code{plot.SC_output()}. With \code{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 \code{balance_gap}.

\strong{Boxplot statistics.}

The following phase-level variables can be visualized in
\code{type = "boxplot"}. For \code{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:
\itemize{
  \item \code{"Duration_h"}
  \item \code{"Magnitude"}
  \item \code{"rate"}
  \item \code{"max.twd"}
  \item \code{"Avg.twd"}
  \item \code{"STD.twd"}
  \item \code{"AUC.load"}
  \item \code{"AUC.total"}
  \item \code{"ABr.value"}
}

\strong{Phase handling.}

For \code{phase = "auto"}, TWD-specific statistics
(\code{max.twd}, \code{Avg.twd}, \code{STD.twd}, \code{AUC.load},
\code{AUC.total}, \code{ABr.value}) automatically select TWD phases,
whereas GRO-specific variables (\code{Magnitude}, \code{rate}) select GRO
phases.
}
\examples{
\donttest{
# 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")
}

}
