% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dm_wavelet_coherence.R
\name{dm_wavelet_coherence}
\alias{dm_wavelet_coherence}
\title{Wavelet coherence between dendrometer and climate series}
\usage{
dm_wavelet_coherence(
  dm,
  clim,
  TreeNum = "all",
  clim_vars = "all",
  source = c("auto", "raw", "detrended", "first_diff"),
  detrended_col = c("detrended_data"),
  dm_fun = c("mean", "max", "min", "sum"),
  clim_funs = "mean",
  na_action = c("interpolate", "fail"),
  loess_span = 0,
  dj = 1/20,
  lowerPeriod = NULL,
  upperPeriod = NULL,
  window.type.t = 1,
  window.type.s = 1,
  window.size.t = 5,
  window.size.s = 1/4,
  make.pval = TRUE,
  make_pval = NULL,
  method = "white.noise",
  n.sim = 10,
  n_sim = NULL,
  verbose = TRUE
)
}
\arguments{
\item{dm}{Dendrometer input. Either a data frame with time in the first column
or an object of class \code{"dm_detrended"}.}

\item{clim}{Climate data frame. The first column must be time; remaining
selected columns must be numeric climate variables.}

\item{TreeNum}{Dendrometer series selector: \code{"all"}, numeric indices,
or character names.}

\item{clim_vars}{Climate variable selector: \code{"all"}, numeric indices,
or character names.}

\item{source}{One of \code{"auto"}, \code{"raw"}, \code{"detrended"},
or \code{"first_diff"}.}

\item{detrended_col}{For \code{dm_detrended} input, which table to use.}

\item{dm_fun}{Aggregation function for dendrometer resampling: one of
\code{"mean"}, \code{"max"}, \code{"min"}, \code{"sum"}.}

\item{clim_funs}{Either a single aggregation function applied to all climate
variables, or a named character vector such as
\code{c(temp = "mean", VPD = "mean", prec = "sum")}.}

\item{na_action}{One of \code{"interpolate"} or \code{"fail"}.}

\item{loess_span}{Detrending span passed to \code{WaveletComp::analyze.coherency()}.
Use \code{0} to disable internal loess detrending.}

\item{dj}{Frequency resolution passed to \code{WaveletComp::analyze.coherency()}.}

\item{lowerPeriod}{Optional lower period in native analysis units.}

\item{upperPeriod}{Optional upper period in native analysis units.}

\item{window.type.t}{Time-direction smoothing window type.}

\item{window.type.s}{Scale-direction smoothing window type.}

\item{window.size.t}{Time-direction smoothing window size.}

\item{window.size.s}{Scale-direction smoothing window size.}

\item{make.pval}{Logical. If \code{TRUE}, compute p-values.}

\item{make_pval}{Optional alias for \code{make.pval}.}

\item{method}{Surrogate generation method for p-values.}

\item{n.sim}{Number of simulations.}

\item{n_sim}{Optional alias for \code{n.sim}.}

\item{verbose}{Logical.}
}
\value{
An object of class \code{"dm_wavelet_coherence"}.
}
\description{
Computes cross-wavelet power and wavelet coherence between dendrometer series
and climate variables using \code{WaveletComp::analyze.coherency()}.

The function:
\itemize{
  \item crops dendrometer and climate inputs to their common time window,
  \item detects their temporal resolutions,
  \item resamples both to the coarser detected resolution,
  \item optionally interpolates missing values,
  \item optionally uses first differences of the dendrometer series,
  \item computes pairwise coherence for all selected tree/climate combinations.
}
}
\details{
\code{WaveletComp::analyze.coherency()} expects two aligned series in one data
frame plus a \code{dt} value in the analysis time units, and returns
cross-wavelet power, coherence, phase angles, p-values, Fourier periods, and
cone-of-influence fields.
}
\examples{
\donttest{
wc <- dm_wavelet_coherence(
  dm = gf_nepa17,
  clim = ktm_clim_hourly,
  TreeNum = 1,
  clim_vars = c("temp", "VPD"),
  source = "raw",
  dm_fun = "mean",
  clim_funs = c(temp = "mean", VPD = "mean"),
  loess_span = 0,
  make.pval = TRUE,
  n.sim = 10,
  verbose = FALSE
)

plot(wc)
plot(wc, type = "cross_power")
plot(wc, type = "average_coherence")
plot(wc, type = "phase")
plot(wc, type = "series")
}

}
