% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pheno_trend_turning.R
\name{pheno_trend_turning}
\alias{pheno_trend_turning}
\title{Detect Trend Turning Points in Phenological Time Series}
\usage{
pheno_trend_turning(pep, by = NULL, min_years = 10, aggregate = TRUE)
}
\arguments{
\item{pep}{A \code{pep} object, data.table, or numeric vector of DOY values.
If a data.frame/data.table, must contain \code{year} and \code{day} columns.}

\item{by}{Character vector of column names to group by before analysis.
Default is \code{NULL} (analyze all data as one series). Common choices:
\code{c("genus", "species", "phase_id")} or \code{c("country", "phase_id")}.}

\item{min_years}{Integer. Minimum number of years required for analysis.
Default is 10. Shorter series may produce unreliable results.}

\item{aggregate}{Logical. If \code{TRUE} (default), aggregates multiple
observations per year (e.g., from multiple stations) using the median.
If \code{FALSE}, expects exactly one value per year.}
}
\value{
An object of class \code{pheno_turning} containing:
\describe{
\item{results}{Data.table with columns: year, day (or median_day),
tau_prog (progressive tau), tau_retr (retrograde tau),
is_turning (logical indicating turning points)}
\item{turning_points}{Years identified as potential turning points}
\item{n_years}{Number of years in the series}
\item{by}{Grouping variables used (if any)}
\item{group_results}{If \code{by} is specified, list of results per group}
}
}
\description{
Applies a sequential Mann-Kendall test to detect approximate trend turning
points in phenological time series. This identifies years where trends
may have changed direction (e.g., when spring advancement accelerated or
reversed).
}
\details{
The sequential Mann-Kendall test calculates two series:
\itemize{
\item \strong{Progressive}: Kendall's tau computed from the start forward
\item \strong{Retrograde}: Kendall's tau computed from the end backward
}

Points where these series cross indicate potential trend turning points.
When either series exceeds confidence thresholds (|tau| > 1.96 for 95\%,
|tau| > 2.58 for 99\%) before and after a crossing, the turning point
is considered statistically significant.
}
\section{Interpretation}{

\itemize{
\item Positive tau indicates an increasing trend (later DOY = delayed phenology)
\item Negative tau indicates a decreasing trend (earlier DOY = advanced phenology)
\item Crossing points suggest the trend direction may have changed
}
}

\examples{
# Simple vector input (fast)
doy_series <- c(120, 118, 122, 115, 110, 108, 112, 105, 102, 100)
turning <- pheno_trend_turning(doy_series)
print(turning)

# Using pep_seed data (no grouping for speed)
data(pep_seed)
vine <- pep_seed[pep_seed$species == "Vitis vinifera" &
                 pep_seed$phase_id == 65, ]
if (nrow(vine) > 0) {
  turning <- pheno_trend_turning(vine)
}

}
\references{
Sneyers R (1990). On statistical analysis of series of observations.
Technical Note No 143. World Meteorological Organization.
}
\seealso{
\code{\link{pheno_gradient}} for spatial trend analysis,
\code{\link{pheno_normals}} for baseline calculations
}
\author{
Matthias Templ
}
