% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pheno_combine.R
\name{pheno_combine}
\alias{pheno_combine}
\title{Create Combined Phenological Time Series}
\usage{
pheno_combine(
  pep,
  by = NULL,
  method = c("robust", "mixed", "ols"),
  min_years = 5,
  min_stations = 3,
  check_connectivity = TRUE
)
}
\arguments{
\item{pep}{A \code{pep} object or \code{data.table} containing phenological
observations with columns \code{year}, \code{day}, and \code{s_id}.}

\item{by}{Character vector of grouping variables (e.g., \code{c("genus",
  "species", "phase_id")}). A separate combined series is created for each
group. Default is \code{NULL} (treat all data as one group).}

\item{method}{Character. Estimation method:
\describe{
\item{"robust"}{(Default) Least Absolute Deviations (LAD/L1) regression.
Minimizes sum of absolute residuals, robust to outliers.}
\item{"mixed"}{Mixed-effects model with year as fixed effect and station
as random effect. Uses REML estimation.}
\item{"ols"}{Ordinary Least Squares. Sensitive to outliers but provides
standard errors and confidence intervals.}
}}

\item{min_years}{Integer. Minimum years of overlap required. Default 5.}

\item{min_stations}{Integer. Minimum stations required. Default 3.}

\item{check_connectivity}{Logical. If \code{TRUE} (default), checks whether
station-year combinations form a connected set. Warns if data is
disconnected (which prevents valid combined series estimation).}
}
\value{
An object of class \code{pheno_combined} containing:
\describe{
\item{combined}{Data.table with the combined time series: year,
year_effect (the combined DOY), se (standard error, if available)}
\item{station_effects}{Data.table of station effects: s_id, effect, se}
\item{residuals}{Data.table with original data plus fitted values and
residuals for outlier detection}
\item{method}{Estimation method used}
\item{connectivity}{Connectivity check results (if performed)}
\item{by}{Grouping variables used}
\item{group_results}{For grouped analysis, results per group}
}
}
\description{
Estimates a combined (regional/national) phenological time series from
multi-station observations by separating year effects from station effects.
This is essential for creating representative time series from networks
with varying station coverage over time.
}
\details{
The model fitted is: \deqn{DOY_{ij} = \mu_i + \sigma_j + \epsilon_{ij}}
where \eqn{\mu_i} is the year effect (combined series), \eqn{\sigma_j} is
the station effect, and \eqn{\epsilon_{ij}} is the residual.

Station effects represent systematic differences between stations (e.g.,
due to altitude, microclimate, or observer differences). The combined
series removes these effects to reveal the underlying temporal trend.
}
\section{Connectivity}{

A prerequisite for valid estimation is that station-year combinations
form a "connected" set - meaning there must be overlapping years between
stations to separate year and station effects. The function checks this
automatically and warns if data is disconnected.
}

\section{Outlier Detection}{

With \code{method = "robust"}, large residuals (e.g., > 30 days) indicate
potential outliers or data errors. The residuals table can be used to
identify and investigate these.
}

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

# Grapevine flowering in Switzerland (longest historical records)
vine_ch <- pep[species == "Vitis vinifera" &
               phase_id == 65 & country == "Switzerland"]

if (nrow(vine_ch) > 0) {
  # Create combined series using OLS
  combined <- pheno_combine(vine_ch, method = "ols")
  print(combined)

  # Identify potential outliers (residuals > 30 days)
  outliers <- combined$residuals[abs(residual) > 30]
  outliers
}
}

}
\references{
Schaber J, Badeck F-W (2002). Evaluation of methods for the combination
of phenological time series and outlier detection. Tree Physiology 22:973-982.
}
\seealso{
\code{\link{pheno_normals}} for climatological baselines,
\code{\link{pheno_trend_turning}} for trend turning point detection,
\code{\link{pep_check_connectivity}} for connectivity assessment
}
\author{
Matthias Templ
}
