% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cgmguru-package.R
\docType{package}
\name{cgmguru-package}
\alias{cgmguru}
\alias{cgmguru-package}
\title{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)
}
}

\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}}
}
\author{
Sang Ho Park \email{shstat1729@gmail.com}
}
\keyword{internal}
