% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pep_quality.R
\name{pep_quality}
\alias{pep_quality}
\title{Assess Data Quality of Phenological Observations}
\usage{
pep_quality(
  pep,
  by = c("s_id", "genus", "phase_id"),
  year_range = NULL,
  species = NULL,
  phase_id = NULL,
  outlier_method = c("tukey", "zscore"),
  na.rm = TRUE
)
}
\arguments{
\item{pep}{A \code{pep} object or \code{data.table} containing phenological
observations with columns \code{year}, \code{day}, and grouping variables.}

\item{by}{Character vector of column names to group by for quality assessment.
Default is \code{c("s_id", "genus", "phase_id")} for station-level assessment.}

\item{year_range}{Optional integer vector of length 2 specifying the start and
end years for assessment. If \code{NULL} (default), uses the full range
of years in the data.}

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

\item{phase_id}{Optional integer vector to filter by BBCH phase codes.}

\item{outlier_method}{Character string specifying outlier detection method.
Either \code{"tukey"} (default, uses 1.5*IQR rule) or \code{"zscore"}
(flags values with |z| > 3).}

\item{na.rm}{Logical. Should missing values be removed? Default \code{TRUE}.}
}
\value{
A \code{data.table} with the following columns:
\describe{
\item{by variables}{Grouping variables as specified in \code{by}}
\item{n_obs}{Total number of observations}
\item{year_min}{First year of observations}
\item{year_max}{Last year of observations}
\item{year_span}{Total span in years (year_max - year_min + 1)}
\item{n_years}{Number of distinct years with data}
\item{completeness_pct}{Percentage of years with data within the span}
\item{max_gap_years}{Length of the longest gap (consecutive missing years)}
\item{n_gaps}{Number of gaps in the time series}
\item{n_outliers}{Number of statistical outliers detected}
\item{outlier_pct}{Percentage of observations that are outliers}
\item{doy_mean}{Mean day-of-year}
\item{doy_sd}{Standard deviation of day-of-year}
\item{doy_range}{Range of day-of-year values}
\item{quality_grade}{Overall quality grade (A, B, C, or D)}
}
}
\description{
Provides a comprehensive assessment of data completeness, temporal coverage,
outlier prevalence, and assigns quality grades to phenological time series.
}
\details{
This function evaluates phenological time series quality based on multiple
criteria important for trend analysis and climatological calculations.
}
\section{Quality Grading Criteria}{

\describe{
\item{Grade A}{Completeness >= 80\%, no gaps > 2 years, outliers < 2\%}
\item{Grade B}{Completeness >= 60\%, no gaps > 5 years, outliers < 5\%}
\item{Grade C}{Completeness >= 40\%, gaps <= 10 years, outliers < 10\%}
\item{Grade D}{Below grade C thresholds}
}
}

\section{Outlier Detection}{

The Tukey method (default) flags observations outside the interquartile
fences: \code{[Q1 - 1.5*IQR, Q3 + 1.5*IQR]}. This is robust to non-normal
distributions common in phenological data.
}

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

# Subset to one country for speed
pep_ch <- pep[country == "Switzerland"]

# Assess quality for stations in Switzerland
quality <- pep_quality(pep_ch)
print(quality)

# Filter to high-quality stations only
high_quality <- quality[quality_grade \%in\% c("A", "B")]
high_quality

# Assess specific species and phase
apple_quality <- pep_quality(pep_ch,
                             species = "Malus",
                             phase_id = 60)
apple_quality

# Country-level assessment (use subset of countries)
pep_subset <- pep[country \%in\% c("Switzerland", "Austria")]
country_quality <- pep_quality(pep_subset,
                               by = c("country", "genus", "phase_id"))
country_quality

# Assess quality within a specific time window
modern_quality <- pep_quality(pep_ch,
                              year_range = c(1991, 2020))
modern_quality
}

}
\references{
Schaber, J. and Badeck, F.-W. (2002). Evaluation of methods for the
combination of phenological time series and outlier detection.
\emph{Tree Physiology}, 22, 973--982.
\doi{10.1093/treephys/22.14.973}
}
\seealso{
\code{\link{pheno_normals}} for calculating climatological normals,
\code{\link{pheno_anomaly}} for anomaly detection
}
\author{
Matthias Templ
}
