% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plot.dm_growth_fit.R
\name{plot.dm_growth_fit}
\alias{plot.dm_growth_fit}
\title{Plot dendrometer growth-fit results}
\usage{
\method{plot}{dm_growth_fit}(
  x,
  type = c("fit", "season", "residuals", "timing", "overlay", "parameters"),
  series = NULL,
  fit_id = NULL,
  facet_by = c("default", "tree", "year", "none"),
  ncol = NULL,
  normalize = FALSE,
  x_axis = c("default", "season_day", "doy", "date"),
  observed_source = c("processed", "original_daily"),
  show_observed = TRUE,
  show_fitted = TRUE,
  show_timing = TRUE,
  point_alpha = 0.7,
  line_width = 0.8,
  legend_position = "right",
  ...
)
}
\arguments{
\item{x}{An object of class \code{"dm_growth_fit"} returned by
[dm.growth.fit()] or [dm.growth.fit.double()].}

\item{type}{Character string specifying the plot type. One of
\code{"fit"}, \code{"season"}, \code{"residuals"}, \code{"timing"},
\code{"overlay"}, or \code{"parameters"}.}

\item{series}{Optional filter selecting one or more dendrometer series to
plot. May be a character vector of series names. Default is \code{NULL},
meaning all available series are used.}

\item{fit_id}{Optional filter selecting one or more fit identifiers to plot.
May be a character or numeric vector. Numeric values are coerced internally
to character. Default is \code{NULL}, meaning all fits are used.}

\item{facet_by}{Character string controlling faceting layout. One of
\code{"default"}, \code{"tree"}, \code{"year"}, or \code{"none"}.}

\item{ncol}{Optional integer giving the number of columns in faceted plots.
Passed to [ggplot2::facet_wrap()].}

\item{normalize}{Logical. If \code{TRUE}, observed and fitted values are
divided by the maximum observed or fitted value within each curve.}

\item{x_axis}{Character string controlling the x-axis representation. One of
\code{"default"}, \code{"season_day"}, \code{"doy"}, or \code{"date"}.}

\item{observed_source}{Character string controlling which observed daily
series is plotted against the fitted curve. One of \code{"processed"} or
\code{"original_daily"}.}

\item{show_observed}{Logical. If \code{TRUE}, observed values are shown in
plot types where observed data are relevant.}

\item{show_fitted}{Logical. If \code{TRUE}, fitted values are shown in plot
types where fitted curves are relevant.}

\item{show_timing}{Logical. If \code{TRUE}, timing markers are added to
\code{"fit"} and \code{"season"} plots whenever timing information is
available in \code{x$fit_statistics}.}

\item{point_alpha}{Numeric alpha level used for observed points.}

\item{line_width}{Numeric line width used for fitted curves.}

\item{legend_position}{Character string specifying legend position, passed to
[ggplot2::theme()].}

\item{...}{Further arguments passed to or from other methods.}
}
\value{
A \code{ggplot} object.
}
\description{
Creates \pkg{ggplot2}-based plots for objects returned by
[dm.growth.fit()] and [dm.growth.fit.double()].

The plotting method supports multiple views of fitted dendrometer growth
curves, including observed versus fitted trajectories, residuals, timing
summaries, overlays of multiple curves, and distributions of fitted model
parameters.

The x-axis can be displayed as vegetation-season day, calendar day-of-year
(DOY), or actual date, depending on the selected \code{x_axis} argument and
the type of plot.

When \code{x_axis = "date"} and faceting separates individual years or
series-year combinations, each facet receives its own x-axis range. This
avoids plotting one yearly fitted curve inside the full dendrometer time
window when several seasons are present in the input object.
}
\details{
The plotting method returns a \code{ggplot} object. The returned plot can be
further modified using normal \pkg{ggplot2} syntax.

Timing markers are taken from the \code{fit_statistics} table inside the
\code{"dm_growth_fit"} object:
\itemize{
  \item \code{growth_start_*} and \code{growth_end_*} represent growing-season
    timing based on cumulative fitted growth.
  \item \code{rate_start_*} and \code{rate_end_*} represent active-growth
    timing based on the fitted growth-rate curve.
  \item For double-growth fits, pulse-specific timing such as
    \code{pulse1_start_*}, \code{pulse2_start_*}, and \code{separator_*} is
    used in \code{type = "timing"} when available.
}

For yearly fits in southern hemisphere or cross-year custom seasons,
calendar timing variables such as \code{growth_start_day} and
\code{rate_start_day} are interpreted as true calendar DOY, while
\code{*_season_day} variables represent day counts relative to vegetation
season start.

In pooled fits, date-based and calendar-DOY timing fields may be unavailable,
because pooled fits are not anchored to a single season start date.
}
\examples{
\donttest{
# fit <- dm.growth.fit(...)
# plot(fit, type = "fit")
# plot(fit, type = "fit", facet_by = "year", x_axis = "date")
# plot(fit, type = "fit", facet_by = "year", x_axis = "season_day")
# plot(fit, type = "residuals", facet_by = "year")
# plot(fit, type = "timing")
# plot(fit, type = "parameters")
}

}
\seealso{
[dm.growth.fit()], [dm.growth.fit.double()], [summary.dm_growth_fit()]
}
