% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pheno_map.R
\name{pheno_map}
\alias{pheno_map}
\title{Plot Phenology Station Maps}
\usage{
pheno_map(
  pep,
  location = c(lon = 6.233, lat = 46.4),
  zoom = 4,
  background = c("google", "none"),
  color_by = c("none", "n_obs", "n_species", "mean_doy", "trend", "species_cv"),
  phase_id = NULL,
  period = NULL,
  min_years = 10,
  min_species = 3,
  point_size = 0.8,
  output_file = NULL,
  key = NULL
)
}
\arguments{
\item{pep}{A \code{data.table} or \code{data.frame} with phenological observations.
Required columns depend on \code{color_by}:
\itemize{
\item Always required: \code{lon}, \code{lat}
\item For \code{"n_species"}, \code{"mean_doy"}, \code{"species_cv"}: \code{species}
\item For \code{"mean_doy"}, \code{"trend"}: \code{year}, \code{day}
}}

\item{location}{Named vector with center longitude and latitude for the map.
Defaults to near Changins: \code{c(lon = 6.233, lat = 46.400)}.
Used primarily for \code{background = "google"}.}

\item{zoom}{Zoom level for the map. For \code{background = "google"}, this is
the Google Maps zoom level (4 = Europe, 7 = regional). For
\code{background = "none"}, this controls the padding around data extent
(4 = wide view, 7 = tight view). Default is 4.}

\item{background}{Character. Map background type:
\describe{
\item{"google"}{Google Maps satellite/terrain background. Requires API key
(set via \code{ggmap::register_google()} or \code{key} parameter).}
\item{"none"}{Simple map with country borders from Natural Earth data.
No API key required. Good for publications and vignettes.}
}}

\item{color_by}{Character. What to color stations by:
\describe{
\item{"none"}{Black points showing station locations only}
\item{"n_obs"}{Number of observations per station}
\item{"n_species"}{Number of species recorded per station}
\item{"mean_doy"}{Mean day-of-year (phenological timing) per station}
\item{"trend"}{Trend in days/year per station (positive = later, negative = earlier)}
\item{"species_cv"}{Coefficient of variation in timing across species at each station
(higher = more variation among species)}
}}

\item{phase_id}{Integer. BBCH phase code to filter by. Recommended for
\code{"mean_doy"} and \code{"trend"} to ensure meaningful comparisons.
If \code{NULL} (default), all phases are included.}

\item{period}{Integer vector of years to include. Default is all years.
For trend calculation, at least 10 years are recommended.}

\item{min_years}{Integer. Minimum years required for trend calculation.
Stations with fewer years show as NA. Default is 10.}

\item{min_species}{Integer. Minimum species required for \code{species_cv}.
Default is 3.}

\item{point_size}{Size of station points (default: 0.8).}

\item{output_file}{Optional file path to export the plot (e.g. \code{"map.pdf"}).}

\item{key}{Google Maps API key. Only needed for \code{background = "google"}.
You can set globally via \code{ggmap::register_google()} instead.}
}
\value{
A ggplot map object.
}
\description{
Generates a map of PEP725 phenological station locations with optional coloring
by various statistics including mean phenological timing, trends, and species
variation.
}
\details{
The function supports two background types:

\strong{Google Maps background} (\code{background = "google"}):
Provides detailed satellite or terrain imagery but requires a Google Maps API key.
Register at \url{https://console.cloud.google.com/} and enable the Maps Static API.

\strong{No background} (\code{background = "none"}):
Uses country outlines from Natural Earth data. No API key required, making it
suitable for:
\itemize{
\item CRAN package vignettes (no external API calls)
\item Reproducible research (no authentication needed)
\item Publication-quality maps with clean appearance
}

The color options provide insights into:
\itemize{
\item \strong{mean_doy}: Spatial patterns in phenological timing. Earlier
timing (lower DOY) typically in southern/lowland areas.
\item \strong{trend}: Where phenology is advancing (negative = earlier over time,
shown in blue) or delaying (positive, shown in red). Uses Kendall's tau
normalized statistic for robustness.
\item \strong{species_cv}: Stations where different species show similar timing
(low CV) vs. divergent timing (high CV). High variation may indicate
species-specific responses to local conditions.
}
}
\section{Interpreting Trends}{

The trend is calculated as Kendall's normalized tau statistic, which ranges
roughly from -3 to +3 for typical data:
\itemize{
\item Negative values (blue): Phenology is getting earlier over time
\item Positive values (red): Phenology is getting later over time
\item Values near 0: No clear trend
\item |tau| > 1.96: Statistically significant at 95\% level
}
}

\examples{
\donttest{
pep <- pep_download()
pep_alpine <- pep[country \%in\% c("Switzerland", "Austria")]
pheno_map(pep_alpine, background = "none", color_by = "n_obs")
}
\dontrun{
# With Google Maps background (requires API key)
ggmap::register_google(key = "your_api_key_here")
pheno_map(pep, background = "google", color_by = "n_species", zoom = 5)
}
}
\seealso{
\code{\link{pheno_normals}} for detailed normal calculations,
\code{\link{mann_kendall_z}} for trend calculation,
\code{\link{pheno_synchrony}} for synchrony analysis
}
\author{
Matthias Templ
}
