mage_rcpp: Rcpp MAGE Calculation

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

Rcpp MAGE Calculation

Description

Calculates Mean Amplitude of Glycemic Excursions (MAGE) with an Rcpp backend.

Usage

mage_rcpp(
  data,
  version = c("ma", "naive"),
  sd_multiplier = 1,
  short_ma = 5,
  long_ma = 32,
  return_type = c("num", "df"),
  direction = c("avg", "service", "max", "plus", "minus"),
  tz = "",
  inter_gap = 45,
  max_gap = 180
)

Arguments

data	A dataframe containing CGM data with columns id, time, and gl.
version	Either "ma" or "naive". Defaults to "ma".
sd_multiplier	Multiplier for the standard deviation threshold in version = "naive".
short_ma	Short moving-average window length. Defaults to 5.
long_ma	Long moving-average window length. Defaults to 32.
return_type	Either "num" for one metric per id or "df" for a list-column of segment-level MAGE rows.
direction	One of "avg", "service", "max", "plus", or "minus".
tz	Time zone used for day-grid alignment when supplied.
inter_gap	Maximum gap, in minutes, over which linear interpolation is allowed. Defaults to 45.
max_gap	Gap length, in minutes, above which MAGE is calculated on separate trace segments. Defaults to 180.

Details

The implementation follows the MAGE calculation approaches used by iglu::mage. The default version = "ma" follows iglu's moving-average approach: CGM is interpolated to 5-minute intervals, short and long moving-average crossings identify candidate peak/nadir intervals, and countable excursions are those whose peak-to-nadir or nadir-to-peak amplitude is at least one glucose standard deviation.

The version = "naive" option matches iglu's older standard-deviation based calculation. This function is calculation-only and does not implement iglu's plotting options.

Value

A tibble with columns id and MAGE. With return_type = "df", MAGE is a list-column of tibbles with start, end, mage, plus_or_minus, and first_excursion.

References

Service, F. John, et al. (1970). Mean amplitude of glycemic excursions, a measure of diabetic instability. Diabetes, 19(9), 644-655. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.2337/diab.19.9.644")}

Fernandes, Nathaniel J., et al. (2022). Open-source algorithm to calculate mean amplitude of glycemic excursions using short and long moving averages. Journal of Diabetes Science and Technology, 16(2), 576-577. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1177/19322968211061165")}

See Also

iglu::mage, conga_rcpp

Examples

library(iglu)
data(example_data_5_subject)
mage_rcpp(example_data_5_subject)
mage_rcpp(example_data_5_subject, version = "naive")

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