detect_all_events: Detect All Glycemic Events

In cgmguru: Advanced Continuous Glucose Monitoring Analysis with High-Performance C++ Backend

Detect All Glycemic Events

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, Level 1 excluded events, and rebound hypo-/hyperglycemia summaries. Rebound hypoglycemia and hyperglycemia definitions follow Hansen and Bibby (2024). 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 grid, maxima_grid, or excursion. CGM summary metrics in subject_summary are calculated from the original raw glucose values by default. Set summary_metrics_source = "preprocessed" to calculate them from the internal event-preprocessed grid. Numeric summary outputs are rounded to summary_digits decimal places; set summary_digits = NULL or summary_digits = "none" to return unrounded values.

Usage

detect_all_events(df, reading_minutes = NULL, sort_time = FALSE,
 inter_gap = 45, return_interpolated = FALSE,
 summary_metrics_source = c("raw", "preprocessed"),
 sensor_wear_ndays = NULL, summary_digits = 2)

Arguments

df	A dataframe containing continuous glucose monitoring (CGM) data. Must include columns: id: Subject identifier (string or factor) time: Time of measurement (POSIXct) gl: Glucose value (integer or numeric, mg/dL)
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 NULL. If omitted or NULL, the interval is calculated automatically per id as the median positive time difference in the data.
sort_time	Logical. If TRUE, sort rows within each id by time in C++ before interpolation. Defaults to FALSE.
inter_gap	Maximum gap in minutes to interpolate across. Defaults to 45; larger gaps split event-detection segments.
return_interpolated	Logical. If TRUE, include the internal event-preprocessed grid as interpolated_data. Defaults to FALSE.
summary_metrics_source	Character. Source glucose values for CGM summary metrics. Defaults to "raw" for original observed data; use "preprocessed" for the internal event-preprocessed grid after interpolation and gap masking. sensor_wear_percent is always calculated from the original timestamps and glucose readings.
sensor_wear_ndays	Number of days for fixed-window sensor_wear_percent calculation. Defaults to NULL, which uses the original timestamp span. Set to a positive number such as 90 to calculate observed readings over the last 90 days for each subject divided by the expected number of readings in 90 days.
summary_digits	Number of decimal places for numeric summary outputs in subject_summary and rate/duration columns in glycemic_event_summary. Defaults to 2. Use NULL or "none" to return unrounded values.

Value

A list containing:

• subject_summary: One row per subject. CGM summary metric columns are calculated on the original raw glucose values by default; set summary_metrics_source = "preprocessed" to use the event-preprocessed glucose grid. Event summaries are included as wide *_total_episodes columns only. Numeric summary columns are rounded according to summary_digits.

• glycemic_event_summary: One row per subject, event type, and event level. Contains the full event summary: id, type, level, total_episodes, avg_ep_per_day, and avg_minutes_below_54_per_episode.

• interpolated_data: Included when return_interpolated = TRUE, with columns id, time, and gl.

subject_summary includes:

• id: Subject identifier

• TIR: Percent of glucose readings in range 70-180 mg/dL

• TITR: Percent of glucose readings in tight range 70-140 mg/dL

• TBR70: Percent of glucose readings below 70 mg/dL

• TBR54: Percent of glucose readings below 54 mg/dL

• TAR180: Percent of glucose readings above 180 mg/dL

• TAR250: Percent of glucose readings above 250 mg/dL

• CV: Coefficient of variation in percent, 100 * SD / mean_glucose

• SD: Sample standard deviation of glucose, mg/dL

• mean_glucose: Mean glucose, mg/dL

• GMI: Glucose Management Indicator, 3.31 + 0.02392 * mean_glucose

• uGMI: Unitless GMI-style metric, 1 / (15.36 / mean_glucose + 0.0425)

• GRI: Glycemia Risk Index, 3.0 * VLow + 2.4 * Low + 1.6 * VHigh + 0.8 * High, where VLow is percent time <54 mg/dL, Low is 54-<70 mg/dL, VHigh is >250 mg/dL, and High is >180-\leq250 mg/dL

• sensor_wear_percent: Percent of expected CGM readings observed, calculated from the original timestamps using the same automatic range method as iglu::active_percent() by default. If sensor_wear_ndays is supplied, this is calculated over the last N days for each subject.

• hypo_lv1_total_episodes: Number of Level 1 hypoglycemia episodes

• hypo_lv2_total_episodes: Number of Level 2 hypoglycemia episodes

• hypo_extended_total_episodes: Number of extended hypoglycemia episodes

• hypo_lv1_excl_total_episodes: Number of Level 1 hypoglycemia episodes that do not overlap a Level 2 episode

• hypo_rebound_total_episodes: Number of rebound hypoglycemia episodes

• hyper_lv1_total_episodes: Number of Level 1 hyperglycemia episodes

• hyper_lv2_total_episodes: Number of Level 2 hyperglycemia episodes

• hyper_extended_total_episodes: Number of extended hyperglycemia episodes

• hyper_lv1_excl_total_episodes: Number of Level 1 hyperglycemia episodes that do not overlap a Level 2 episode

• hyper_rebound_total_episodes: Number of rebound hyperglycemia episodes

glycemic_event_summary includes:

• id: Subject identifier

• type: Event direction, either "hypo" or "hyper"

• level: Event level, one of "lv1", "lv2", "extended", "lv1_excl", or "rebound"

• total_episodes: Number of episodes for the subject, event direction, and event level

• avg_ep_per_day: Average episodes per day for the subject, event direction, and event level, rounded according to summary_digits

• avg_minutes_below_54_per_episode: For hypoglycemia rows, average minutes below 54 mg/dL per episode, rounded according to summary_digits; for hyperglycemia rows, 0

Event types

- Hypoglycemia: lv1 (< 70 mg/dL, \geq 15 min), lv2 (< 54 mg/dL, \geq 15 min), extended (< 70 mg/dL, \geq 120 min). - Hyperglycemia: lv1 (> 180 mg/dL, \geq 15 min), lv2 (> 250 mg/dL, \geq 15 min), extended (> 250 mg/dL, \geq 90 min in 120 min, end \leq 180 mg/dL for \geq 15 min). - Rebound: hypo rebound is Level 1 hyperglycemia followed by <70 mg/dL within 120 minutes; hyper rebound is Level 1 hypoglycemia followed by >180 mg/dL within 120 minutes.

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.

Hansen, K. W., and Bibby, B. M. (2024). Rebound hypoglycemia and hyperglycemia in type 1 diabetes. Journal of Diabetes Science and Technology, 18(6), 1392-1398.

See Also

detect_hyperglycemic_events, detect_hypoglycemic_events, rebound_events

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$subject_summary)
print(all_outputs$glycemic_event_summary)

# Detect all events on larger dataset
large_outputs <- detect_all_events(example_data_hall)
print(paste("Total subjects analyzed:", nrow(large_outputs$subject_summary)))

cgmguru documentation built on July 8, 2026, 9:06 a.m.