% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cgmguru-functions-docs.R
\name{detect_all_events}
\alias{detect_all_events}
\title{Detect All Glycemic Events}
\usage{
detect_all_events(df, reading_minutes = NULL, sort_time = FALSE,
 inter_gap = 45, return_interpolated = FALSE)
}
\arguments{
\item{df}{A dataframe containing continuous glucose monitoring (CGM) data.
Must include columns:
\itemize{
  \item \code{id}: Subject identifier (string or factor)
  \item \code{time}: Time of measurement (POSIXct)
  \item \code{gl}: Glucose value (integer or numeric, mg/dL)
}}

\item{reading_minutes}{Time interval between readings in minutes (optional).
Can be a single integer/numeric value (applied to all subjects), a vector
matching data length, or \code{NULL}. If omitted or \code{NULL}, the
interval is calculated automatically per id as the median positive time
difference in the data.}

\item{sort_time}{Logical. If \code{TRUE}, sort rows within each id by
\code{time} in C++ before interpolation. Defaults to \code{FALSE}.}

\item{inter_gap}{Maximum gap in minutes to interpolate across. Defaults to
45; larger gaps split event-detection segments.}

\item{return_interpolated}{Logical. Retained for backward compatibility and
ignored; \code{detect_all_events()} does not return interpolated data.}
}
\value{
A list with two tibbles:
\itemize{
  \item \code{events_long_df}: One row per subject, event type, and event
    level. Contains the full event summary: \code{id}, \code{type},
    \code{level}, \code{total_episodes}, \code{avg_ep_per_day}, and
    \code{avg_episode_duration_below_54}.
  \item \code{summary_df}: One row per subject. CGM summary metric columns
    are calculated on the interpolated glucose grid, and event summaries are
    included as wide \code{*_event_count} columns only.
}
\code{summary_df} includes:
\itemize{
  \item \code{id}: Subject identifier
  \item \code{TIR}: Time in range 70-180 mg/dL, percent
  \item \code{TITR}: Time in tight range 70-140 mg/dL, percent
  \item \code{TBR70}, \code{TBR54}: Time below 70 and 54 mg/dL, percent
  \item \code{TAR180}, \code{TAR250}: Time above 180 and 250 mg/dL, percent
  \item \code{CV}: Glucose standard deviation divided by mean glucose
  \item \code{SD}: Glucose standard deviation
  \item \code{mean_glucose}: Mean glucose in mg/dL
  \item \code{GMI}: \eqn{3.31 + 0.02392 * mean_glucose}
  \item \code{uGMI}: \eqn{1 / (15.36 / mean_glucose + 0.0425)}
  \item \code{GRI}: Glycemia Risk Index,
    \eqn{3.0 * VLow + 2.4 * Low + 1.6 * VHigh + 0.8 * High}, where
    \code{VLow} is percent time \eqn{<}54 mg/dL, \code{Low} is 54-\eqn{<}70
    mg/dL, \code{VHigh} is \eqn{>}250 mg/dL, and \code{High} is
    \eqn{>}180-\eqn{\leq}250 mg/dL
  \item \code{sensor_wear}: Percent of expected CGM readings observed,
    calculated from the original timestamps using the same automatic range
    method as \code{iglu::active_percent()}
}
Event counts are returned in wide columns for each hypo/hyper level
combination, for example \code{hypo_lv1_event_count}. The same pattern is
repeated for \code{lv1}, \code{lv2}, \code{extended}, and \code{lv1_excl}
within both \code{hypo} and \code{hyper}.
}
\description{
Comprehensive function to detect all types of glycemic events aligned with
international consensus CGM metrics (Battelino et al., 2023). This function
provides a unified interface for detecting multiple event types including
Level 1/2/Extended hypo- and hyperglycemia, and Level 1 excluded events.
Events are counted only after the required recovery condition is confirmed;
duration summaries use the event boundary immediately before recovery starts.
Event preprocessing uses cgmguru's independent C++ implementation of an
iglu-compatible day-based grid: each subject is interpolated from the first
observed day's midnight plus one reading interval, rather than from the first
observed timestamp. Larger gaps are masked and removed before event
classification, preserving gap-based segment boundaries. This preprocessing
is specific to event calculation and does not affect \code{\link{grid}},
\code{\link{maxima_grid}}, or \code{\link{excursion}}.
}
\section{Event types}{

- Hypoglycemia: lv1 (\eqn{<} 70 mg/dL, \eqn{\geq} 15 min), lv2 (\eqn{<} 54 mg/dL, \eqn{\geq} 15 min), extended (\eqn{<} 70 mg/dL, \eqn{\geq} 120 min).
- Hyperglycemia: lv1 (\eqn{>} 180 mg/dL, \eqn{\geq} 15 min), lv2 (\eqn{>} 250 mg/dL, \eqn{\geq} 15 min), extended (\eqn{>} 250 mg/dL, \eqn{\geq} 90 min in 120 min, end \eqn{\leq} 180 mg/dL for \eqn{\geq} 15 min).
}

\examples{
# Load sample data
library(iglu)
data(example_data_5_subject)
data(example_data_hall)

# Detect all glycemic events; reading_minutes is calculated automatically
# from the timestamp spacing when omitted
all_outputs <- detect_all_events(example_data_5_subject)
print(all_outputs$summary_df)
print(all_outputs$events_long_df)

# Detect all events on larger dataset
large_outputs <- detect_all_events(example_data_hall)
print(paste("Total subjects analyzed:", nrow(large_outputs$summary_df)))
}
\references{
Battelino, T., et al. (2023). Continuous glucose monitoring and metrics for clinical trials: an international consensus statement. The Lancet Diabetes & Endocrinology, 11(1), 42-57.
}
\seealso{
\link{detect_hyperglycemic_events}, \link{detect_hypoglycemic_events}
}
