Updated MAG computation in the presence of large missing data

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: iglu
 Type: Package
 Title: Interpreting Glucose Data from Continuous Glucose Monitors
-Version: 4.2.3
+Version: 4.3.0
 Authors@R: c(person("Elizabeth", "Chun",
             role = c("aut")),
             person("Steve", "Broll",
@@ -34,6 +34,8 @@ Authors@R: c(person("Elizabeth", "Chun",
             role = c("ctb")),
             person("Nhan", "Nguyen",
             role = c("ctb")),
+            person("Neo", "Kok",
+            role = c("ctb")),
             person("Irina", "Gaynanova",
             email = "irinagn@umich.edu",role = c("aut", "cre"),
             comment = c(ORCID = "0000-0002-4116-0268")))

NEWS.md

@@ -1,3 +1,7 @@
+# iglu 4.3.0
+* Updated MAG computation in the presence of large missing data
+* Default MAG now calculates differences at the CGM frequency rather than hourly
+
 # iglu 4.2.3
 * Fixed GVP output for iglu::all_metrics
 

R/mag.R

@@ -4,10 +4,11 @@
 #' The function mag calculates the mean absolute glucose or MAG.
 #'
 #' @usage
-#' mag(data, n = 60, dt0 = NULL, inter_gap = 45, tz = "")
+#' mag(data, n = NULL, dt0 = NULL, inter_gap = 45, tz = "")
 #'
 #' @param n Integer giving the desired interval in minutes over which to calculate
-#' the change in glucose. Default is 60 to have hourly (60 minutes) intervals.
+#' the change in glucose. Default is the CGM meter's frequency (dt0)
+#' to measure change in every reading.
 #'
 #' @inheritParams roc
 #'
@@ -22,18 +23,24 @@
 #' The glucose values are linearly interpolated over a time grid starting at the
 #' beginning of the first day of data and ending on the last day of data. Then, MAG
 #' is calculated as \eqn{\frac{|\Delta G|}{\Delta t}} where \eqn{|\Delta G|} is
-#' the sum of the absolute change in glucose calculated for each interval as specified
-#' by n, default n = 60 for hourly change in glucose. The sum is then divided by
-#' \eqn{\Delta t} which is the total time in hours.
+#' the sum of the absolute change in glucose per n-minute interval (default n = dt0).
+#' The sum is then divided by \eqn{\Delta t}, the total elapsed time (in hours),
+#' yieldng the Mean Absolute change in Glucose (mg/dL per hour).
 #'
-#' @author Elizabeth Chun
+#' @author Elizabeth Chun, Neo Kok
 #'
 #' @references
 #' Hermanides et al. (2010) Glucose Variability is Associated with Intensive Care Unit
-#' Mortaility,
+#' Mortality,
 #' \emph{Critical Care Medicine} \strong{38(3)} 838-842,
 #' \doi{10.1097/CCM.0b013e3181cc4be9}
 #'
+#' Kohnert et al. (2013) Evaluation of the Mean Absolute Glucose Change as a Measure
+#' of Glycemic Variability Using  Continuous Glucose Monitoring Data,
+#' \emph{Diabetes Technol Ther.} \strong{15(6)} 448-454,
+#' \doi{10.1089/dia.2012.0303}
+#'
+#'
 #' @examples
 #'
 #' data(example_data_1_subject)
@@ -43,29 +50,43 @@
 #' mag(example_data_5_subject)
 #'
 
-mag <- function (data, n = 60L, dt0 = NULL, inter_gap = 45, tz = "") {
+mag <- function (data, n = NULL, dt0 = NULL, inter_gap = 45, tz = "") {
 
   mag_single <- function (data) {
     data_ip = CGMS2DayByDay(data, dt0 = dt0, inter_gap = inter_gap, tz = tz)
     dt0 <- data_ip[[3]]
-    if (n < dt0) {
+
+    if(is.null(n)) {
+      n <- dt0
+    } else if (n < dt0) {
       message(paste("Parameter n cannot be less than the data collection frequency: " ,
                     dt0, " , function will be evaluated with n = ", dt0, sep = ""))
       n <- dt0
+    } else if (n %% dt0 != 0){
+      new_n <- round(n/dt0) * dt0
+      message(paste("Parameter n must be a multiple of the data collection frequency: ",
+                    dt0, " , function will be evaluated with n = ", new_n, sep = ""))
+      n <- new_n
     }
 
-    idx = seq(1, ncol(data_ip[[1]]), by = round(n/data_ip[[3]]))
-    idx_gl = as.vector(t(data_ip[[1]][, idx]))
-    mag = sum(abs(diff(idx_gl)), na.rm = TRUE)/
-      (length(na.omit(idx_gl))*n/60)
+    step_cols <- n / dt0
+
+    flat_gl = as.vector(t(data_ip[[1]]))
+    idx <- seq(1, length(flat_gl), by = step_cols)
+    idx_gl = flat_gl[idx]
+    diffs = na.omit(diff(idx_gl))
+
+    mag = sum(abs(diffs)) /
+      (length(diffs) * (n/60))
+
     return(mag)
   }
 
   id = mag = NULL
   rm(list = c("id", "mag"))
   data = check_data_columns(data)
 
-  if (!is.integer(n)) {
+  if (!is.integer(n) && !is.null(n)) {
     n <- round(n)
     message("Parameter n must be an integer, input has been rounded to nearest
             integer")