Skip to contents

Calculate Mean Amplitude of Glycemic Excursions

Source: R/mage.R
mage.Rd

The function calculates MAGE values and can optionally return a plot of the glucose trace.

Usage

mage(
  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"),
  dt0 = NULL,
  tz = "",
  inter_gap = 45,
  max_gap = 180,
  plot = FALSE,
  title = NA,
  xlab = NA,
  ylab = NA,
  show_ma = FALSE,
  show_excursions = TRUE
)

Arguments

data

DataFrame object with column names "id", "time", and "gl" OR numeric vector of glucose values.

version

Either 'ma' or 'naive'. Default: 'ma'. Chooses which version of the MAGE algorithm to use. 'ma' algorithm is more accurate, and is the default. Earlier versions of iglu package (<=2.0.0) used 'naive'.

sd_multiplier

A numeric value that can change the sd value used to determine size of glycemic excursions used in the calculation. This is the only parameter that can be specified for version = "naive", and it is ignored if version = "ma".

short_ma

Integer for period length of the short moving average. Default: 5. Must be positive and less than "long_ma". (Recommended <15)

long_ma

Integer for period length for the long moving average. Default: 32. Must be positive and greater than "short_ma". (Recommended >20)

return_type

One of "num" or "df". Default: "num". Will return either a single number for the "MAGE over the entire trace" (weighted by segment length) or a DataFrame with the MAGE value for each segment (see the MAGE vignette for discussion of handling gaps by splitting trace into multiple segments).

direction

One of "avg", "service", "max", "plus", or "minus". Default: "avg". Algorithm will calculate one of the following: MAGE+ (nadir to peak), MAGE- (peak to nadir), MAGEavg = avg(MAGE+, MAGE-), MAGEmax = max(MAGE+, MAGE-), or automatically choose MAGE+/MAGE- based on the first countable excursion (i.e., "service"). NOTE: the selection of peak-to-nadir or nadir-to-peak is chosen independently on each segment, thus MAGEservice may choose peak-to-nadir on one segment and nadir-to-peak on another, for example.

dt0

The time frequency for interpolation in minutes, the default will match the CGM meter's frequency (e.g. 5 min for Dexcom).

tz

A character string specifying the time zone to be used. System-specific (see as.POSIXct), but " " is the current time zone, and "GMT" is UTC (Universal Time, Coordinated). Invalid values are most commonly treated as UTC, on some platforms with a warning.

inter_gap

The maximum allowable gap (in minutes) for interpolation. The values will not be interpolated between the glucose measurements that are more than inter_gap minutes apart. The default value is 45 min.

max_gap

Integer for the maximum length of a gap in minutes before the trace is split into segments and MAGE is calculated on each segment independently. Default: 180.

plot

Boolean. Default: FALSE. If TRUE, returns a plot that visualizes all identified peaks and nadirs, excursions, and missing gaps. An interactive GUI can be loaded with plot_type = 'plotly'.

title

Title for the ggplot. Default: "Glucose Trace - Subject [ID]".

xlab

Label for x-axis of ggplot. Default: "Time".

ylab

Label for y-axis of ggplot. Default: "Glucose Level".

show_ma

Boolean. Default: FALSE. If TRUE, plots the moving average lines on the plot.

show_excursions

Boolean. Default: TRUE. If TRUE, shows identified excursions as arrows from peak-to-nadir/nadir-to-peak on the plot.

Value

A tibble object with two columns: the subject id and corresponding MAGE value. If a vector of glucose values is passed, then a tibble object with just the MAGE value is returned.

In version = "ma", if plot = TRUE, a list of ggplots will be returned with one plot per subject. To return an interactive plot, use iglu::mage_ma_single with plot_type='plotly' on each subject individually.

Details

If version 'ma' is selected, the function computationally emulates the manual method for calculating the mean amplitude of glycemic excursions (MAGE) first suggested in "Mean Amplitude of Glycemic Excursions, a Measure of Diabetic Instability", (Service, 1970). For this version, glucose values will be interpolated over a uniform time grid prior to calculation.

'ma' is a more accurate algorithm that uses the crosses of a short and long moving average to identify intervals where a peak/nadir might exist. Then, the height from one peak/nadir to the next nadir/peak is calculated from the _original_ (not moving average) glucose values.

'naive' algorithm calculates MAGE by taking the mean of absolute glucose differences (between each value and the mean) that are greater than the standard deviation. A multiplier can be added to the standard deviation using the sd_multiplier argument.

References

Service et al. (1970) Mean amplitude of glycemic excursions, a measure of diabetic instability Diabetes 19 .644-655, doi:10.2337/diab.19.9.644 .

Examples

data(example_data_5_subject)
mage(example_data_5_subject, version = 'ma')
#> Gap found in data for subject id: Subject 2, that exceeds 12 hours.
#> # A tibble: 5 × 2
#> # Rowwise: 
#>   id         MAGE
#>   <fct>     <dbl>
#> 1 Subject 1  72.4
#> 2 Subject 2 118. 
#> 3 Subject 3 116. 
#> 4 Subject 4  70.9
#> 5 Subject 5 142.