detect_hyperglycemic_events: Detect Hyperglycemic Events

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

Detect Hyperglycemic Events

Description

Identifies and segments hyperglycemic events in CGM data based on international consensus CGM metrics (Battelino et al., 2023). Use type to select one of three event definitions:

• Level 1: \geq 15 consecutive min of > 180 mg/dL, ends with \geq 15 consecutive min \leq 180 mg/dL

• Level 2: \geq 15 consecutive min of > 250 mg/dL, ends with \geq 15 consecutive min \leq 250 mg/dL

• Extended: > 250 mg/dL lasting \geq 90 cumulative min within a 120-min period, ends when glucose returns to \leq 180 mg/dL for \geq 15 consecutive min after

Events are counted only after glucose remains at or below the end threshold for the specified end length. In events_detailed, end_time, end_glucose, and end_index report the last hyperglycemic reading immediately before that confirmed recovery period starts.

Usage

detect_hyperglycemic_events(df, ..., type = "extended",
 reading_minutes = NULL, sort_time = FALSE, inter_gap = 45,
 return_interpolated = TRUE)

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)
...	Custom event criteria supplied by name. Prefer type for standard Level 1, Level 2, and Extended events. Supported custom criteria are: dur_length: Minimum event duration in minutes required for an event to qualify. end_length: Required recovery duration in minutes before event termination is confirmed. start_gl: Glucose threshold in mg/dL used to qualify hyperglycemic readings. Hyperglycemic readings are above this value. end_gl: Glucose threshold in mg/dL used to confirm recovery. Hyperglycemic events end after glucose remains at or below this value for end_length minutes.
type	Hyperglycemia event definition. One of "extended" (default), "lv1", "lv2", or "lv1_excl".
reading_minutes	Time interval between readings in minutes (optional). 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 interpolated grid data used for event detection in the returned list. Defaults to TRUE.

Value

A list containing:

• events_total: Tibble with summary statistics per subject (id, total_episodes, avg_ep_per_day)

• events_detailed: Tibble with detailed event information (id, start_time, start_glucose, end_time, end_glucose, start_index, end_index). End fields report the last dysglycemic reading before confirmed recovery starts. start_index and end_index are 1-based row positions in the internal interpolated event grid, returned as interpolated_data when return_interpolated = TRUE.

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

Methods

Hyperglycemic events can be detected using either the recommended type argument or named custom threshold and duration criteria.

1. Preset method using type (recommended): Use type when you want the standard Level 1, Level 2, or Extended hyperglycemia definitions without manually entering thresholds.

• type = "lv1" uses start_gl = 180, dur_length = 15, end_length = 15, and end_gl = 180.

• type = "lv2" uses start_gl = 250, dur_length = 15, end_length = 15, and end_gl = 250.

• type = "extended" uses start_gl = 250, dur_length = 120, end_length = 15, and end_gl = 180.

• type = "lv1_excl" returns Level 1 episodes that do not overlap Level 2 episodes.

2. Custom criteria method: Supply start_gl, dur_length, end_length, and end_gl directly when using a custom definition, for example detect_hyperglycemic_events(df, start_gl = 180, dur_length = 15, end_length = 15, end_gl = 180) for Level 1 hyperglycemia. If an explicit type is supplied together with custom numeric criteria, the function returns results based on type; the custom criteria are ignored and a warning is issued.

Units and sampling

- reading_minutes can be a scalar (all rows) or a vector per-row. - If reading_minutes is omitted or NULL, it is calculated automatically per id from timestamp spacing. - Event classification uses cgmguru's independent C++ implementation of an iglu-compatible, midnight-aligned full-day grid. Data are linearly interpolated at the id-specific interval up to inter_gap; larger gaps are masked, removed from the event-classification data, and split segments. - This preprocessing is specific to event calculation and does not affect grid, maxima_grid, or excursion.

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.

See Also

detect_all_events

Examples

# Load sample data
library(iglu)
data(example_data_5_subject)
data(example_data_hall)

# Level 1 Hyperglycemia Event (>=15 consecutive min of >180 mg/dL and event
# ends when there is >=15 consecutive min with a CGM sensor value of <=180 mg/dL)
hyper_lv1 <- detect_hyperglycemic_events(example_data_5_subject, type = "lv1")
print(hyper_lv1$events_total)

# Level 2 Hyperglycemia Event (>=15 consecutive min of >250 mg/dL and event
# ends when there is >=15 consecutive min with a CGM sensor value of <=250 mg/dL)
hyper_lv2 <- detect_hyperglycemic_events(example_data_5_subject, type = "lv2")
print(hyper_lv2$events_total)

# Extended Hyperglycemia Event (>250 mg/dL lasting >=90 cumulative min within a
# 120-min period, ends when glucose returns to <=180 mg/dL for >=15 consecutive
# min after)
hyper_extended <- detect_hyperglycemic_events(example_data_5_subject, type = "extended")
print(hyper_extended$events_total)

# Custom criteria method for the same standard definitions
hyper_lv1_custom <- detect_hyperglycemic_events(
  example_data_5_subject,
  start_gl = 180,
  dur_length = 15,
  end_length = 15,
  end_gl = 180
)
hyper_lv2_custom <- detect_hyperglycemic_events(
  example_data_5_subject,
  start_gl = 250,
  dur_length = 15,
  end_length = 15,
  end_gl = 250
)
hyper_extended_custom <- detect_hyperglycemic_events(
  example_data_5_subject,
  start_gl = 250,
  dur_length = 120,
  end_length = 15,
  end_gl = 180
)

# Compare event rates across levels
cat("Level 1 episodes:", sum(hyper_lv1$events_total$total_episodes), "\n")
cat("Level 2 episodes:", sum(hyper_lv2$events_total$total_episodes), "\n")
cat("Extended episodes:", sum(hyper_extended$events_total$total_episodes), "\n")

# Analysis on larger dataset with Level 1 criteria
large_hyper <- detect_hyperglycemic_events(example_data_hall, type = "lv1")
print(large_hyper$events_total)

# Analysis on larger dataset with Level 2 criteria
large_hyper_lv2 <- detect_hyperglycemic_events(example_data_hall, type = "lv2")
print(large_hyper_lv2$events_total)

# Analysis on larger dataset with Extended criteria
large_hyper_extended <- detect_hyperglycemic_events(example_data_hall, type = "extended")
print(large_hyper_extended$events_total)

# View detailed events for specific subject
if(nrow(hyper_lv1$events_detailed) > 0) {
  first_subject <- hyper_lv1$events_detailed$id[1]
  subject_events <- hyper_lv1$events_detailed[hyper_lv1$events_detailed$id == first_subject, ]
  head(subject_events)
}

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