% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dm_wavelet_reconstruct.R
\name{dm_wavelet_reconstruct}
\alias{dm_wavelet_reconstruct}
\title{Reconstruct or remove selected cycle components from a dm_wavelet object}
\usage{
dm_wavelet_reconstruct(
  x,
  series = NULL,
  mode = c("extract", "remove"),
  period_hours = NULL,
  lower_hours = NULL,
  upper_hours = NULL,
  lvl = 0,
  only_sig = TRUE,
  siglvl = 0.05,
  only_coi = FALSE,
  only_ridge = FALSE,
  rescale = FALSE,
  verbose = TRUE
)
}
\arguments{
\item{x}{An object of class \code{"dm_wavelet"} returned by
\code{dm_wavelet()}.}

\item{series}{Optional character vector of series names to reconstruct. If
\code{NULL}, all available series are used.}

\item{mode}{One of \code{"extract"} or \code{"remove"}.}

\item{period_hours}{Optional numeric vector of exact periods, in hours, to
reconstruct. If supplied, \code{lower_hours} and \code{upper_hours} are
ignored.}

\item{lower_hours}{Optional lower period bound in hours for band
reconstruction.}

\item{upper_hours}{Optional upper period bound in hours for band
reconstruction.}

\item{lvl}{Minimum wavelet power level to include in the reconstruction.}

\item{only_sig}{Logical. If \code{TRUE}, use wavelet power significance in
reconstruction.}

\item{siglvl}{Significance level used when \code{only_sig = TRUE}.}

\item{only_coi}{Logical. If \code{TRUE}, restrict reconstruction to the cone
of influence.}

\item{only_ridge}{Logical. If \code{TRUE}, reconstruct from the power ridge
only.}

\item{rescale}{Logical. Passed to \code{WaveletComp::reconstruct()}.}

\item{verbose}{Logical. If \code{TRUE}, prints a completion message.}
}
\value{
An object of class \code{"dm_wavelet_reconstruct"} with elements:
\describe{
  \item{call}{Matched function call.}
  \item{series}{Selected series names.}
  \item{mode}{Reconstruction mode, either \code{"extract"} or \code{"remove"}.}
  \item{selection}{A list describing the requested selection in hours and in
  native wavelet units.}
  \item{results}{Named list of \code{WaveletComp::reconstruct()} outputs.}
  \item{reconstructed_long}{Tidy table with columns \code{TIME},
  \code{series}, \code{original}, \code{reconstructed}, \code{difference},
  and \code{filtered}.}
  \item{used_periods}{Per-series table of periods actually used in the
  reconstruction, in native units and in hours.}
  \item{filtered_wide}{Wide table with \code{TIME} in the first column and
  one filtered series column per selected tree/series.}
  \item{parent}{Minimal metadata copied from the parent \code{dm_wavelet}
  object.}
}
}
\description{
Reconstructs a selected oscillatory component, or a selected period band,
from a \code{dm_wavelet} object using \code{WaveletComp::reconstruct()}.

Requested periods are supplied in \strong{hours}. They are internally
converted to the native wavelet period units used when \code{dm_wavelet()}
was computed, then passed to \code{WaveletComp::reconstruct()}.

The function supports two modes:
\itemize{
  \item \code{mode = "extract"} returns the selected cycle or band itself.
  \item \code{mode = "remove"} returns the original series with the selected
  cycle or band removed.
}
}
\examples{
\donttest{
wv <- dm_wavelet(
  x = gf_nepa17,
  TreeNum = 1:2,
  source = "raw",
  make_pval = TRUE,
  verbose = FALSE
)

# extract circadian component
rec_extract <- dm_wavelet_reconstruct(
  wv,
  mode = "extract",
  lower_hours = 20,
  upper_hours = 28,
  only_sig = TRUE
)

# remove circadian component
rec_remove <- dm_wavelet_reconstruct(
  wv,
  mode = "remove",
  lower_hours = 20,
  upper_hours = 28,
  only_sig = TRUE
)

head(rec_extract$filtered_wide)
head(rec_remove$filtered_wide)
}

}
