% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dm_add_climate.R
\name{dm_add_climate}
\alias{dm_add_climate}
\title{Add climate information to dendrometer outputs}
\usage{
dm_add_climate(
  x,
  clim,
  scale = c("auto", "daily", "phase", "subdaily"),
  mean_vars = NULL,
  min_vars = NULL,
  max_vars = NULL,
  sum_vars = NULL,
  median_vars = NULL,
  lag_vars = NULL,
  lagmean_vars = NULL,
  lagsum_vars = NULL,
  lag_days = c(1, 3, 7),
  sub_mean_vars = NULL,
  sub_sum_vars = NULL,
  sub_lag_vars = NULL,
  roll_hours = c(3, 6, 24),
  lag_hours = c(1, 3, 6, 24),
  suffix = "_phase"
)
}
\arguments{
\item{x}{Object returned by \code{daily.data()}, \code{phase.zg()}, or \code{phase.sc()}.}

\item{clim}{Climate input. This can be:
\itemize{
  \item a standardized object returned by \code{read.climate()}
  \item a raw climate data frame
  \item a valid climate file path readable by \code{read.climate()}
  \item a daily climate table returned by \code{dm_daily_clim()}
  \item a subdaily climate-feature table returned by \code{dm_subdaily_clim()}
}}

\item{scale}{Character string controlling how climate is attached.
One of \code{"auto"}, \code{"daily"}, \code{"phase"}, or \code{"subdaily"}.
\itemize{
  \item For \code{daily_output}, only \code{"daily"} is supported.
  \item For \code{ZG_output} and \code{SC_output}, \code{"phase"} adds climate
        summaries to \code{ZG_cycle}/\code{SC_cycle}, while \code{"subdaily"}
        adds timestamp-level climate to \code{ZG_phase}/\code{SC_phase}.
}}

\item{mean_vars, min_vars, max_vars, sum_vars, median_vars}{Climate variables to
summarize by mean, minimum, maximum, sum, or median.
These are used by \code{dm_daily_clim()} and \code{dm_join_phase_clim()}.}

\item{lag_vars, lagmean_vars, lagsum_vars}{Variables used by \code{dm_daily_clim()}
to build lagged and antecedent daily climate features.}

\item{lag_days}{Integer vector of lag/antecedent windows in days for
\code{dm_daily_clim()}.}

\item{sub_mean_vars, sub_sum_vars, sub_lag_vars}{Variables used by
\code{dm_subdaily_clim()} to build rolling and lagged subdaily features.}

\item{roll_hours, lag_hours}{Numeric vectors of rolling-window and lag sizes
in hours for \code{dm_subdaily_clim()}.}

\item{suffix}{Suffix appended to climate summaries added by
\code{dm_join_phase_clim()}.}
}
\value{
The same biological object with climate information added.
}
\description{
A single helper function that adds climate information to outputs from
\code{daily.data()}, \code{phase.zg()}, or \code{phase.sc()}.

Depending on the class of \code{x} and the selected \code{scale}, the function:
\itemize{
  \item joins daily climate to \code{daily.data()} output
  \item joins climate summaries to phase windows in \code{ZG_cycle} or \code{SC_cycle}
  \item joins subdaily climate features to point-level \code{ZG_phase} or \code{SC_phase}
}
}
\examples{
\donttest{
data(nepa17)
data(gf_nepa17)
data(ktm_clim_hourly)

# daily.data() output + daily climate
dd <- daily.data(df = nepa17[1:1000, ], TreeNum = 1)
dd_clim <- dm_add_climate(
  dd,
  ktm_clim_hourly,
  scale = "daily",
  mean_vars = c("temp", "VPD", "RH"),
  max_vars  = c("temp", "VPD"),
  sum_vars  = c("prec")
)
head(dd_clim)

# phase.zg() output + phase-window climate
zg <- phase.zg(df = gf_nepa17[1:800, ], TreeNum = 1)
zg_clim <- dm_add_climate(
  zg,
  ktm_clim_hourly,
  scale = "phase",
  mean_vars = c("temp", "VPD", "RH"),
  max_vars  = c("temp", "VPD"),
  sum_vars  = c("prec")
)
head(zg_clim$ZG_cycle)

# phase.sc() output + point-level subdaily climate
sc <- phase.sc(df = gf_nepa17[1:800, ], TreeNum = 1, smoothing = 12)
sc_point <- dm_add_climate(
  sc,
  ktm_clim_hourly,
  scale = "subdaily",
  sub_mean_vars = c("temp", "VPD", "RH"),
  sub_sum_vars  = c("prec"),
  sub_lag_vars  = c("temp", "VPD", "RH"),
  roll_hours = c(1, 3, 6, 24),
  lag_hours  = c(1, 3, 6, 24)
)
head(sc_point$SC_phase)
}

}
