% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pep_completeness.R
\name{pep_completeness}
\alias{pep_completeness}
\title{Assess Species and Phase Completeness of Phenological Data}
\usage{
pep_completeness(
  pep,
  by = c("genus", "species", "phase_id"),
  year_range = NULL,
  min_obs = 1,
  include_years = FALSE
)
}
\arguments{
\item{pep}{A \code{pep} object or \code{data.table} containing phenological
observations with columns \code{year}, \code{day}, \code{genus},
\code{species}, and \code{phase_id}.}

\item{by}{Character vector specifying grouping dimensions. Options include
\code{"species"}, \code{"genus"}, \code{"phase_id"}, \code{"year"},
\code{"country"}, and \code{"s_id"}. Default is
\code{c("genus", "species", "phase_id")}.}

\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{min_obs}{Integer. Minimum number of observations required to include
a group in the output. Default is 1.}

\item{include_years}{Logical. If \code{TRUE}, includes year-level detail
in the output (creates a row per group × year). Default is \code{FALSE}
for summary mode.}
}
\value{
A \code{data.table} of class \code{pep_completeness} with columns:
\describe{
\item{by variables}{Grouping variables as specified in \code{by}}
\item{n_obs}{Total number of observations}
\item{n_stations}{Number of unique stations}
\item{n_years}{Number of years with data}
\item{year_min}{First year of observations}
\item{year_max}{Last year of observations}
\item{year_span}{Total span in years}
\item{completeness_pct}{Percentage of years with data within span}
\item{median_doy}{Median day of year}
\item{iqr_doy}{Interquartile range of day of year}
}
}
\description{
Provides comprehensive assessment of data completeness across species,
phases, years, and optionally countries. Useful for identifying data gaps
and planning analyses.
}
\details{
This function assesses data coverage across multiple dimensions, helping
users understand where data is available and where gaps exist. It is
particularly useful for:
\itemize{
\item Identifying which species × phase combinations have sufficient data
\item Finding temporal gaps in time series
\item Comparing coverage across countries or regions
\item Planning analyses that require minimum observation counts
}
}
\section{Completeness Calculation}{

Completeness is calculated as the percentage of years with at least one
observation within the year span (year_max - year_min + 1). A completeness
of 100\% means every year in the span has data.
}

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

# Use Swiss subset for faster computation
pep_ch <- pep[country == "Switzerland"]

# Basic completeness by species and phase
comp <- pep_completeness(pep_ch)
print(comp)

# Filter to well-observed combinations
comp_good <- comp[n_obs >= 100 & completeness_pct >= 80]

# Completeness by country (use Alpine countries)
pep_alpine <- pep[country \%in\% c("Switzerland", "Austria")]
comp_country <- pep_completeness(pep_alpine,
                                 by = c("country", "genus", "phase_id"))

# Year-level detail for a specific period
comp_yearly <- pep_completeness(pep_ch,
                                 year_range = c(1991, 2020),
                                 include_years = TRUE)

# Visualize completeness
plot(comp)
}

}
\seealso{
\code{\link{pep_check_phases}} for validating expected phases exist,
\code{\link{pep_quality}} for quality grading,
\code{\link{pep_coverage}} for overall data coverage
}
\author{
Matthias Templ
}
