#' Advanced Continuous Glucose Monitoring Analysis and GRID-Based Event Detection
#'
#' @description
#' A high-performance R package for comprehensive Continuous Glucose Monitoring (CGM) data
#' analysis with optimized C++ implementations. The package provides advanced tools for
#' CGM data analysis with two primary capabilities: GRID and postprandial peak detection,
#' and extended glycemic events detection aligned with international consensus CGM metrics.
#'
#' @details
#' The package implements several key algorithms for CGM analysis:
#' \itemize{
#'   \item \strong{GRID Algorithm}: Detects rapid glucose rate increases (commonly \eqn{\geq} 90-95 mg/dL/hour)
#'         with configurable thresholds and gaps for postprandial peak detection
#'   \item \strong{Postprandial Peak Detection}: Finds peak glucose after GRID points using
#'         local maxima and configurable time windows
#'   \item \strong{Consensus CGM Metrics Event Detection}: Level 1/2 hypo- and hyperglycemia
#'         detection with duration validation (default minimum 15 minutes) aligned with
#'         Battelino et al. (2023) international consensus
#'   \item \strong{Advanced Analysis Tools}: Local maxima finding, excursion analysis,
#'         and robust episode validation utilities
#' }
#'
#' Core algorithms are implemented in optimized C++ via 'Rcpp' for accurate and fast
#' analysis on large datasets, making the package suitable for both research and
#' clinical applications.
#'
#' @section Relationship to iglu:
#' cgmguru uses the \pkg{iglu} package as a formal methodological reference,
#' source of example datasets, and comparison target. Event preprocessing is an
#' independent C++ implementation of iglu-compatible semantics: a midnight-aligned
#' full-day grid, interpolation up to \code{inter_gap}, removal of gap-masked
#' rows, and segment-wise event classification. cgmguru does not call \pkg{iglu}
#' at runtime for its core algorithms.
#'
#' The event preprocessing grid applies only to event functions and
#' \code{\link{interpolate_cgm}}. GRID-family functions, including
#' \code{\link{grid}}, \code{\link{maxima_grid}}, and \code{\link{excursion}},
#' operate on the input timestamps and glucose values supplied by the user.
#'
#' @section Main Functions:
#' \describe{
#'   \item{\code{\link{grid}}}{GRID algorithm for detecting rapid glucose rate increases}
#'   \item{\code{\link{maxima_grid}}}{Combined maxima detection and GRID analysis for postprandial peaks}
#'   \item{\code{\link{detect_hyperglycemic_events}}}{Hyperglycemic event detection (Level 1/2/Extended)}
#'   \item{\code{\link{detect_hypoglycemic_events}}}{Hypoglycemic event detection (Level 1/2/Extended)}
#'   \item{\code{\link{detect_all_events}}}{Comprehensive detection of all glycemic event types}
#'   \item{\code{\link{find_local_maxima}}}{Local maxima identification in glucose time series}
#'   \item{\code{\link{interpolate_cgm}}}{C++ iglu-compatible event-grid interpolation}
#'   \item{\code{\link{orderfast}}}{Fast dataframe ordering utility}
#' }
#'
#' @section Data Requirements:
#' Input dataframes should contain:
#' \itemize{
#'   \item \code{id}: Patient identifier (character or factor)
#'   \item \code{time}: POSIXct timestamps
#'   \item \code{gl}: Glucose values in mg/dL
#' }
#'
#' All function arguments and return values are expected to be in tibble format.
#' For convenience, single-column parameters can be passed as vectors in R, which
#' will be automatically converted to single-column tibbles.
#'
#' @section Examples:
#' \preformatted{
#' # Basic GRID analysis
#' result <- grid(cgm_data, gap = 15, threshold = 130)
#'
#' # Postprandial peak detection (GRID-based)
#' maxima <- maxima_grid(cgm_data, threshold = 130, gap = 60, hours = 2)
#'
#' # Level 1 Hyperglycemic event detection
#' events <- detect_hyperglycemic_events(cgm_data, type = "lv1")
#'
#' # Comprehensive event detection; reading_minutes is calculated automatically
#' all_events <- detect_all_events(cgm_data)
#' }
#'
#' @author Sang Ho Park \email{shstat1729@gmail.com}
#'
#' @references
#' \itemize{
#'   \item Battelino, T., et al. "Continuous glucose monitoring and metrics for clinical trials: an international consensus statement." *The Lancet Diabetes & Endocrinology* 11.1 (2023): 42-57.
#'   \item Harvey, Rebecca A., et al. "Design of the glucose rate increase detector: a meal detection module for the health monitoring system." *Journal of diabetes science and technology* 8.2 (2014): 307-320.
#'   \item Adolfsson, Peter, et al. "Increased time in range and fewer missed bolus injections after introduction of a smart connected insulin pen." Diabetes Technology & Therapeutics 22.10 (2020): 709-718.
#'   \item Broll, S., Urbanek, J., Buchanan, D., Chun, E., Muschelli, J., Punjabi, N., and Gaynanova, I. "Interpreting blood glucose data with R package iglu." PLoS One 16.4 (2021): e0248560. doi:10.1371/journal.pone.0248560.
#'   \item Chun, E., Fernandes, J. N., and Gaynanova, I. "An Update on the iglu Software Package for Interpreting Continuous Glucose Monitoring Data." Diabetes Technology & Therapeutics 26.12 (2024): 939-950. doi:10.1089/dia.2024.0154.
#'   \item Park, Sang Ho, et al. "Identification of clinically meaningful automatically detected postprandial glucose excursions in individuals with type 1 diabetes using personal continuous glucose monitoring." Diabetes Research and Clinical Practice (2025): 112951.
#'   \item Park, Soojin, et al. "High-Amplitude and Prolonged Glucose Excursions as a Key Determinant of Discordance Between Glucose Management Indicator and Glycated Hemoglobin in Type 1 Diabetes." Diabetes Care (2026): dc252820. https://doi.org/10.2337/dc25-2820
#'   \item Edwards, Stephanie, et al. "Use of connected pen as a diagnostic tool to evaluate missed bolus dosing behavior in people with type 1 and type 2 diabetes." Diabetes Technology & Therapeutics 24.1 (2022): 61-66.
#' }
#'
#' For more information about the GRID algorithm and CGM analysis methodologies,
#' see the package vignette: \code{vignette("intro", package = "cgmguru")}
#'
#' @seealso
#' \code{\link{grid}}, \code{\link{maxima_grid}}, \code{\link{detect_hyperglycemic_events}}, \code{\link{detect_all_events}}
#'
#' @keywords internal
#' @useDynLib cgmguru, .registration = TRUE
#' @importFrom Rcpp evalCpp
"_PACKAGE"

## usethis namespace: start
## usethis namespace: end
NULL
