% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pep_second_events.R
\name{pep_second_events}
\alias{pep_second_events}
\title{Detect Second Flowering and Other Repeated Phenological Events}
\usage{
pep_second_events(
  pep,
  phases = c(60, 65),
  method = c("late_season", "multiple_per_year", "both"),
  late_threshold = 250,
  gap_threshold = 60,
  reference_period = 1991:2020,
  z_threshold = 3,
  min_obs = 10
)
}
\arguments{
\item{pep}{A \code{pep} object or data.table with phenological observations.}

\item{phases}{Integer vector of phase IDs to analyze. Default is
\code{c(60, 65)} for flowering phases. Use \code{NULL} to analyze all phases.}

\item{method}{Character. Detection method:
\describe{
\item{"late_season"}{(Default) Flag observations occurring after the
expected phenological window (DOY > late_threshold).}
\item{"multiple_per_year"}{Detect multiple observations of the same
phase at the same station within a single year.}
\item{"both"}{Apply both methods.}
}}

\item{late_threshold}{Integer. DOY threshold for "late season" events.
Default is 250 (~September 7). Events after this date for spring phases
are flagged as potential second events.}

\item{gap_threshold}{Integer. For "multiple_per_year" method, minimum days
between observations to consider them separate events. Default is 60.}

\item{reference_period}{Integer vector of years to calculate expected
phenological windows. Default is \code{1991:2020}.}

\item{z_threshold}{Numeric. Z-score threshold for identifying late events
relative to the reference period. Default is 3.}

\item{min_obs}{Integer. Minimum observations in reference period to calculate
expected windows. Default is 10.}
}
\value{
A list of class \code{second_events} containing:
\describe{
\item{events}{Data.table of detected second/repeated events with columns:
s_id, species, phase_id, year, day, event_type, expected timing info}
\item{summary}{Summary statistics by species, phase, and event type}
\item{by_year}{Annual counts of detected events}
\item{by_month}{Monthly distribution of events}
\item{total_by_year}{Total observations per year (for relative scaling in plots)}
\item{method}{Detection method used}
\item{params}{Parameters used for detection}
}
}
\description{
Identifies potential second flowering events and other irregular repeated
phenological observations. These may represent biologically meaningful
responses to climate disruption rather than data errors.
}
\details{
Second flowering and other repeated phenological events are increasingly
reported as climate patterns become more irregular. These events may indicate:
\itemize{
\item Disrupted coordination between environmental cues and development
\item Response to unusual autumn warmth after summer dormancy
\item Failure of normal seasonal inhibition mechanisms
}

The function uses two complementary approaches:
\enumerate{
\item \strong{Late season detection}: Identifies observations occurring
well after the normal phenological window (e.g., flowering in autumn)
\item \strong{Multiple events}: Finds stations reporting the same phase
multiple times in one year with sufficient gap between observations
}
}
\section{Interpreting Results}{

Not all detected events are necessarily "true" second flowering. Consider:
\itemize{
\item \strong{High confidence}: Same station reports phase twice with
60+ day gap; late observation is clearly outside normal window
\item \strong{Medium confidence}: Single late observation at a station;
could be second event or data entry error
\item \strong{Requires verification}: Check original data sources,
geographic context, species biology
}
}

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

# Use grapevine flowering in Alpine region (long records, second events possible)
pep_subset <- pep[species == "Vitis vinifera" & phase_id \%in\% c(60, 65) &
                  country \%in\% c("Germany-South", "Switzerland", "Austria")]

if (nrow(pep_subset) > 0) {
  # Method 1: Detect late-season flowering events (default)
  second <- pep_second_events(pep_subset, phases = c(60, 65))
  print(second)
  summary(second)

  # Plot from 1980 onwards for clearer trends
  plot(second, from_year = 1980)
  plot(second, type = "overview", scale = "relative", from_year = 1980)

  # Method 2: Detect repeated observations at same station
  repeated <- pep_second_events(pep_subset, method = "multiple_per_year")
  print(repeated)
  plot(repeated, type = "timeline", from_year = 1980)

  # Method 3: Combine both detection methods
  all_events <- pep_second_events(pep_subset, method = "both")
  summary(all_events)
  plot(all_events)
  plot(all_events, scale = "relative")
}
}

}
\references{
Related to emerging research on phenological irregularity and climate
disruption of seasonal timing.
}
\seealso{
\code{\link{pep_flag_outliers}} for general outlier detection,
\code{\link{pep_plot_outliers}} for outlier visualization
}
\author{
Matthias Templ
}
