% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/subspecies_report.R
\name{subspecies_report}
\alias{subspecies_report}
\title{Comprehensive Subspecies Availability Report}
\usage{
subspecies_report(
  pep,
  genus_name = NULL,
  species_name = NULL,
  subspecies_name = NULL,
  phases = c(65, 87),
  years = 1961:2024,
  subregions = c("Austria", "Germany-North", "Germany-South", "Switzerland"),
  include_empty = TRUE,
  metric = "all",
  bbch_names = NULL,
  return_results = TRUE
)
}
\arguments{
\item{pep}{A PEP725-style data frame containing at least:
\code{genus}, \code{species}, \code{subspecies}, \code{country}, \code{year}, \code{phase_id},
\code{s_id}, and \code{day} or \code{DOY}.}

\item{genus_name}{Character (optional). Genus to filter.}

\item{species_name}{Character (optional). Species to filter.}

\item{subspecies_name}{Character vector (optional). One or more subspecies.}

\item{phases}{Integer vector. BBCH phases to evaluate.}

\item{years}{Numeric vector. Years to include.}

\item{subregions}{Character vector of region/country names.}

\item{include_empty}{Logical. If TRUE, include subspecies x country rows
even when no observations are present.}

\item{metric}{Character vector. Metrics to compute. Use \code{"all"} for:
\code{"n_obs"}, \code{"n_stations"}, \code{"first_year"}, \code{"last_year"},
\code{"median_doy"}, \code{"completeness"}.}

\item{bbch_names}{Optional named list mapping BBCH phase numbers to labels,
e.g. \code{list("65" = "Flowering", "87" = "Maturity")}.}

\item{return_results}{Logical. If TRUE, returns a list invisibly.}
}
\value{
Invisibly returns a list with:
\describe{
\item{summary_table}{Tidy long-format summary}
\item{wide_table}{Publication-ready wide-format summary}
\item{heatmap}{A ggplot2 object}
}
}
\description{
This function produces a complete report for phenological subspecies
availability, combining:
(1) a tidy summary table,
(2) a publication-ready wide table, and
(3) a ggplot2 heatmap showing data presence/absence.
}
\details{
Users may specify a \strong{genus}, \strong{species}, or one or more
\strong{subspecies}. The report evaluates BBCH phases, regions, years,
completeness, and several optional availability metrics.
}
\examples{
\donttest{
pep <- pep_download()

# Use Alpine subset for faster computation
pep_alpine <- pep[country \%in\% c("Switzerland", "Austria")]

# Grapevine subspecies (wine varieties) - longest historical records
if (nrow(pep_alpine[species == "Vitis vinifera"]) > 0) {
  subspecies_report(
    pep_alpine,
    subspecies_name = c("Vitis vinifera Riesling",
                        "Vitis vinifera MUELLER THURGAU WEISS"),
    subregions = c("Switzerland", "Austria"),
    metric = "all",
    bbch_names = list("65"="Flowering", "81"="Veraison")
  )

  subspecies_report(
    pep_alpine,
    species_name = "Vitis vinifera",
    subregions = c("Switzerland", "Austria"),
    metric = c("n_obs","median_doy","completeness")
  )

  subspecies_report(
    pep_alpine,
    genus_name = "Vitis",
    subregions = c("Switzerland", "Austria"),
    metric = "all"
  )
}
}
}
\seealso{
\code{\link{pheno_trend_turning}} for trend visualization
}
\author{
Matthias Templ
}
