% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dm_smooth.R
\name{smooth_dm}
\alias{smooth_dm}
\title{Smoothing of Dendrometer Time Series}
\usage{
smooth_dm(
  time,
  dm,
  resolution_min = NULL,
  method = c("median_mean", "pspline", "sg", "ema", "loess"),
  window_hours = 3,
  sg_order = 2,
  ema_alpha = NULL
)
}
\arguments{
\item{time}{A POSIXct vector representing the time column.}

\item{dm}{A numeric vector of dendrometer values corresponding to \code{time}.}

\item{resolution_min}{Integer. The resolution of the time series in minutes. If \code{NULL},
the resolution is auto-detected based on median time difference.}

\item{method}{Smoothing method. One of: \code{"median_mean"}, \code{"pspline"},
\code{"sg"} (Savitzky-Golay), \code{"ema"} (exponential moving average), or \code{"loess"}.}

\item{window_hours}{Numeric. Smoothing window length in hours. Converted to points using resolution.}

\item{sg_order}{Integer. Polynomial order for Savitzky-Golay smoothing. Ignored unless \code{method = "sg"}.}

\item{ema_alpha}{Numeric. Smoothing factor (0–1) for exponential moving average. If \code{NULL},
it is automatically calculated from the window size.}
}
\value{
A numeric vector of the same length as \code{dm} containing the smoothed values.
}
\description{
Applies various smoothing techniques to dendrometer (dm) time series data
using a user-defined or automatically detected temporal resolution. The function
supports several smoothing methods: robust median+mean, penalized spline,
Savitzky-Golay filter, exponential moving average (EMA), and LOESS.
}
\details{
The function is designed to smooth dendrometer time series (e.g., 10–60 min resolution)
while preserving key features such as diurnal fluctuations or long-term growth,
depending on the window size. It auto-detects the resolution (in minutes) if not provided.
}
\examples{
\dontrun{
# Example: Create synthetic dendrometer time series (30-min resolution)
time_seq <- seq.POSIXt(from = as.POSIXct("2023-06-01 00:00:00"),
                       to   = as.POSIXct("2023-06-03 00:00:00"),
                       by   = "30 mins")
set.seed(123)
dm_raw <- cumsum(rnorm(length(time_seq), mean = 0.005, sd = 0.01)) +
          0.1 * sin(2 * pi * as.numeric(difftime(time_seq, min(time_seq), units = "hours")) / 24)

# Median plus moving mean smoothing (default robust filter)
dm_medmean <- smooth_dm(time = time_seq, dm = dm_raw,
                        method = "median_mean", window_hours = 3)

# Penalized spline smoothing
dm_pspline <- smooth_dm(time = time_seq, dm = dm_raw,
                        method = "pspline", window_hours = 6)

# Savitzky-Golay filter (requires 'signal' package)
if (requireNamespace("signal", quietly = TRUE)) {
  dm_sg <- smooth_dm(time = time_seq, dm = dm_raw,
                     method = "sg", window_hours = 2, sg_order = 2)
}

# Exponential moving average smoothing
dm_ema <- smooth_dm(time = time_seq, dm = dm_raw,
                    method = "ema", window_hours = 4)

# LOESS smoothing
dm_loess <- smooth_dm(time = time_seq, dm = dm_raw,
                      method = "loess", window_hours = 3)

# Plot raw and smoothed series
plot(time_seq, dm_raw, type = "l", col = "gray", lwd = 1, main = "Smoothed Dendrometer Series",
     ylab = "DM", xlab = "Time")
lines(time_seq, dm_medmean, col = "blue", lwd = 2)
lines(time_seq, dm_pspline, col = "green", lwd = 2)
lines(time_seq, dm_ema, col = "orange", lwd = 2)
lines(time_seq, dm_loess, col = "purple", lwd = 2)
legend("topright", legend = c("Raw", "Median+Mean", "P-spline", "EMA", "LOESS"),
       col = c("gray", "blue", "green", "orange", "purple"), lwd = 2)
}

}
