% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dm_wavelet.R
\name{dm_wavelet}
\alias{dm_wavelet}
\title{Wavelet analysis of dendrometer series}
\usage{
dm_wavelet(
  x,
  TreeNum = "all",
  source = c("auto", "raw", "detrended", "first_diff"),
  detrended_col = c("detrended_data"),
  na_action = c("interpolate", "fail"),
  loess_span = 0.75,
  dj = 1/20,
  lowerPeriod = NULL,
  upperPeriod = NULL,
  make_pval = TRUE,
  n_sim = 10,
  verbose = TRUE
)
}
\arguments{
\item{x}{Input data. Either:
\describe{
  \item{data.frame}{First column must be time, remaining selected numeric
    columns are dendrometer series.}
  \item{dm_detrended object}{Uses \code{x$detrended_data} as input.}
}}

\item{TreeNum}{Either \code{"all"} to use all available dendrometer series,
a numeric vector selecting series by position, or a character vector of
series names.}

\item{source}{Which series to analyze. One of:
\describe{
  \item{`"auto"`}{Uses raw series for a data frame input and detrended
    series for a \code{dm_detrended} object.}
  \item{`"raw"`}{Use raw dendrometer series from a data frame input.}
  \item{`"detrended"`}{Use detrended series from a \code{dm_detrended} object.}
  \item{`"first_diff"`}{Use first differences of the available input series.}
}}

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

\item{na_action}{How to handle missing values after completing the regular time
grid. One of:
\describe{
  \item{`"interpolate"`}{Linearly interpolate internal gaps and carry ends
    forward/backward.}
  \item{`"fail"`}{Stop if missing values are found.}
}}

\item{loess_span}{Smoothing span passed to \code{WaveletComp::analyze.wavelet()}.}

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

\item{lowerPeriod}{Optional lower period bound in native time units of the
detected input resolution. If \code{NULL}, the default from
\code{WaveletComp::analyze.wavelet()} is used.}

\item{upperPeriod}{Optional upper period bound in native time units of the
detected input resolution. If \code{NULL}, the default from
\code{WaveletComp::analyze.wavelet()} is used.}

\item{make_pval}{Logical; if \code{TRUE}, compute Monte Carlo significance.}

\item{n_sim}{Number of simulations used when \code{make_pval = TRUE}.}

\item{verbose}{Logical; if \code{TRUE}, prints a completion message.}
}
\value{
An object of class \code{"dm_wavelet"} with elements:
\describe{
  \item{call}{The matched function call.}
  \item{input_type}{Either \code{"raw"} or \code{"dm_detrended"}.}
  \item{source}{Series source actually used.}
  \item{series}{Character vector of analyzed series names.}
  \item{time_unit}{Detected time unit of the input series.}
  \item{dt}{Detected time step in native units.}
  \item{dt_hours}{Detected time step expressed in hours.}
  \item{resolution_seconds}{Detected time step in seconds.}
  \item{data_used}{Regularized time series used for analysis.}
  \item{results}{Named list of wavelet results, one per series. Each entry
    contains the original \code{WaveletComp} object plus time and
    period-in-hours information.}
  \item{settings}{Analysis settings.}
}
}
\description{
Performs continuous wavelet analysis on dendrometer time series.

The function can work with:
\itemize{
  \item raw dendrometer series from a data frame,
  \item detrended dendrometer series from \code{dm.detrend.fit()} output,
  \item first differences of either raw or detrended series.
}

It automatically:
\itemize{
  \item identifies the temporal resolution of the input series,
  \item regularizes the series to a complete time grid,
  \item optionally interpolates missing values,
  \item performs wavelet analysis separately for each selected tree/series,
  \item converts wavelet periods to hours for summary and plotting.
}
}
