% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plot_phenology_trends.R
\name{plot_phenology_trends}
\alias{plot_phenology_trends}
\title{Plot Robust Phenological Trends}
\usage{
plot_phenology_trends(
  pep,
  genus_name = NULL,
  species_name = NULL,
  subspecies_name = NULL,
  phases = c(65, 87),
  common_stations = TRUE,
  combine_regions = FALSE,
  combine_layout = c("vertical", "horizontal"),
  years = 1961:2024,
  calib_years = 1991:2020,
  pred_years = NULL,
  subregions = c("Austria", "Germany-North", "Germany-South", "Switzerland"),
  giss_data = NULL,
  layout = c("country_phase", "phase_country"),
  title = NULL
)
}
\arguments{
\item{pep}{A PEP725-style data frame with columns \code{year}, \code{DOY},
\code{phase_id}, \code{country}, \code{s_id}, \code{genus}, \code{species}.}

\item{genus_name}{Character string specifying a genus to filter (optional).}

\item{species_name}{Character string specifying a species to filter (optional).
If both genus and species are provided, the species filter is applied last.}

\item{subspecies_name}{Character string specifying a subspecies to filter (optional).
Only one of genus_name, species_name, or subspecies_name can be specified.}

\item{phases}{Integer vector of phenological phase IDs to include
(default: \code{c(65, 87)} for flowering and maturity of fruit).}

\item{common_stations}{Logical. If \code{TRUE} (default), only stations with observations
for all selected phases are included. If \code{FALSE}, all stations with any of the selected phases are included.}

\item{combine_regions}{Logical. If \code{TRUE}, combines all regions into a single panel. Default is \code{FALSE}.}

\item{combine_layout}{Character. Layout for combined regions plot: either \code{"vertical"} or \code{"horizontal"}.}

\item{years}{Numeric vector of years to include in the analysis.
Default is \code{1961:2024}.}

\item{calib_years}{Numeric vector specifying the calibration window for robust
regression (default: \code{1991:2020}).}

\item{pred_years}{Numeric vector of years for projecting future phenology.
Default is \code{1990:2090}.}

\item{subregions}{Character vector of country names to include
(default: DACH region).}

\item{giss_data}{Deprecated. Previously used for climate data integration;
now ignored.}

\item{layout}{Either \code{"country_phase"} (default) or \code{"phase_country"}
to control facet arrangement.}

\item{title}{Optional plot title. If \code{NULL}, the function generates one
from genus and species information.}
}
\value{
A \code{ggplot} object.
}
\description{
This function visualizes long-term phenological trends for one genus or species,
using robust MM-regression (\code{robustbase::lmrob}) applied to mean annual DOYs.
}
\details{
The function produces a faceted panel plot showing:
\itemize{
\item annual mean DOY and interquartile range,
\item robust trend lines for past and future periods,
\item CTRL (1991-2020) and PGW (2066-2095) climate windows,
\item optional layouts (country x phase or phase x country).
}

The function performs the following steps:
\enumerate{
\item Filter PEP data by species, phases, regions, years.
\item Aggregate DOYs by year-country-phase.
\item Fit robust regression \eqn{DOY \sim year} over the calibration window.
\item Predict past and future trends.
\item Draw ribbon (IQR), annual means, trend lines, climate windows.
\item Facet by country or by phase.
}

The robust regression uses \code{robustbase::lmrob}, which is resistant to
outliers and non-normality, and therefore ideal for phenological time series.
}
\examples{
\donttest{
pep <- pep_download()
plot_phenology_trends(
  pep,
  species_name = "Vitis vinifera",
  phases = c(65, 81),
  layout = "country_phase"
)
}
}
\author{
Matthias Templ
}
