mage_ma_single: Calculates Mean Amplitude of Glycemic Excursions (see "mage")

In irinagain/iglu: Interpreting Glucose Data from Continuous Glucose Monitors

Calculates Mean Amplitude of Glycemic Excursions (see "mage")

Description

This function is an internal function used by "mage". The function will calculate the Mean Amplitude of Glycemic Excursions (MAGE) on all the values of the inputted data set. To calculate separate MAGE values for a group of subjects, use the "mage" function.

Usage

mage_ma_single(
  data,
  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,
  plot_type = c("ggplot", "plotly")
)

Arguments

data	DataFrame object with column names "id", "time", and "gl". Should only be data for 1 subject. In case multiple subject ids are detected, a warning is produced and only 1st subject is used.
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.
plot_type	One of "ggplot" or "plotly". Default: "gglplot". Returns either a ggplot (static image) or Plotly chart (interactive GUI).

Details

See "mage".

Value

A ggplot or Plotly chart if plot = TRUE, depending on plot_type. Otherwise, a numeric MAGE value for the inputted glucose trace or a DataFrame with the MAGE values on each segment, depending on return_type.

Author(s)

Nathaniel J. Fernandes

Examples

data(example_data_1_subject)
mage_ma_single(
   example_data_1_subject,
   short_ma = 4,
   long_ma = 24,
   direction = 'plus')

mage_ma_single(
   example_data_1_subject,
   inter_gap = 300)

mage_ma_single(
   example_data_1_subject,
   plot=TRUE,
   title="Patient X",
   xlab="Time",
   ylab="Glucose Level (mg/dL)",
   show_ma=FALSE)

irinagain/iglu documentation built on April 15, 2024, 4:20 p.m.