% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dm.na.interpolation.R
\name{dm.na.interpolation}
\alias{dm.na.interpolation}
\title{Detection and interpolation of missing values in dendrometer data}
\usage{
dm.na.interpolation(
  df,
  resolution,
  fill = FALSE,
  method = "spline",
  assess = FALSE,
  assess_lengths_hours = seq(6, 72, by = 6),
  assess_samples_per_length = 10,
  assess_buffer_hours = 6,
  assess_seed = NULL,
  verbose = FALSE
)
}
\arguments{
\item{df}{A data frame with the first column as datetime (\code{"yyyy-mm-dd HH:MM:SS"},
or POSIXct/Date), followed by dendrometer values.}

\item{resolution}{Integer. Temporal resolution in minutes (e.g., 60 for hourly data).}

\item{fill}{Logical. If \code{TRUE}, missing values will be interpolated.}

\item{method}{Character. Interpolation method (only used if \code{fill = TRUE}):
\itemize{
  \item \code{"spline"} --- cubic spline (\code{zoo::na.spline}).
  \item \code{"seasonal"} --- seasonal decomposition (\code{forecast::na.interp}).
}}

\item{assess}{Logical. If \code{TRUE}, run a simulation-based test to evaluate how well
interpolation performs at different gap lengths (on existing data).}

\item{assess_lengths_hours}{Integer vector. The gap durations (in hours) to test during
assessment. Default: \code{seq(6, 72, by = 6)}.}

\item{assess_samples_per_length}{Integer. Number of artificial gaps per gap length
per series. Default: \code{10}.}

\item{assess_buffer_hours}{Integer. Minimum number of hours of valid data required
before and after the artificial gap to allow valid assessment. Default: \code{6}.}

\item{assess_seed}{Integer or \code{NULL}. Random seed to ensure reproducibility
of sampling windows. Default: \code{NULL}.}

\item{verbose}{Logical. If \code{TRUE}, prints messages during filling and testing.}
}
\value{
A list of class \code{"dm_na_interpolation"} with components:
\describe{
  \item{\code{$data}}{Data frame containing the original or gap-filled series.}
  \item{\code{$gap_info}}{Table describing timestamp gaps and internal NA runs.}
  \item{\code{$assessment}}{A tibble summarizing interpolation accuracy for each
  series and gap length, or \code{NULL} when \code{assess = FALSE}.}
  \item{\code{$filled}}{Logical indicating whether interpolation was performed.}
  \item{\code{$assessed}}{Logical indicating whether interpolation assessment was performed.}
  \item{\code{$method}}{Interpolation method used.}
  \item{\code{$resolution}}{Temporal resolution in minutes.}
}
}
\description{
Detects missing timestamps (based on provided resolution), inserts rows with \code{NA},
and optionally interpolates missing values using either cubic spline interpolation
(\code{\link[zoo:na.spline]{na.spline}}) or seasonal decomposition interpolation
(\code{\link[forecast:na.interp]{na.interp}}).

Optionally, the function can test the reliability of interpolation for increasing
gap lengths (e.g., 6 hours to 3 days) using real data. This allows the user to assess
how well a given interpolation method recovers missing values over different durations.
}
\details{
The assessment simulates interpolation over artificial gaps of different durations.
For each dendrometer series and each gap length:
\enumerate{
  \item Random windows (with clean data) are selected.
  \item Data in the window is temporarily set to \code{NA}.
  \item The gap is interpolated using the selected method.
  \item The predicted values are compared to the original (true) values using:
    \itemize{
      \item MAPE --- Mean Absolute Percentage Error.
      \item MdAPE --- Median Absolute Percentage Error.
      \item RMSE_pct --- Root Mean Square Error (\%).
      \item Bias_pct --- Mean Percentage Error (\%).
      \item Max_diff_abs --- Mean absolute difference in daily maximum.
      \item Min_diff_abs --- Mean absolute difference in daily minimum.
      \item Time_max_diff_h --- Mean absolute difference in time of daily maximum (hours).
      \item Time_min_diff_h --- Mean absolute difference in time of daily minimum (hours).
    }
}
}
\examples{
\donttest{
library(dendRoAnalyst)
data(nepa17)

#res0 <- dm.na.interpolation(nepa17[1:1000, ], resolution = 60)
#plot(res0)
#plot(res0, type = "gaps")

#res1 <- dm.na.interpolation(
#  nepa17[1:1000, ],
#  resolution = 60,
#  fill = TRUE,
#  method = "spline"
#)
#plot(res1)
#plot(res1, type = "gaps")
#plot(res1, type = "interpolation", original = nepa17[1:1000, ])

#res2 <- dm.na.interpolation(
#  nepa17[1:1000, ],
#  resolution = 60,
#  fill = TRUE,
#  method = "seasonal",
#  assess = TRUE
# )
#plot(res2)
#plot(res2, type = "assessment", metric = "MdAPE")
}

}
