% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pheno_synchrony.R
\name{pheno_synchrony}
\alias{pheno_synchrony}
\title{Analyze Phenological Synchrony Across Stations}
\usage{
pheno_synchrony(
  pep,
  species = NULL,
  phase_id = NULL,
  by = c("country", "year"),
  min_stations = 5,
  compute_trend = 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 \code{s_id} (station ID).}

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

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

\item{by}{Character vector of column names to group by for synchrony calculation.
Default is \code{c("country", "year")} for annual synchrony by country.}

\item{min_stations}{Minimum number of stations required to calculate synchrony.
Default is 5. Groups with fewer stations return NA.}

\item{compute_trend}{Logical. If \code{TRUE} (default), computes trend in
synchrony over time using robust regression.}

\item{na.rm}{Logical. Should missing values be removed? Default \code{TRUE}.}
}
\value{
A \code{pheno_synchrony} object (list) containing:
\describe{
\item{data}{A \code{data.table} with synchrony metrics per group:
n_stations, mean_doy, sd_doy, cv_pct, and quality indicators}
\item{trend}{If \code{compute_trend = TRUE}, a data.table with trend
analysis results per region (slope, p-value, direction)}
\item{overall}{Summary statistics across all groups}
}
}
\description{
Measures how synchronized phenological events are across stations within
regions and whether synchrony is changing over time. Higher synchrony
indicates more uniform timing of phenological events.
}
\details{
Synchrony measures how similar phenological timing is across different
stations within the same region and year. This is important for:
\itemize{
\item Understanding spatial coherence of phenological signals
\item Detecting changes in spatial variability over time
\item Assessing network representativeness
}
}
\section{Synchrony Metrics}{

\describe{
\item{sd_doy}{Standard deviation across stations - lower values indicate
higher synchrony}
\item{cv_pct}{Coefficient of variation (SD/mean * 100) - relative measure
that allows comparison across phases with different mean timing}
\item{range_doy}{Range of DOY values across stations}
}
}

\section{Trend Interpretation}{

\itemize{
\item Negative trend in SD: Increasing synchrony over time
\item Positive trend in SD: Decreasing synchrony (more variable)
}
}

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

# Subset to two countries for speed
pep_subset <- pep[country \%in\% c("Switzerland", "Austria")]

# Calculate synchrony for apple flowering by country and year
sync <- pheno_synchrony(pep_subset,
                        species = "Malus",
                        phase_id = 60)
print(sync)

# Get trend results (robust regression per country)
sync$trend

# Synchrony without trend analysis (faster)
sync_simple <- pheno_synchrony(pep_subset,
                               species = "Malus",
                               phase_id = 60,
                               compute_trend = FALSE)
sync_simple

# Custom grouping variables
sync_detailed <- pheno_synchrony(pep_subset,
                                 species = "Malus",
                                 phase_id = 60,
                                 by = c("country", "year"))
sync_detailed
}

}
\references{
Rosenzweig, C. et al. (2008). Attributing physical and biological
impacts to anthropogenic climate change.
\emph{Nature}, 453, 353--357.
\doi{10.1038/nature06937}
}
\seealso{
\code{\link{pheno_normals}} for climatological statistics,
\code{\link{pheno_anomaly}} for anomaly detection
}
\author{
Matthias Templ
}
