% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dm_wavelet.R
\name{plot.dm_wavelet}
\alias{plot.dm_wavelet}
\title{Plot method for wavelet analysis output}
\usage{
\method{plot}{dm_wavelet}(
  x,
  y = NULL,
  series = NULL,
  type = c("power", "average", "series"),
  facet = TRUE,
  log_period = TRUE,
  log_power = TRUE,
  clip_quantile = c(0.01, 0.99),
  show_sig = TRUE,
  show_coi = TRUE,
  coi_fill = "white",
  coi_alpha = 0.45,
  siglvl = 0.05,
  sig_color = "black",
  sig_size = 0.4,
  main = NULL,
  ...
)
}
\arguments{
\item{x}{An object of class \code{"dm_wavelet"} returned by
\code{dm_wavelet()}.}

\item{y}{Unused.}

\item{series}{Optional character vector giving one or more series names to
plot. If \code{NULL}, the first available series is used.}

\item{type}{Character string specifying the plot type. One of:
\describe{
  \item{`"power"`}{Wavelet power spectrum as a raster image.}
  \item{`"average"`}{Average wavelet power spectrum across the full time series.}
  \item{`"series"`}{Original analyzed series over time.}
}}

\item{facet}{Logical. If \code{TRUE} and more than one series is selected,
panels are faceted by series.}

\item{log_period}{Logical. If \code{TRUE}, the period axis is shown on a
log10 scale where applicable.}

\item{log_power}{Logical. If \code{TRUE} and \code{type = "power"}, the
plotted wavelet power is transformed using \code{log10(power + eps)} to
improve contrast.}

\item{clip_quantile}{Optional numeric vector of length 2 giving lower and
upper quantiles used to clip wavelet power before plotting, for example
\code{c(0.01, 0.99)}. This is useful when a few extreme values dominate the
colour scale. Use \code{NULL} to disable clipping.}

\item{show_sig}{Logical. If \code{TRUE}, overlays significance information
when available. For \code{type = "average"}, significant periods are marked
as points. For \code{type = "power"}, significant regions are shown as
contour lines.}

\item{show_coi}{Logical. If \code{TRUE} and \code{type = "power"}, the cone of
influence (COI) is added as a shaded overlay.}

\item{coi_fill}{Fill colour used for the cone of influence shading.}

\item{coi_alpha}{Numeric transparency of the cone of influence shading.}

\item{siglvl}{Numeric significance threshold between 0 and 1. Default is
\code{0.05}.}

\item{sig_color}{Colour used for significance overlays.}

\item{sig_size}{Line width or point size used for significance overlays.}

\item{main}{Optional plot title. If \code{NULL}, a default title is used.}

\item{...}{Further arguments passed to or from other methods. Currently unused.}
}
\value{
A \code{ggplot2} object.
}
\description{
S3 plotting method for objects returned by \code{dm_wavelet()}.

The function provides three main visualization types:
\itemize{
  \item \code{"series"}: plots the analyzed input dendrometer series over time,
  \item \code{"average"}: plots the average wavelet power spectrum against period,
  \item \code{"power"}: plots the full wavelet power spectrum as a time-period image.
}

Periods are shown in \strong{hours}, regardless of the original temporal
resolution of the input series. For power plots, the x-axis shows the actual
time series timestamps and the y-axis shows the wavelet period in hours.
}
\details{
For \code{type = "power"}, the function uses the wavelet power matrix stored
in the \code{"dm_wavelet"} object and converts the Fourier periods to hours.
The power plot may also show:
\itemize{
  \item significance contours, when p-values are available,
  \item the cone of influence (COI), when COI information is available.
}

For \code{type = "average"}, the function plots the average wavelet power
spectrum and may optionally indicate significant periods when average-spectrum
p-values are available.

For \code{type = "series"}, the original analyzed series are plotted without
any wavelet transformation.
}
\examples{
\donttest{
wv <- dm_wavelet(
  x = gf_nepa17,
  TreeNum = 1:2,
  source = "raw",
  make_pval = TRUE,
  verbose = FALSE
)

# original series
plot(wv, type = "series")

# average wavelet power
plot(wv, type = "average")

# full power spectrum
plot(wv, type = "power")

# one selected series
plot(wv, series = names(wv$results)[1], type = "power")

# stronger contrast in the power plot
plot(
  wv,
  type = "power",
  log_power = TRUE,
  clip_quantile = c(0.05, 0.95)
)
}

}
\seealso{
\code{\link{dm_wavelet}}, \code{\link[ggplot2]{ggplot}}
}
