excursion: Calculate Glucose Excursions

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

Calculate Glucose Excursions

Description

Calculates glucose excursions in CGM data. An excursion is defined as a > 70 mg/dL (> 3.9 mmol/L) rise within 2 hours, not preceded by a value < 70 mg/dL (< 3.9 mmol/L).

Usage

excursion(df, gap = 15)

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)
gap	Gap threshold in minutes for excursion calculation (default: 15). This parameter defines the minimum time interval between consecutive GRID events.

Value

A list containing:

• excursion_vector: Tibble with excursion results (excursion)

• episode_counts: Tibble with episode counts per subject (id, episode_counts)

• episode_start: Tibble with all episode starts with columns:

  • id: Subject identifier

  • time: Timestamp at which the event occurs; equivalent to df$time[indices]

  • gl: Glucose value at the event; equivalent to df$gl[indices]

  • indices: R-based (1-indexed) row number(s) in df denoting where the event occurs

Notes

- gap is minutes; change to enforce minimum separation between excursions.

References

Edwards, S., et al. (2022). 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), 61-66.

See Also

grid

Examples

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

# Calculate glucose excursions
excursion_result <- excursion(example_data_5_subject, gap = 15)
print(paste("Excursion vector length:", length(excursion_result$excursion_vector)))
print(excursion_result$episode_counts)

# Excursion analysis with different gap
excursion_30min <- excursion(example_data_5_subject, gap = 30)

# Analysis on larger dataset
large_excursion <- excursion(example_data_hall, gap = 15)
print(paste("Excursion vector length in larger dataset:", length(large_excursion$excursion_vector)))
print(paste("Total episodes:", sum(large_excursion$episode_counts$episode_counts)))

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