detect_hypoglycemic_events: Detect Hypoglycemic Events

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

Detect Hypoglycemic Events

Description

Identifies and segments hypoglycemic events in CGM data based on international consensus CGM metrics (Battelino et al., 2023). Supports three event types:

• Level 1: \geq 15 consecutive min of < 70 mg/dL, ends with \geq 15 consecutive min \geq 70 mg/dL

• Level 2: \geq 15 consecutive min of < 54 mg/dL, ends with \geq 15 consecutive min \geq 54 mg/dL

• Extended: > 120 consecutive min of < 70 mg/dL, ends with \geq 15 consecutive min \geq 70 mg/dL

Events are detected when glucose falls below the start threshold for the minimum duration and ends when glucose rises above the end threshold for the specified end length.

Usage

detect_hypoglycemic_events(df,
                                 reading_minutes = NULL,
                                 dur_length = 120,
                                 end_length = 15,
                                 start_gl = 70)

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)
dur_length	Minimum duration in minutes for event classification (default: 120)
end_length	End length criteria in minutes (default: 15)
start_gl	Starting glucose threshold in mg/dL (default: 70)

Value

A list containing:

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

• events_detailed: Tibble with detailed event information (id, start_time, start_glucose, end_time, end_glucose, start_indices, end_indices, duration_below_54_minutes)

Units and sampling

- reading_minutes can be a scalar (all rows) or a vector per-row. - If reading_minutes is NULL, duration is computed from time deltas.

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: \eqn{<} 70 \eqn{\geq} 15 min,
# ends \eqn{\geq} 70 \eqn{\geq} 15 min
hypo_lv1 <- detect_hypoglycemic_events(
  example_data_5_subject, 
  start_gl = 70, 
  dur_length = 15, 
  end_length = 15
)
print(hypo_lv1$events_total)

# Level 2: \eqn{<} 54 \eqn{\geq} 15 min,
# ends \eqn{\geq} 54 \eqn{\geq} 15 min
hypo_lv2 <- detect_hypoglycemic_events(
  example_data_5_subject, 
  start_gl = 54, 
  dur_length = 15, 
  end_length = 15
)

# Extended: \eqn{<} 70 \eqn{\geq} 120 min, 
# ends \eqn{\geq} 70 \eqn{\geq} 15 min
hypo_extended <- detect_hypoglycemic_events(example_data_5_subject)
print(hypo_extended$events_total)

# Compare event rates across levels
cat("Level 1 events:", sum(hypo_lv1$events_total$total_events), "\n")
cat("Level 2 events:", sum(hypo_lv2$events_total$total_events), "\n")
cat("Extended events:", sum(hypo_extended$events_total$total_events), "\n")

# Analysis on larger dataset with Level 1 criteria
large_hypo <- detect_hypoglycemic_events(example_data_hall, 
                                         start_gl = 70, 
                                         dur_length = 15, 
                                         end_length = 15)
print(large_hypo$events_total)

# Analysis on larger dataset with Level 2 criteria
large_hypo_lv2 <- detect_hypoglycemic_events(example_data_hall,
                                             start_gl = 54,
                                             dur_length = 15,
                                             end_length = 15)
print(large_hypo_lv2$events_total)

# Analysis on larger dataset with Extended criteria
large_hypo_extended <- detect_hypoglycemic_events(example_data_hall)
print(large_hypo_extended$events_total)

cgmguru documentation built on Nov. 6, 2025, 1:07 a.m.