% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/calc_daylength.R
\name{calc_daylength}
\alias{calc_daylength}
\title{Calculate Daylength (Photoperiod)}
\usage{
calc_daylength(doy, lat, method = c("brock", "cbm"))
}
\arguments{
\item{doy}{Integer or numeric vector. Day of year (1-365/366).}

\item{lat}{Numeric. Latitude in decimal degrees. Positive for Northern
Hemisphere, negative for Southern Hemisphere.}

\item{method}{Character. Daylength model:
\describe{
\item{\code{"brock"}}{(Default) Brock (1981) / Spencer (1971)
simple declination model: \eqn{\delta = 23.45^\circ \cdot
      \sin(2\pi(284 + \mathrm{DOY})/365)}. Fast and adequate at
mid-latitudes; differs from CBM by up to a few minutes/day
near the poles.}
\item{\code{"cbm"}}{Forsythe et al. (1995) Climate-Budget-Model
formulation. Includes the eccentricity correction of the Earth's
orbit and is generally the most accurate of the four models
Forsythe et al. compared.}
}}
}
\value{
A list with components:
\describe{
\item{daylength}{Daylength in hours}
\item{declination}{Solar declination angle in degrees}
}
If \code{doy} is a vector, returns a data.frame with these columns.
}
\description{
Computes the astronomical daylength (hours of daylight) for a given
day of year and latitude. Photoperiod is an important environmental
driver of plant phenology.
}
\details{
Both methods assume a "flat horizon" (sunrise/sunset when the geometric
centre of the sun crosses the horizon) and do not account for
atmospheric refraction, elevation, or local topography.

At polar latitudes (\eqn{|lat| > 66.5^\circ}), continuous daylight or
darkness may occur around solstices.
}
\section{Phenological Relevance}{

Many phenological events are triggered by photoperiod thresholds:
\itemize{
\item Spring bud burst often requires both temperature accumulation
and minimum daylength
\item Autumn leaf senescence may be triggered by shortening days
\item Flowering in many species is photoperiod-dependent
}
}

\examples{
# Daylength at spring equinox (DOY 80) at 50°N
calc_daylength(80, 50)

# Summer solstice at different latitudes
calc_daylength(172, c(30, 45, 60))

# Daylength through the year at 45°N
yearly <- calc_daylength(1:365, 45)
plot(yearly$doy, yearly$daylength, type = "l",
     xlab = "Day of Year", ylab = "Daylength (hours)")

}
\references{
Spencer, J. W. (1971). Fourier series representation of the position of
the sun. \emph{Search} 2(5):172. (Declination formula used by the
\code{"brock"} method.)

Brock, T. D. (1981). Calculating solar radiation for ecological studies.
\emph{Ecological Modelling} 14(1-2):1-19.
\doi{10.1016/0304-3800(81)90011-9}

Forsythe, W. C., Rykiel, E. J., Stahl, R. S., Wu, H., and
Schoolfield, R. M. (1995). A model comparison for daylength as a
function of latitude and day of year. \emph{Ecological Modelling}
80(1):87-95. \doi{10.1016/0304-3800(94)00034-F}
(CBM daylength model used by the \code{"cbm"} method.)
}
\author{
Matthias Templ
}
