% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pep_plot_outliers.R
\name{pep_plot_outliers}
\alias{pep_plot_outliers}
\title{Visualize Phenological Outliers for Inspection}
\usage{
pep_plot_outliers(
  x,
  type = c("overview", "seasonal", "map", "detail", "station", "doy_context",
    "diagnostic", "profile"),
  phase_id = NULL,
  outlier_only = NULL,
  late_threshold = 250,
  n_top = 20,
  ...
)
}
\arguments{
\item{x}{A \code{pep_outliers} object from \code{\link{pep_flag_outliers}}.}

\item{type}{Character. Type of plot to produce:
\describe{
\item{"overview"}{(Default) Multi-panel overview with distribution,
seasonal pattern, and summary statistics.}
\item{"seasonal"}{Distribution of outliers by month/season, useful for
detecting second flowering (late-season outliers for spring phases).}
\item{"map"}{Geographic distribution of outliers (requires lon/lat).}
\item{"detail"}{Detailed view of individual outlier events with context.}
\item{"station"}{Station-level outlier patterns over time.}
\item{"doy_context"}{Shows outliers in context of full DOY distribution
per phase, highlighting potential second events.}
\item{"diagnostic"}{Paper- and vignette-ready 4-panel figure of
model fit quality: (A) residuals vs fitted; (B) Q-Q plot of
residuals; (C) |residual| vs altitude (if available) or year;
(D) spatial map of maximum |residual| per station. Designed to
accompany \code{method = "gam_residual"} but usable for every
method (uses the \code{deviation} column as the residual). For
\code{method = "mahalanobis"} the panels automatically switch
to MD-specific diagnostics (sorted MD with chi-square
threshold; Q-Q against \eqn{\chi^2_p}; mean / max MD over time;
per-station worst-case MD map).}
\item{"profile"}{Parallel-coordinates plot of the phase profile
(one line per station-year across phases), with flagged
station-years highlighted and the robust central profile
overlaid. Designed for \code{method = "mahalanobis"} where the
outlierness lives in the \emph{shape} of a station-year across
phases, not in any single DOY. The primary paper figure for
the multivariate method.}
}}

\item{phase_id}{Optional integer vector to filter specific phases for plotting.}

\item{outlier_only}{Logical. If TRUE (default for some types), show only
outlier observations. If FALSE, show all data with outliers highlighted.}

\item{late_threshold}{Integer. DOY threshold for classifying "late" outliers
as potential second events (default 250, ~September 7).}

\item{n_top}{Integer. For detail view, number of most extreme outliers to show.
Default 20.}

\item{...}{Additional arguments passed to plotting functions.}
}
\value{
A \code{ggplot} object (or list of ggplots for "overview").
}
\description{
Creates diagnostic plots to help distinguish between data errors and
biologically meaningful extreme events (e.g., second flowering). Multiple
plot types reveal different aspects of outlier patterns.
}
\details{
This function is designed to support quality control workflows where the
goal is to distinguish:
\enumerate{
\item \strong{Data errors}: Typos, wrong dates, mis-coded phases
\item \strong{Observer errors}: Misidentified species or phases
\item \strong{Biologically meaningful extremes}: Second flowering, delayed
development, climate-driven anomalies
}

For detecting potential \strong{second flowering events}:
\itemize{
\item Use \code{type = "seasonal"} to see if late-season outliers cluster
in autumn months
\item Use \code{type = "doy_context"} to visualize outliers relative to
the main flowering distribution
\item Focus on flowering phases (60, 65) with late DOY values (>250)
}
}
\examples{
\donttest{
pep <- pep_download()

# Use Swiss subset for faster outlier detection
pep_ch <- pep[country == "Switzerland"]
pep_flagged <- pep_flag_outliers(pep_ch)

# Overview of all outliers
pep_plot_outliers(pep_flagged, type = "overview")

# Seasonal distribution - look for autumn outliers in flowering phases
pep_plot_outliers(pep_flagged, type = "seasonal", phase_id = c(60, 65))

# Geographic pattern
pep_plot_outliers(pep_flagged, type = "map")

# Detailed view of most extreme outliers
pep_plot_outliers(pep_flagged, type = "detail", n_top = 30)

# DOY context for flowering phase - spot potential second flowering
pep_plot_outliers(pep_flagged, type = "doy_context", phase_id = 65)
}

}
\seealso{
\code{\link{pep_flag_outliers}} for detecting outliers,
\code{\link{pep_quality}} for comprehensive quality assessment
}
\author{
Matthias Templ
}
