% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pheno_gradient.R
\name{pheno_gradient}
\alias{pheno_gradient}
\title{Analyze Phenological Gradients with Elevation or Latitude}
\usage{
pheno_gradient(
  pep,
  variable = c("alt", "lat"),
  species = NULL,
  phase_id = NULL,
  year_range = NULL,
  by = NULL,
  method = c("robust", "ols", "quantile"),
  aggregate = TRUE,
  na.rm = TRUE
)
}
\arguments{
\item{pep}{A \code{pep} object or \code{data.table} containing phenological
observations with columns \code{year}, \code{day}, and either \code{alt}
(altitude) or \code{lat} (latitude).}

\item{variable}{Character string specifying the gradient variable.
Either \code{"alt"} (altitude/elevation) or \code{"lat"} (latitude).
Default is \code{"alt"}.}

\item{species}{Optional character string to filter by species/genus.}

\item{phase_id}{Optional integer to filter by a single BBCH phase code.}

\item{year_range}{Optional integer vector of length 2 specifying years to include.}

\item{by}{Optional character vector of grouping variables (e.g., "country").
If provided, separate gradients are calculated for each group.}

\item{method}{Character string specifying regression method:
\itemize{
\item \code{"robust"} (default): Robust regression using \code{robustbase::lmrob}
\item \code{"ols"}: Ordinary least squares regression
\item \code{"quantile"}: Quantile regression for median using \code{quantreg::rq}
}}

\item{aggregate}{Logical. If \code{TRUE} (default), first aggregate to station
means before fitting. If \code{FALSE}, use all individual observations.}

\item{na.rm}{Logical. Should missing values be removed? Default \code{TRUE}.}
}
\value{
A list with class \code{pheno_gradient} containing:
\describe{
\item{summary}{A \code{data.table} with slope, intercept, R-squared,
RMSE, n_stations, and interpretation}
\item{model}{The fitted model object(s)}
\item{data}{The data used for fitting}
\item{variable}{The gradient variable used}
\item{method}{The regression method used}
}
}
\description{
Quantifies how phenological timing shifts with altitude or latitude,
calculating the phenological lapse rate using robust regression methods.
}
\details{
Phenological gradients describe how the timing of biological events changes
with environmental factors. This function calculates:

\itemize{
\item \strong{Altitude gradient}: Typically 2-4 days delay per 100m elevation
gain in temperate regions
\item \strong{Latitude gradient}: Typically 2-5 days delay per degree north
in Europe
}

The robust regression method (default) is recommended because phenological
data often contains outliers from observation errors or microclimate effects.
}
\section{Interpretation}{

The slope represents:
\itemize{
\item For altitude: days delay per 100 meters elevation increase
\item For latitude: days delay per degree latitude increase
}
Positive slopes indicate later phenology at higher elevations/latitudes.
}

\examples{
\donttest{
pep <- pep_download()

# Subset to Alpine countries (good elevation variation)
pep_subset <- pep[country \%in\% c("Switzerland", "Austria")]

# Altitude gradient for apple flowering
grad_alt <- pheno_gradient(pep_subset,
                           variable = "alt",
                           species = "Malus",
                           phase_id = 60)
print(grad_alt)

# Latitude gradient
grad_lat <- pheno_gradient(pep_subset,
                           variable = "lat",
                           species = "Malus",
                           phase_id = 60)
print(grad_lat)

# Compare regression methods
grad_ols <- pheno_gradient(pep_subset, species = "Malus",
                           phase_id = 60, method = "ols")
print(grad_ols)

grad_robust <- pheno_gradient(pep_subset, species = "Malus",
                              phase_id = 60, method = "robust")
print(grad_robust)

# Gradient by country (separate regression per country)
grad_by_country <- pheno_gradient(pep_subset,
                                  variable = "alt",
                                  species = "Malus",
                                  phase_id = 60,
                                  by = "country")
print(grad_by_country)
}

}
\references{
Defila, C. and Clot, B. (2001). Phytophenological trends in Switzerland.
\emph{International Journal of Biometeorology}, 45, 203--207.
\doi{10.1007/s004840100101}

Ziello, C. et al. (2009). Influence of altitude on phenology of selected
plant species in the Alpine region (1971--2000).
\emph{Climate Research}, 39, 227--234.
\doi{10.3354/cr00822}
}
\seealso{
\code{\link{pheno_normals}} for calculating climatological normals,
\code{\link[robustbase]{lmrob}} for robust regression details
}
\author{
Matthias Templ
}
