% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/calc_thermal_units.R
\name{calc_thermal_units}
\alias{calc_thermal_units}
\title{Calculate Thermal Units (Growing Degree Days)}
\usage{
calc_thermal_units(
  tmin,
  tmax = NULL,
  t_base = 5,
  t_cap = NULL,
  method = c("average", "modified", "single_sine"),
  cumulative = TRUE,
  na.rm = TRUE
)
}
\arguments{
\item{tmin}{Numeric vector of daily minimum temperatures (°C).}

\item{tmax}{Numeric vector of daily maximum temperatures (°C). If \code{NULL},
\code{tmin} is treated as daily mean temperature.}

\item{t_base}{Numeric. Base temperature (°C) below which no development occurs.
Default is 5°C, typical for temperate crops.}

\item{t_cap}{Numeric. Optional upper temperature cap (°C). Temperatures above
this are set to \code{t_cap} before GDD calculation. Default \code{NULL}
(no cap). Use ~30°C for crops where high heat doesn't increase development.}

\item{method}{Character. Calculation method:
\describe{
\item{"average"}{(Default) GDD = max(0, (tmax + tmin)/2 - t_base)}
\item{"modified"}{Sets negative daily GDD to 0 before averaging}
\item{"single_sine"}{Sine wave approximation for more accurate heat units}
}}

\item{cumulative}{Logical. If \code{TRUE} (default), returns cumulative sum.
If \code{FALSE}, returns daily values.}

\item{na.rm}{Logical. Remove NA values in accumulation? Default \code{TRUE}.}
}
\value{
Numeric vector of thermal units (degree-days). Same length as input.
If \code{cumulative = TRUE}, returns running sum.
}
\description{
Computes accumulated thermal units (growing degree days, GDD) from daily
temperature data. Thermal time is a fundamental concept in phenology,
representing the heat accumulation that drives plant development.
}
\details{
Growing Degree Days (GDD) quantify heat accumulation above a base temperature.
Plants require a certain thermal sum to reach phenological stages (e.g.,
flowering typically requires 500-1500 GDD depending on species).

The base temperature represents the minimum temperature for growth:
\itemize{
\item Cool-season crops (wheat, barley): 0-5°C
\item Warm-season crops (maize, soybean): 10°C
\item Fruit trees (apple, cherry): 4-7°C
\item Grapevine: 10°C
}
}
\section{Methods}{

\describe{
\item{average}{Simple average: GDD = max(0, (Tmax + Tmin)/2 - Tbase).
Most common method, used by many agricultural agencies.}
\item{modified}{Like average, but Tmin and Tmax are first bounded to
the range from Tbase to Tcap before averaging. Prevents negative contributions.}
\item{single_sine}{Approximates the daily temperature curve as a sine
wave, computing the mean excess over Tbase. More accurate when
temperatures cross the base threshold during the day. Implements the
Baskerville-Emin (1969) / Snyder (1985) single-sine formula: with
\eqn{T_{avg} = (T_{min} + T_{max})/2}, \eqn{T_{amp} = (T_{max} - T_{min})/2},
and \eqn{\theta = \mathrm{acos}\left((T_{base} - T_{avg})/T_{amp}\right)},
the daily GDD in the mixed case
(\eqn{T_{min} < T_{base} < T_{max}}) is
\eqn{\mathrm{GDD} = \frac{1}{\pi}\left[(T_{avg} - T_{base})\,\theta +
      T_{amp}\,\sin(\theta)\right]}.}
}
}

\examples{
# Daily temperatures for a week
tmin <- c(5, 7, 8, 10, 12, 11, 9)
tmax <- c(15, 18, 20, 22, 25, 23, 19)

# Cumulative GDD with base 10°C
calc_thermal_units(tmin, tmax, t_base = 10)

# Daily GDD values
calc_thermal_units(tmin, tmax, t_base = 10, cumulative = FALSE)

# With upper cap at 30°C
calc_thermal_units(tmin, tmax, t_base = 10, t_cap = 30)

# Using mean temperature only
tmean <- (tmin + tmax) / 2
calc_thermal_units(tmean, t_base = 10)

}
\references{
McMaster, G.S., Wilhelm, W.W. (1997). Growing degree-days: one equation,
two interpretations. \emph{Agricultural and Forest Meteorology} 87:291-300.

Baskerville, G.L., Emin, P. (1969). Rapid estimation of heat accumulation
from maximum and minimum temperatures. \emph{Ecology} 50:514-517.

Snyder, R.L. (1985). Hand calculating degree days. \emph{Agricultural and
Forest Meteorology} 35:353-358.
}
\seealso{
\code{\link{calc_thermal_sum}} for computing thermal sum at
phenological observations
}
\author{
Matthias Templ
}
