% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dm_sea.R
\name{dm_epoch_extract}
\alias{dm_epoch_extract}
\title{Build an epoch table around event times}
\usage{
dm_epoch_extract(
  events,
  clim,
  vars = "all",
  lag_before = 24,
  lag_after = 24,
  step = 1,
  unit = c("hours", "days", "mins"),
  agg_fun = "mean",
  var_funs = NULL,
  Year = NULL,
  DOY = NULL,
  restrict_null_to_window = TRUE
)
}
\arguments{
\item{events}{Output of [dm_event_times()] or a data frame containing an
\code{event_time} column.}

\item{clim}{Climate data frame. The first column must contain timestamps.}

\item{vars}{Climate variables to use, or \code{"all"}.}

\item{lag_before}{Number of lag steps before the event.}

\item{lag_after}{Number of lag steps after the event.}

\item{step}{Step size in units.}

\item{unit}{One of \code{"hours"}, \code{"days"}, or \code{"mins"}.}

\item{agg_fun}{Aggregation function applied to all climate variables when
\code{var_funs} is not supplied.}

\item{var_funs}{Optional named vector or named list of aggregation functions
for each variable.}

\item{Year}{Optional numeric vector of calendar years to include in the SEA.
Events whose \code{event_time} falls outside these years are removed before
epoch extraction.}

\item{DOY}{Optional numeric vector of length one or two giving the
day-of-year window to include in the SEA. If length one, only that DOY is
retained. If length two, the inclusive range is retained. Cross-year DOY
windows are supported, for example \code{DOY = c(300, 60)}.}

\item{restrict_null_to_window}{Logical. If \code{TRUE}, null anchor times in
[dm_epoch_test()] are sampled only from the same \code{Year}/\code{DOY}
window. The full climate table is still retained for extracting
\code{lag_before} and \code{lag_after} windows. Default is \code{TRUE}.}
}
\value{
An object of class \code{c("dm_epoch", "dm_epoch_extract")}.
}
\description{
Builds a long-format epoch table by extracting climate values before and
after event times.

The optional \code{Year} and \code{DOY} arguments allow the user to restrict
which events are included in the superposed epoch analysis. The full climate
table is retained for lag extraction so that values before and after selected
events are still available.
}
\examples{
\donttest{
# events <- dm_event_times(zg, event = "GRO_start")
# ep <- dm_epoch_extract(
#   events = events,
#   clim = climate,
#   vars = c("Rain", "temp", "vpd"),
#   Year = c(2022, 2023, 2024),
#   DOY = c(100, 300),
#   lag_before = 24,
#   lag_after = 24,
#   unit = "hours"
# )
}

}
