From 9f0dd14c74d3e9272e7bd8ac7a48ce249e24d188 Mon Sep 17 00:00:00 2001 From: Vincent van Hees Date: Thu, 23 May 2024 17:11:50 +0200 Subject: [PATCH 01/18] improve handling of recordings where sensor was not worn during sleep --- R/g.plot5.R | 20 +++++++++++++------- R/g.sib.det.R | 1 + 2 files changed, 14 insertions(+), 7 deletions(-) diff --git a/R/g.plot5.R b/R/g.plot5.R index 93b22f7b4..be98df2c3 100644 --- a/R/g.plot5.R +++ b/R/g.plot5.R @@ -86,16 +86,18 @@ g.plot5 = function(metadatadir = c(), dofirstpage = FALSE, viewingwindow = 1, fnames_ms1_stripped[sel], " because part 4 output was not available." ) ) - next() + next } - pdf(paste0(metadatadir, "/results/file summary reports/Report_", - fnames_ms1_stripped[sel], ".pdf"), paper = "a4", - width = 0, height = 0) + sib.cla.sum = c() load(paste0(ms3dir,"/",fname_ms3[i])) load(paste0(ms1dir,"/",fname_ms1[sel])) ws3 = M$windowsizes[1] ws2 = M$windowsizes[2] + if (nrow(sib.cla.sum) == 0) next + pdf(paste0(metadatadir, "/results/file summary reports/Report_", + fnames_ms1_stripped[sel], ".pdf"), paper = "a4", + width = 0, height = 0) # P2daysummary_tmp = P2daysummary[which(P2daysummary$filename == fnames_ms1_stripped[sel]),] # note that the reports are generated from the raw sleep classification (part4) and no attempt is made to clean it up, @@ -116,7 +118,7 @@ g.plot5 = function(metadatadir = c(), dofirstpage = FALSE, viewingwindow = 1, if (includenightcrit > 1) includenightcrit = includenightcrit / 24 d2excludeb = d2exclude = which(P2daysummary_tmp$`N valid hours` < max(c(includedaycrit, threshold_hrs_of_data_per_day))) - n2excludeb = n2exclude = which(summarysleep_tmp$fraction_night_invalid > includenightcrit + n2excludeb = n2exclude = which(summarysleep_tmp$fraction_night_invalid > (1 - includenightcrit) | summarysleep_tmp$SptDuration == 0) if (length(d2exclude) > 0) { @@ -130,8 +132,12 @@ g.plot5 = function(metadatadir = c(), dofirstpage = FALSE, viewingwindow = 1, n2exclude = n2excludeb } # nights missing in sleep summary? - allnights = 1:max(summarysleep_tmp$night) - missingNights = which(allnights %in% summarysleep_tmp$night == FALSE) + if (length(summarysleep_tmp$night) > 0) { + allnights = 1:max(summarysleep_tmp$night) + missingNights = which(allnights %in% summarysleep_tmp$night == FALSE) + } else { + missingNights = NULL + } if (length(missingNights) > 0) { n2exclude = sort(unique(c(n2exclude, missingNights))) } diff --git a/R/g.sib.det.R b/R/g.sib.det.R index b8f599cd1..b6afc54cd 100644 --- a/R/g.sib.det.R +++ b/R/g.sib.det.R @@ -230,6 +230,7 @@ g.sib.det = function(M, IMP, I, twd = c(-12, 12), qqq1 = midnightsi[j] + (twd[1] * (3600 / ws3)) #preceding noon qqq2 = midnightsi[j] + (twd[2] * (3600 / ws3)) #next noon } + if (qqq2 - qqq1 < 60) next # skip night if it has less than 60 epochs sptei = sptei + 1 if (qqq2 > length(time)) qqq2 = length(time) if (qqq1 < 1) qqq1 = 1 From 50ae357c6cd05dd29b2d401fc523ffa2bf535530 Mon Sep 17 00:00:00 2001 From: Vincent van Hees Date: Thu, 30 May 2024 14:13:42 +0200 Subject: [PATCH 02/18] ignore rawaccfiles_formats when stored config file. --- R/GGIR.R | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/R/GGIR.R b/R/GGIR.R index d2df87c17..cd8c98deb 100644 --- a/R/GGIR.R +++ b/R/GGIR.R @@ -335,7 +335,7 @@ GGIR = function(mode = 1:5, datadir = c(), outputdir = c(), "GGIRversion", "dupArgValues", "verbose", "is_GGIRread_installed", "is_read.gt3x_installed", "is_ActCR_installed", "is_actilifecounts_installed", "rawaccfiles", "is_readxl_installed", - "checkFormat", "getExt") == FALSE)] + "checkFormat", "getExt", "rawaccfiles_formats") == FALSE)] config.parameters = mget(LS) config.matrix = as.data.frame(createConfigFile(config.parameters, GGIRversion)) From 638c07a23c07de2afa787a513ef387831233f533 Mon Sep 17 00:00:00 2001 From: Vincent van Hees Date: Fri, 31 May 2024 11:39:28 +0200 Subject: [PATCH 03/18] Force all columns other than time to be numeric (did not go well before for ActiGraph csv) --- R/convertEpochData.R | 3 +++ 1 file changed, 3 insertions(+) diff --git a/R/convertEpochData.R b/R/convertEpochData.R index 3323d13ee..0c1f02bf5 100644 --- a/R/convertEpochData.R +++ b/R/convertEpochData.R @@ -522,6 +522,9 @@ convertEpochData = function(datadir = c(), metadatadir = c(), M$metashort = as.data.frame(cbind(time_shortEp_8601, D[1:length(time_shortEp_8601), ])) colnames(M$metashort) = c("timestamp", colnames(D)) + for (ic in 2:ncol(M$metashort)) { + M$metashort[, ic] <- as.numeric(M$metashort[, ic]) + } } if (length(which(is.na(M$metashort$ZCY) == TRUE)) > 0) { # impute missing data by zero From 43203af03d8ec43ce84b7c1c984bbb2df32814f7 Mon Sep 17 00:00:00 2001 From: Vincent van Hees Date: Fri, 31 May 2024 11:39:48 +0200 Subject: [PATCH 04/18] handle time series without any sleeponset --- R/g.part5.addfirstwake.R | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/R/g.part5.addfirstwake.R b/R/g.part5.addfirstwake.R index ac292813c..29f852d4f 100644 --- a/R/g.part5.addfirstwake.R +++ b/R/g.part5.addfirstwake.R @@ -81,9 +81,11 @@ g.part5.addfirstwake = function(ts, summarysleep, nightsi, sleeplog, ID, # We do this to make sure that the day numbering # and merging of the sleep variables is still consistent with # the other recording. - dummywake = max(firstonset - round(Nepochsinhour/12), nightsi[1] + round(Nepochsinhour * 6)) - ts$diur[1:dummywake] = 1 - ts$nonwear[1:firstonset] = 1 + if (!is.na(firstonset)) { + dummywake = max(firstonset - round(Nepochsinhour/12), nightsi[1] + round(Nepochsinhour * 6)) + ts$diur[1:dummywake] = 1 + ts$nonwear[1:firstonset] = 1 + } } } return(ts) From 715990255a576871b5ce13d8e03afc4e016798b6 Mon Sep 17 00:00:00 2001 From: Vincent van Hees Date: Fri, 31 May 2024 11:40:23 +0200 Subject: [PATCH 05/18] align syntax second HASPT call with first call to ease comparing --- R/g.sib.det.R | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/R/g.sib.det.R b/R/g.sib.det.R index b6afc54cd..b1d9535e6 100644 --- a/R/g.sib.det.R +++ b/R/g.sib.det.R @@ -296,9 +296,10 @@ g.sib.det = function(M, IMP, I, twd = c(-12, 12), } } spt_estimate_tmp = HASPT(angle = tmpANGLE, ws3 = ws3, - sptblocksize = sptblocksize, - spt_max_gap = spt_max_gap, - HASPT.algo = params_sleep[["HASPT.algo"]], invalid = invalid[newqqq1:newqqq2], + sptblocksize = sptblocksize, spt_max_gap = spt_max_gap, + HASPT.algo = params_sleep[["HASPT.algo"]], + invalid = invalid[newqqq1:newqqq2], + HDCZA_threshold = params_sleep[["HDCZA_threshold"]], HASPT.ignore.invalid = params_sleep[["HASPT.ignore.invalid"]], activity = ACC[newqqq1:newqqq2]) if (length(spt_estimate_tmp$SPTE_start) > 0) { From d1c17649b2b7ebd5aa34a19edf63c928bfbaa158 Mon Sep 17 00:00:00 2001 From: Vincent van Hees Date: Fri, 31 May 2024 11:41:05 +0200 Subject: [PATCH 06/18] update NotWorn algorithm to work for both raw and count data and handle varying degrees of nonwear time --- R/HASIB.R | 13 +++++++++++-- R/HASPT.R | 45 ++++++++++++++++++++++++++++++++++++--------- 2 files changed, 47 insertions(+), 11 deletions(-) diff --git a/R/HASIB.R b/R/HASIB.R index ac7558474..e995e8de8 100644 --- a/R/HASIB.R +++ b/R/HASIB.R @@ -223,8 +223,17 @@ HASIB = function(HASIB.algo = "vanHees2015", timethreshold = c(), anglethreshold # around to avoid having to completely redesign GGIR just for those studies. sib_classification = as.data.frame(matrix(0, Nvalues, 1)) - activityThreshold = as.numeric(quantile(x = activity, probs = 0.1) * 2) - activity2 = zoo::rollmax(x = activity, k = 3600 / epochsize, fill = 1) + activity2 = zoo::rollmax(x = activity, k = 300 / epochsize, fill = 1) + # ignore zeros because in ActiGraph with many zeros it skews the distribution + nonzero = which(activity2 != 0) + if (length(nonzero) > 0) { + activityThreshold = sd(activity2[nonzero], na.rm = TRUE) * 0.05 + if (activityThreshold < min(activity)) { + activityThreshold = quantile(activity2[nonzero], probs = 0.1) + } + } else { + activityThreshold = 0 + } zeroMovement = which(activity2 <= activityThreshold) if (length(zeroMovement) > 0) { sib_classification[zeroMovement, 1] = 1 diff --git a/R/HASPT.R b/R/HASPT.R index 89362a50d..6fd651aa0 100644 --- a/R/HASPT.R +++ b/R/HASPT.R @@ -18,7 +18,7 @@ HASPT = function(angle, sptblocksize = 30, spt_max_gap = 60, ws3 = 5, # threshold = 10th percentile (constrained to 0.13-0.5 if required) medabsdi = function(angle) { #50th percentile, do not use mean because that will be outlier sensitive - angvar = stats::median(abs(diff(angle))) + angvar = stats::median(abs(diff(angle))) return(angvar) } k1 = 5 * (60/ws3) @@ -39,7 +39,7 @@ HASPT = function(angle, sptblocksize = 30, spt_max_gap = 60, ws3 = 5, # threshold = 45 degrees x = abs(angle) threshold = 45 - } else if (HASPT.algo == "NotWorn") { + } else if (HASPT.algo == "NotWorn") { # When protocol is to not wear sensor during the night, # and data is collected in count units we do not know angle # as needed for HorAngle and HDCZA. @@ -52,15 +52,20 @@ HASPT = function(angle, sptblocksize = 30, spt_max_gap = 60, ws3 = 5, # smooth x to 5 minute rolling average to reduce sensitivity to sudden peaks ma <- function(x, n = 300 / ws3){stats::filter(x, rep(1 / n, n), sides = 2, circular = TRUE)} x = ma(x) - activityThreshold = sd(x, na.rm = TRUE) * 0.2 - # For sensewear external data this will not work as it mostly has values of 1 and up. - if (activityThreshold < min(activity)) { - activityThreshold = quantile(x, probs = 0.1) + nonzero = which(x != 0) + if (length(nonzero) > 0) { + activityThreshold = sd(x[nonzero], na.rm = TRUE) * 0.05 + # For sensewear external data this will not work as it mostly has values of 1 and up. + if (activityThreshold < min(activity)) { + activityThreshold = quantile(x, probs = 0.1) + } + } else { + activityThreshold = 0 } # this algorithm looked for x <= threshold, now a minimum quantity is added # to the threshold to allow for consistent definition of nomov below # i.e., x < threshold - threshold = activityThreshold + 0.001 + threshold = activityThreshold + 0.001 } # Now define nomov periods with the selected strategy for invalid time nomov = rep(0,length(x)) # no movement @@ -129,8 +134,8 @@ HASPT = function(angle, sptblocksize = 30, spt_max_gap = 60, ws3 = 5, if (SPTE_start == 0) SPTE_start = 1 part3_guider = HASPT.algo if (is.na(HASPT.ignore.invalid)) { - # investigate if invalid time was included in the SPT definition, - # and if so, keep track of that in the guider. This is needed in the + # investigate if invalid time was included in the SPT definition, + # and if so, keep track of that in the guider. This is needed in the # case that sleeplog is used, to inform part 4 that it should # trust the sleeplog times for this specific night. spt_long = rep(0, length(invalid)) @@ -141,6 +146,28 @@ HASPT = function(angle, sptblocksize = 30, spt_max_gap = 60, ws3 = 5, } } + # # Code to help investigate classifications: + # plot(x, col = "black", type = "l") + # abline(v = SPTE_start, col = "green", lwd = 2) + # abline(v = SPTE_end, col = "red", lwd = 2) + # rect(xleft = s1, ybottom = rep(0, length(s1)), + # xright = e1, ytop = rep(0.1, length(s1)), + # col = rgb(0, 0, 255, max = 255, alpha = 50), border = NA) + # + # rect(xleft = s5, ybottom = rep(0.1, length(s1)), + # xright = e5, ytop = rep(1, length(s1)), + # col = rgb(255, 0, 0, max = 255, alpha = 20), border = NA) + # lines(x, col = "black", type = "l") + # abline(h = threshold, col = "purple", lwd = 2) + # inva = which(invalid == 1) + # if (length(inva) > 0) { + # lines(inva, rep(0.1, length(inva)), + # type = "p", pch = 20, lwd = 4, col = "black") + # } + # lines(invalid* 0.05, type = "l", col = "red") + # # graphics.off() + # browser() + } else { SPTE_end = c() SPTE_start = c() From 49a530a4b1eeb5e9fc4c27f915a9eef361924f28 Mon Sep 17 00:00:00 2001 From: Vincent van Hees Date: Fri, 31 May 2024 11:56:00 +0200 Subject: [PATCH 07/18] Update NEWS.md --- NEWS.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/NEWS.md b/NEWS.md index cadf84272..427cf66b4 100644 --- a/NEWS.md +++ b/NEWS.md @@ -2,6 +2,10 @@ - Part 2: Corrected calculation of LXhr and MXhr which had one hour offset when timing was after midnight, #1117 +- Part 3 and 4: Revise NotWorn algorithm to work with both count and raw data with varying degrees of nonwear. + +- Visualreport: Improve handling of recordings where the accelerometer was not worn. + # CHANGES IN GGIR VERSION 3.1-0 - Minor issue fixes introduced in 3.0-10 related to handling nights without sustained inactivity bouts, handling recordings without midnight and storage of GGIR version in the part 4 output when there are no valid nights. From 3b9e2b7f47f701c1ce2f2f998a81f875595d3ac2 Mon Sep 17 00:00:00 2001 From: Vincent van Hees Date: Fri, 31 May 2024 13:24:02 +0200 Subject: [PATCH 08/18] improve handling of NotWorn guider --- R/g.part4.R | 37 +++++++++++++++++++++++++++---------- 1 file changed, 27 insertions(+), 10 deletions(-) diff --git a/R/g.part4.R b/R/g.part4.R index b8e0df018..8b0bd5289 100644 --- a/R/g.part4.R +++ b/R/g.part4.R @@ -591,10 +591,16 @@ g.part4 = function(datadir = c(), metadatadir = c(), f0 = f0, f1 = f1, } # If no SIBs overlap with the SPT window if (relyonguider_thisnight == TRUE) { - newlines = rbind(spo[1, ], spo[1, ]) - newlines[1, 1:4] = c(nrow(spo) + 1, SptOnset, SptOnset + 1/60, 1) - newlines[2, 1:4] = c(nrow(spo) + 1, SptWake - 1/60, SptWake, 1) - spo = rbind(spo, newlines) + if (guider != "NotWorn") { + newlines = rbind(spo[1, ], spo[1, ]) + newlines[1, 1:4] = c(nrow(spo) + 1, SptOnset, SptOnset + 1/60, 1) + newlines[2, 1:4] = c(nrow(spo) + 1, SptWake - 1/60, SptWake, 1) + spo = rbind(spo, newlines) # When NotWorn was used then fully trust on guider and ignore sibs detected + } else { + newlines = spo[1, ] # initialise object + newlines[1, 1:4] = c(nrow(spo) + 1, SptOnset, SptWake, 1) + spo = newlines + } spo = spo[order(spo$start), ] spo$nb = 1:nrow(spo) relyonguider_thisnight = TRUE @@ -631,7 +637,7 @@ g.part4 = function(datadir = c(), metadatadir = c(), f0 = f0, f1 = f1, # for the labelling above it was needed to have times > 36, but for the plotting # time in the second day needs to be returned to a normal 24 hour scale. reversetime2 = which(spo$start >= 36) - reversetime3 = which(spo$end >= 36) + reversetime3 = which(spo$end >= 36 & spo$end - 24 > spo$start) if (length(reversetime2) > 0) spo$start[reversetime2] = spo$start[reversetime2] - 24 if (length(reversetime3) > 0) spo$end[reversetime3] = spo$end[reversetime3] - 24 } @@ -694,6 +700,18 @@ g.part4 = function(datadir = c(), metadatadir = c(), f0 = f0, f1 = f1, if (length(rowswithdefi) > 0) { # only process day if there are at least 2 sustained inactivity bouts spocum.t = spocum[rowswithdefi, ] + evin = 2 + if (guider == "NotWorn") { + while (evin <= nrow(spocum.t)) { + if (spocum.t$start[evin] - spocum.t$start[evin - 1] < -2) { + spocum.t$start[evin] = spocum.t$start[evin] + 24 + } + if (spocum.t$end[evin] - spocum.t$end[evin - 1] < -2) { + spocum.t$end[evin] = spocum.t$end[evin] + 24 + } + evin = evin + 1 + } + } # in DST it can be that a double hour is not recognized as part of the SPT correct01010pattern = function(x) { x = as.numeric(x) @@ -790,10 +808,9 @@ g.part4 = function(datadir = c(), metadatadir = c(), f0 = f0, f1 = f1, # in the autumn and ends inside the dst hour negval = which(nocs < 0) if (length(negval) > 0) { - kk0 = as.numeric(spocum.t$start[which(spocum.t$dur == 1)]) # episode onsets - kk1 = as.numeric(spocum.t$end[which(spocum.t$dur == 1)]) # episode endings - kk1[negval] = kk1[negval] + 1 - nocs = kk1 - kk0 + kk0 = as.numeric(spocum.t$start[negval]) # episode onsets + kk1 = as.numeric(spocum.t$end[negval]) + 1 # episode endings + nocs[negval] = kk1 - kk0 } if (length(nocs) > 0) { spocum.t.dur.noc = sum(nocs) @@ -895,7 +912,7 @@ g.part4 = function(datadir = c(), metadatadir = c(), f0 = f0, f1 = f1, spocum.t.dur_sibd_atleast15min = 0 } - nightsummary[sumi, 14] = spocum.t.dur.noc #total nocturnalsleep /accumulated sleep duration + nightsummary[sumi, 14] = spocum.t.dur.noc #SleepDurationInSpt nightsummary[sumi, 15] = nightsummary[sumi, 5] - spocum.t.dur.noc #WASO nightsummary[sumi, 16] = spocum.t.dur_sibd #total sib (sustained inactivty bout) duration during wakinghours nightsummary[sumi, 17] = length(which(spocum.t$dur == 1)) #number of nocturnalsleep periods From e29cc829391ffa4db2cbb1068d95fb95dd9bbde5 Mon Sep 17 00:00:00 2001 From: Vincent van Hees Date: Sat, 1 Jun 2024 14:57:48 +0200 Subject: [PATCH 09/18] rename dur column with overlapGuider because it is an indicator (0 or 1) of overlap with guider --- R/g.part4.R | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/R/g.part4.R b/R/g.part4.R index 193cccf00..880b5d76d 100644 --- a/R/g.part4.R +++ b/R/g.part4.R @@ -442,7 +442,7 @@ g.part4 = function(datadir = c(), metadatadir = c(), f0 = f0, f1 = f1, } # now generate empty overview for this night / person dummyspo = data.frame(nb = numeric(1), start = numeric(1), end = numeric(1), - dur = numeric(1), def = character(1)) + overlapGuider = numeric(1), def = character(1)) dummyspo$nb[1] = 1 spo_day = c() spo_day_exists = FALSE @@ -480,11 +480,11 @@ g.part4 = function(datadir = c(), metadatadir = c(), f0 = f0, f1 = f1, # now get sleep periods nsp = length(unique(sleepdet.t$sib.period)) #number of sleep periods spo = data.frame(nb = numeric(nsp), start = numeric(nsp), end = numeric(nsp), - dur = numeric(nsp), def = character(nsp)) + overlapGuider = numeric(nsp), def = character(nsp)) if (nsp <= 1 & unique(sleepdet.t$sib.period)[1] == 0) { # no sleep periods spo$nb[1] = 1 - spo[1, c("start", "end", "dur")] = 0 + spo[1, c("start", "end", "overlapGuider")] = 0 spo$def[1] = k if (daysleeper[j] == TRUE) { tmpCmd = paste0("spo_day", k, "= c()") @@ -574,7 +574,7 @@ g.part4 = function(datadir = c(), metadatadir = c(), f0 = f0, f1 = f1, # add empty spo object, in case it was removed above # we do this because code below assumes that spo is a matrix spo = data.frame(nb = numeric(1), start = numeric(1), end = numeric(1), - dur = numeric(1), def = character(1)) + overlapGuider = numeric(1), def = character(1)) spo$nb[1] = 1 spo[1, 2:4] = 0 spo$def[1] = k @@ -613,10 +613,10 @@ g.part4 = function(datadir = c(), metadatadir = c(), f0 = f0, f1 = f1, if (spo$end[evi] < GuiderWake & spo$start[evi] > GuiderOnset) { # if using a time in bed reference, then sleep can never # start before time in bed - spo$dur[evi] = 1 #All sib that start after guider onset and end before guider wake + spo$overlapGuider[evi] = 1 #All sib that start after guider onset and end before guider wake } } else { - spo$dur[evi] = 1 # All sib that end after guider onset and start before guider wake + spo$overlapGuider[evi] = 1 # All sib that end after guider onset and start before guider wake } if (params_sleep[["relyonguider"]] == TRUE | relyonguider_thisnight == TRUE) { # Redefine sib start and end if it overlaps with guider @@ -722,7 +722,7 @@ g.part4 = function(datadir = c(), metadatadir = c(), f0 = f0, f1 = f1, return(x) } delta_t1 = diff(as.numeric(spocum.t$end)) - spocum.t$dur = correct01010pattern(spocum.t$dur) + spocum.t$overlapGuider = correct01010pattern(spocum.t$overlapGuider) #---------------------------- nightsummary[sumi, 1] = accid @@ -732,8 +732,8 @@ g.part4 = function(datadir = c(), metadatadir = c(), f0 = f0, f1 = f1, #------------------------------------ # ACCELEROMETER - if (length(which(as.numeric(spocum.t$dur) == 1)) > 0) { - rtl = which(spocum.t$dur == 1) + if (length(which(as.numeric(spocum.t$overlapGuider) == 1)) > 0) { + rtl = which(spocum.t$overlapGuider == 1) nightsummary[sumi, 3] = spocum.t$start[rtl[1]] nightsummary[sumi, 4] = spocum.t$end[rtl[length(rtl)]] } else { @@ -799,10 +799,10 @@ g.part4 = function(datadir = c(), metadatadir = c(), f0 = f0, f1 = f1, nightsummary[sumi, 13] = 1 } # Accumulated sustained inactivity bouts during SPT (nocturnal) and dyatime - nocs = as.numeric(spocum.t$end[which(spocum.t$dur == 1)]) - - as.numeric(spocum.t$start[which(spocum.t$dur == 1)]) - sibds = as.numeric(spocum.t$end[which(spocum.t$dur == 0)]) - - as.numeric(spocum.t$start[which(spocum.t$dur == 0)]) + nocs = as.numeric(spocum.t$end[which(spocum.t$overlapGuider == 1)]) - + as.numeric(spocum.t$start[which(spocum.t$overlapGuider == 1)]) + sibds = as.numeric(spocum.t$end[which(spocum.t$overlapGuider == 0)]) - + as.numeric(spocum.t$start[which(spocum.t$overlapGuider == 0)]) # it is possible that nocs is negative if when sleep episode starts before dst # in the autumn and ends inside the dst hour negval = which(nocs < 0) @@ -826,7 +826,7 @@ g.part4 = function(datadir = c(), metadatadir = c(), f0 = f0, f1 = f1, # if yes, then check whether any of the sleep episodes overlaps dst in spring, # one hour skipped if (dst_night_or_not == 1) { - checkoverlap = spocum.t[which(spocum.t$dur == 1), c("start", "end")] + checkoverlap = spocum.t[which(spocum.t$overlapGuider == 1), c("start", "end")] if (nrow(checkoverlap) > 0) { overlaps = which(checkoverlap[, 1] <= (dsthour + 24) & checkoverlap[, 2] >= (dsthour + 25)) @@ -914,9 +914,9 @@ g.part4 = function(datadir = c(), metadatadir = c(), f0 = f0, f1 = f1, nightsummary[sumi, 14] = spocum.t.dur.noc #SleepDurationInSpt nightsummary[sumi, 15] = nightsummary[sumi, 5] - spocum.t.dur.noc #WASO nightsummary[sumi, 16] = spocum.t.dur_sibd #total sib (sustained inactivty bout) duration during wakinghours - nightsummary[sumi, 17] = length(which(spocum.t$dur == 1)) #number of nocturnalsleep periods + nightsummary[sumi, 17] = length(which(spocum.t$overlapGuider == 1)) #number of nocturnalsleep periods nightsummary[sumi, 18] = nightsummary[sumi, 17] - 1 #number of awakenings - nightsummary[sumi, 19] = length(which(spocum.t$dur == 0)) #number of sib (sustained inactivty bout) during wakinghours + nightsummary[sumi, 19] = length(which(spocum.t$overlapGuider == 0)) #number of sib (sustained inactivty bout) during wakinghours nightsummary[sumi, 20] = as.numeric(spocum.t.dur_sibd_atleast15min) #total sib (sustained inactivty bout) duration during wakinghours of at least 5 minutes #------------------------------------------------------- # Also report timestamps in non-numeric format: @@ -990,7 +990,7 @@ g.part4 = function(datadir = c(), metadatadir = c(), f0 = f0, f1 = f1, spocum.t[pli, c("start", "end")] = spocum.t[pli, c("end", "start")] } } - if (spocum.t$dur[pli] == 1) { + if (spocum.t$overlapGuider[pli] == 1) { colb = rainbow(length(undef), start = 0.7, end = 1) } else { colb = rainbow(length(undef), start = 0.2, end = 0.4) From 59f27a9910be242564c72e3d88eb6d1d1047fdfe Mon Sep 17 00:00:00 2001 From: Vincent van Hees Date: Sat, 1 Jun 2024 17:10:12 +0200 Subject: [PATCH 10/18] Update NEWS.md --- NEWS.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/NEWS.md b/NEWS.md index 974974140..2b57c8d66 100644 --- a/NEWS.md +++ b/NEWS.md @@ -9,6 +9,8 @@ - Visualreport: Improve handling of recordings where the accelerometer was not worn. +- Part 5: Fix incorrect calendar date when window starts 5 seconds before midnight, #1082 + # CHANGES IN GGIR VERSION 3.1-0 - Minor issue fixes introduced in 3.0-10 related to handling nights without sustained inactivity bouts, handling recordings without midnight and storage of GGIR version in the part 4 output when there are no valid nights. From e311066f81dc7ca12bed5effff0c0e94b5f1342f Mon Sep 17 00:00:00 2001 From: Vincent van Hees Date: Fri, 14 Jun 2024 08:31:28 +0200 Subject: [PATCH 11/18] sync branch with master by first deleting all html files --- docs/articles/GGIR.html | 3371 ---------------- docs/articles/chapter0_contributing.html | 184 - docs/articles/chapter10_CircadianRhythms.html | 177 - docs/articles/chapter10_SleepAnalysis.html | 399 -- .../chapter11_DescribingDataCutPoints.html | 486 --- .../chapter11_HouseholdCoanalysis.html | 628 --- docs/articles/chapter12_TimeUseAnalyses.html | 499 --- docs/articles/chapter12_TimeUseAnalysis.html | 500 --- docs/articles/chapter6_DataImptutation.html | 274 -- docs/articles/chapter6_DataImputation.html | 276 -- ...er7_DescribingDataWithoutKnowingSleep.html | 388 -- docs/articles/chapter7_SleepAnalysis.html | 189 - .../articles/chapter8_24hTimeUseAnalysis.html | 173 - .../chapter8_SleepFundamentalsSibs.html | 288 -- .../chapter9_PhysicalBehavioursAnalysis.html | 229 -- .../chapter9_SleepFundamentalsGuiders.html | 506 --- .../chapter9_SleepFundamentalsSpt.html | 505 --- docs/articles/copy-of-GGIR.html | 3528 ----------------- 18 files changed, 12600 deletions(-) delete mode 100644 docs/articles/GGIR.html delete mode 100644 docs/articles/chapter0_contributing.html delete mode 100644 docs/articles/chapter10_CircadianRhythms.html delete mode 100644 docs/articles/chapter10_SleepAnalysis.html delete mode 100644 docs/articles/chapter11_DescribingDataCutPoints.html delete mode 100644 docs/articles/chapter11_HouseholdCoanalysis.html delete mode 100644 docs/articles/chapter12_TimeUseAnalyses.html delete mode 100644 docs/articles/chapter12_TimeUseAnalysis.html delete mode 100644 docs/articles/chapter6_DataImptutation.html delete mode 100644 docs/articles/chapter6_DataImputation.html delete mode 100644 docs/articles/chapter7_DescribingDataWithoutKnowingSleep.html delete mode 100644 docs/articles/chapter7_SleepAnalysis.html delete mode 100644 docs/articles/chapter8_24hTimeUseAnalysis.html delete mode 100644 docs/articles/chapter8_SleepFundamentalsSibs.html delete mode 100644 docs/articles/chapter9_PhysicalBehavioursAnalysis.html delete mode 100644 docs/articles/chapter9_SleepFundamentalsGuiders.html delete mode 100644 docs/articles/chapter9_SleepFundamentalsSpt.html delete mode 100644 docs/articles/copy-of-GGIR.html diff --git a/docs/articles/GGIR.html b/docs/articles/GGIR.html deleted file mode 100644 index bea296c2f..000000000 --- a/docs/articles/GGIR.html +++ /dev/null @@ -1,3371 +0,0 @@ - - - - - - - - -Accelerometer data processing with GGIR • GGIR - - - - - - - - - - - - - Skip to contents - - -
- - - - -
-
-

Accelerometer data processing with GGIR

- - - Source: vignettes/GGIR.Rmd -
GGIR.Rmd
-
- - - -

-

You are now in the main GGIR vignette. See also the complementary -vignettes on: Cut-points, -Day -segment analyses, GGIR -parameters, Embedding -external functions (pdf), and Reading -ad-hoc csv file formats.

-
-

Introduction -

-
-

What is GGIR? -

-

GGIR is an -R-package to process multi-day raw accelerometer data for physical -activity and sleep research. The term raw -refers to data being expressed in m/s2 or gravitational -acceleration as opposed to the previous generation accelerometers which -stored data in accelerometer brand specific units. The signal processing -includes automatic calibration, detection of sustained abnormally high -values, detection of non-wear and calculation of average magnitude of -dynamic acceleration based on a variety of metrics. Next, GGIR uses this -information to describe the data per recording, per day of measurement, -and (optionally) per segment of a day of measurement, including -estimates of physical activity, inactivity and sleep. We published an -overview paper of GGIR in 2019 link.

-

This vignette provides a general introduction on how to use GGIR and -interpret the output, additionally you can find a introduction video and a mini-tutorial on YouTube. If you -want to use your own algorithms for raw data then GGIR facilitates this -with it’s external function embedding feature, documented in a separate -vignette: Embedding -external functions in GGIR. GGIR is increasingly being used by -research groups across the world. A non-exhaustive overview of academic -publications related to GGIR can be found here. R -package GGIR would not have been possible without the support of the -contributors listed in the author list at GGIR, with specific -code contributions over time since April 2016 (when GGIR development -moved to GitHub) shown here.

-

Cite GGIR:

-

When you use GGIR in publications do not forget to cite it properly -as that makes your research more reproducible and it gives credit to -it’s developers. See paragraph on Citing GGIR -for details.

-
-
-

Contributing, Support, and Keeping up to date -

-

How to contribute to the code?

-

The development version of GGIR can be found on github, which is also where -you will find guidance -on how to contribute.

-

How can I get service and support?

-

GGIR is open source software and does not come with service or -support guarantees. However, as user-community you can help each other -via the GGIR google -group or the GitHub -issue tracker. Please use these public platform rather than private -e-mails such that other users can learn from the conversations.

-

If you need dedicated support with the use of GGIR or need someone to -adapt GGIR to your needs then Vincent van Hees is available as independent consultant.

-

Training in R essentials and GGIR We offer frequent -online GGIR training courses. Check our dedicated training website with more -details and the option to book your training. Do you have questions -about the training or the booking process? Do not hesitate to contact us -via: .

-

Also of interest may be the brief free R -introduction tutorial.

-

Change log

-

Our log of main changes to GGIR over time can be found here.

-
-
-
-

Setting up your work environment -

-
-

Install R and RStudio -

-

Download and install R

-

Download and -install RStudio

-

Install GGIR with its dependencies from CRAN. You can do this with -one command from the console command line:

-
-install.packages("GGIR", dependencies = TRUE)
-

Alternatively, to install the latest development version with the -latest bug fixes use instead:

-
-install.packages("remotes")
-remotes::install_github("wadpac/GGIR")
-

Additionally, in some use-cases you will need to install one or -multiple additional packages:

-
    -
  • If you are working with Axivity, GENEActiv, or GENEA files, install -the GGIRread package with install.packages("GGIRread") -
    • -
  • If you are working with ActiGraph gt3x files, install the read.gt3x -package with install.packages("read.gt3x") -
    • -
  • If you want to derive Neishabouricounts (with -do.neishabouricounts = TRUE), install the actilifecounts -package with install.packages("actilifecounts") -
    • -
  • If you want to derive circadian rhythm indicators using the Cosinor analysis -and Extended Cosinor analysis (with cosinor = TRUE), -install the ActCR package with -install.packages("ActCR") -
    • -
-
-
-

Prepare folder structure -

-
    -
  1. GGIR works with the following accelerometer brands and formats: -
      -
    • -GENEActiv .bin
      • -
    • -Axivity AX3 and AX6 .cwa
      • -
    • -ActiGraph .csv and .gt3x -(.gt3x only the newer format generated with firmware versions above -2.5.0. Serial numbers that start with “NEO” or “MRA” and have firmware -version of 2.5.0 or earlier use an older format of the .gt3x file). Note -for Actigraph users: If you want to work with .csv exports via the -commercial ActiLife software then note that you have the option to -export data with timestamps. Please do not do this as this causes memory -issues for GGIR. To cope with the absence of timestamps GGIR will -calculate timestamps from the sample frequency, the start time and start -date as presented in the file header.
      • -
    • -Movisens .bin files with -data stored in folders. GGIR expects that each participant’s folder -contains at least a file named acc.bin.
      • -
    • Any other accelerometer brand that generates csv output, see -documentation for functions read.myacc.csv and argument -rmc.noise in the GGIR function -documentation (pdf). Note that functionality for the following file -formats was part of GGIR but has been deprecated as it required a -significant maintenance effort without a clear use case or community -support: (1) .bin for the Genea monitor by Unilever Discover, an -accelerometer that was used for some studies between 2007 and 2012) -.bin, and (2) .wav files as can be exported by the Axivity Ltd OMGUI -software. Please contact us if you think these data formats should be -facilitated by GGIR again and if you are interested in supporting their -ongoing maintenance.
      • -
    -
    2. -
  2. All accelerometer data that needs to be analysed should be stored in -one folder, or subfolders of that folder.
    3. -
  3. Give the folder an appropriate name, preferable with a reference to -the study or project it is related to rather than just ‘data’, because -the name of this folder will be used later on as an identifier of the -dataset.
    4. -
-
-
-

GGIR shell function -

-

GGIR comes with a large number of functions and optional settings -(arguments) per functions.

-

To ease interacting with GGIR there is one central function, named -GGIR, to talk to all the other functions. In the past this -function was called g.shell.GGIR, but we decided to shorten -it to GGIR for convenience. You can still use -g.shell.GGIR because g.shell.GGIR has become a -wrapper function around GGIR passing on all arguments to -GGIR and by that providing identical functionality.

-

In this paragraph we will guide you through the main arguments to -GGIR relevant for 99% of research. First of all, it is -important to understand that the GGIR package is structured in two -ways.

-

Firstly, it has a computational structure of five parts which are -applied sequentially to the data, and that GGIR controls -each of these parts:

-
    -
  • Part 1: Loads the data and stores derived features (aggregations) -needed for the other parts. This is the time-consuming part. Once this -is done, parts 2-5 can be run (or re-run with different parameters in -parts 2-5) relatively quickly.
    • -
  • Part 2: Data quality analyses and low-level description of signal -features per day and per file. At this point a day is defined from -midnight to midnight
    • -
  • Part 3: Estimation of sustained inactivity and sleep periods, needed -for input to Part 4 for sleep detection
    • -
  • Part 4: Labels the sustained inactive periods detected in Part 3 as -sleep, or daytime sustained inactivity, per night and per file
    • -
  • Part 5: Derives sleep and physical activity characteristics by -re-using information derived in part 2, 3 and 4. Total time in intensity -categories, the number of bouts, time spent in bouts and average -acceleration (overall activity) is calculated.
    • -
-

The reason why it split up in parts is that it avoids having the -re-do all analysis if you only want to make a small change in the more -downstream parts. The specific order and content of the parts has grown -for historical and computational reasons.

-

Secondly, the function arguments which we will refer to as input -parameters are structured thematically independently of the five parts -they are used in:

-
    -
  • params_rawdata: parameters related to handling the raw data such as -resampling or calibrating
    • -
  • params_metrics: parameters related to aggregating the raw data to -epoch level summary metrics
    • -
  • params_sleep: parameters related to sleep detection
    • -
  • params_physact: parameters related to physical activity
    • -
  • params_247: parameters related to 24/7 behaviours that do not fall -into the typical sleep or physical activity research category.
    • -
  • params_output: parameters relating to how and whether output is -stored.
    • -
  • params_general: general parameters not covered by any of the above -categories
    • -
-

This structure was introduced in GGIR version 2.5-6 to make the GGIR -code and documentation easier to navigate.

-

To see the parameters in each parameter category and their default -values do:

- -

If you are only interested in one specific category like sleep:

-
-library(GGIR)
-print(load_params()$params_sleep)
-

If you are only interested in parameter “HASIB.algo” from the -sleep_params object:

-
-library(GGIR)
-print(load_params()$params_sleep[["HASIB.algo"]])
-

Documentation for all arguments in the parameter objects can be found -the vignette: GGIR -configuration parameters.

-

All of these arguments are accepted as argument to function -GGIR, because GGIR is a shell around all GGIR -functionality. However, the params_ objects themselves can -not be provided as input to GGIR.

-
-

Key general arguments -

-

You will probably never need to think about most of the arguments -listed above, because a lot of arguments are only included to facilitate -methodological studies where researchers want to have control over every -little detail. See previous paragraph for links to the documentation and -how to find the default value of each parameter.

-

The bare minimum input needed for GGIR is:

-
-library(GGIR)
-GGIR(datadir="C:/mystudy/mydata",
- outputdir="D:/myresults")
-

Argument datadir allows you to specify where you have -stored your accelerometer data and outputdir allows you to -specify where you would like the output of the analyses to be stored. -This cannot be equal to datadir. If you copy paste the -above code to a new R script (file ending with .R) and Source it in -R(Studio) then the dataset will be processed and the output will be -stored in the specified output directory.

-

Below we have highlighted the key arguments you may want to be aware -of. We are not giving a detailed explanation, please see the package -manual for that.

-
    -
  • -mode - which part of GGIR to run, GGIR is constructed -in five parts with a sixth part under development.
    • -
  • -overwrite - whether to overwrite previously produced -milestone output. Between each GGIR part, GGIR stores milestone output -to ease re-running parts of the pipeline.
    • -
  • -idloc - tells GGIR where to find the participant ID -(default: inside file header)
    • -
  • -data_masking_strategy - informs GGIR how to consider -the design of the experiment. -
      -
    • If data_masking_strategy is set to value 1, then check -out arguments hrs.del.start and -hrs.del.end.
      • -
    • If data_masking_strategy is set to value 3 or 5, then -check out arguments ndayswindow, hrs.del.start -and hrs.del.end.
      • -
    -
    • -
  • -maxdur - maximum number of days you expect in a data -file based on the study protocol.
    • -
  • -desiredtz - time zone of the experiment.
    • -
  • -chunksize - a way to tell GGIR to use less memory, -which can be useful on machines with limited memory.
    • -
  • -includedaycrit - tell GGIR how many hours of valid data -per day (midnight-midnight) is acceptable.
    • -
  • -includenightcrit - tell GGIR how many hours of a valid -night (noon-noon) is acceptable.
    • -
  • -qwindow - argument to tell GGIR whether and how to -segment the day for day-segment specific analysis.
    • -
  • -mvpathreshold and boutcriter - -acceleration threshold and bout criteria used for calculating time spent -in MVPA (only used in GGIR part2).
    • -
  • -epochvalues2csv - to export epoch level magnitude of -acceleration to a csv files (in addition to already being stored as -RData file)
    • -
  • -dayborder - to decide whether the edge of a day should -be other than midnight.
    • -
  • -iglevels - argument related to intensity gradient -method proposed by A. Rowlands.
    • -
  • -do.report - specify reports that need to be -generated.
    • -
  • -viewingwindow and visualreport - to create -a visual report, this only works when all five parts of GGIR have -successfully run. Note that the visual report was initially developed to -provide something to show to study participants and not for data quality -checking purposes. Over time we have improved the visual report to also -be useful for QC-ing the data. however, some of the scorings as shown in -the visual report are created for the visual report only and may not -reflect the scorings in the main GGIR analyses as reported in the -quantitative csv-reports. Most of our effort in the past 10 years has -gone into making sure that the csv-report are correct, while the -visualreport has mostly been a side project. This is unfortunate and we -hope to find funding in the future to design a new report specifically -for the purpose of QC-ing the anlayses done by GGIR.
    • -
  • -maxRecordingInterval - if specified controls whether -neighboring or overlapping recordings with the same participant ID and -brand are appended at epoch level. This can be useful when the intention -is to monitor behaviour over larger periods of time but accelerometers -only allow for a few weeks of data collection. GGIR will never append or -alter the raw input file, this operation is preformed on the derived -data.
    • -
  • -study_dates_file - if specified trims the recorded data -to the first and last date in which the study took place. This is -relevant for studies that started the recording several days before the -accelerometers were actually worn by participants. This is used on the -top of data_masking_strategy, so that it may be combined with the -strategies in GGIR.
    • -
-
-
- -

For an explanation on how sleep is detected and the specific role of -the various function arguments see section Sleep analysis.

-
    -
  • Arguments related to configuring the sleep detection algorithm: -anglethreshold, timethreshold, -HASPT.algo, HASIB.algo, -Sadeh_axis, and HASPT.ignore.invalid.
    • -
  • -ignorenonwear if set to TRUE then ignore detected -monitor non-wear periods in the detection of sustained inactivity bouts -to avoid confusion between monitor non-wear time.
    • -
  • If you want to create a visualisation of how sleep period time and -sustained inactivity bouts match throughout a day then consider -arguments do.visual, outliers.only, and -criterror.
    • -
  • If you want to exclude the first and last night from the sleep -analysis then used excludefirstlast.
    • -
  • -def.noc.sleep specifies how the sleep period time -window should be estimated if no sleeplog is used.
    • -
  • -includenightcrit Minimum number of valid hours per -night (24 hour window between noon and noon or 6pm-6pm).
    • -
  • -data_cleaning_file to ginore specific nights for -specific individuals, see also section Data cleaning file.
    • -
  • If you want the sleep analysis to be guided by a sleeplog (diary) -then check out arguments loglocation which specifies the -location of the spreadsheet (csv) with sleep log information. Further, -use arguments colid and coln1 to specify the -details of your sleep log structure.
    • -
-

GGIR facilitates two possible sleeplog file structures:

-
-
Basic sleep log -
-

Example of a basic sleeplog:

- ----------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
IDonset_N1wakeup_N1onset_N2wakeup_N2onset_N3wakeup_N3onset_N4…
12322:00:0009:00:0021:00:0008:00:0023:45:0006:30:0000:00:00…
34521:55:0008:47:0023:45:0006:30:0000:00:00…
-
    -
  • One column for participant id, this does not have to be the first -column. Specify which column it is with argument -colid.
    • -
  • Alternatingly one column for onset time and one column for waking -time. Specify which column is the column for the first night by argument -coln1, in the above example coln1=2.
    • -
  • Timestamps are to be stored without date as in hh:mm:ss with hour -values ranging between 0 and 23 (not 24). If onset corresponds to lights -out or intention to fall asleep, then it specify -sleepwindowType = "TimeInBed".
    • -
  • There can be multiple sleeplogs in the same spreadsheet. Each row -representing a single recording.
    • -
  • First row: The first row of the spreadsheet needs to be filled with -column names. For the basic sleep log format it does not matter what -these column names are.
    • -
-
-
-
Advanced sleep log -
-

Example of an advanced sleeplog for two recordings:

- ------------ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
IDD1_dateD1_wakeupD1_inbedD1_nap_startD1_nap_endD1_nonwear1_offD1_nonwear1_onD2_date…
12330/03/201509:00:0022:00:0011:15:0011:45:0013:35:0014:10:0031/03/2015…
56720/04/201508:30:0023:15:0021/04/2015…
-

Relative to the basic sleeplog format the advanced sleep log format -comes with the following changes:

-
    -
  • Recording are stored in rows, while all information per days are -stored in columns.
    • -
  • Information per day is preceded by one columns that holds the -calendar date. GGIR has been designed to recognise and handle any date -format but assumes that you have used the same date format consistently -through the sleeplog.
    • -
  • Per calendar date there is a column for wakeup time and followed by -a column for onset or in-bed time. Note that this is different from the -basic sleep log, where wakeup time follows the column for onset or -in-bed time. So, the advanced sleep log is calendar date oriented: -asking the participant when they woke up and when the fell asleep on a -certain date. However, if the sleep onset time is at 2am, you should -still fill in the 02:00:00, even though it is the 02:00:00 of the next -calendar date.
    • -
  • You can add columns relating to self-reported napping time and -nonwear time. These are not used for the sleep analysis in g.part3 and -g.part4, but used in g.part5 to facilitate napping analysis, see -argument do.sibreport and the paragraph on naps. Multiple -naps and multiple nonwear periods can be entered per day.
    • -
  • Leave cells for missing values blank.
    • -
  • Column names are critical for the advanced sleeplog format: Date -columns are recognised by GGIR as any column name with the word “date” -in it. The advanced sleep log format is recognised by GGIR by looking -out for the occurrence of at least two columnnames with the word “date” -in their name. Wakeup times are recognised with the words “wakeup” in -the column name. Sleeponset, to bed or in bed times are recognised as -the columns with any of the following character combinations in their -name: “onset”, “inbed”, “tobed”, or “lightsout”. Napping times are -recognised by columns with the word “nap” in their name. Nonwear times -are recognised by columns with the word “nonwear” in their name.
    • -
-
-
-
- -

For an explanation on how time use analysis is performed see section -Waking-waking or 24 hour time-use -analysis.

-
    -
  • -excludefirstlast.part5 - whether to ignore the last and -first day.
    • -
  • -includedaycrit.part5 - tell GGIR what fraction of the -waking hours in a day (value below 1) is acceptable.
    • -
  • -minimum_MM_length.part5 - tell GGIR what the minimum -length (hours) should be of the MM window in part 5.
    • -
  • Configure thresholds for acceleration levels (some may want to -interpret this as intensity levels): threshold.lig, -threshold.mod, threshold.vig.
    • -
  • Configure what fraction of a bout needs to meet the threshold -(cut-point) crtieria boutcriter.in, -boutcriter.lig, boutcriter.mvpa. Note that -boutcriter.mvpa = 0.8 means that an MVPA bout can have interruptions -(i.e., the time out of MVPA intensity) that meet the following criteria: -
      -
    1. A single interruption can last < 1 min
      2. -
    2. Repeated interruptions are allowed provided that their total time -does not exceed 20% of the bout duration
      3. -
    3. The time spent in the interruptions is included in the duration of -the MVPA bout. For example: A 25-minute bout can have two 1 minute -interruption, but not a single 2-minute interruption. Here, the full 25 -minutes would count towards the duration of the MVPA bout.
      4. -
    -
    • -
  • -timewindow to specify whether days should be defined -from midnight to midnight "MM", from waking-up to waking-up -"WW", from sleep onset to sleep onset "OO", or -any combination of them.
    • -
  • Configure durations of bouts: boutdur.mvpa, -boutdur.in, and boutdur.lig. Note that this -can be a vector of multiple values indicating the minimum and maximum -duration of subsequent bout types, e.g. 1-5 minutes MVPA, 5-10 minutes -MVPA, and longer than 10 minutes MVPA.
    • -
-
-
-

Published cut-points and how to use them -

-

This section has been rewritten and moved. Please, visit the vignette -Published cut-points -and how to use them in GGIR for more details on the cut-points -available, how to use them, and some additional reflections on the use -of cut-points in GGIR.

-
-
-

Example call -

-

If you consider all the arguments above you me may end up with a call -to GGIR that could look as follows.

-
-library(GGIR)
-GGIR(mode=c(1,2,3,4,5),
-      datadir="C:/mystudy/mydata",
-      outputdir="D:/myresults",
-      do.report=c(2,4,5),
-      #=====================
-      # Part 2
-      #=====================
-      data_masking_strategy = 1,
-      hrs.del.start = 0,          hrs.del.end = 0,
-      maxdur = 9,                 includedaycrit = 16,
-      qwindow=c(0,24),
-      mvpathreshold =c(100),
-      excludefirstlast = FALSE,
-      includenightcrit = 16,
-      #=====================
-      # Part 3 + 4
-      #=====================
-      def.noc.sleep = 1,
-      outliers.only = TRUE,
-      criterror = 4,
-      do.visual = TRUE,
-      #=====================
-      # Part 5
-      #=====================
-      threshold.lig = c(30), threshold.mod = c(100),  threshold.vig = c(400),
-      boutcriter = 0.8,      boutcriter.in = 0.9,     boutcriter.lig = 0.8,
-      boutcriter.mvpa = 0.8, boutdur.in = c(1,10,30), boutdur.lig = c(1,10),
-      boutdur.mvpa = c(1),
-      includedaycrit.part5 = 2/3,
-      #=====================
-      # Visual report
-      #=====================
-      timewindow = c("WW"),
-      visualreport=TRUE)
-

Once you have used GGIR and the output directory -(outputdir) will be filled with milestone data and results.

-
-
-

Configuration file -

-

Function GGIR stores all the explicitly entered argument -values and default values for the argument that are not explicitly -provided in a csv-file named config.csv stored in the root of the output -folder. The config.csv file is accepted as input to GGIR -with argument configfile to replace the specification of -all the arguments, except datadir and -outputdir, see example below.

-
-library(GGIR)
-GGIR(datadir="C:/mystudy/mydata",
-             outputdir="D:/myresults", configfile = "D:/myconfigfiles/config.csv")
-

The practical value of this is that it eases the replication of -analysis, because instead of having to share you R script, sharing your -config.csv file will be sufficient. Further, the config.csv file -contribute to the reproducibility of your data analysis.

-

Note 1: When combining a configuration file with explicitly provided -argument values, the explicitly provided argument values will overrule -the argument values in the configuration file. Note 2: The config.csv -file in the root of the output folder will be overwritten every time you -use GGIR. So, if you would like to add annotations in the -file, e.g. in the fourth column, then you will need to store it -somewhere outside the output folder and explicitly point to it with -configfile argument.

-
-
-
-
-

Time for action: How to run your analysis? -

-
-

From the R console on your own desktop/laptop -

-

Create an R-script and put the GGIR call in it. Next, you can source -the R-script with the source function in R:

-

source("pathtoscript/myshellscript.R")

-

or use the Source button in RStudio if you use RStudio.

-
-
-

In a cluster -

-

GGIR by default support multi-thread processing, which can be turned -off by seting argument do.parallel = FALSE. If this is -still not fast enough then we advise using a GGIR on a computing -cluster. The way we did it on a Sun Grid Engine cluster is shown below, -please note that some of these commands are specific to the computing -cluster you are working on. Also, you may actually want to use an R -package like clustermq or snowfall, which avoids having to write bash -script. Please consult your local cluster specialist to tailor this to -your situation. In our case, we had three files for the SGE setting:

-

submit.sh

-
for i in {1..707}; do
-    n=1
-    s=$(($(($n * $[$i-1]))+1))
-    e=$(($i * $n))
-    qsub /home/nvhv/WORKING_DATA/bashscripts/run-mainscript.sh $s $e
-done
-

run-mainscript.sh

-
#! /bin/bash
-#$ -cwd -V
-#$ -l h_vmem=12G
-/usr/bin/R --vanilla --args f0=$1 f1=$2 < /home/nvhv/WORKING_DATA/test/myshellscript.R
-

myshellscript.R

-
-options(echo=TRUE)
-args = commandArgs(TRUE)
-if(length(args) > 0) {
-  for (i in 1:length(args)) {
-    eval(parse(text = args[[i]]))
-  }
-}
-GGIR(f0=f0,f1=f1,...)
-

You will need to update the ... in the last line with -the arguments you used for GGIR. Note that -f0=f0,f1=f1 is essential for this to work. The values of -f0 and f1 are passed on from the bash -script.

-

Once this is all setup you will need to call -bash submit.sh from the command line.

-

With the help of computing clusters GGIR has successfully been run on -some of the worlds largest accelerometer data sets such as UK Biobank -and German NAKO study.

-
-
-

Processing time -

-

The time to process a typical seven day recording should be anywhere -in between 3 and 10 minutes depending on the sample frequency of the -recording, the sensor brand, data format, the exact configuration of -GGIR, and the specifications of your computer. If you are observing -processing times of 20 minutes or longer for a 7 day recording then -probably you are slowed down by other factors.

-

Some tips on how you may be able to address this:

-
    -
  • Make sure the data you process is on the same machine as where GGIR -is run. Processing data located somewhere else on a computer network can -substantially slow software down.
    • -
  • Make sure your machine has 8GB or more RAM memory, using GGIR on old -machines with only 4GB is known to be slow. However, total memory is not -the only bottle neck, also consider the number of processes (threads) -your CPU can run relative to the amount of memory. Ending up with 2GB -per process seems a good target.
    • -
  • Avoid doing other computational activities with your machine while -running GGIR. For example, if you use DropBox or OneDrive make sure they -do not sync while you are running GGIR. When using GGIR to process large -datasets it is probably best to not use the machine, but make sure the -machine is configured not to fall asleep as that would terminate the -analyses.
    • -
-
-
-
-

Inspecting the results -

-

GGIR generates the following types of output. - csv-spreadsheets with -all the variables you need for physical activity, sleep and circadian -rhythm research - Pdfs with on each page a low resolution plot of the -data per file and quality indicators - R objects with milestone data - -Pdfs with a visual summary of the physical activity and sleep patterns -as identified (see example below)

-

-
-

Output part 2 -

-

Part 2 generates the following output:

-
    -
  • part2_summary.csv: Person level summary (see below)
    • -
  • part2_daysummary.csv: Day level summary (see below)
    • -
  • QC/data_quality_report.csv: Overview of calibration results and -whether or not a file was corrupt or too short to be processed,
    • -
  • QC/plots to check data quality 1.pdf: A pdf with visualisation of -the acceleration time series in 15 minute resolution and with invalid -data segments highlighted in colours (yellow: non-wear based on standard -deviation threshold, brown: non-wear after extra filtering step -(introduced in 2013), and purple: clipping)
    • -
-
-

Person level summary -

- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(Part of) variable nameDescription
IDParticipant id
device_snDevice serial number
bodylocationBody location extracted from file header
filenameName of the data file
start_timeTimestamp when recording started
startdayDay of the week on which recording started
samplefreqSample frequency (Hz)
deviceAccelerometer brand, e.g. GENEACtiv
clipping_scoreThe Clipping score: Fraction of 15 minute windows per file for which -the acceleration in one of the three axis was close to the maximum for -at least 80% of the time. This should be 0.
meas_dur_dysMeasurement duration (days)
complete_24hcycleCompleteness score: Fraction of 15 minute windows per 24 hours for -which no valid data is available at any day of the measurement.
meas_dur_def_proto_daymeasurement duration according to protocol (days): Measurement -duration (days) minus the hours that are ignored at the beginning and -end of the measurement motivated by protocol design
wear_dur_def_proto_daywear duration duration according to protocol (days): So, if the -protocol was seven days of measurement, then wearing the accelerometer -for 8 days and recording data for 8 days will still make that the wear -duration is 7 days
calib_errCalibration error (static estimate) Estimated based on all -‘non-movement’ periods in the measurement after applying the -autocalibration.
calib_statusCalibration status: Summary statement about the status of the -calibration error minimisation
ENMO_fullRecordingMeanENMO is the main summary measure of acceleration. The value -presented is the average ENMO over all the available data normalised per -24-hour cycles (diurnal balanced), with invalid data imputed by the -average at similar time points on different days of the week. In -addition to ENMO it is possible to extract other acceleration metrics -(i.e. BFEN, HFEN, HFENplus). We emphasize that it is calculated over the -full recording because the alternative is that a variable is only -calculated overmeasurement days with sufficient valid hours of -data.
ENMO(only available if set to true in part1.R) ENMO is the main summary -measure of acceleration. The value presented is the average ENMO over -all the available data normalised per 24 hour cycles, with invalid data -imputed by the average at similar timepoints on different days of the -week. In addition to ENMO it is possible to extract other acceleration -metrics in part1.R (i.e. BFEN, HFEN, HFENplus) See also van -Hees PLoSONE April 2013 for a detailed description and comparison of -these techniques.
pX_A_mg_0-24h_fullRecordingThis variable represents the Xth percentile in the distribution of -short epoch metric value A of the average day. The average day may not -be ideal for describing the distribution. Therefore, the code also -extracts the following variable.
AD_pX_A_mg_0-24hThis variable represents the Xth percentile in the distribution of -short epoch metric value A per day averaged across all days.
L5_A_mg_0-24Average of metric A during the least active five* hours in the day -that is the lowest rolling average value of metric A. (* window size is -modifiable by argument winhr)
M5_A_mg_0-24Average of metric A during the most active five* hours in the day -that is the lowest rolling average value of metric A. (* window size is -modifiable by argument winhr)
L5hr_A_mg_0-24Starting time in hours and fractions of hours of L5_A_mg_0-24, where -hours below 12 are incremented with 24 to create a continuous scale -throughout the night (e.g. 36 = 6am) in line with numeric timeing of -sleep variables in GGIR part 4 output.
M5hr_A_mg_0-24Starting time in hours and fractions of hours of M5_A_mg_0-24
ig_gradient_ENMO_0 -24hr_fullRecordingIntensity gradient calculated over the full recording.
1to6am_ENMO_mgAverage metric value ENMO between 1am and 6am
N valid WEdaysNumber of valid weekend days
N valid WKdaysNumber of valid week days
IS_interdailystabilityinter daily stability. The movement count that is derived for this -was an attempt to follow the original approach by Eus J. W. Van Someren -(Chronobiology International. 1999. Volume 16, issue 4).
IV_in tradailyvariabilityintra daily variability. In contrast to the original paper, we -ignore the epoch transitions between the end of a day and the beginning -of the next day for the numerator of the equation, this to make it a -true measure of intradaily variability. Same note as for IS: The -movement count that is derived for this was an attempt to follow the -original approach.
IVIS_windowsize_minutesSizes of the windows based on which IV and IS are calculated (note -that this is modifiable)
IVIS_epochsize_secondsArgument has been deprecated
AD_All days (plain average of all available days, no weighting). The -variable was calculated per day and then averaged over all the available -days
WE_Weekend days (plain average of all available days, no weighting). -The variable was calculated per day and then averaged over weekend days -only
WD_Week days (plain average of all available days, no weighting). The -variable was calculated per day and then averaged over week days -only
WWE_Weekend days (weighted average) The variable was calculated per day -and then averaged over weekend days. Double weekend days are averaged. -This is only relevant for experiments that last for more than seven -days.
WWD_Week days (weighted average) The variable was calculated per day and -then averaged over week days. Double week days were averaged. This is -only relevant for experiments that last for more than seven days)
WWD_MVPA_E5S_T100_ENMOTime spent in moderate-to-vigorous based on 5 second epoch size and -an ENMO metric threshold of 100
WWE_MVPA_E5 S_B1M80%_T100_ENMOTime spent in moderate-to-vigorous based on 5 second epoch size and -an ENMO metric threshold of 100 based on a bout criteria of 100
WE_[100, 150)_mg_0-24h_ENMOTime spent between (and including) 100 mg and 150 (excluding 150 -itself) between 0 and 24 hours (the full day) using metric ENMO data -exclusion data_masking_strategy (value=1, ignore specific hours; -value=2, ignore all data before the first midnight and after the last -midnight)
_M VPA_E5S_B1M80_T100MVPA calculated based on 5 second epoch setting bout duration 1 -Minute and inclusion criterion of more than 80 percent. This is only -done for metric ENMO at the moment, and only if mvpa threshold is not -left blank
_ENMO_mgENMO or other metric was first calculated per day and then average -according to AD, WD, WWE, WWD
data exclusion data_masking_strategyA log of the decision made when calling g.impute: value=1 mean -ignore specific hours; value=2 mean ignore all data before the first -midnight and after the last midnight
n hours ignored at start of meas (if data_masking_strategy=1, 3 or -5)number of hours ignored at the start of the measurement (if -data_masking_strategy = 1) or at the start of the -ndayswindow (if data_masking_strategy = 3 or 5) A log of -decision made in part2.R
n hours ignored at end of meas (if data_masking_strategy=1, 3 or -5)number of hours ignored at the end of the measurement (if -data_masking_strategy = 1) or at the end of the ndayswindow -(if data_masking_strategy = 3 or 5). A log of decision made in -part2.R
n hours ignored at end of meas (if data_masking_strategy = 1, 3 or -5)number of days of measurement after which all data is ignored (if -data_masking_strategy = 1, 3 or 5) A log of decision made in -part2.R
epoch size to which acceleration was averaged (seconds)A log of decision made in part1.R
pdffilenumbIndicator of in which pdf-file the plot was stored
pdfpagecountIndicator of in which pdf-page the plot was stored
cosinor_Cosinor analysis estimates such as mes, amp, acrophase, and -acrotime, as documented in the Ac tCR package.
cosinorExt_Extended Cosinor analysis estimates such as minimum, amp, alpha, -beta, acrotime, UpMesor, DownMesor, MESOR, and F_pseudo, as documented -in the Ac tCR -package.
cosinorIVCosinor analysis compatible estimate of the Intradaily Variability -(IV)
cosinorISCosinor analysis compatible estimate of Interdaily Stability -(IS)
-
-
-

Day level summary -

-

This is a non-exhaustive list, because most concepts have been -explained in summary.csv

- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(Part of) variable nameDescription
IDParticipant id
filenameName of the data file
calender_dateTimestamp and date on which measurement started
bodylocationLocation of the accelerometer as extracted from file header
N valid hoursNumber of hours with valid data in the day
N hoursNumber of hours of measurement in a day, which typically is 24, -unless it is a day on which the clock changes (DST) resulting in 23 or -25 hours. The value can be less than 23 if the measurement started or -ended this day
weekdayName of weekday
measurementDay of measurement Day number relative to start of the -measurement
L5hr_ENMO_mg_0-24hHour on which L5 starts for these 24 hours (defined with metric -ENMO)
L5_ENMO_mg_0-24hAverage acceleration for L5 (defined with metric ENMO)
[A,B)_mg_0-24h_ENMOTime spent in minutes between (and including) acceleration value A -in mg and (excluding) acceleration value B in mg based on metric -ENMO
ig_gradient_ENMO_0-24hrGradient from intensity gradient analysis proposed by Rowlands -et al. 2018 based on metric ENMO for the time segment 0 to 24 -hours
ig_intercept_ENMO_0-24hrIntercept from intensity gradient analysis proposed by Rowlands -et al. 2018 based on metric ENMO for the time segment 0 to 24 -hours
ig_rsquared_ENMO_0-24hrr squared from intensity gradient analysis proposed by Rowlands -et al. 2018 based on metric ENMO for the time segment 0 to 24 -hours
-
-
-

Data_quality_report -

-

The data_quality_report.csv is stored in subfolder folder -results/QC.

- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(Part of) variable nameDescription
filenamefile name
file.corruptIs file corrupt? TRUE or FALSE (mainly tested for GENEActiv bin -files)
file.too.shortFile too short for processing? (definition) TRUE or FALSE
use.temperatureTemperature used for auto-calibration? TRUE or FALSE
scale.xAuto-calibration scaling coefficient for x-axis (same for y and z -axis, not shown here)
offset.xAuto-calibration offset coefficient for x-axis (same for y and z -axis, not shown here)
temperature.offset.xAuto-calibration temperature offset coefficient for x-axis (same for -y and z axis, not shown here)
cal.error.startCalibration error prior to auto-calibration
cal.error.endCalibration error after auto-calibration
n.10sec.windowsNumber of 10 second epochs used as sphere data in -auto-calibration
n.hours.consideredNumber of hours of data considered for auto-calibration
QCmessageCharacter QC message at the end of the auto-calibration
mean.tempMean temperature in sphere data
device.serial.numberDevice serial number
NFilePagesSkipped(Only for Axivity .cwa format) Number of raw data blocks -skipped
filehealth_totimp_min(Only for Axivity .cwa, ActiGraph gt3x, and ad-hoc csv format) Total -number of minutes of raw data imputed
filehealth_checksumfail_min(Only for Axivity .cwa format) Total number of minutes of raw data -where the checksum failed
filehealth_niblockid_min(Only for Axivity .cwa format) Total number of minutes of raw data -with non-incremental block ids
filehealth_fbias0510_min(Only for Axivity .cwa format) Total number of minutes with a -sampling frequency bias between 5 and 10%
filehealth_fbias1020_min(Only for Axivity .cwa format) Total number of minutes with a -sampling frequency bias between 10 and 20%
filehealth_fbias2030_min(Only for Axivity .cwa format) Total number of minutes with a -sampling frequency bias between 20 and 30%
filehealth_fbias30_min(Only for Axivity .cwa format) Total number of minutes with a -sampling frequency bias higher than 30%
filehealth_totimp_N(Only for Axivity .cwa, ActiGraph gt3x, and ad-hoc csv format) Total -number of data blocks that were imputed
filehealth_checksumfail_N(Only for Axivity .cwa format) Total number of blocks where the -checksum failed
filehealth_niblockid_N(Only for Axivity .cwa format) Total number of raw data blocks with -non-incremental block ids
filehealth_fbias0510_N(Only for Axivity .cwa format) Total number of raw data blocks with -a sampling frequency bias between 5 and 10%
filehealth_fbias1020_N(Only for Axivity .cwa format) Total number of raw data blocks with -a sampling frequency bias between 10 and 20%
filehealth_fbias2030_N(Only for Axivity .cwa format) Total number of raw data blocks with -a sampling frequency bias between 20 and 30%
filehealth_fbias30_N(Only for Axivity .cwa format) Total number of raw data blocks with -a sampling frequency bias higher than 30%
-
-
-
-

Output part 4 -

-

Part 4 generates the following output:

-
-

Night level summaries -

-
    -
  • part4_nightsummary_sleep_cleaned.csv
    • -
  • QC/part4_nightsummary_sleep_full.csv
    • -
-

The latter with ’_full’ in the name is intended to aid clarifying why -some nights (if any) are excluded from the cleaned summary report. -Although, nights where the accelerometer was not worn at all are -excluded from this. So, if you have a 30 day recording where the -accelerometer was not worn from day 7 onward then you will not find the -last 22 nights in either csv-report.

-

The csv. files contain the variables as shown below.

- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(Part of) variable nameDescription
IDParticipant ID extracted from file
nightNumber of the night in the recording
sleeponsetDetected onset of sleep expressed as hours since the midnight of the -previous night.
wakeupDetected waking time (after sleep period) expressed as hours since -the midnight of the previous night.
SptDurationDifference between onset and waking time.
sleepparamDefinition of sustained inactivity by accelerometer.
guiderguider used as discussed in paragraph Sleep analysis.
guider_onsetStart of Sleep Period Time window derived from the guider.
guider_wakeEnd of Sleep Period Time window derived guider.
guider_SptDurationTime SPT duration derived from guider_wake and guider_onset.
error_onsetDifference between sleeponset and guider_onset
error_wakeDifference between wakeup and guider_wake
fraction_night_invalidFraction of the night (noon-noon or 6pm-6pm) for which the data was -invalid, e.g. monitor not worn or no accelerometer measurement -started/ended within the night.
SleepDurationInSptTotal sleep duration, which equals the accumulated nocturnal -sustained inactivity bouts within the Sleep Period Time.
duration_sib_wakinghoursAccumulated sustained inactivity bouts during the day. These are the -periods we would label during the night as sleep, but during the day -they form a subclass of inactivity, which may represent day time sleep -or wakefulness while being motionless for a sustained period of time -number_sib_sleepperiod} Number of nocturnal sleep periods, with -nocturnal referring to the Sleep Period Time window.
duration_sib_wakinghours_atleast15minSame as duration_sib_wakinghours, but limited to SIBs that last at -least 15 minutes.
num ber_sib_wakinghoursNumber of sustained inactivity bouts during the day, with day -referring to the time outside the Sleep Period Time window.
sleeponset_tssleeponset formatted as a timestamp
wakeup_tswakeup formatted as a timestamp
guider_onset_tsguider_onset formatted as a timestamp
guider_wake_tsguider_wake formatted as a timestamp
pagepdf page on which the visualisation can be found
daysleeperIf 0 then the person is a nightsleeper (sleep period did not overlap -with noon) if value=1 then the person is a daysleeper (sleep period did -overlap with noon)
weekdayDay of the week on which the night started
calendardateCalendar date on which the night started in day/month/year -format.
filenameName of the accelerometer file
cleaningcodesee paragraph Cleaningcode -
sleeplog_usedWhether a sleep log was used (TRUE/FALSE)
acc_availableWhether accelerometer data was available (TRUE/FALSE).
WASOWake After Sleep Onset: SptDuration - SleepDurationInSpt
SptDurationSleep Period Time window duration: wakeup - sleeponset
error_onsetDifference between sleeponset and guider_onset (this variable is -only available in the full report as stored in the QC folder)
error_wakeDifference between wakeup and guider_wake (this variable is only -available in the full report as stored in the QC folder)
SleepRegularityIndexThe Sleep Regularity Index as proposed by Phillips et -al. 2017, but calculated per day-pair to enable user to study -patterns across days
SriFractionValidFraction of the 24 hour period that was valid in both current as -well as in matching timestamps for the next calendar day. See GGIR -function manual for details
nonwear_perc_sptNon-wear percentage during the spt hours of this day. This is a copy -of the nonwear_perc_spt calculated in part 5, -only included in part 4 reports if part 5 has been run with timewindow = -WW
-
-
Non-default variables in part 4 csv report -
-

These additional are only stored if you used a sleeplog that captures -time in bed, or when using guider HorAngle for hip-worn accelerometer -data. If either of these applies set argument -sleepwindowType to “TimeInBed”.

- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - -
(Part of) variable nameDescription
guider_guider_inbedStartTime of getting in bed
guider_guider_inbedEndTime of getting out of bed
guider_inbedDurationTime in Bed: guider_inbedEnd - guider_inbedStart
sleepefficiencySleep efficiency, calculated by one of two metrics as controlled by -argument sleepefficiency.metric: SleepDurationInSpt / -guider_inbedDuration (default) or SleepDurationInSpt / (SptDuration + -latency)
sleeplatencySleep latency, calculated as: sleeponset - guider_inbedStart
-
-
-
-

Person level summaries -

-
    -
  • part4_summary_sleep_cleaned.csv
    • -
  • QC/part4_summary_sleep_full.csv
    • -
-

In the person level report the variables are derived from the -variables in the night level summary. Minor extensions to the variable -names explain how variables are aggregated across the days. Please find -below extra clarification on a few of the variable names for which the -meaning may not be obvious:

- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(Part of) variable nameDescription
_mnmean across days
_sdstandard deviation across days
_ADAll days
_WEWeekend days
_WDWeek days
sleeplog_usedWhether a sleeplog was available (TRUE) or not (FALSE)
sleep_efficiencyAccelerometer derived sleep efficiency within the sleep period time -calculated as the ratio between acc_SleepDurationInSpt and -guider_SptDuration (denominator) or acc_SleepDurationInSpt and -acc_SptDuration + latency (denominator), as defined with -sleepefficiency.metric. Only available at person level, because at night -level the user can calculate this from existing variables.
n_nights_accNumber of nights of accelerometer data
n_nights_sleeplogNumber of nights of sleeplog data.
n_WE_nights_completeNumber of weekend nights complete which means both accelerometer and -estimate from guider.
n_WD_nights_completeNumber of weekday nights complete which means both accelerometer and -estimate from guider.
n_WEnights_daysleeperNumber of weekend nights on which the person slept until after -noon.
n_WDnights_daysleeperNumber of weekday nights on which the person slept until after -noon.
duration_sib_wakinghourTotal duration of sustained inactivity bouts during the waking -hours.
number_sib_wakinghoursNumber of sustained inactivity bouts during the waking hours.
average_dur_sib_wakinghoursAverage duration of the sustained inactivity bouts during the day -(outside the sleep period duration). Calculated as -duration_sib_wakinghour divided by number_sib_wakinghours per day, after -which the mean and standard deviation are calculated across days.
-
-
-

visualisation_sleep.pdf -

-

Visualisation to support data quality checks: - -visualisation_sleep.pdf (optional)

-

When input argument do.visual is set to TRUE GGIR can -show the following visual comparison between the time window of being -asleep (or in bed) according to the sleeplog and the detected sustained -inactivity bouts according to the accelerometer data. This visualisation -is stored in the results folder as -visualisation_sleep.pdf.

-

Explanation of the image: Each line represents one night. Colours are -used to distinguish definitions of sustained inactivity bouts (2 -definitions in this case) and to indicate existence or absence of -overlap with the sleeplog. When argument outliers.only is -set to FALSE it will visualise all available nights in the dataset. If -outliers.only is set to TRUE it will visualise only nights -with a difference in onset or waking time between sleeplog and sustained -inactivity bouts larger than the value of argument -criterror.

-

This visualisation with outliers.only set to TRUE and critererror set -to 4 was very powerful to identify entry errors in sleeplog data in van -Hees et al PLoSONE 2015. We had over 25 thousand nights of data, and -this visualisation allowed us to quickly zoom in on the most problematic -nights to investigate possible mistakes in GGIR or mistakes in data -entry.

-

-
-
-
-

Output part 5 -

-

The output of part 5 is dependent on the parameter configuration, it -will generate as many output files as there are unique combination of -the three thresholds provided.

-

For example, the following files will be generated if the threshold -configuration was 30 for light activity, 100 for moderate and 400 for -vigorous activity:

-
    -
  • part5_daysummary_MM_L30M100V400_T5A5.csv
    • -
  • part5_daysummary_WW_L30M100V400_T5A5.csv
    • -
  • part5_personsummary_MM_L30M100V400_T5A5.csv
    • -
  • part5_personsummary_WW_L30M100V400_T5A5.csv
    • -
  • file summary reports/Report_nameofdatafile.pdf
    • -
-
-

Day level summary -

- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(Term in) variable nameDescription
sleeponsetonset of sleep expressed in hours since the midnight in the night -preceding the night of interest, e.g. 26 is 2am.
wakeupwaking up time express in the same way as sleeponset.
sleeponset_tsonset of sleep expressed as a timestamp hours:minutes:seconds
daysleeperif 0 then the person woke up before noon, if 1 then the person woke -up after noon
cleaningcodeSee paragraph Cleaningcode.
dur_day_spt_minTotal length of daytime waking hours and spt combined (typically 24 -hours for MM report).
dur_duration of a behavioral class that will be specified int he rest of -the variable name
ACC_(average) acceleration according to default metric specific by -acc.metric
_spt_wake_Wakefulness within the Sleep period time window.
_spt_sleep_Sleep within the Sleep period time window.
_IN_Inactivity. Note that we use the term inactivity instead of -sedentary behaviour for the lowest intensity level of behaviour. The -reason for this is that GGIR does not attempt to classifying the -activity type sitting at the moment, by which we feel that using the -term sedentary behaviour would fail to communicate that.
_LIG_Light activity
_MOD_Moderate activity
_VIG_Vigorous activity
_MVPA_Moderate or Vigorous activity
_unbt_Unbouted
_bts_Bouts (also known as sojourns), which are segments that for which -the acceleration is within a specified range for a specified fraction of -the time.
_bts_1_10_Bouts lasting at least 1 minute and less than 10 minutes (1 and 9.99 -minutes are included, but 10 minutes is not).
Nblocknumber of blocks of a certain behavioral class, not these are not -bouts but a count of the number of times the behavioral class occurs -without interruptions.
WWin filename refers to analyses based on the timewindow from waking -to waking up
MMin filename refers to analyses done on windows between midnight and -midnight
calendar_datecalendar date on which the window started in day/month/year format. -So, for WW window this could mean that you have two windows starting on -the same date.
weekdayweekday on which the window started. So, for WW window this could -mean that you have two windows starting on the weekday.
_total_INtotal time spent in inactivity (no distinction between bouted or -unbouted behavior, this is a simple count of the number of epochs that -meet the threshold criteria.
_total_LIGtotal time spent in light activity.
nonwear_perc_dayNon-wear percentage during the waking hours of this day.
nonwear_perc_sptNon-wear percentage during the spt hours of this day.
nonwear_perc_day_sptNon-wear percentage during the whole day, including waking and -spt.
dur_day_minDuration of waking hours within this day window
dur_spt_minDuration of Sleep Period Time within this day window.
dur_day_spt_minDuration this day window, including both waking hours and SPT.
sleep_efficiencysleep_efficiency in part 5 is not the same as in part 4, but -calculated as the percentage of sleep within the sleep period time -window. The conventional approach is the approach used in part 4.
L5TIMETiming of least active 5hrs, expressed as timestamp in the day
M5TIMETiming of most active 5hrs
L5TIME_num, M5TIME_numTiming of least/most active 5hrs, expressed as hours in the day. -Note that L5/M5 timing variables are difficult to average across days -because 23:00 and 1:00 would average to noon and not to midnight. So, -caution is needed when interpreting person averages.
L5VALUEAcceleration value for least active 5hrs
M5VALUEAcceleration value for most active 5hrs
ig_All variables related to intensity gradient analysis
_gradientGradient from intensity gradient analysis proposed by Rowlands -et al. 2018 for the waking hours window (_day_) and for -the full window (_day_spt_)
_interceptIntercept from intensity gradient analysis proposed by Rowlands -et al. 2018 for the waking hours window (_day_) and for -the full window (_day_spt_)
_rsquaredr squared from intensity gradient analysis proposed by Rowlands -et al. 2018 for the waking hours window (_day_) and for -the full window (_day_spt_)
FRAG_All variables related to behavioural fragmentation analysis
TP_Transition probability
PA2INPhysical activity fragments followed by inactivity fragments
IN2PAPhysical inactivity fragments followed by activity fragments
NfragNumber of fragments
IN2LIPAInactivity fragments followed by LIPA
IN2MVPAInactivity fragments followed by MVPA
mean_durmean duration of a fragment category
Gini_durGini index
CoV_durCoefficient of Variation
alphaPower law exponent
x0.5Derived from power law exponent alpha, see Chastin et al. 201 -0 -
W0.5Derived from power law exponent alpha, see Chastin et al. 201 -0 -
nap_countTotal number of naps, only calculated when argument do.sibreport = -TRUE, currently optimised for 3.5-year olds. See function documentation -for function g.part5.classifyNaps in the GGIR function -documentation (pdf).
nap_totaldurationTotal nap duration, only calculated when argument do.sibreport = -TRUE, currently optimised for 3.5-year old. See function documentation -for function g.part5.classifyNaps in the GGIR function -documentation (pdf).
sibreport_n_itemsOnly created if do.sibreport = TRUE. Number of items in -the sibreport
sibreport_n_items_dayOnly created if do.sibreport = TRUE. Number of items in -the sibreport for this specific day
nbouts_day_XOnly created if do.sibreport = TRUE. Number of bouts in -a day of X where X can be sib (sustained inactivity bout), srnap -(self-reported nap) or srnonw (self-reported nonwear)
noverl_XOnly created if do.sibreport = TRUE. Number of -overlapping bouts in a day of X where X can be sib_srnap, sib_srnonw, -srnap_sib, or srnonw_sib
frag_mean_dur_X_dayOnly created if do.sibreport = TRUE. Mean duration of X -per day, where X can be sib, srnap or srnonw
dur_day_X_minOnly created if do.sibreport = TRUE. Total duration in -minutes of X per day, where X can be sib, srnap or srnonw
mdur_X_overl_YOnly created if do.sibreport = TRUE. Mean duration of -the overlap between X and Y, which are combinations of sib, srnap or -srnonw
tdur_X_overl_YOnly created if do.sibreport = TRUE. Total duration in -minutes of the overlap between X and Y, which are combinations of sib, -srnap or srnonw
perc_X_overl_YOnly created if do.sibreport = TRUE. Percentage of -overlap between X and Y, which are combinations of sib, srnap or -srnonw
-

Special note if you are working on compositional data -analysis:

-

The duration of all dur_ variables that have -_total_ in their name should add up to the total length of -the waking hours in a day. Similarly, the duration of all other -dur_ variables excluding the variables _total_ -in their name and excluding the variable with dur_day_min, -dur_spt_min, and dur_day_spt_min should also -add up to the length of the full day.

-

Motivation for default boutcriter.in = 0.9:

-

The idea is that if you allow for bouts of 30 minutes it would not -make sense to allow for breaks of 20 percent (6 minutes!) this is why I -used a more stringent criteria for the highest category. Please note -that you can change these criteria via arguments -boutcriter.mvpa, boutcriter.in, and -boutcriter.lig.

-
-
-

Person level summary -

-

Most variables in the person level summary are derived from the day -level summary, but extended with _pla to indicate that the -variable was calculated as the plain average across all valid days. -Variables extended with _wei represent the weighted average -of across all days where weekend days always weighted 2/5 relative to -the contribution of week days.

- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Variable nameDescription
NvaliddaysTotal number of valid days.
Nvaliddays_WDNumber of valid week days.
Nvaliddays_WENumber of valid weekend days, where the days that start on Saturday -or Sunday are considered weekend.
NcleaningcodeXNumber of days that had cleaning code X for the corresponding sleep -analysis in part 4. In case of MM analysis this refers to the night at -the end of the day.
Nvaliddays_AL10F_WDNumber of valid week days with at least 10 fragments (5 inactivity -or 5 inactive)
Nvaliddays_AL10F_WENumber of valid weekend days with at least 10 fragments (5 -inactivity or 5 inactive)
_weiweighted average of weekend and week days, using a 2/5 ratio, see -above.
_plaplain average of all days, see above
-
-
-
-
-

Motivation and clarification -

-

In this chapter we will try to collect motivations and clarification -behind GGIR which may not have been clear from the existing -publications.

-
-

Reproducibilty of GGIR analyses -

-

Some tips to increase reproducibility of your findings:

-
    -
  1. When you publish your findings, please remember to add the GGIR -package version number. All of GGIR are archived by CRAN and available -from the archive section on the package website. GGIR has -evolved over the years. To get a better understanding of how versions -differ you should check the NEWS sections from the package website -
    2. -
  2. Report how you configured the accelerometer
    3. -
  3. Report the study protocol and wear instructions given to the -participants
    4. -
  4. Report GGIR version
    5. -
  5. Report how GGIR was used: Share the config.csv file or your R -script
    6. -
  6. Report how you post-processed / cleaned GGIR output
    7. -
  7. Report how reported outcomes relate to the specific variable names -in GGIR
    8. -
-
-
-

Auto-calibration -

-

This section has been migrated this section -in the GitHub pages, which is a more narrative book-style overview of -GGIR.

-
-
-

Non-wear detection -

-

This section has been migrated this section -in the GitHub pages, which is a more narrative book-style overview of -GGIR.

-
-
-

Clipping score -

-

This section has been migrated this section -in the GitHub pages, which is a more narrative book-style overview of -GGIR.

-
-
-

Why collapse information to epoch level? -

-

Although many data points are collected we decide to only work with -aggregated values (e.g. 1 or 5 second epochs) for the following -reasons:

-
    -

  1. Accelerometers are often used to describe patterns in metabolic -energy expenditure. Metabolic energy expenditure is typically defined -per breath or per minute (indirect calorimetry), per day (room -calorimeter), or per multiple days (doubly labelled water method). In -order to validate our methods against these reference standards we need -to work with a similar time resolution.

    2. -

  2. Collapsing the data to epoch summary measures helps to -standardise for differences in sample frequency between -studies.

    3. -

  3. There is little evidence that the raw data is an accurate -representation of body acceleration. All scientific evidence on the -validity of accelerometer data has so far been based on epoch -averages.

    4. -

  4. Collapsing the data to epoch summary measures may help to average -out different noise levels and make sensor brands more -comparable.

    5. -
-
-

Why does the first epoch not allign with the original start of the -recording -

-

GGIR uses short (default 5 seconds) and long epochs (default 15 -minutes). The epochs are aligned to the hour in the day, and to each -other. For example, if a recording starts at 9:52:00 then the GGIR will -work with epochs derived from 10:00:00 onward. If the recording starts -at 10:12 then GGIR will work with epochs derived from 10:15:00 -onward.

-

Motivation:

-
    -
  • This allows us to have a standardised time grid across recordings to -describe behaviour.
    • -
  • This allows us to calculate behaviour exactly per day or per -specified time interval in a day.
    • -
-

If the first 15 minute epochs would start at 9:52 then the next one -would start at 10:07, which makes it impossible to make statement about -behaviour between 10:00 and 13:00.

-
-
-
-

Sleep analysis -

-

In GGIR sleep analysis has been implemented in part 3 and 4. Sleep -analysis comes at two levels: The identification of the main Sleep -Period Time (SPT) window or the time in bed window (TIB), and the -discrimination of sleep and wakefulness periods. The term sleep is -somewhat controversial in the context of accelerometry, because -accelerometer only capture lack of movement. To acknowledge this -challenge GGIR refers to these classified sleep periods as -sustained inactivity bouts (abbreviated as SIB).

-

Current, GGIR offers the user the choice to identify SIB period using -any of the following algorithms:

-
    -
  • -vanHees2015: Heuristic algorithm proposed in 2015 -link which -looks for periods of time where the z-angle does not change by more than -5 degrees for at least 5 minutes. This in contrast to conventional sleep -detection algorithms such as Sadeh, Galland, and ColeKripke which rely -on acceleration to estimate sleep. The vanHees2015 algorithm is the -default.
    • -
  • -Sadeh1994: The algorithm proposed by Sadeh et al. -link. To use the -GGIR implementation of the zero-crossing counts and Sadeh algorithm, -specify argument HASIB.algo = "Sadeh1994" and argument -Sadeh_axis = "Y" to indicate that the algorithm should use -the Y-axis of the sensor.
    • -
  • -Galland2012: The count-scaled algorithm proposed by -Galland et al. link. To use -our implementation of the Galland2012 algorithm specify argument -HASIB.algo = "Galland2012". Further, set -Sadeh_axis = "Y" to specify that the algorithm should use -the Y-axis.
    • -
  • -ColeKripke1992: The algorithm proposed by Cole et -al. link, more -specifically GGIR uses the algortihm proposed in the paper for 10-second -non-overlapping epochs with counts e xpressed average per minute. We -skip the re-scoring steps as the paper showed marginal added value of -this added complexity. To use the GGIR implementation of the -zero-crossing counts and Sadeh algorithm, specify argument -HASIB.algo = "ColeKripke1992" and argument -Sadeh_axis = "Y" to indicate that the algorithm should use -the Y-axis of the sensor.
    • -
  • -NotWorn: This algorithm can be used if the study -protocol was to not wear the accelerometer at night. GGIR will then look -for hours with close to zero movement and treat those as sustained -inactivity bouts. It should be obvious that this does not facilitate any -meaningful sleep analysis but it does allow GGIR to then run GGIR part 5 -based on the assumption that this analysis helped to isolate night time -from daytime.
    • -
-
-

Notes on sleep classification algorithms designed for count -data -

-
-
Replication of the movement counts needed -
-

The implementation of the zero-crossing count in GGIR is not an exact -copy of the original approach as used in the AMA-32 Motionlogger -Actigraph by Ambulatory-monitoring Inc. (“AMI”) that was used in the -studies by Sadeh, Cole, Kripke and colleagues in late 1980s and 1990s. -No complete publicly accessible description of that approach exists. -From personal correspondence with AMI, we learnt that the technique has -been kept proprietary and has never been shared with or sold to other -actigraphy manufacturers (time of correspondence October 2021). -Therefore, if you would like to replicate the exact zero-crossing counts -calculation used by Sadeh and colleague’s consider using AMI’s actigraph -device (you will have to trust AMI that hardware has not changed since -the 1980s). However, if you prioritise openness over methodological -consistency with the original studies by Sadeh, Cole, and colleagues -then you may want to consider any of the open source techniques in this -library.

-
-
-
Missing information for replicating movement counts -
-

More specifically, the missing information about the calculation -includes: (1) Sadeh specified that calculations were done on data from -the Y-axis but the direction of the Y-axis was not clarified. Therefore, -it is unclear whether the Y-axis at the time corresponds to the Y-axis -of modern sensors, (2) Properties of the frequency filter are missing -like the filter order and more generally it is unclear how to simulate -original acceleration sensor behaviour with modern sensor data, and (3) -Sensitivity of the sensor, we are now guessing that the Motionlogger had -a sensitivity of 0.01 g but without direct proof.

-

The method proposed by Galland and colleagues in 2012 was designed -for counts captured with the Actical device (Mini Mitter Co, Inc Bend -OR). Based on the correspondence with AMI we can conclude that Actical -counts are not identical to AMI’s actigraph counts. Further, a publicly -accessible complete description of the Actical calculation does not -exist. Therefore, we can also conclude that methodological consistency -cannot be guaranteed for Actical counts.

-
-
-
An educated guess and how you can to help optimise the -implementation -
-

Following the above challenges the implementation of the -zero-crossing count in GGIR is based on an educated guess where we used -all information we could find in literature and product documentation. -In our own evaluation the zero-crossing count value range looks -plausible when compared to the value range in the original -publications.

-

How you can help to optimise the implementation:

-

Given the uncertainties surrounding the older sleep algorithm we -encourage GGIR users to evaluate and help optimise the algorithms. Here, -we have the following suggestions:

-
    -
  • For ActiGraph users, when comparing GGIR Cole-Kripke estimates with -ActiLife Cole Kripke estimate be aware that ActiLife may have adopted a -different Cole-Kripke algorithm as the original publication presented -four algorithms. Further, ActiLife may have used different educated -guesses about how Motionlogger counts are calculated.
    • -
  • Compare GGIR sleep estimate with Polysomnography or Motionlogger -output and try to optimise the zero crossing count parameters as -discussed below.
    • -
-

Input argument to aid in the optimisation:

-

To aid research in exploring count type algorithms, we also -implemented the brondcounts as proposed by Brønd and -Brondeel and available via R package activityCounts, as well as the -neishabouricounts that follows the algorithm implemented in -the close-source software ActiLife by ActiGraph and is available in the -R package actilifecounts. DISCLAIMER: the brondcounts option has been -deprecated as of October2022 due to issues with the activityCounts -package it relies on. We will reactivate brondcounts once the issues are -resolved. To extract these metrics in addition to the zero crossing -count, specify do.brondcounts = TRUE and/or -do.neishabouricounts = TRUE which is used in GGIR part 1 -and uses R packages activityCounts and actilifecounts in the background. -As a result, sleep estimates for Sadeh, Cole-Kripke or Galland will be -derived based on the zero crossing algorithm and additionally on the -brondcounts or/and actilifecounts algorithms -if requested by the user. Further, we have added parameters to help -modify the configuration of the zero-crossing count calculation, see -arguments: zc.lb, zc.hb, zc.sb, -zc/order, and zc.scale. As well as one -parameter to modify the neishabouricounts calculation, see argument: -actilife_LFE.

-
-
-
-

Guiders -

-

SIBs (explained above) can occur anytime in the day. In order to -differentiate SIBs that correspond to daytime rest/naps from SIBs that -correspond to the main Sleep Period Time window (abbreviated as SPT), a -guiding method referred as guider is used. All SIBs -that overlap with the window defined by guider are considered as sleep -within the SPT window. The start of the first SIB identified as sleep -period and the end of the last SIB identified as sleep period define the -beginning and the end of the SPT window. In this way the classification -relies on the accelerometer for detecting the timing of sleep onset and -waking up time, but the guider tells it in what part of the day it -should look, as SPT window will be defined only if SIB is detected -during the guider specified window.

-

If a guider reflects the Time in Bed the interpretation of the Sleep -Period Time, Sleep onset time and Wakeup time remains unchanged. -However, we can then also assess sleep latency and and sleep efficiency, -which will be included in the report.

-

The guiding method as introduced above can be one of the following -methods:

-
    -
  • -Guider = sleep log: As presented in before mentioned -2015 article.See section on sleep analysis -related arguments for a discussion fo sleep log data formats. -Specify argument sleepwindowType to clarify whether the -sleeplog capture “TimeInBed” or “SPT”. If it is set to “TimeInBed”, GGIR -will automatically expand its part 4 analyses with sleep latency and -sleep efficiency assessment.
    • -
  • -Guider = HDCZA: As presented in our 2018 -article. The HDCZA algorithm does not require access to a sleep log, -and is designed for studies where no sleep log is available. The time -segment over which the HDCZA is derived are by default from noon to -noon. However, if the HDCZA ends between 11am and noon then it will be -applied again but to a 6pm-6pm window.
    • -
  • -Guider = L5+/-12: As presented in our 2018 -article. Twelve hour window centred around the least active 5 hours -of the day.
    • -
  • -Guider = setwindow: Window times are specified by -user, constant at specific clock times with argument -def.noc.sleep.
    • -
  • -Guider = HorAngle: Only used if argument -sensor.location="hip", because this will trigger the -identification of the longitudinal axis based on 24-hour lagged -correlation. You can also force GGIR to use a specific axis as -longitudinal axis with argument longitudinal_axis. Next, it -identifies when the horizontal axis is between -45 and 45 degrees and -considers this a horizontal posture. Next, this is used to identify the -largest time in bed period, by only considering horizontal time segments -of at least 30 minutes, and then looking for longest horizontal period -in the day where gaps of less than 60 minutes are ignored. Therefore, it -is partially similar to the HDCZA algorithm. When “HorAngle” is used, -sleepwindowType is automatically set to “TimeInBed”.
    • -
  • -Guider = NotWorn: Used for studies where the -instruction was not to wear the accelerometer durating the night. GGIR -then searches for the longest period with zero movement.
    • -
-

For all guiders other than “HorAngle” and “sleep log” argument -sleepwindowType is automatically switched to “SPT”, such -that no attempt is made to estimate sleep latency or sleep -efficiency.

-

GGIR uses by default the sleep log, if the sleep log is not available -it falls back on the HDCZA algorithm (or HorAngle if -sensor.location="hip"). If HDCZA is not successful GGIR -will falls back on the L5+/-12 definition, and if this is not available -it will use the setwindow. The user can specify the priority with -argument def.noc.sleep. So, when we refer to guider then we -refer to one of these five methods.

-
-
-

Daysleepers (nights workers) -

-

If the guider indicates that the person woke up after noon, the sleep -analysis in part 4 is performed again on a window from 6pm-6pm. In this -way our method is sensitive to people who have their main sleep period -starting before noon and ending after noon, referred as daysleeper=1 in -daysummary.csv file, which you can interpret as night workers. Note that -the L5+/-12 algorithm is not configured to identify daysleepers, it will -only consider the noon-noon time window.

-
-
-

Cleaningcode -

-

To monitor possible problems with the sleep assessment, the variable -cleaningcode is recorded for each night. Cleaningcode -per night (noon-noon or 6pm-6pm as described above) can have one of the -following values:

-
    -
  • 0: no problem, sleep log available and SPT is identified;
    • -
  • 1: sleep log not available, thus HDCZA is used and SPT is -identified,
    • -
  • 2: not enough valid accelerometer data based on the non-wear and -clipping detection from part summarised over the present night where the -argument includenightcrit indicates the minimum number of -hours of valid data needed within those 24 hours.
    • -
  • 3: no accelerometer data available,
    • -
  • 4: there were no nights to be analysed for this person,
    • -
  • 5: SPT estimated based on guider only, because either no SIB was -found during the entire guider window, which complicates defining the -start and end of the SPT, or the user specified the ID number of the -recording and the night number in the data_cleaning_file to tell GGIR to rely -on the guider and not rely on the accelerometer data for this particular -night
    • -
  • 6: no sleep log available and HDCZA also failed for this specific -night then use average of HDCZA estimates from other nights in the -recording as guider for this night. If HDCZA estimates are not available -during the entire recording then use L5+/-12 estimate for this night. -The last scenario seems highly unlikely in a recording where the -accelerometer was worn for at least one day.
    • -
-
-
-

Difference between cleaned and full output -

-

All the information for each night is stored in the -results/QC folder allowing tracing of the data analysis and -night selection. The cleaned results stored in the results folder. In -part 4 a night is excluded from the ‘cleaned’ results based on the -following criteria:

-
    -
  • If the study proposed a sleep log to the individuals, then nights -are excluded for which the sleep log was not used as a guider (i.o.w. -nights with cleaningcode not equal to 0 or variable sleep log used -equals FALSE).
    • -
  • If the study did not propose a sleep log to the individuals, then -all nights are removed with cleaningcode higher than 1.
    • -
-

Be aware that if using the full output and working with wrist -accelerometer data, then missing entries in a sleep log that asks for -Time in Bed will be replaced by HDCZA estimates of SPT. Therefore, extra -caution should be taken when working with the full output.

-

Notice that part 4 is focused on sleep research, by which the cleaned -reported is the way it is. In the next section we will discuss the -analysis done by part 5. There, the choice of guider may be considered -less important, by which we use different criteria for including nights. -So, you may see that a night that is excluded from the cleaned results -in part 4 still appears in the cleaned results for part 5.

-
-
-

Data cleaning file -

-

The package allows some adjustments to be made after data quality -check. The data_cleaning_file argument allows you to -specify individuals and nights for whom part4 should entirely rely on -the guider (for example if we decide to use sleep log only information). -The first column of this file should have header ID and -there should be a column relyonguider_part4 to specify the -night. The data_cleaning_file allows you to tell GGIR which -person(s) and night(s) should be omitted in part 4. The the night -numbers to be excluded should be listed in a column -night_part4 as header.

-
-
-
-

Waking-waking or 24 hour time-use analysis -

-

In part 5 the sleep estimates from part 4 are used to describe -24-hour time use. Part 5 allows you to do this in two ways: Literally 24 -hours which start and end a calendar day (default midnight, but -modifiable with argument dayborder) or from waking up to -waking up. In GGIR we refer to the former as MM windows -and to the latter as WW windows. The onset and waking -times are guided by the estimates from part 4, but if they are missing -part 5 will attempt to retrieve the estimate from the guider method, -because even if the accelerometer was not worn during the night, or a -sleep log is missing in a study where sleep log was proposed to the -participants, estimates from a sleep log or HDCZA can still be -considered a reasonable estimate of the SPT window in the context of -24-hour time use analysis.

-

If WW is used in combination with ignoring the first and last -midnight, argument excludefirstlast, then the first wake-up -time (on the second recording day) needs to be extracted for the first -WW day. This is done with the guider method. This also means that the -last WW window ends on the before last morning of the recording.

-

A distinction is made between the full results stored in the -results/QC folder and the cleaned results stored in the -results folder.

-
-

Time series output files -

-

If you want to inspect the time series corresponding to these windows -then see argument save_ms5rawlevels, which allows you to -export the time series including behavioral classes and non-wear -information to csv files. The behavioral classes are included as -numbers, the legend for these classes is stored as a separate legend -file in the meta/ms5.outraw folder named “behavioralcodes2020-04-26.csv” -where the date will correspond to the date of analysis.

-

Additional input arguments that may be of -interest:

-
    -
  • -save_ms5raw_format is a character string to specify how -data should be stored: either “csv” (default) or “RData”. Only used if -save_ms5rawlevels=TRUE.
    • -
  • -save_ms5raw_without_invalid is Boolean to indicate -whether to remove invalid days from the time series output files. Only -used if save_ms5rawlevels=TRUE.
    • -
-

The time series output file comes with the following -columns:

- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Column nameDescription
timenumTime stamp in UTC time format (i.e., seconds since 1970-01-01). To -convert timenum to time stamp format, you need to specify your desired -time zone, e.g., -as.POSIXct(mdat$timenum, tz = "Europe/London").
ACCAverage acceleration metric selected by acc.metric, -default = “ENMO”.
SleepPeriodTimeIs 1 if SPT is detected, 0 if not. Note that this refers to the -combined usage of guider and detected sustained inactivity bouts (rest -periods).
invalidepochIs 1 if epoch was detect as invalid (e.g. non-wear), 0 if not.
guiderNumber to indicate what guider type was used, where 1=sleeplog, -2=HDCZA, 3=swetwindow, 4=L512, 5=HorAngle, 6=NotWorn
windowNumeric indicator of the analysis window in the recording. If -timewindow = “MM” then these correspond to calendar days, if timewindow -= “WW” then these correspond to which wakingup-wakingup window in the -recording, if timewindow = “OO” then these correspond to which -sleeponset-sleeponset window in the recording. So, in a recording of one -week you may find window numbers 1, 2, 3, 4, 5 and 6.
class_idThe behavioural class codes are documented in the exported csv file -meta/ms5outraw/behaviouralcodes.csv. Class codes above class 8 will be -analysis specific, because it depends on the number time variants of the -bouts used. For example, if you look at MVPA lasting 1-10, 10-20, 30-40 -then all of them will have their own class_id. In behaviouralcodes.csv -you will find a column with class_names which match the behavioural -classes as reported in the part 5 report.
invalid_fullwindowPercentage of the window (see above) that represents invalid data, -included to ease filtering the timeseries based on whether windows are -valid or not.
invalid_sleepperiodPercentage of SPT within the current window that represents invalid -data.
invalid_wakinghoursPercentage of waking hours within the current window that represents -invalid data.
timestampTime stamp derived from converting the column timenum, only -available if save_ms5raw_format = TRUE.
angleanglez by default. If sensor.location = "hip" or -HASPT.algo = "HorAngle" then angle represents the angle for -the longitudinal axis as provided by argument longitudinal_axis or -estimated if no angle was provided. If more angles were extracted in -part 1 then these will be add with their letter appended.
lightpeakIf lux sensor data is available in the data file then it was -summarised at an epoch length defined by the second value of parameter -windowsizes (defaults to 900 seconds = 15 minutes), to add -this value to the time series it is interpolated, so the original time -resolution is not necessarily reflected in this column.
temperatureIf temperature was available in the data file then it was summarised -at an epoch length defined by the second value of parameter -windowsizes (defaults to 900 seconds = 15 minutes), to add -this value to the time series it is interpolated, so the original time -resolution is not necessarily reflected in this column.
-

For users we also want to export the time series of multiple metric -values see argument epochvalues2csv which relates to the -storage of time series in GGIR part 2.

-
-
-

Day inclusion criteria -

-

The full part 5 output is stored in the results/QC -folder. The default inclusion criteria for days in the cleaned output -from part 5 (stored in the results folder) are:

-
    -
  • For both MM and WW defined days: The valid (sensor worn) time -fraction of the day needs to be above the fraction specified with -argument includedaycrit.part5 (default 2/3).
    • -
  • For MM defined days only: The length of the day needs to be at least -the number of hours as specified by minimum_MM_length.part5 -(default 23). Note that if your experiment started and ended in the -middle of the day then this default setting will exclude those -incomplete first and last days. If you think including these days is -still meaningful for your work then adjust the argument -minimum_MM_length.part5.
    • -
-

Important notes:

-
    -
  • No criteria is set for the amount of valid data during the SPT -window, because all we are interested in part 5 is knowing the borders -of the night and we trust that this was sufficiently estimated by part -4. If you disagree then please notice that all the days are included in -the full report available in results/QC folder.
    • -
  • This means that argument includenightcrit as used for -part 4 is not used in part 5.
    • -
-

The data_cleaning_file argument discussed in Data_cleaning_file also allows you to -tell GGIR which person(s) and day(s) should be omitted in part 5. The -the day numbers to be excluded should be listed in a column -day_part5 as header.

-
-
-

Fragmentation metrics -

-

When setting input argument as frag.metrics="all" GGIR -part 5 will perform behavioural fragmentation analysis for daytime and -(separately) for spt. Do this in combination with argument -part5_agg2_60seconds=TRUE as that will aggregate the time -series to 1 minute resolution as is common in behavioural fragmentation -literature.

-

In GGIR, a fragment for daytime is a defined as a sequence of epochs -that belong to one of the four categories:

-
    -
  1. Inactivity
    2. -
  2. Light Physical Activity (LIPA)
    3. -
  3. Moderate or Vigorous Physical Acitivty (MVPA)
    4. -
  4. Physical activity (can be either LIPA or MVPA)
    5. -
-

Each of these categories represents the combination of bouted and -unbouted time in the respective categories. Inactivity and physical -activity add up to a full day (outside SPT), as well as inactivity, LIPA -and MVPA. The fragmentation metrics are applied in function -g.fragmentation.

-

A fragment of SPT is defined as a sequence of epochs that belong to -one of the four categories: 1. Estimated sleep 2. Estimated wakefulness -3. Inactivity 4. Physical activity (can be either LIPA or MVPA)

-

Note that from the metrics below only fragmentation metrics TP and -NFrag are calculated for the SPT fragments.

-

Literature about these metrics:

-
    -
  • Coefficient of Variance (CoV) is calculated according -to Blikman et al. -2014.
    • -
  • Transition probability (TP) from Inactivity (IN) to -Physical activity (IN2PA) and from Physical activity to inactivity -(PA2IN) are calculated as 1 divided by the mean fragment duration. The -transition probability from Inactivity to LIPA and MVPA are calculated -as: (Total duration in IN followed by LIPA or MVPA, respectively, -divided by total duration in IN) divided by the average duration in -IN.
    • -
  • Gini index is calculated with function Gini from the -ineq R package, and with it’s argument corr -set to TRUE.
    • -
  • Power law exponent metrics: Alpha, x0.5, and W0.5 are calculated -according to Chastin et al. -2010.
    • -
  • Number of fragment per minutes (NFragPM) is calculated -identical to metric fragmentation in Chastin et -al. 2012, but it is renamed here to be a more specific reflection of -the calculation. The term fragmentation appears too generic -given that all fragmentation metrics inform us about fragmentation. -Please not that this is effectively the same metric as the transition -probability, because total number divided by total sum in duration -equals 1 divided by average duration. This is just different terminology -for the same construct.
    • -
-

Conditions for calculation and value when condition is not -met:

-
    -
  • Metrics Gini and CoV are only calculated -if there are at least 10 fragments (e.g. 5 inactive and 5 active). If -this condition is not met the metric value will be set to missing.
    • -
  • Metrics related to power law exponent alpha are also only calculated -when there are at least 10 fragments, but with the additional condition -that the standard deviation in fragment duration is not zero. If these -conditions are not met the metric value will be set to missing.
    • -
  • Other metrics related to binary fragmentation -(mean_dur_PA and mean_dur_IN), are calculated -when there are at least 2 fragments (1 inactive, 1 active). If this -condition is not met the value will is set to zero.
    • -
  • Metrics related to TP are calculated if: There is at -least 1 inactivity fragment AND (1 LIPA OR 1 MVPA fragment). If this -condition is not met the TP metric value is set to -zero.
    • -
-

To keep an overview of which recording days met the criteria for -non-zero standard deviation and at least ten fragments, GGIR part5 -stores variable Nvaliddays_AL10F at person level (=Number -of valid days with at least 10 fragments), and SD_dur -(=standard deviation of fragment durations) at day level as well as -aggregated per person.

-

Difference between fragments and blocks:

-

Elsewhere in the part5 we use the term block. A -block is a sequence of epochs that belong to the same -behavioural class. This may sound similar to the definition of a -fragment, but for blocks we distinguish every behavioural class, which -includes the subcategories such as bouted and unbouted behaviour. This -means that variables Nblock_day_total_IN and -Nblock_day_total_LIG are identical to -Nfrag_IN_day and Nfrag_LIPA_day, respectively. -In contrast, for fragments we may group LIPA and MVPA together when -refering to the fragmentation of PA.

-

Differences with R package ActFrag:

-

The fragmentation functionality is loosely inspired on the great work -done by Dr. Junrui Di and colleages in R package ActFrag, as described -in Junrui Di -et al. 2017.

-

However, we made a couple of a different decisions that may affect -comparability:

-
    -
  • GGIR derives fragmentation metrics per day. This allows us to avoid -the issue of gaps between days that need to be dealt with. Further, it -allows us to test for behavioural differences between days of the week. -It is well known that human behaviour can be driven by weekly rhythms, -e.g. work days versus weekend. Estimating fragmentation per day of the -week allows us to study and account for such possible variation. As with -all other GGIR variables we also report recording level aggregates of -the daily estimates.
    • -
  • Transition probability is according to Lim et al. 2011 -
    • -
  • Power law alpha exponent metrics were calculated according to Chastin et al. -2010 using the theoretical minimum fragment duration instead of the -observed minimum fragment duration.
    • -
-
-
-
-

Why use data metric ENMO as default? -

-

GGIR offers a range of acceleration metrics to choose from, but only -one metric can be the default. Acceleration metric ENMO (Euclidean Norm -Minus One with negative values rounded to zero) has been the default -metric in GGIR. In 2013 we wrote a paper in which we investigated -different ways of summarising the raw acceleration data. In short, -different metrics exist and there is very little literature to support -the superiority of any metric at the time. As long as different studies -use different metrics their findings will not be comparable. Therefore, -the choice for metric ENMO is partially pragmatic. GGIR uses ENMO as -default because:

-
    -
  1. ENMO has demonstrated value in describing variance in energy -expenditure, correlated with questionnaire data, able to describe -patterns in physical activity
    2. -
  2. ENMO is easy to describe mathematically and by that improves -reproducibility across studies and software tools
    3. -
  3. ENMO attempts to quantify the actual biomechanical acceleration in -universal units.
    4. -
  4. The 2013 paper showed that when ENMO is used in combination with -auto-calibration it has similar validity to filter-based metrics like -HFEN and BFEN, which are conceptually similar to metrics proposed later -such as MIMSunit, MAD, AI0.
    5. -
  5. Studies who have criticised ENMO consistently failed to apply -auto-calibration, or attempted to apply auto-calibration in a lab -setting, ignoring the fact that the auto-calibration is not designed for -short lasting lab settings. It needs free-living data to work properly. -Further, studies are often not clear about how the problematic zero -imputation during the idle sleep mode in ActiGraph devices is dealt -with. See for a more detailed discussion on this the paragraph: Published -cut-points and how to use them.
    6. -
-

See also this -blog post on this topic.

-
-
-

What does GGIR stand for? -

-

I wanted a short name and not to spend too much time finding it. At -the time I was primarily working with GENEActiv and GENEA data In R, and -that’s how the name GGIR was born: Short, easy to remember, and as -acronym sufficiently vague to not be tight up with a specific -functionality. However, later the functionality expanded to other sensor -brands, so the abbreviation has lost its functional meaning.

-
-
-

Circadian Rhythm analyses -

-
-

MXLX -

-

Detection of the continuous least (LX) and most (MX) active X hours -in a day, where X is defined by argument winhr. For both -GGIR calculates the average acceleration, the start time, and if -argument iglevels is specified also the intensity gradient. -If argument winhr is a vector then descriptive values for -LX and MX are derived per value in winhr. Within GGIR part -2 MXLX is calculated per calendar day and, if argument -qwindow is specified, per segment of the day. Within GGIR -part 5 MXLX is calculated per window, and if used in combination with -the GENEActiv or Axivity accelerometer brand LUX estimates per LX and MX -are included.

-

The MX metric describe here should not be confused by the MX metrics -as proposed by Rowlands et al. -which looks at accumulated most active time which may not always be -continuous in time. The MX metrics by Rowlands et all are discussed -further down.

-
-
-

Cosinor analysis and Extended Cosinor analysis -

-

The (Extended) Cosinor analysis quantifies the circadian 24 hour -cycle. To do this GGIR uses R package ActCR as a -dependency. Specify argument cosinor = TRUE to perform -these analysis.

-

The implementation within GGIR part 2 is as follows:

-
    -
  • Acceleration values are averaged per minute, and then log -transformation as -log(acceleration converted to _mg_ + 1).
    • -
  • Invalid data points such as caused by non-wear are set to missing -(NA) in order to prevent the imputation approach used elsewhere in GGIR -to influence the Cosinor analysis. We do this because imputation -technique generally come with some assumptions about circadian -rhythm.
    • -
  • GGIR looks for the first valid data point in the recording and then -selects the maximum integer number of recording days following this data -point and feeds these to the ActCosinor and ActExtendCosinor functions -of ActCR. The time offset between the start and the following midnight -is then used to reverse offset the ActCR results, to ensure that -acrophase and acrotime can be interpreted relative to midnight.
    • -
  • In relation to Day Saving Time: Duplicated time stamps when clock -moves backward are ignored and missing time stamps when clock moves -forward are inserted as missing values.
    • -
  • Time series corresponding to the fitted models are stored inside the -part 2 milestone data to facilitate visual inspection. For the moment -they are not used in any GGIR visualisation, but you may want to look -them up and try to plot them yourself.
    • -
-
-
-

Intradaily Variability (IV) and Interdaily Stability (IS) -

-
-
IV and IS - Default -
-

The original implementation (argument IVIS.activity.metric = 1) uses -the continuous numeric acceleration values. However, as we later -realised this is not compatible with the original approach by van -Someren and colleagues, which uses a binary distinction between active -and inactive. Therefore, a second option was added (argument -IVIS.activity.metric = 2), which needs to be used in combination with -accelerometer metric ENMO, and collapses the acceleration values into a -binary score of rest versus active. This is the current default.

-
-
-
IV and IS - Cosinor analysis compatible -
-

Disclaimer: The following has been implemented 2022, but is currently -undergoing critical evaluation. As a result, we may update this -algorithm during the course of 2023.

-

IS is sometimes used as a measure of behavioural robustness when -conducting Cosinor analysis. However, to work with the combination of -the two outcomes it seems important that IS is calculated from the same -time series. Therefore, when cosinor = TRUE IV and IS are -calculated twice: Once as part of the default IV and IS analysis as -discussed above, and once as part of the Cosinor analysis using the same -log transformed time series. More specifically, the IV and IS algorithm -is applied with IVIS.activity.metric = 2 and -IVIS_acc_threshold = log(20 + 1) to make the binary -distinction between active and inactive, and -IVIS_per_daypair = TRUE. The setting -IVIS_per_daypair was specifically designed for this context -to handle the potentially missing values in the time series as used for -Cosinor analysis. Applying the default IVIS algorithm would not be able -to handle the missing values and would result in a loss of information -if all non-matching epochs across the entire recording were excluded. -Instead, IV and IS are calculated as follows:

-
    -
  1. Per day pair based on matching valid epochs only IV and IS and -calculated. Here, a log is kept of the number of valid epoch per day -pair.
    2. -
  2. Omit day pairs where the fraction of valid epoch pairs is below 0.66 -(0.66 is hard-coded at the moment).
    3. -
  3. Calculate average IS across days weighted by fraction of valid -epochs per day pairs.
    4. -
-

The new Cosinor-compatible IV and IS estimates are stored as output -variables cosinorIV and cosinorIS.

-
-
-
-
-

ActiGraph’s idle sleep mode -

-

The idle sleep mode is explained -on the manufacturer’s website. In short, idle sleep mode is a setting -that can be turned on or off by the user. When it is turned on the -device will fall asleep during periods of no movement, resulting in time -gaps in the data. This functionality was probably introduced to safe -battery life and minimize data size. However, it also means that we end -up with time gaps that need to be accounted for.

-
-

Time gap imputation -

-

Studies done with ActiGraph devices when configured with ‘idle sleep -mode’ and with data exported to .csv by the commerical ActiLife software -will have imputed values in all three axes during periods of no -movement. Note that the imputation by the ActiLife software has changed -at some point in time. Initially the imputation was zeros but with more -recent versions of ActiLife the imputation uses the last recorded value -for each axes.

-

When processing gt3x files that have time gaps GGIR takes care of the -time gap imputation: Time gaps shorter than 90 minutes are imputed at -raw data level with the last known recorded value before the timeg gap, -while longer time gaps are imputed at epoch level. We do this to make -the data processing more memory efficient and faster.

-

Time gaps in the data are considered non-wear time in GGIR, this -implies that we trust the ActiGraph sleep mode to only be activated when -the device is not worn, although there is always a risk of -sleep/sedentary misclassification.

-
-
-

The importance of reporting idle.sleep.mode usage -

-

Studies often forget to clarify whether idle sleep mode was used and -if so, how it was accounted for in the data processing. Especially, the -insertion of zero strings is problematic as raw data accelerometers -should always measure the gravitational component when not moving. This -directly impacts metrics that rely on the presence of a gravitational -component such as ENMO, EN, ENMOa, SVMgs, and angles. Further, also -other metrics may be affected as the sudden disappearance of -gravitational acceleration will cause a spike at the start and end of -the idle sleep mode period. More generally speaking, we advise ActiGraph -users to:

-
    -
  • Disable the ‘idle sleep mode’ as it harms the transparency and -reproducibility since no mechanism exists to replicate it in other -accelerometer brands, and it is likely to challenge accurate assessment -of sleep and sedentary behaviour.
    • -
  • That data collected with ‘idle sleep mode’ turned on is not be -referred to as raw data accelerometry, because the data collection -process has involved proprietary pre-processing steps which violate the -core principle of raw data collection.
    • -
  • Report whether ‘idle sleep mode’ was used. If the choice was not -consistent within a study then try to account for idle mode sleep usage -in the statistical analyses.
    • -
-
-
-
-

MX metrics (minimum intensity of most active X minutes) -

-

The qlevels argument (the percentile in the distribution -of short epoch metric value) can be used to describe the accelerations -that participants spend “X” accumulated minutes a day above, described -as the MX metrics (e.g., Rowlands et -al).

-

The MX metrics should not be confused with the most active continuous -X hours, e.g. M10, as used in circadian rhythm research that also can be -derived with GGIR, see argument winhr.

-

Usage To use the MX metrics as proposed by Rowlands et al, -specify the durations of the 24h day that you wish to filter out the -accelerations for. For example, to generate the minimum acceleration -value for the most active 30 minutes you can call qlevels = (1410/1440), -which will filter out the lowest 1410 minutes of the day. This can also -be used as a nested term to generate multiple metrics, for example to -call M60, M30 and M10, you can use argument:

-

qlevels = c(c(1380/1440),c(1410/1440),c(1430/1440)).

-

Note: if your qwindow is less than 24 h, e.g. the school day (e.g. Fairclough et al 2020) the -denominator should be changed from 1440 (24h) accordingly, e.g. if an 8 -h window the denominator would be 480 rather than 1440.

-

Output The output in part2 summary files will refer -to this as a percentile of the day. Thus, for a 24 h day, M30 will -appear as “p 97.91666_ENMO_mg_0.24hr”. To graph the radar plots of these -MX metrics as first described by Rowlands et al, you -can access this github -repository which provides the R code and detailed instructions on how to -make the radar plots using your own data.

-
-
-

Minimum recording duration -

-

GGIR has been designed to process multi-day recordings. The minimum -recording duration considered by GGIR depends on the type of -analysis:

-

Running part 1 and 2

-
    -

  • File size; At least 2MB, where 2MB can be adjusted with argument -minimumFileSizeMB. This should not be changed unless you have good -reason to believe that a smaller file size is also acceptable.

    • -

  • Recording duration: At least two long epoch windows (default 60 -minutes) in g.readaccfile. The size of this epoch can be altered with -the second and third value of vector argument windowsizes, -where the third should not be smaller than the second. For example, in -short lasting lab-experiments you may find it easier to set this to -windowsizes = c(5, 600, 600) as non-wear detection is -usually not necessary in lab studies.

    • -
-

Running part 3 and 4

-
    -
  • At least one night of data is expected, where a night is expected to -have at least the timestamp for midnight. If midnight is not found the -sleep detection is skipped.
    • -
-

Running part 5

-
    -
  • Ideally two valid consecutive nights and the waking hours in -between.
    • -
-
-
-

LUX sensor data processing -

-

Although GGIR focuses on accelerometer data a few brands come with -LUX data.

-

In part 1 GGIR calculates the peak lux per long epoch at a default -resolution of 15 minutes, which can be modified with argument -windowsizes. Peak light offers a more reliable estimate of light -exposure per time window compared with taking the average. Further, LUX -is used in the auto-calibration.

-

In GGIR part 2 we visualise the LUX values in the qc plot. In part 3 -and 4 LUX is not used for sleep classification because relation between -light exposure and sleep is weak.

-

In part 5 we calculate the mean and maximum of the peak LUX per epoch -across all waking hours of the day. Here, the mean (peak per epoch) LUX -would then indicate average light exposure per time segment, while max -peak would indicate the maximum light exposure per day. Further, we -calculate the max and mean peak LUX per most active consecutive X hour -of the day. This is intended to offer an alternative to LUX exposure -during waking hours which relies on correct sleep classification. LUX -exposure during M10 may be seen as an alternative if you are unsure -whether you can trust the sleep classification in your data set.

-
-
-
-

Other Resources -

- -
-
-

Citing GGIR -

-

A correct citation of research software is important to make your -research reproducible and to acknowledge the effort that goes into the -development of open-source software.

-

To do so, please report the GGIR version you used in the text. -Additionally, please also cite:

-
    -
  1. Migueles JH, Rowlands AV, et al. GGIR: A Research Community–Driven -Open Source R Package for Generating Physical Activity and Sleep -Outcomes From Multi-Day Raw Accelerometer Data. Journal for the -Measurement of Physical Behaviour. 2(3) 2019. doi: -10.1123/jmpb.2018-0063.
    2. -
-

If your work depends on the quantification of physical -activity then also cite:

-
    -
  1. van Hees VT, Gorzelniak L, et al. Separating Movement and Gravity -Components in an Acceleration Signal and Implications for the Assessment -of Human Daily Physical Activity. PLoS ONE 8(4) 2013. link -
    2. -
  2. Sabia S, van Hees VT, Shipley MJ, Trenell MI, Hagger-Johnson G, -Elbaz A, Kivimaki M, Singh-Manoux A. Association between questionnaire- -and accelerometer-assessed physical activity: the role of -sociodemographic factors. Am J Epidemiol. 2014 Mar 15;179(6):781-90. -doi: 10.1093/aje/kwt330. Epub 2014 Feb 4. PMID: 24500862 link -
    3. -
-

If you used the auto-calibration functionality then -also cite:

-
    -
  1. van Hees VT, Fang Z, et al. Auto-calibration of accelerometer data -for free-living physical activity assessment using local gravity and -temperature: an evaluation on four continents. J Appl Physiol 2014. link -
    2. -
-

If you used the sleep detection then also cite:

-
    -
  1. van Hees VT, Sabia S, et al. A novel, open access method to assess -sleep duration using a wrist-worn accelerometer, PLoS ONE, 2015 link -
    2. -
-

If you used the sleep detection without relying on sleep -diary then also cite:

-
    -
  1. van Hees VT, Sabia S, et al. Estimating sleep parameters using an -accelerometer without sleep diary. Scientific Reports 2018. doi: -10.1038/s41598-018-31266-z. link -
    2. -
-

If you used the sleep regularity index then also -cite:

-
    -
  1. Andrew J. K. Phillips, William M. Clerx, et al. Irregular sleep/wake -patterns are associated with poorer academic performance and delayed -circadian and sleep/wake timing. Scientific Reports. 2017 June 12 link.
    2. -
-
- -

The copyright of the GGIR logo lies with Accelting (Almere, The -Netherlands), please contact to ask for permission to use -this logo.

-

-
-
-
-
- - - -
-

Developed by Vincent T van Hees, Jairo H Migueles, Medical Research Council UK, Accelting, French National Research Agency.

-
- -
-

Site built with pkgdown 2.0.9.

-
- -
-
- - - - - - - diff --git a/docs/articles/chapter0_contributing.html b/docs/articles/chapter0_contributing.html deleted file mode 100644 index 64019130a..000000000 --- a/docs/articles/chapter0_contributing.html +++ /dev/null @@ -1,184 +0,0 @@ - - - - - - - - -Contributing • GGIR - - - - - - - - - - - - - Skip to contents - - -
- - - - -
-
-

Contributing

- - - Source: vignettes/chapter0_Contributing.Rmd -
chapter0_Contributing.Rmd
-
- - - -
-

If you have coding skills… -

-

We welcome contributions in the development, maintenance, and -documentation of GGIR. Please find the GGIR’s contributing guidelines here.

-
-
-

If you do not have coding skills…. -

-

You might not have the coding skills to contribute to the code base -of GGIR, and still your contribution could be very important for us. For -example:

-
    -
  • -Doing research on algorithms is crucial to support -the development of GGIR. We welcome contributions on any aspect in this -regard.
    • -
  • -Reporting any issue you might have in the google -group dedicated to GGIR community. Our answers to your issues might also -help other GGIR users.
    • -
  • -Proofreading the GGIR documentation and informing -us if you miss any essential aspect or you found it difficult to follow -any of the instructions provided.
    • -
-
-
-
- - - -
-

Developed by Vincent T van Hees, Jairo H Migueles, Medical Research Council UK, Accelting, French National Research Agency.

-
- -
-

Site built with pkgdown 2.0.9.

-
- -
-
- - - - - - - diff --git a/docs/articles/chapter10_CircadianRhythms.html b/docs/articles/chapter10_CircadianRhythms.html deleted file mode 100644 index 9bde8d2c5..000000000 --- a/docs/articles/chapter10_CircadianRhythms.html +++ /dev/null @@ -1,177 +0,0 @@ - - - - - - - - -9. Circadian rhythms • GGIR - - - - - - - - - - - - - Skip to contents - - -
- - - - -
-
-

9. Circadian rhythms

- - - Source: vignettes/chapter10_CircadianRhythms.Rmd -
chapter10_CircadianRhythms.Rmd
-
- - - -

Work in progress…

-
-

MXLX metrics (consecutive hours, instead of cumulative hours) -

-
-
-

Cosinor and extended cosinor analysis -

-
-
-

Intradaily variability and interdaily stability -

-
-
-

Key arguments -

-
-
- -
-
-
- - - -
-

Developed by Vincent T van Hees, Jairo H Migueles, Medical Research Council UK, Accelting, French National Research Agency.

-
- -
-

Site built with pkgdown 2.0.9.

-
- -
-
- - - - - - - diff --git a/docs/articles/chapter10_SleepAnalysis.html b/docs/articles/chapter10_SleepAnalysis.html deleted file mode 100644 index ef475d16c..000000000 --- a/docs/articles/chapter10_SleepAnalysis.html +++ /dev/null @@ -1,399 +0,0 @@ - - - - - - - - -10. Sleep Analysis • GGIR - - - - - - - - - - - - - Skip to contents - - -
- - - - -
-
-

10. Sleep Analysis

- - - Source: vignettes/chapter10_SleepAnalysis.Rmd -
chapter10_SleepAnalysis.Rmd
-
- - - -
-

Sleep analysis -

-

Sleep analysis in GGIR comes at three stages:

-
    -

  1. The discrimination of sustained inactivity and wakefulness -periods, discussed in chapter 8.

    2. -

  2. Identification of time windows that guide the eventual sleep -detection, as discussed chapter 9.

    3. -

  3. Assess overlap between the windows identified in step 1 and 2, -which we use to define the Sleep Period Time window (SPT) or the time in -bed window (TimeInBed) as discussed in this chapter.

    4. -
-

In the previous two chapters you learnt about the first two steps in -this chapter we will discuss the last step.

-
-

Sleep Period Time (SPT) window or Time in Bed -

-

Here we have two scenarios:

-
    -

  1. If the guider reflects an approximation of the Sleep Period Time -window, which is the window between sleep onset and waking up at the end -of the night, then any SIB that fully or partially overlaps with the -guider is considered sleep.

    2. -

  2. If a guider reflects the Time in Bed then any SIB that fully -overlaps with the guider is considered sleep. In this scenario sleep -latency and sleep efficiency can be estimated and are included in the -GGIR part 4 report.

    3. -
-

In both cases the start of the first SIB is then considered sleep -onset and the end of the last SIB is considered waking up.

-

For all guiders, other than “HorAngle”, parameter -sleepwindowType is automatically set to “SPT” corresponding -to scenario 1, such that no attempt is made to estimate sleep latency or -sleep efficiency.

-

If you use as guider a sleeplog that reflects the Time in Bed you -will need to set parameter sleepwindowType = “TimeInBed” to -tell GGIR to follow scenario 2.

-
-
-

Quality assurance -

-
-

Cleaningcode -

-

To monitor possible problems with the sleep detection, the output -variable cleaningcode is stored per night. Cleaningcode -per night (noon-noon or 6pm-6pm as described above) can have one of the -following values:

-
    -

  • 0: sleep log available and SPT is identified.

    • -

  • 1: sleep log not available, and alternative guider used (HDCZA by -default) and SPT is identified with that.

    • -

  • 2: not enough valid accelerometer data in the present night, -where parameter includenightcrit is used to define how many -valid hours are need.

    • -

  • 3: no accelerometer data available.

    • -

  • 4: there are no nights to be analysed for this person.

    • -

  • 5: SPT estimated based on guider only, because either no SIB was -found during the entire guider window which complicates defining the -start and end of the SPT, or the user specified the ID number of the -recording and the night number in the data_cleaning_file, more about -this further down, to tell GGIR to rely on the guider and not rely on -the accelerometer data for this particular night.

    • -

  • 6: no sleep log available and also alternative guider -(HDCZA/HorAngle) failed for this specific night then use average guider -estimates from other nights in the recording as guider for this night. -If HDCZA/HorAngle estimates are also not available during the entire -recording then use L5+/-12 estimate for this night.

    • -
-
-
-

Visual inspection of classifications -

-

As overlap between sib and guiders is difficult to review in a -quantitative way, GGIR offers the option to export a visualisation, with -parameter do.visual = TRUE. To manage the number of -visualisations generated it is possible to tell GGIR to only show -outliers. Here, outliers are defined as a difference between guider edge -and the final classification of sleep onset and wakeup time larger than -parameter criterror. When you set parameter -outliers.only = TRUE only nights considered to be an -outlier will be displayed.

-

This functionality is useful when reviewing classifications in large -data sets that use sleep logs. Visual inspection of outliers in this way -can for example help to identify data entry errors for sleep logs.

-
-
-

Data cleaning file -

-

After data quality check you may observe that some adjustments are -needed. Parameter data_cleaning_file (path to a csv file -you create) allows you to specify individuals and nights for whom part4 -should entirely rely on the guider. The first column of this csv file -should have column name ID and there should be a column -relyonguider_part4 to specify the night. The -night_part4 allows you to tell GGIR which night(s) should -be omitted in part 4.

-
-
-
-

Sleep metrics available in GGIR -

-

For a full overview of all sleep variables in part 4 see: https://cran.r-project.org/web/packages/GGIR/vignettes/GGIR.html#42_Output_part_4

-

Among these we assume that most are intuitive:

-
    -

  • sleep onset and wakeup

    • -

  • Sleep duration during SPT, which is the accumulate sleep time -(sustained inactivity bouts classified as sleep)

    • -

  • WASO, the time spent in wakefulness after sleep onset. However, -there are possible a few concepts that need clarifications:

    • -
-
-

Sleep Regularity Index (SRI) -

-

This is a measure of sleep regularity between successive days, as -first described by Phillips and colleagues. The SRI can have a value -between -100 and 100, where 100 reflects perfect regularity (identical -days), 0 reflects random pattern, and -100 reflects perfect reversed -regularity. The SRI is proposed to only be calculated based on seven, or -a multitude of seven, consecutive days of data without missing values. -This to avoid a possible role of imbalanced data to the final estimate. -However, this renders many datasets unsuitable for analysis and leads to -a painful loss in sample size and statistical power.

-
-
Sleep Regularity Index – Dealing with unbalanced data -
-

To address this, I implemented the SRI in GGIR per day-pair. Per -day-pair GGIR now stores the SRI value and the fraction of the 30 second -epoch-pairs between both days that are valid. This fraction can be found -in the output under the variable name SriFractionValid. By default, -day-pairs are excluded if this fraction is below 0.66. For those -familiar with GGIR this threshold is coupled with the 16-hour default -value for parameter “includenightcrit”. For example, if you set -parameter “includenightcrit = 12”, the fraction threshold will be: 12 / -24 = 0.5. Note that I have implemented the SRI calculation such that it -accounts for the missing values in the denominator. As a result, the SRI -value interpretation remains unchanged.

-

The 30 second epoch setting is automatically applied, even if the -rest of the GGIR process works with a different epoch duration.

-

The day-pair level estimates are stored as variable -SleepRegularityIndex in the GGIR part 4 .csv-report on -sleep. Further, GGIR also stores the person-level aggregates such as: -the plain average over all valid days, the average of all valid weekend -days, and the average of all valid week days. No GGIR input arguments -are needed to invoke the SRI calculation. The calculation is -automatically performed after updating GGIR and processing your -data.

-
-
-
Sleep Regularity Index – Benefits of the revised approach -
-

It enables the user to study the day-pair to day-pair variation in -SRI, and the role of day-pair inclusion criteria.

-

The access to SRI at day-pair level makes it possible to account for -an imbalanced datasets via multilevel regression analysis applied to the -output of GGIR, with day-pair as one of the model levels.

-
-
-
Nap detection -
-

Any references to daytime nap detection in GGIR is based on -experimental functionality that requires ongoing investigation. Once -this functionality has matured we will expand the documentation -accordingly.

-
-
-
-
-

Key parameters -

-

All parameters that are part of the params_sleep category as -discussed in section “Sleep parameters” in https://cran.r-project.org/web/packages/GGIR/vignettes/GGIRParameters.html

-

and

-
    -
  • -do.visual, outliers.only, and -criterror.
    • -
  • -excludefirstlast.
    • -
  • def.noc.sleep
    • -
  • includenightcrit
    • -
  • data_cleaning_file
    • -
-
-
- -

GGIR stores two type of output: The cleaned and the full output. In -the cleaned output invalid nights have been removed, while in the full -output these nights are included.

-

More specifically, a night is excluded from the ‘cleaned’ results -based on the following criteria:

-
    -

  • If the study proposed a sleep log to the individuals, then nights -are excluded for which the sleep log was not used as a guider. In other -words: nights with cleaningcode not equal to 0 or variable sleep log -used equals FALSE).

    • -

  • If the study did not propose a sleep log to the individuals, then -all nights are removed with cleaningcode higher than 1.

    • -
- ----- - - - - - - - - - - - - - - - - - - - - - - -
FilenameFolderContent
part4_nightsummary_cleaned.csvresultscleaned night level results
part4_summary_cleaned.csvresultscleaned person level results
part4_nigthsummary_full.csvresultsfull night level results
-

Be aware that if using the full output and working with wrist -accelerometer data, missing entries in a sleep log that asks for Time in -Bed will be replaced by HDCZA estimates of SPT. Therefore, extra caution -should be taken when working with the full output.

-

Notice that part 4 is focused on sleep research. In the chapters we -will discuss the analysis done by part 5. There, the choice of guider -may be considered less important, by which any estimate of the time in -bed is considered useful. So, you may see that a night that is excluded -from the cleaned results in part 4 still appears in the cleaned results -for part 5.

-
-
-
-
- - - -
-

Developed by Vincent T van Hees, Jairo H Migueles, Medical Research Council UK, Accelting, French National Research Agency.

-
- -
-

Site built with pkgdown 2.0.9.

-
- -
-
- - - - - - - diff --git a/docs/articles/chapter11_DescribingDataCutPoints.html b/docs/articles/chapter11_DescribingDataCutPoints.html deleted file mode 100644 index 7e0980650..000000000 --- a/docs/articles/chapter11_DescribingDataCutPoints.html +++ /dev/null @@ -1,486 +0,0 @@ - - - - - - - - -11. Physical Activity Fundamentals: Describing the data with cut-points • GGIR - - - - - - - - - - - - - Skip to contents - - -
- - - - -
-
-

11. Physical Activity Fundamentals: Describing the data with cut-points

- - - Source: vignettes/chapter11_DescribingDataCutPoints.Rmd -
chapter11_DescribingDataCutPoints.Rmd
-
- - - -

Descriptive variables such as average acceleration as discussed in -the previous chapter are powerful indicators of physical activity. -Extensive evidence exists on the association between magnitude of -acceleration as captured by an accelerometer and physical activity -related energy expenditure as measured by indirect calorimetry. The -value of MX metrics and intensity gradient as discussed in chapter 7 has -been shown in several studies (for example: Rowlands, 2019a; Rowlands 2019b). -However, historically the physical activity research community has been -keen on having a single or a small number of measures of physical -activity that can be expressed in the unit minutes per day.

-
-

MVPA, LIPA, and Inactivity -

-
-

Construct definition -

-

A popular approach to describe time series data in physical activity -research is to distinguish so called intensity levels. Here, the -community distinguishes sedentary behaviour (SB), light physical -activity (LIPA), moderate, and vigorous physical activity. The latter -two categories are often combined into moderate or vigorous physical -activity (MVPA).

-

The exact definition of these levels is poor which has caused -methodological discrepancies for decades:

-
    -

  • Intensity levels are defined based on metabolic equality of task -(MET), which is based on oxygen consumption measured with indirect -calorimetry divided by body weight. MET as a construct fail to normalise -for body weight by which comparisons of individuals or activity types -that have a different relation with body weight are bound to drive -differences.

    • -

  • The MET thresholds themselves (e.g. 3 MET) has a different -meaning per person as MET value is not only driven by what people do in -terms of movement but also their fitness and anthropometry.

    • -

  • Lack of consensus on how to handle the temporal nature of -behaviour. For example, is a few seconds enough to define a behaviour or -do we require minimum time duration?

    • -

  • Criterion methods are hard to standardise across studies. For -example, the studies differ in specific equipment, study protocols, and -preparation of the data from the criterion method.

    • -
-
-
-

Classification with accelerometer data -

-

From an accelerometer data processing perspective time spent in -intensity levels is often simplified to time spent below, above, or -between certain acceleration level(s) chosen to make a crude separation -of the intensity levels. The acceleration magnitude(s) to use as -threshold(s), is often referred to as cut-point in the literature.

-

Time spent below, above, or between the cut-point(s) is intended to -be a crude indicator of time spent in behaviours and sufficient to rank -individuals on their amount of time spent in these behaviours. The -simple threshold approach has indisputably been the most powerful method -so far to drive physical activity research.

-

In GGIR part 2, only MVPA is estimate. The threshold(s) for MVPA as -used in GGIR part 2 are set with parameter mvpathreshold. -You can specify a single value or a vector of multiple values, time -spent in MVPA will then be derived with each of them. However, the -threshold is not the only parameters to influence time spent in MVPA, as -we will discussed in the following paragraphs.

-
-
-

Role of epoch length -

-

Although accelerometers collect data at much higher sampling -frequency, we only work with aggregated values (e.g. 1 or 5 second -epochs) for the following reasons:

-
    -

  1. Accelerometers are often used to describe patterns in metabolic -energy expenditure. Metabolic energy expenditure is typically defined -per breath or per minute (indirect calorimetry), per day (room -calorimeter), or per multiple days (doubly labelled water method). In -order to evaluate our methods against these reference standards, we need -to work with a similar time resolution.

    2. -

  2. Collapsing the data to epoch summary measures helps to -standardise our output across data collected with different sampling -frequencies between studies.

    3. -

  3. There is little evidence that the raw data is an accurate -representation of body acceleration. All scientific evidence on the -validity of accelerometer data has so far been based on epoch -aggregates.

    4. -
-

Short epoch lengths, such as 1 or 5 seconds, are more sensitive to -sporadic behaviours and often combined with bout detection to identify -MVPA only as a sustained behaviour.

-

Longer epochs, such as 30 or 60 seconds, do not have this problem and -are therefore easier to use without bout detection.

-

The epoch length in GGIR is by default 5 seconds, and can be set as -the first value of the vector specified by parameter -windowsizes. Although we discuss epoch length here in the -context of MVPA, please note that epoch length influences many of the -outcomes by GGIR.

-
-
-

Bout detection -

-

A bout is a time segment that meets specific temporal criteria and -has frequently been used in the physical activity research. GGIR -facilitates processing data both with and without accounting for bouts. -The motivation to look for bouts can be one of the following:

-
    -

  • With the idea that only behaviour with a certain minimum duration -contributes to certain physiological benefits.

    • -

  • To make the classification of behaviour consistent with -self-report data, only sensitive to duration of specific -duration.

    • -

  • To aid studying the fragmentation of behaviour.

    • -
-

To define a bout we need to answer series of question:

-
    -
  1. What should the cut-point be?
    2. -
  2. What should the epoch length be?
    3. -
  3. What should minimum duration of bout be?
    4. -
  4. Should we allow for gaps in a bout as in breaks in the behaviour of -interest?
    5. -
  5. If yes to 4, should this be a percentage of the bout duration, an -absolute minimum in seconds, or a combination of both?
    6. -
  6. If yes to 4, are bout gaps counted towards the time spent in -bouts?
    7. -
  7. Do the first and last epoch need to meet the threshold -criteria?
    8. -
  8. In what order are the bouts extracted? For example, if a short MVPA -bout is part of a longer Inactivity bout which of the two prevails?
    9. -
  9. How many bout categories should there be?
    10. -
-

GGIR facilitates the following freedom in bout detection:

-

User decides on:

-
    -

  • Acceleration thresholds for light, moderate, and vigorous -intensity

    • -

  • Fraction of time for which cut-point criteria need to be met -(light, inactive, MVPA)

    • -

  • Bout duration range. For example, a simple scenario could be to -consider all bouts of a minimum length of 10 minutes, while it is also -possible to subdivide them in bouts lasting [1, 5) [5, 10) and [10, ∞) -minutes.

    • -

  • Epoch length.

    • -
-

User does NOT decide on:

-
    -

  • Maximum bout gap of 1 minute, if the fraction of time for which -the cut-point criteria need to be met is less than 100%

    • -

  • First and last epoch need to meet cut-point criteria.

    • -

  • Number of intensity levels, which are always: inactive, light and -MVPA.

    • -

  • Order in which bouts are calculated (1 MVPA; 2 inactive; 3 -Light)

    • -
-
-
-

Differences in physical activity estimates in part 2 and 5 -

-

The parameters needed for MVPA estimates in GGIR part 2 are different -from the parameters used for estimating MVPA, LIPA and Inactivity in -part 5.

-

GGIR part 2 always provides six distinct approaches to MVPA -calculation that are controlled with parameters -mvpathreshold, boutcriter, -mvpadur, and the first element of vector -windowsdur. Here, MVPA provides time spent in MVPA based -on:

-
    -

  • 5 second, 1 minute or 5 minute epochs and no bouts

    • -

  • 5 second epochs and 3 different minimum bout duration as -specified with parameter mvpadur.

    • -
-

The bout durations are each used for separate estimates and not used -complimentary to each other as is the case in part 5. For example, -specifying boutdur.mod = c(5, 10) in part 5 will result in -an estimate of time spent in bouts lasting from 5 till 10 minutes and in -bouts lasting 10 minutes and longer.

-
-
-
-

Controlling the time window of analysis: -

-

As discussed in chapter 7, it is possible to tell both GGIR part 2 -and part 5 to extract variables per segment of the day. We do this with -parameter qwindow for which you can find a detailed -discussion in Annex Day segment analysis.

-
-
-

Behavioural fragmentation -

-

In addition to classifying the time spent in each behavioural class -it is also informative to study the fragmentation of behaviours.

-
-

Classes of behaviour used to study fragmentation -

-

In GGIR, a fragment for daytime is a defined as a sequence of epochs -that belong to one of the four categories:

-
    -
  1. Inactivity
    2. -
  2. Light Physical Activity (LIPA)
    3. -
  3. Moderate or Vigorous Physical Acitivty (MVPA)
    4. -
  4. Physical activity (can be either LIPA or MVPA)
    5. -
-

Each of these categories represents the combination of bouted and -unbouted time in the respective categories. Inactivity and physical -activity add up to a full day (outside SPT), as well as inactivity, LIPA -and MVPA. The fragmentation metrics are applied in function -g.fragmentation.

-

A fragment of SPT is defined as a sequence of epochs that belong to -one of the four categories:

-
    -
  1. Estimated sleep
    2. -
  2. Estimated wakefulness
    3. -
  3. Inactivity
    4. -
  4. Physical activity (can be either LIPA or MVPA)
    5. -
-

Note that from the metrics below only fragmentation metrics -TP and NFrag are calculated for the SPT -fragments.

-

With parameter frag.metrics="all" we can tell GGIR part -5 to derive behavioural fragmentation metrics for daytime and -(separately) for spt. You may want to consider combining this with -parameter part5_agg2_60seconds=TRUE as that will aggregate -the time series to 1 minute resolution as is common in behavioural -fragmentation literature.

-
-
-

Fragmentation metrics -

-
    -

  • Coefficient of Variance (CoV) is calculated -according to Blikman et -al. 2014, which entails dividing the standard deviation by the mean -lognormal transformed fragment length (minutes).

    • -

  • Transition probability (TP) from Inactivity (IN) to -Physical activity (IN2PA), from Physical activity to inactivity (PA2IN), -and from IN to LIPA or MVPA are all calculated according to Danilevicz -et al. 2023 10.21203/rs.3.rs-3543711/v1.

    • -

  • Gini index is calculated with function Gini from the -ineq R package, and with ineq argument -corr set to TRUE.

    • -

  • Power law exponent metrics: Alpha, x0.5, and W0.5 are calculated -according to Chastin et -al. 2010.

    • -

  • Number of fragment per minutes (NFragPM) is -calculated identical to metric fragmentation index in Chastin et -al. 2012, but it is renamed here to be a more specific reflection of -the calculation. The term fragmentation index appears too -generic given that all fragmentation metrics inform us about -fragmentation. Please note that this is close to the metrics for -transition probability, because total number divided by total sum in -duration equals 1 divided by average duration. Although the exact math -is slightly different.

    • -
-
-

Conditions for calculation and value when condition is not met -

-
    -

  • Metrics Gini and CoV are only -calculated if there are at least 10 fragments (e.g. 5 inactive and 5 -active). If this condition is not met the metric value will be set to -missing.

    • -

  • Metrics related to power law exponent alpha are also only -calculated when there are at least 10 fragments, but with the additional -condition that the standard deviation in fragment duration is not zero. -If these conditions are not met the metric value will be set to -missing.

    • -

  • Other metrics related to binary fragmentation -(mean_dur_PA and mean_dur_IN), are calculated -when there are at least 2 fragments (1 inactive, 1 active). If this -condition is not met the value will is set to zero.

    • -

  • Metrics related to TP are calculated if: There is at -least 1 inactivity fragment AND (1 LIPA OR 1 MVPA fragment). If this -condition is not met the TP metric value is set to -zero.

    • -
-

To keep an overview of which recording days met the criteria for -non-zero standard deviation and at least ten fragments, GGIR part 5 -stores variable Nvaliddays_AL10F at person level (i.e., -number of valid days with at least 10 fragments), and -SD_dur (i.e., standard deviation of fragment durations) at -day level as well as aggregated per person.

-
    -
  • GGIR derives fragmentation metrics per waking hours of the day in -part 5 and per recording in part 6. Calculation per day allows us to -explore and possibly account for behavioural differences between days of -the week. However, for rare behaviours a day level estimate could be -considered less robust than the recording level estimates as generated -in part 6.
    • -
-
-
-

Differences with R package ActFrag: -

-

The fragmentation functionality was initially inspired on the great -work done by Dr. Junrui Di and colleagues in R package ActFrag, as -described in Junrui Di et -al. 2017. However, we made a couple of a different decisions that -may affect comparability:

-
    -

  • Transition probability is according to Danilevicz et al. 2023 -10.21203/rs.3.rs-3543711/v1

    • -

  • Power law alpha exponent metrics were calculated according to Chastin et al. -2010 using the theoretical minimum fragment duration instead of the -observed minimum fragment duration.

    • -
-
-
-
-

Key arguments -

-

The parameters related to cut-points and bout detection are all -concentrated in the “Physical activity parameters” as discussed in https://cran.r-project.org/ -package=GGIR/vignettes/GGIRParameters.html.

-
-
- -

In GGIR part 2 csv reports you will find:

-
    -
  • Time spent in MVPA
    • -
-

In GGIR part 5 csv reports you will find:

-
    -
  • Time spent in MVPA
    • -
  • Time spent in LIPA
    • -
  • Time spent in inactivity (abbreviated as IN)
    • -
-

In chapter 7 we discussed the structure of the part 2 output and in -chapter 11 will provide a more detailed discuss of all the part 5 -output. Further, for a detailed discussion of specific all output -variables in all parts see https://cran.r-project.org/web/packages/GGIR/vignettes/GGIR.html#4_Inspecting_the_results

-
-
-
-
- - - -
-

Developed by Vincent T van Hees, Jairo H Migueles, Medical Research Council UK, Accelting, French National Research Agency.

-
- -
-

Site built with pkgdown 2.0.9.

-
- -
-
- - - - - - - diff --git a/docs/articles/chapter11_HouseholdCoanalysis.html b/docs/articles/chapter11_HouseholdCoanalysis.html deleted file mode 100644 index 61de6bab4..000000000 --- a/docs/articles/chapter11_HouseholdCoanalysis.html +++ /dev/null @@ -1,628 +0,0 @@ - - - - - - - - -10. Household Co-analysis • GGIR - - - - - - - - - - - - - Skip to contents - - -
- - - - -
-
-

10. Household Co-analysis

- - - Source: vignettes/chapter11_HouseholdCoanalysis.Rmd -
chapter11_HouseholdCoanalysis.Rmd
-
- - - -

Work in progress…

-

See also complementary vignettes on: General -introduction to GGIR, Day -segment analyses, GGIR -parameters, Embedding -external functions (pdf), and Reading -ad-hoc csv file formats.

-

Household co-analysis facilitates the analysis of how sleep and -physical activity relate between members of the same household.

-
-

Accelerometer file names -

-

The household co-analysis requires that households and family member -can be recognised. To do this we assume the following logic in the file -names:

-

StudyNumber-HouseholdID-MemberID_anyotherinformation.bin

-

This example is for a .bin file, but the same applies to .cwa or .csv -files.

-

For example the files:

-
    -
  • 001-002-001_12345-2023.bin
    • -
  • 001-002-002_23456-2023.bin
    • -
  • 001-002-M_23456-2023.bin
    • -
-

will be recognised as household ID 002 with member IDs -001, 002, and M.

-
-
-

Configuring GGIR -

-

The following input arguments are needed to run the Household -co-analysis:

-
    -
  • The Household co-analysis is integrated in GGIR as part 6, so we -need to run GGIR with part 1 to 6, with mode = 1:6.
    • -
  • -windowsizes = c(5, 60, 3600). Setting the second value -to 60 ensures that light and temperature, if available, are aggregated -per minute.
    • -
  • -part5_agg2_60seconds = TRUE. This ensures that GGIR -part 5 stores the time series at 1 minute resolution.
    • -
  • -part6HCA = TRUE to tell GGIR to perform Household -Co-Analysis.
    • -
  • -part6_threshold_combi = "30_100_400" where 30, 100 and -400 need to correspond to the accelerometer threshold combination that -is used in part 5 that you want to use in part 6. GGIR part 5 -facilitates multiple threshold combinations but in part 6 you need to -select one.
    • -
-

Other GGIR arguments can be set according to your own needs. For an -example:

-
datadir = "C:/projects/studyZ/binfiles"
-outputdir = "C:/projects/studyZ"
-library(GGIR)
-GGIR(mode = 1:5, 
-     datadir = datadir,
-     idloc = 2, 
-     outputdir = outputdir,
-     do.report = c(2, 4, 5),
-     do.parallel = TRUE,
-     overwrite = FALSE,
-     printsummary = TRUE,
-     desiredtz = "America/Halifax",
-     windowsizes = c(5, 60, 3600),
-     threshold.lig = 30,
-     threshold.mod = 100,
-     threshold.vig = 400,
-     part6_threshold_combi = "30_100_400",
-     boutcriter.in = 1, boutcriter.lig = 1,  boutcriter.mvpa = 0.9,
-     boutdur.in = 30,
-     boutdur.lig = 10,
-     boutdur.mvpa = 5,
-     part6HCA = TRUE,
-     save_ms5rawlevels = TRUE, # Not necessary because GGIR will set this to TRUE when part6HCA is TRUE.
-     save_ms5raw_without_invalid = FALSE, # <= Needed for household co-analysis
-     part5_agg2_60seconds = TRUE,
-     visualreport = FALSE) 
-
-
-
-

Household co-analysis -

-

In GGIR part 1, 2, 3, 4, and 5 each recording is processed -individually without considering relations between recordings. Next, -part 6 is subdivided in alligning the time series produced by part 1 and -5 per household, and the pairwise analysis of the data.

-
-

Align individuals -

-

Household members with only one member are ignored. Next, per -household and per household member the code loads and merges the time -series produced by GGIR part 1 and part 5. Days, defined from waking-up -to waking-up, are removed if they have less than 20% valid data during -waking hours, the sleep period time window, or the day as a whole. Next, -time series are completed with indicates of valid household member pairs -for each time points.

-

Finally, we store:

-
    -
  • The aligned time series per household in separate csv files in the -GGIR output directory -(.../results/part6HouseholdCoAnalysis/alignedTimeseries). -The columns for this file are documented further down.
    • -
  • A pdf file names timeseriesPlot.pdf with plots of the aligned time -series to facilitate visual inspection of the data completeness per -household.
    • -
-
-
-

Pairwise analysis -

-

Per household we identify all possible member pairs and loop over -these pairs.

-

Per member pair the code identify wake-up time pairs. Here, wake-up -times that occur within the last 15 minutes of the time series are -ignored as we need at least some recording time to quantify behaviour -after waking up.

-

Per wake-up pair we assess who woke up first and second, the time -difference, and the corresponding calendar dates of waking up.

-

Next, the code quantifies:

-
    -
  • Activity of person who first woke up during minute before second -person woke up
    • -
  • Activity of second person to wake up before they woke up
    • -
  • LUX of person who first woke up during tminute before second person -woke up
    • -
  • LUX of second person to wake up before they woke up.
    • -
-

Describe matching waking hours between pairs:

-
    -
  • Correlation between continuous acceleration values (ENMO -metric)
    • -
  • Derive binary class of inactivity/active (ENMO metric, and threshold -< 50)
    • -
  • ICC based on binary scores (irr package, model=twoway, -type=agreement, unit=single)
    • -
  • Cohen’s Kappa (psych package)
    • -
  • Similarity in binary scores (calculation in line with Sleep -Regularity Index)
    • -
-

Describe noon-noon window with a stronger focus on sleep:

-
    -
  • Describe binary class of sleep/wakefulness (note: does not attempt -to classify daytime naps)
    • -
  • ICC based on binary scores (irr package, model=twoway, -type=agreement, unit=single)
    • -
  • Cohen’s Kappa (psych package)
    • -
  • Similarity in binary scores (calculation in line with Sleep -Regularity Index)
    • -
-

Describe wakefulness dynamics during the SPT prior to wakeup:

-
    -
  • Look up indices of spt prior to wakeup where both individuals where -in SPT.
    • -
  • Assess fraction of data valid
    • -
  • Identify wake up times during the night
    • -
-

For each wake-up time:

-
    -
  • Assess whether both persons woke up at the same time, other person -wake up within 5 minutes, or other person does not wake up within 5 -minutes.
    • -
  • Store output to csv one row per unique household pair, with columns -to clarify who the household members are in the pair and from which -household they are.
    • -
-
-
-
-

Output variables -

-
-

alignedTimesieres -

-

In the GGIR output folder -.../results/part6HouseholdCoAnalysis/alignedTimeseries you -will find csv files with the time series per household.

-

The data dictionary below shows the column names you would get for a -household with two members: X and Y. Most of the columns are copied from -the time series output files, which are documented here. -Therefore, those column are not documented here.

- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Variable nameDescription
timenumTimestamp for tSeconds since since 1-1-1970
HIDHousehold ID
ACC.XAverage magnitude of acceleration for household member X
SleepPeriodTime.X-
invalidepoch.X-
guider.X-
window.X-
class_id.X-
lightmean.XMean light sensor value for member X
lightpeak.XPeak light sensor value for member X
temperaturemean.XMean temperature value for member X
onset.X1 to indicate sleep onset time for member X
wakeup.X1 to indicate waking up for member X
validepoch.X1 if epoch was valid
ACC.YAverage magnitude of acceleration for household member X
SleepPeriodTime.Y-
invalidepoch.Y-
guider.Y-
window.Y-
class_id.Y-
lightmean.YSee lightmean.X but now for member Y
lightpeak.YSee lightpeak.X but now for member Y
temperaturemean.Y-
onset.Y-
wakeup.Y-
validepoch.Y-
time_POSIXTimestamp in character format
N_valid_hhmembersNumber of valid household member pairs
validpair_X_YTRUE or FALSE to indicate whether the pair had valid data for this -timestamp
-
-
-

Pairwise summary report -

-

As stored inside pairwise_summary_all_housholds.csv

- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Variable nameDescription
HIDHousehold ID
NpairsNumber of unique pairs in a household
PIDPair ID
MID1Household member ID for the first person in the pair
MID2Household member ID for the second person in the pair
eventNumber to count the number of events, for now these are days with -valid wake-up estimates in both individuals
time1Time person 1 wakes up
time2Time person 2 wakes up
date1Date person 1 wakes up
date2Date person 2 wakes up
index_wake1Index in the time series when person 1 woke up (probably not -relevant for end-user)
index_wake2Index in the time series when person 2 woke up (probably not -relevant for end-user)
firstawakeWho of the two individuals woke up first? If equal then value will -be “equal”
wakeup_acc_wake1_before_wake2_mgMean acceleration (mg) of the person who wakes up first -during the four minutes before the second person wakes up
wakeup_acc_wake2_before_wake2_mgMean acceleration (mg) of second person to wake up before -they woke up
wakeup_lux_wake1_before_wake2Peak LUX of the person who wakes up first during the four minutes -before the second person wakes up
wakeup_lux_wake2_before_wake2Peak LUX of second person to wake up before they woke up
wakeup_deltatime_minDifference in wake up time in minutes
r_accelerationPearson correlation in continuous acceleration values
ICC_sleepICC (from R package irr) calculated based on binary scores of sleep -(excluding WASO)
ICC_sleep_FvalueFvalue for ICC_sleep
ICC_activeICC (from R package irr) calculated based on binary scores of -activity (metric ENMO < 50 chosen for now)
ICC_active_FvalueFavlue for ICC_active
frac_validFraction of pair epochs between individuals for a certain day that -were valid
SleepSimilarityIndexSimilarity in binary sleep/wake patterns between pairs per calendar -day
ActivitySimilarityIndexSimilarity in binary active/inactive patterns between pairs per -calendar day
Kappa_sleepWeighted Cohen’s Kappa coefficient calculated based on binary scores -of sleep (excluding WASO)
Kappa_sleep_CI_lowerLower confidence interval of Kappa_sleep
Kappa_sleep_CI_lupperUpper confidence interval of Kappa_sleep
Kappa_activeWeighted Cohen’s Kappa coefficient calculated based on binary scores -of activity (metric ENMO < 50 chosen for now)
Kappa_active_CI_lowerLower confidence interval of Kappa_active
Kappa_active_CI_upperUpper confidence interval of Kappa_active
-
-
-
-
- - - - -
- - - - - - - diff --git a/docs/articles/chapter12_TimeUseAnalyses.html b/docs/articles/chapter12_TimeUseAnalyses.html deleted file mode 100644 index b353b11e3..000000000 --- a/docs/articles/chapter12_TimeUseAnalyses.html +++ /dev/null @@ -1,499 +0,0 @@ - - - - - - - - -12. Time-use Analyses • GGIR - - - - - - - - - - - - - Skip to contents - - -
- - - - -
-
-

12. Time-use Analyses

- - - Source: vignettes/chapter12_TimeUseAnalyses.Rmd -
chapter12_TimeUseAnalyses.Rmd
-
- - - -

With the sleep classifications from GGIR part 4 as discussed in the -previous chapter it is now possible to segment the recording into waking -periods and sleeping periods. With this segmentation we can do a -time-use analysis for both periods. The main purpose of GGIR part 5 is -to facilitate this.

-
-

Creating a multi-variate time series object -

-

As a first step we need to map out what happens when during the -recording. Here, the GGIR code combines the information derived in parts -2, 3 and 4 into a multi-variate single time series object, -including:

-
    -
  • Timestamp
    • -
  • A log of when data was classified as invalid.
    • -
  • Average acceleration as derived in GGIR part 2, where invalid epochs -are imputed and only the acceleration metric is used as specified with -parameter acc.metric.
    • -
  • Sleep classifications from GGIR part 3 and 4. Behavioural class -code, which GGIR part 5 derives the behavioural classes based on the -magnitude of acceleration and sleep classification.
    • -
-

The exact number of behavioural classes as codified depends on how -parameters are set, but constructed and codified as:

-

During the sleep period time window: - Sleep - -Wakefulness with low acceleration - Wakefulness with moderate -acceleration - Wakefulness with vigorous acceleration

-

During the waking hours of the day: - Inactivity -unbouted - Inactivity bouted, subdivided into one or multiple bout -durations - Total inactivity time - LIPA unbouted - LIPA bouted, -subdivided into one or multiple bout durations - Total LIPA time - -Moderate activity unbouted - Vigorous activity unbouted - MVPA bouted, -subdivided into one or multiple bout durations - Total MVPA time

-

It is possible to export the time series generated, which will be -discussed towards the end of this chapter.

-
-
-

Defining the time windows -

-

In GGIR part 2 we defined days from midnight to midnight, and in GGIR -part 4 we typically defined nights from noon to noon. With the access to -sleep timing, GGIR part 5 offers additional definitions of a day. -However, given that our definitions of a day are becoming very different -from a calendar day, we refer to them as windows in the data.

-

GGIR part 5 facilitates the following time window definitions, which -can be selected with parameter timewindow:

- - ----- - - - - - - - - - - - - - - - - - - - - - - -
For “WW” and “OO”, the onset and waking times are guided by the -estimates from part 4, but if they are missing, part 5 will attempt to -retrieve the estimate from the guider method. Note that the parameter -timewindow can consist of one of the options -beforementioned or any combination of them, for example, the default -value is timewindow = c(“MM”, “WW”).
TimewindowMeaningDefinition
“MM”midnight to midnightEach day is defined as the 24 hours starting and ending a calendar -day (by default midnight, but modifiable with the parameter -dayborder).
“WW”waking up to waking upEach day is defined as the time from the participant wakes up a -given day to the time they wake up the next day.
“OO”sleep onset to sleep onsetEach day is defined as the time from the sleep onset a given day to -the sleep onset of the next day.
-
-

Defining segments within the MM window -

-

By default GGIR segments a window in waking hours of the day -(referred to as day) and the sleep period time window -(referred to as spt). Additionally, when timewindow is set -to “MM”, day segment specific analysis are performed based on the -segments as defined by parameters qwindow . Please see the -annex on day segmentation for more information.

-
-
-
-

Metrics calculated per window and per segment -

-

GGIR provides the following metrics over the time windows calculated, -i.e., full day, awake time, sleep period time, as well as (optionally) -the day segments that might have been provided via the parameter -qwindow.

-
    -
  • Duration: Time spent in minute per behavioural class.
    • -
  • Acceleration: Average acceleration per behavioural class
    • -
  • Number of blocks: Number of blocks per behavioural class, where a -distinction is made between bouted and unbouted, except for the total -number of blocks per intensity levels (Nblocks_day_total_IN, -Nblocks_day_total_LIPA, Nblocks_day_total_MOD, and -Nblocks_day_total_VIG).
    • -
  • Number of bouts: Number of bouts per behavioural class.
    • -
  • Fragmentation: The fragmentation metrics as discussed in the -previous chapter. Here no distinction is made between bouted or unbouted -behavour. Note that fragmentation classes sometimes group multiple -intensity levels, e.g. the fragmentation of physical activity reflects -the fragmentation of LIPA and MVPA combined relative to Inactive -time.
    • -
-
-

Complementary variables -

-

If your primary interest is on sleep research then we recommend you -to work with the GGIR part 4 reports. However, for those who want to -look at interactions between behaviour and sleep, GGIR part 5 reports -include sleep estimates as used for the part 5 analysis. Note that in -part 5 the criteria for sleep estimate inclusion are different than for -part 4. In part 5 we are happy with any estimate, even if the -accelerometer was not worn during the night.

-

Additionally, part 5 will also come with the duration of the awake -time, the sleep period time, the full-day windows, and percentage of -non-wear (read invalid data, which is typically non-wear).

-
-
-

Seemingly overlapping variables between GGIR part 2 and part 5 -output -

-

As it might be noticed, there are some variables that are reported in -both GGIR part 2 and part 5, such as the average acceleration and the -bouts of moderate-to-vigorous physical activity. However, please note -that their values are not necessarily identical for the following -reasons:

-
    -

  • Times when MVPA can happen . In part 2 MVPA can -happen at any time in the day, but never overlap with midnight. In part -5 MVPA only happens during the waking hours of a single day, but can -overlap with midnight if midnight is not part of the sleep period time -window. For those of you who use the dayborder parameter -with a value not equal to zero: midnight in this scenario is not -actually midnight but the time you set with parameter -dayborder, e.g. 2 equates to 2am. .

    • -

  • Difference in epoch length. GGIR part 5 comes -with the possibility to aggregate the epochs to 60 seconds with the -parameter part5_agg2_60seconds. If this parameter is set to -TRUE, then the full time series will be aggregated to 60 seconds, in -contrast to the default 5 second epoch length used in part 2.

    • -

  • Different time window definition. GGIR part 2 -always uses the “MM” definition of the days. In GGIR part 5, you have -the option to define the days in different ways (see above).

    • -
-
-
-

Exporting time series -

-

To export the time series set parameter -save_ms5rawlevels = TRUE. GGIR part 5 will then store them -in a subfolder of meta/ms5.outraw where each subfolder is -named after the unique MVPA threshold combination used.

-

The behavioral classes are included as numbers, the legend for these -classes numbers is stored as a separate legend file in the -meta/ms5.outraw folder named “behavioralcodes2020-04-26.csv” where the -date will correspond to the date you ran GGIR.

-

Note that the time series exported in GGIR part 5 only includes the -acceleration metric as specified with parameter acc.metric -(default = “ENMO”), and if angle metrics are selected, the angle -metrics. If you want to explore multiple acceleration metric values, -please see documentation for parameter epochvalues2csv as -discussed in chapter 3.

-

Additional input parameters that may be of -interest:

-
    -
  • -save_ms5raw_format is a character string to specify how -data should be stored: either “csv” (default) or “RData”. Only used if -save_ms5rawlevels=TRUE.
    • -
  • -save_ms5raw_without_invalid is Boolean to indicate -whether to remove invalid days from the time series output files. Only -used if save_ms5rawlevels=TRUE.
    • -
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Column nameDescription
timenumTime stamp in UTC time format (i.e., seconds since 1970-01-01). To -convert timenum to time stamp format, you need to specify your desired -time zone, e.g., -as.POSIXct(mdat$timenum, tz = "Europe/London").
ACCAverage acceleration metric selected by acc.metric, -default = “ENMO”.
SleepPeriodTimeIs 1 if SPT is detected, 0 if not. Note that this refers to the -combined usage of guider and detected sustained inactivity bouts (rest -periods).
invalidepochIs 1 if epoch was detect as invalid (e.g. non-wear), 0 if not.
guiderNumber to indicate what guider type was used, where 1=sleeplog, -2=HDCZA, 3=swetwindow, 4=L512, 5=HorAngle, 6=NotWorn
windowNumeric indicator of the analysis window in the recording. If -timewindow = “MM” then these correspond to calendar days, if timewindow -= “WW” then these correspond to which wakingup-wakingup window in the -recording, if timewindow = “OO” then these correspond to which -sleeponset-sleeponset window in the recording. So, in a recording of one -week you may find window numbers 1, 2, 3, 4, 5 and 6.
class_idThe behavioural class codes are documented in the exported csv file -meta/ms5outraw/behaviouralcodes.csv. Class codes above class 8 will be -analysis specific, because it depends on the number time variants of the -bouts used. For example, if you look at MVPA lasting 1-10, 10-20, 30-40 -then all of them will have their own class_id. In behaviouralcodes.csv -you will find a column with class_names which match the behavioural -classes as reported in the part 5 report.
invalid_fullwindowPercentage of the window (see above) that represents invalid data, -included to ease filtering the timeseries based on whether windows are -valid or not.
invalid_sleepperiodPercentage of SPT within the current window that represents invalid -data.
invalid_wakinghoursPercentage of waking hours within the current window that represents -invalid data.
timestampTime stamp derived from converting the column timenum, only -available if save_ms5raw_format = TRUE.
angleanglez by default. If sensor.location = "hip" or -HASPT.algo = "HorAngle" then angle represents the angle for -the longitudinal axis as provided by argument longitudinal_axis or -estimated if no angle was provided. If more angles were extracted in -part 1 then these will be add with their letter appended.
lightpeakIf lux sensor data is available in the data file then it was -summarised at an epoch length defined by the second value of parameter -windowsizes (defaults to 900 seconds = 15 minutes), to add -this value to the time series it is interpolated, so the original time -resolution is not necessarily reflected in this column.
temperatureIf temperature was available in the data file then it was summarised -at an epoch length defined by the second value of parameter -windowsizes (defaults to 900 seconds = 15 minutes), to add -this value to the time series it is interpolated, so the original time -resolution is not necessarily reflected in this column.
-
-
-
-

Key arguments -

-
    -
  • -threshold.lig, threshold.mod, -threshold.vig -
    • -
  • -boudur.in, boutdur.lig, -boutdur.mvpa -
    • -
  • -boutcriter.in, boutcriter.lig, -boutcriter.mvpa -
    • -
  • frag.metrics
    • -
  • timewindow
    • -
  • part5_agg2_60seconds
    • -
  • save_ms5rawlevels
    • -
  • save_ms5raw_format
    • -
  • save_ms5raw_without_invalid
    • -
-
-
- -

In https://cran.r-project.org/web/packages/GGIR/vignettes/GGIR.html#43_Output_part_5 -you will find a detailed discussion of the part 5 output. In summary, -part 5 produces the following files. - Day level summary - Person level -summary - Day level summary of behaviour per segment of a day - analysis -- Person level summary of behaviour per segment of a day - Variable -dictionary (see below) - Time series - Pdf reports with -vsiualisation

-
-

Variables dictionary -

-

Considering the different time window segmentation options, the -number of metrics calculated, and the different aggregation strategies -(i.e., plain averages, weighted averages, and -optionally- weekday and -weekend-day averages), the number of variables exported in Part 5 can be -high. To help you with the understanding and interpretation of the -variables, GGIR Part5 exports a variable dictionary for the daysummary -and personsummary csv reports. The dictionaries include a list of the -variable names calculated in your analyses together with the definition -of the variables.

-
-
-
-
- - - -
-

Developed by Vincent T van Hees, Jairo H Migueles, Medical Research Council UK, Accelting, French National Research Agency.

-
- -
-

Site built with pkgdown 2.0.9.

-
- -
-
- - - - - - - diff --git a/docs/articles/chapter12_TimeUseAnalysis.html b/docs/articles/chapter12_TimeUseAnalysis.html deleted file mode 100644 index 9046baf3e..000000000 --- a/docs/articles/chapter12_TimeUseAnalysis.html +++ /dev/null @@ -1,500 +0,0 @@ - - - - - - - - -12. Time-use Analysis • GGIR - - - - - - - - - - - - - Skip to contents - - -
- - - - -
-
-

12. Time-use Analysis

- - - Source: vignettes/chapter12_TimeUseAnalysis.Rmd -
chapter12_TimeUseAnalysis.Rmd
-
- - - -

With the sleep classifications from GGIR part 4 as discussed in the -previous chapter it is now possible to segment the recording into waking -periods and sleeping periods. With this segmentation we can do a -time-use analysis for both periods. The main purpose of GGIR part 5 is -to facilitate this.

-
-

Creating a multi-variate time series object -

-

As a first step we need to map out what happens when during the -recording. Here, the GGIR code combines the information derived in parts -2, 3 and 4 into a multi-variate single time series object, -including:

-
    -
  • Timestamp
    • -
  • A log of when data was classified as invalid.
    • -
  • Average acceleration as derived in GGIR part 2, where invalid epochs -are imputed and only the acceleration metric is used as specified with -parameter acc.metric.
    • -
  • Sleep classifications from GGIR part 3 and 4. Behavioural class -code, which GGIR part 5 derives the behavioural classes based on the -magnitude of acceleration and sleep classification.
    • -
-

The exact number of behavioural classes as codified depends on how -parameters are set, but constructed and codified as:

-

During the sleep period time window: - Sleep - -Wakefulness with low acceleration - Wakefulness with moderate -acceleration - Wakefulness with vigorous acceleration

-

During the waking hours of the day: - Inactivity -unbouted - Inactivity bouted, subdivided into one or multiple bout -durations - Total inactivity time - LIPA unbouted - LIPA bouted, -subdivided into one or multiple bout durations - Total LIPA time - -Moderate activity unbouted - Vigorous activity unbouted - MVPA bouted, -subdivided into one or multiple bout durations - Total MVPA time

-

It is possible to export the time series generated, which will be -discussed towards the end of this chapter.

-
-
-

Defining the time windows -

-

In GGIR part 2 we defined days from midnight to midnight, and in GGIR -part 4 we typically defined nights from noon to noon. With the access to -sleep timing, GGIR part 5 offers additional definitions of a day. -However, given that our definitions of a day are becoming very different -from a calendar day, we refer to them as windows in the data.

-

GGIR part 5 facilitates the following time window definitions, which -can be selected with parameter timewindow:

- - ----- - - - - - - - - - - - - - - - - - - - - - - -
For “WW” and “OO”, the onset and waking times are guided by the -estimates from part 4, but if they are missing, part 5 will attempt to -retrieve the estimate from the guider method. Note that the parameter -timewindow can consist of one of the options -beforementioned or any combination of them, for example, the default -value is timewindow = c(“MM”, “WW”).
TimewindowMeaningDefinition
“MM”midnight to midnightEach day is defined as the 24 hours starting and ending a calendar -day (by default midnight, but modifiable with the parameter -dayborder).
“WW”waking up to waking upEach day is defined as the time from the participant wakes up a -given day to the time they wake up the next day.
“OO”sleep onset to sleep onsetEach day is defined as the time from the sleep onset a given day to -the sleep onset of the next day.
-
-

Defining segments within the MM window -

-

By default GGIR segments a window in waking hours of the day -(referred to as day) and the sleep period time window -(referred to as spt). Additionally, when timewindow is set -to “MM”, day segment specific analysis are performed based on the -segments as defined by parameters qwindow . Please see the -annex on day segmentation for more information.

-
-
-
-

Metrics calculated per window and per segment -

-

GGIR provides the following metrics over the time windows calculated, -i.e., full day, awake time, sleep period time, as well as (optionally) -the day segments that might have been provided via the parameter -qwindow.

-
    -
  • Duration: Time spent in minute per behavioural class.
    • -
  • Acceleration: Average acceleration per behavioural class
    • -
  • Number of blocks: Number of blocks per behavioural class, where a -distinction is made between bouted and unbouted, except for the total -number of blocks per intensity levels (Nblocks_day_total_IN, -Nblocks_day_total_LIPA, Nblocks_day_total_MOD, and -Nblocks_day_total_VIG).
    • -
  • Number of bouts: Number of bouts per behavioural class.
    • -
  • Fragmentation: The fragmentation metrics as discussed in the -previous chapter. Here no distinction is made between bouted or unbouted -behavour. Note that fragmentation classes sometimes group multiple -intensity levels, e.g. the fragmentation of physical activity reflects -the fragmentation of LIPA and MVPA combined relative to Inactive -time.
    • -
-
-

Complementary variables -

-

If your primary interest is on sleep research then we recommend you -to work with the GGIR part 4 reports. However, for those who want to -look at interactions between behaviour and sleep, GGIR part 5 reports -include sleep estimates as used for the part 5 analysis. Note that in -part 5 the criteria for sleep estimate inclusion are different than for -part 4. In part 5 we are happy with any estimate, even if the -accelerometer was not worn during the night.

-

Additionally, part 5 will also come with the duration of the awake -time, the sleep period time, the full-day windows, and percentage of -non-wear (read invalid data, which is typically non-wear).

-
-
-

Seemingly overlapping variables between GGIR part 2 and part 5 -output -

-

As it might be noticed, there are some variables that are reported in -both GGIR part 2 and part 5, such as the average acceleration and the -bouts of moderate-to-vigorous physical activity. However, please note -that their values are not necessarily identical for the following -reasons:

-
    -

  • Times when MVPA can happen . In part 2 MVPA can -happen at any time in the day, but never overlap with midnight. In part -5 MVPA only happens during the waking hours of a single day, but can -overlap with midnight if midnight is not part of the sleep period time -window. For those of you who use the dayborder parameter -with a value not equal to zero: midnight in this scenario is not -actually midnight but the time you set with parameter -dayborder, e.g. 2 equates to 2am. .

    • -

  • Difference in epoch length. GGIR part 5 comes -with the possibility to aggregate the epochs to 60 seconds with the -parameter part5_agg2_60seconds. If this parameter is set to -TRUE, then the full time series will be aggregated to 60 seconds, in -contrast to the default 5 second epoch length used in part 2.

    • -

  • Different time window definition. GGIR part 2 -always uses the “MM” definition of the days. In GGIR part 5, you have -the option to define the days in different ways (see above).

    • -
-
-
-

Exporting time series -

-

To export the time series set parameter -save_ms5rawlevels = TRUE. GGIR part 5 will then store them -in a subfolder of meta/ms5.outraw where each subfolder is -named after the unique MVPA threshold combination used.

-

The behavioral classes are included as numbers, the legend for these -classes numbers is stored as a separate legend file in the -meta/ms5.outraw folder named “behavioralcodes2020-04-26.csv” where the -date will correspond to the date you ran GGIR.

-

Note that the time series exported in GGIR part 5 only includes the -acceleration metric as specified with parameter acc.metric -(default = “ENMO”), and if angle metrics are selected, the angle -metrics. If you want to explore multiple acceleration metric values, -please see documentation for parameter epochvalues2csv as -discussed in chapter 3.

-

Additional input parameters that may be of -interest:

-
    -
  • -save_ms5raw_format is a character string to specify how -data should be stored: either “csv” (default) or “RData”. Only used if -save_ms5rawlevels=TRUE.
    • -
  • -save_ms5raw_without_invalid is Boolean to indicate -whether to remove invalid days from the time series output files. Only -used if save_ms5rawlevels=TRUE.
    • -
- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Column nameDescription
timenumTime stamp in UTC time format (i.e., seconds since 1970-01-01). To -convert timenum to time stamp format, you need to specify your desired -time zone, e.g., -as.POSIXct(mdat$timenum, tz = "Europe/London").
ACCAverage acceleration metric selected by acc.metric, -default = “ENMO”.
SleepPeriodTimeIs 1 if SPT is detected, 0 if not. Note that this refers to the -combined usage of guider and detected sustained inactivity bouts (rest -periods).
invalidepochIs 1 if epoch was detect as invalid (e.g. non-wear), 0 if not.
guiderNumber to indicate what guider type was used, where 1=sleeplog, -2=HDCZA, 3=swetwindow, 4=L512, 5=HorAngle, 6=NotWorn
windowNumeric indicator of the analysis window in the recording. If -timewindow = “MM” then these correspond to calendar days, if timewindow -= “WW” then these correspond to which wakingup-wakingup window in the -recording, if timewindow = “OO” then these correspond to which -sleeponset-sleeponset window in the recording. So, in a recording of one -week you may find window numbers 1, 2, 3, 4, 5 and 6.
class_idThe behavioural class codes are documented in the exported csv file -meta/ms5outraw/behaviouralcodes.csv. Class codes above class 8 will be -analysis specific, because it depends on the number time variants of the -bouts used. For example, if you look at MVPA lasting 1-10, 10-20, 30-40 -then all of them will have their own class_id. In behaviouralcodes.csv -you will find a column with class_names which match the behavioural -classes as reported in the part 5 report.
invalid_fullwindowPercentage of the window (see above) that represents invalid data, -included to ease filtering the timeseries based on whether windows are -valid or not.
invalid_sleepperiodPercentage of SPT within the current window that represents invalid -data.
invalid_wakinghoursPercentage of waking hours within the current window that represents -invalid data.
timestampTime stamp derived from converting the column timenum, only -available if save_ms5raw_format = TRUE.
angleanglez by default. If sensor.location = "hip" or -HASPT.algo = "HorAngle" then angle represents the angle for -the longitudinal axis as provided by argument longitudinal_axis or -estimated if no angle was provided. If more angles were extracted in -part 1 then these will be add with their letter appended.
lightpeakIf lux sensor data is available in the data file then it was -summarised at an epoch length defined by the second value of parameter -windowsizes (defaults to 900 seconds = 15 minutes), to add -this value to the time series it is interpolated, so the original time -resolution is not necessarily reflected in this column.
temperatureIf temperature was available in the data file then it was summarised -at an epoch length defined by the second value of parameter -windowsizes (defaults to 900 seconds = 15 minutes), to add -this value to the time series it is interpolated, so the original time -resolution is not necessarily reflected in this column.
-
-
-
-

Key arguments -

-
    -
  • -threshold.lig, threshold.mod, -threshold.vig -
    • -
  • -boudur.in, boutdur.lig, -boutdur.mvpa -
    • -
  • -boutcriter.in, boutcriter.lig, -boutcriter.mvpa -
    • -
  • frag.metrics
    • -
  • timewindow
    • -
  • part5_agg2_60seconds
    • -
  • save_ms5rawlevels
    • -
  • save_ms5raw_format
    • -
  • save_ms5raw_without_invalid
    • -
-
-
- -

In https://cran.r-project.org/web/packages/GGIR/vignettes/GGIR.html#43_Output_part_5 -you will find a detailed discussion of the part 5 output. In summary, -part 5 produces the following files. - Day level summary - Person level -summary - Day level summary of behaviour per segment of a day - analysis -- Person level summary of behaviour per segment of a day - Variable -dictionary (see below) - Time series - Pdf reports with -vsiualisation

-
-

Variables dictionary -

-

Considering the different time window segmentation options, the -number of metrics calculated, and the different aggregation strategies -(i.e., plain averages, weighted averages, and -optionally- weekday and -weekend-day averages), the number of variables exported in Part 5 can be -high. To help you with the understanding and interpretation of the -variables, GGIR Part5 exports a variable dictionary for the daysummary -and personsummary csv reports. The dictionaries include a list of the -variable names calculated in your analyses together with the definition -of the variables.

-
-
-
-
- - - -
-

Developed by Vincent T van Hees, Jairo H Migueles, Medical Research Council UK, Accelting, French National Research Agency.

-
- -
-

Site built with pkgdown 2.0.9.

-
- -
-
- - - - - - - diff --git a/docs/articles/chapter6_DataImptutation.html b/docs/articles/chapter6_DataImptutation.html deleted file mode 100644 index 7271a72df..000000000 --- a/docs/articles/chapter6_DataImptutation.html +++ /dev/null @@ -1,274 +0,0 @@ - - - - - - - - -6. How GGIR Deals with Invalid Data • GGIR - - - - - - - - - - - - - Skip to contents - - -
- - - - -
-
-

6. How GGIR Deals with Invalid Data

- - - Source: vignettes/chapter6_DataImptutation.Rmd -
chapter6_DataImptutation.Rmd
-
- - - -
-

Imputation of invalid epoch data -

-

All time segments classified as non-wear or clipping (see Chapter 3) -and those masked by study protocol (see Chapter 5) are treated as -invalid data. In GGIR part 2, the epoch level metric values are imputed -while a log is kept of which epochs were imputed. For most of the -subsequent analysis done by GGIR the imputed time series is used, while -for a few analyses the time series without invalid segments are -used:

-
    -

  • Weighted average of full recording

    • -

  • Cosinor analysis (see Chapter 10)

    • -

  • Optionally, sleep analysis (see Chapter 8)

    • -
-

The imputation of epoch data works is done based on the mean metric -value corresponding to the valid values from the same time in the day on -other days in the recording. However, if the same time interval is -marked as invalid across all recorded days the value is imputed by zero, -except for metric EN which is imputed by 1.

-

For example, imagine a 5-day recording with the following ENMO metric -data for two specific epochs in the day across five days:

- - - - - - - - - - - - - - - - - - - - - - - - - - - -
TimeMonTueWedThuFri
8:59:55 – 9:00:00343invalid3
9:00:00 – 9:00:05invalidinvalidinvalidinvalidinvalid
-

The above would be imputed as shown below because the average of 3, -4, 3 and 3 is 3.25:

- - - - - - - - - - - - - - - - - - - - - - - - - - - -
TimeMonTueWedThuFri
8:59:55 – 9:00:003433.253
9:00:00 – 9:00:0500000
-
-
-

Controlling the imputation -

-

It is worth noting that you have the option to disable the imputation -by setting parameter do.imp = FALSE, which means that -values are kept as they are and not imputed or omitted. Disabling the -imputation is not recommended for most use-cases, but can be relevant -for studies in a controlled sleep or exercise laboratories where the -sensor is known to be worn throughout the experiment. .

-

Additionally, an alternative way to control the imputation is to -specify time segments in which the invalid epochs are to be imputed by -zeros (or ones for the metric EN) instead of following the standard GGIR -imputation method. To do this, you should use the parameter -TimeSegments2ZeroFile.

-
-
-

Key parameters -

-
    -
  • -do.imp,
    • -
  • TimeSegments2ZeroFile
    • -
-
-
- -
    -
  • In GGIR part 2, plots to check the data quality highlight the -segments of the file that were considered invalid and imputed. These -plots can be found in the folder “results/QC/”.
    • -
  • In GGIR part 5, time series are produced and optionally stored -within the folder “meta/ms5out.raw/” in either csv or RData format. -These time series contain an indicator of the epochs that were -considered invalid and imputed.
    • -
-
-
-
- - - - -
- - - - - - - diff --git a/docs/articles/chapter6_DataImputation.html b/docs/articles/chapter6_DataImputation.html deleted file mode 100644 index 1aa954352..000000000 --- a/docs/articles/chapter6_DataImputation.html +++ /dev/null @@ -1,276 +0,0 @@ - - - - - - - - -6. How GGIR Deals with Invalid Data • GGIR - - - - - - - - - - - - - Skip to contents - - -
- - - - -
-
-

6. How GGIR Deals with Invalid Data

- - - Source: vignettes/chapter6_DataImputation.Rmd -
chapter6_DataImputation.Rmd
-
- - - -
-

Imputation of invalid epoch data -

-

All time segments classified as non-wear or clipping (see Chapter 3) -and those masked by the study protocol (see Chapter 5) are treated as -invalid data. In GGIR part 2, the epoch level metric values are imputed, -while a log is kept of which epochs were imputed. For most of the -subsequent analysis done by GGIR, the imputed time series is used. The -time series without invalid segments are used only for a few -analyses:

-
    -

  • Weighted average of full recording

    • -

  • Cosinor analysis (see Chapter 10)

    • -

  • A very specific non-default configuration of sleep analysis (see -Chapter 8)

    • -
-

The imputation of epoch data is done based on the mean metric value -corresponding to the valid values from the same time in the day on other -days in the recording. However, if the same time interval is marked as -invalid across all recorded days, the value is imputed by zero, except -for metric EN which is imputed by 1.

-

For example, imagine a 5-day recording with the following ENMO metric -data for two specific epochs in the day across five days:

- - - - - - - - - - - - - - - - - - - - - - - - - - - -
TimeMonTueWedThuFri
8:59:55 – 9:00:00343invalid3
9:00:00 – 9:00:05invalidinvalidinvalidinvalidinvalid
-

The above would be imputed as shown below because the average of 3, -4, 3 and 3 is 3.25:

- - - - - - - - - - - - - - - - - - - - - - - - - - - -
TimeMonTueWedThuFri
8:59:55 – 9:00:003433.253
9:00:00 – 9:00:0500000
-
-
-

Controlling the imputation -

-

It is worth noting that you have the option to disable the imputation -by setting parameter do.imp = FALSE. This means that values -are kept as they are and not imputed or omitted. Disabling the -imputation is not recommended for most use-cases, but can be relevant -for studies in a controlled sleep or exercise laboratories where the -sensor is known to be worn throughout the experiment.

-

An alternative way to control the imputation is to specify time -segments in which the invalid epochs are to be imputed by zeros (or ones -for the metric EN) instead of following the standard GGIR imputation -method. To do this, you should use the parameter -TimeSegments2ZeroFile.

-
-
-

Key parameters -

-
    -
  • -do.imp,
    • -
  • TimeSegments2ZeroFile
    • -
-
-
- -
    -
  • In GGIR part 2, plots to check the data quality highlight the -segments of the file that were considered invalid and imputed. These -plots can be found in the folder “results/QC/”.
    • -
  • In GGIR part 5, time series are produced and optionally stored -within the folder “meta/ms5out.raw/” in either csv or RData format. -These time series contain an indicator of the epochs that were -considered invalid and imputed.
    • -
-
-
-
- - - -
-

Developed by Vincent T van Hees, Jairo H Migueles, Medical Research Council UK, Accelting, French National Research Agency.

-
- -
-

Site built with pkgdown 2.0.9.

-
- -
-
- - - - - - - diff --git a/docs/articles/chapter7_DescribingDataWithoutKnowingSleep.html b/docs/articles/chapter7_DescribingDataWithoutKnowingSleep.html deleted file mode 100644 index ada1f040e..000000000 --- a/docs/articles/chapter7_DescribingDataWithoutKnowingSleep.html +++ /dev/null @@ -1,388 +0,0 @@ - - - - - - - - -7. Describing the Data Without Knowing Sleep • GGIR - - - - - - - - - - - - - Skip to contents - - -
- - - - -
-
-

7. Describing the Data Without Knowing Sleep

- - - Source: vignettes/chapter7_DescribingDataWithoutKnowingSleep.Rmd -
chapter7_DescribingDataWithoutKnowingSleep.Rmd
-
- - - -

With the metric values imputed in the previous chapter, GGIR part 2 -offers a first descriptive analysis of the data. Although we will have -to wait till later GGIR parts (chapters) to see the segmentation of days -in waking and sleep hours, there is already enough that can be -quantified at this point. In this chapter we focus on descriptives of -the data that are informative even without the knowledge on when the -participant was sleeping or awake.

-
-

Data quality indicators -

-

GGIR part 2 summarises all the data quality checks done in the -previous four chapters, ranging from a report on the successfulness of -the auto-calibration procedure to the number of valid days. In this way, -GGIR part 2 is an ideal place to start for data quality assurance.

-
-
-

Basic descriptives -

-

Descriptive variables are calculated and reported for valid days -only, where the criteria for valid day is defined by parameter -includedaycrit.

-
-

Average acceleration -

-

Average acceleration is known to be correlated with the -activity-related energy expenditure. GGIR part 2 provide two types of -average acceleration:

-
    -

  • Average per day, only stored when the day was considered valid. -Note that this descriptive and most other descriptives are also stored -by GGIR as averages across all days, weekend days, or weekdays, which we -will discuss in more detail later on.

    • -

  • Weighted average of all valid data points in the recording, -weighted by timing in the day of all valid epochs, regardless of whether -they come from days that as a whole are classified as valid or -not.

    • -
-
-
-

Acceleration distribution -

-

To get a more detailed description of the data, looking at the -distribution of acceleration values can be informative. GGIR facilitates -this in two ways:

-
    -

  1. By specifying the quantiles of the distribution with parameter -qlevels, which are fed to the build-in R function -quantile, GGIR gives us the metric values corresponding to -such quantiles (a quantile multiplied by 100 is the same as a -percentile).

    2. -

  2. By describing the time spent in acceleration ranges, which are -defined by parameter ilevels .

    3. -
-

The distribution of acceleration values is often referred to as -intensity distribution in the physical activity literature.

-
-
-
-

Derived descriptives -

-
-

Sets of quantiles (MX metrics by Rowlands et -al.) -

-

The quantiles, as discussed above, can be used to describe the -accelerations that participants exceed in their most active “X” -accumulated minutes in a day. In the specific approach, as proposed by -Rowlands et al., -these quantiles are referred to as the MX metrics. The -MX metrics should not be confused with the most active continuous X -hours, e.g. M10, as used in circadian rhythm research that also can be -derived with GGIR (see parameter winhr).

-

To use the MX metrics as proposed by Rowlands et al., specify the -durations of the 24h day during which you want to identify the -accelerations values. For example, to generate the minimum acceleration -value for the most active accumulated 30 minutes, you can call -qlevels = (1410/1440). This parameter also accepts nested -terms to generate multiple MX metrics. For example, to call M60, M30, -and M10, you can specify the following:

-

qlevels = c(c(1380/1440), c(1410/1440), c(1430/1440)).

-

Note: If time segments shorter than 24 hours are specified in -parameter qwindow, such as the 8-hour school day (as -described in Fairclough et al -2020), the denominator in qlevels should change from -1440 (24h) to the specific segment length. In this example, we would use -480 (8h). Accordingly, the argument to call M60, M30, and M10 would -be:

-

qlevels = c(c(1380/1440), c(1410/1440), c(1430/1440)).

-

At the moment, this only works for one segment length and GGIR does -not facilitate the generation of MX metrics for multiple unequal time -segments within the same GGIR function call.

-

The output in the part 2 summary files will refer to this as a -percentile of the day. Thus, for a 24-h day, M30 will appear as -“p97.91666_ENMO_mg_0.24hr”. To create the radar plots of these MX -metrics as first described by Rowlands et al., -this GitHub -repository provides the R code and detailed instructions on how to -make the radar plots using your own data.

-
-
-

Intensity gradient -

-

If we plot the time spent in equally spaced acceleration ranges, we -would end up with an asymptotic-shaped curve, indicating little time -spent at high intensities (acceleration levels) and much time spent at -low intensities. The shape of the distribution may be informative but is -hard to quantify with a single number in its standard form. Therefore, a -new concept called the intensity gradient was proposed by Rowlands and -colleagues.

-

The intensity gradient defines the slope of the log-transformed axes -of this intensity distribution. More specifically, we calculate the time -accumulated in incremental acceleration bins (bin size = 25 mg) -but also keep track of the mid-point of each intensity bin, e.g. 62.5 -mg for the bin ranging from 50 to 75 mg. Both the -mid-point acceleration of a bin expressed in mg and the time -spent in a bin expressed in minutes are then log-transformed. The -log-transformation is expected to change the asymptotic-shaped curve -into a straight line. Subsequently, a linear regression is fitted -through these data points. The slope of this regression line represents -the intensity gradient. Further, we calculate the correlation -coefficient for the data points to help verify the degree to which they -form a straight line (R^2).

-

The intensity gradient is not calculated by default. To include this -metric in the part 2 output, set iglevels = TRUE.

-

Further, if you want to do more methodological research on this, you -can use this parameter to define alternative acceleration bins, e.g. for -using bins of 20 instead of 25 mg -iglevels = c(seq(0, 4000, by = 20), 8000).

-
-
-
-

Key arguments -

-
    -

  • includedaycrit

    • -

  • ilevels

    • -

  • qlevels

    • -

  • iglevels

    • -

  • qwindow

    • -

  • do.report

    • -
-
-
- -

GGIR part 2 generates three csv reports: part2_daysummary.csv, -part2_summary.csv, and data_quality_report.csv. As -data_quality_report.csv was discussed in chapter 3, we will focus only -on the first two reports in this chapter.

-

The variables in part2_summary.csv are the recording level aggregates -of the variables in part2_daysummary.csv. Here, variable names starting -with the “AD_” refer to average across all days, “WD” refers to the -average across weekdays, “WE” refers to the average across weekend days, -“WWE” refers to weighted weekend days to ensure both weekend days -contribute equally, “WWD” refers to weighted weekdays to ensure all -weekdays contribute equally.

-

Further, GGIR part 2 generates a report named -part2_daysummary_longformat.csv, which is generated when GGIR is used -for day segment analysis, see documentation for parameter -qwindow. This report contains the exact same information as -part2_daysummary.csv, but in long format instead of wide format. In -part2_daysummary_longformat.csv, each row represents one segment from -one day in one recording, while in part2_daysummary.csv, each row -contains one day in one recording and the segments of the day are -organised in different columns.

-
-

Descriptive variables -

- - ----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
To clarify that b refers to both part2_summary.csv -and part2_daysummary.csv, r refers to part2_summary.csv -only.
(Part of) variable nameDescriptionReport(s)
mean_ENMO_mg_0-24hraverage acceleration defined by metric ENMO for the full dayb
ENMO_fullRecordingMeanWeighted average over acceleration across recordingr
p20_ENMO_mg_0-24h20th percentile based on the full dayb
p20_ENMO_mg_0-24h_fullRecording20th percentile based on the weighted average day from the full -recordingr
[0,50)_ENMO_mg_0-24hrtime spent in minutes between 0 and 50 m_g_ acceleration defined by -metric ENMO for the full day. Square bracket means that the value itself -is included, round bracket indicated that value itself is not -includedb
ig_gradient_ENMO_0-24hrGradient for the intensity gradientb
ig_intercept_ENMO_0-24hrIntercept for the intensity gradientb
ig_rsquared_ENMO_0-24hrR-squared for the intensity gradientb
-
-
-
-
- - - -
-

Developed by Vincent T van Hees, Jairo H Migueles, Medical Research Council UK, Accelting, French National Research Agency.

-
- -
-

Site built with pkgdown 2.0.9.

-
- -
-
- - - - - - - diff --git a/docs/articles/chapter7_SleepAnalysis.html b/docs/articles/chapter7_SleepAnalysis.html deleted file mode 100644 index 72037a6fd..000000000 --- a/docs/articles/chapter7_SleepAnalysis.html +++ /dev/null @@ -1,189 +0,0 @@ - - - - - - - - -6. Sleep analysis • GGIR - - - - - - - - - - - - - Skip to contents - - -
- - - - -
-
-

6. Sleep analysis

- - - Source: vignettes/chapter7_SleepAnalysis.Rmd -
chapter7_SleepAnalysis.Rmd
-
- - - -

Work in progress…

-
-

Sustained Inactivity Bouts (SIB) -

-
-
-

Sleep Period Time (SPT) -

-
-
-

Sleep metrics available in GGIR -

-
-
-

Nap detection -

-
-
-

Working with sleeplog -

-
-
-

The cleaning code -

-
-
-

Key arguments -

-
-
- -
-
-
- - - - -
- - - - - - - diff --git a/docs/articles/chapter8_24hTimeUseAnalysis.html b/docs/articles/chapter8_24hTimeUseAnalysis.html deleted file mode 100644 index 61931de69..000000000 --- a/docs/articles/chapter8_24hTimeUseAnalysis.html +++ /dev/null @@ -1,173 +0,0 @@ - - - - - - - - -7. The 24-hour time use analysis • GGIR - - - - - - - - - - - - - Skip to contents - - -
- - - - -
-
-

7. The 24-hour time use analysis

- - - Source: vignettes/chapter8_24hTimeUseAnalysis.Rmd -
chapter8_24hTimeUseAnalysis.Rmd
-
- - - -

Work in progress…

-
-

Waking-to-waking or 24-hour time-use analysis -

-
-
-

Merging the sleep and physical activity information -

-
-
-

Key arguments -

-
-
- -
-
-
- - - -
-

Developed by Vincent T van Hees, Jairo H Migueles, Medical Research Council UK, Accelting, French National Research Agency.

-
- -
-

Site built with pkgdown 2.0.9.

-
- -
-
- - - - - - - diff --git a/docs/articles/chapter8_SleepFundamentalsSibs.html b/docs/articles/chapter8_SleepFundamentalsSibs.html deleted file mode 100644 index d3c925d4f..000000000 --- a/docs/articles/chapter8_SleepFundamentalsSibs.html +++ /dev/null @@ -1,288 +0,0 @@ - - - - - - - - -8. Sleep Fundamentals: Sustained Inactivity Bout Detection (SIB) • GGIR - - - - - - - - - - - - - Skip to contents - - -
- - - - -
-
-

8. Sleep Fundamentals: Sustained Inactivity Bout Detection (SIB)

- - - Source: vignettes/chapter8_SleepFundamentalsSibs.Rmd -
chapter8_SleepFundamentalsSibs.Rmd
-
- - - -

Sleep analysis in GGIR comes at three stages:

-
    -

  1. The discrimination of sustained inactivity and wakefulness -periods, discussed in this chapter.

    2. -

  2. Identification of time windows that guide the eventual sleep -detection, as discussed in the next chapter.

    3. -

  3. Assess overlap between the windows identified in step 1 and 2, -which we use to define the Sleep Period Time window (SPT) or the time in -bed window (TimeInBed) as discussed in chapter 10.

    4. -
-

The term “sleep” is somewhat controversial in the context of -accelerometry, because accelerometers can only capture lack of movement, -while sleep is not formally defined by a lack of movement. To -acknowledge this, GGIR refers to these classified ‘sleep’ periods as -sustained inactivity bouts abbreviated as SIB. However, -we use the term sleep in GGIR to denote the broader topic of describing -the main resting period in the day.

-

Most SIB detection algorithms are designed for wrist-worn data. No -evidence exists that they are informative for other wear locations. -However, if your main interest is in daytime behaviour and not in sleep, -you can still use them. In that case set parameter -relyonguider = TRUE in combination with any of the SIB -algorithms described below. GGIR will then rely on the guider (discussed -in next chapter) to define the Sleep Period Time window (this is, the -main episode of sleep in the day) and by that the waking hours of the -day. The sleep analysis based on the SIB detection may not be -informative though and best ignored.

-

GGIR offers the user the choice to identify SIB period with the -following algorithms:

-
-

SIB: vanHees2015 -

-

This algorithm looks for the periods of time where the z-angle does -not change by more than 5 degrees for at least 5 minutes. This algorithm -was proposed in a 2015 article. -The idea behind the algorithm is that it is a more interpretable -heuristic compared with the conventional approaches that use the -magnitude of acceleration to distinguish sustained inactivity bouts. -There is no reason to assume that vanHees2015 is a better -or worse reflection of sleep, the advancement is purely intended to be -in terms of interpretability. The vanHees2015 algorithm is -the default. The values 5 and 5 in the algorithm can be modified with -parameters anglethreshold and timethreshold, -but we currently see no basis to recommend doing this and advise -sticking to default values.

-
-
-

SIB: NotWorn (EXPERIMENTAL) -

-

Disclaimer: The status of this SIB algorithm is experimental -because it has not been described and evaluated in a peer-reviewed -publication yet. This means revisions to the algorithm can be expected -as the algorithm matures.

-

This algorithm was designed for rare study protocols where sensor is -not worn during the night. It should be obvious that this does not -facilitate any meaningful sleep analysis. Nonetheless for the rest of -GGIR to work we need some estimate of rest and NotWorn offers a -pragmatic work around. The algorithm works as follows: First we take the -1 hour rolling max of the activity signal (i.e., acceleration metric -defined with parameter acc.metric), after which we take -consider the 20th percentile as threshold to classify sustained -inactivity bouts.

-

This SIB is used by setting parameter -HASIB.algo = “NotWorn”

-
-
-

SIB: Count based algorithms (EXPERIMENTAL) -

-

Disclaimer: The status of this SIB algorithm is experimental -because it has not been described and evaluated in a peer-reviewed -publication yet. This means revisions to the algorithm can be expected -as the algorithm matures.

-

Accelerometers have been used for sleep research since the 1990s. -However, the initial accelerometers did not store their data in -gravitational units at sub-second level as we use nowadays but stored -their data in 30 or 60 second epoch aggregates. Although these -aggregates are referred to as counts by many manufacturers the -calculation of counts differs by manufacturer.

-

We have attempted to facilitate several sleep detection algorithms -from the literature in that period such as “Sadeh1994”, -“ColeKripke1992”, and “Galland2012”. A problem with all these algorithms -is that the preprocessing done to generate the counts is insufficiently -described in the literature. For the zero-crossing count as used by -Sadeh1994 and ColeKripke1992 an attempt has been made to collect as much -information as could be found and made an educated guess on the missing -information. The zero-crossing counts are discussed in the chapter 4 -about acceleration metrics.

-

When counts are calculated we can use the following SIB algorithms. -For all of these it is uncertain whether the Y-axis direction on modern -accelerometers matches the direction of the Y-axis in literature because -for old studies the direction of Y-axis was to our knowledge never -clarified.

-
-

Sadeh1994 -

-

The algorithm proposed by Sadeh et al. link. To use this set -parameter HASIB.algo = "Sadeh1994" and argument -Sadeh_axis = "Y" to indicate that the algorithm should use -the Y-axis of the sensor.

-
-
-

Galland2012 -

-

The algorithm proposed by Galland et al. link. To use -our implementation of the Galland2012 algorithm specify parameter -HASIB.algo = "Galland2012". Further, set -Sadeh_axis = "Y" to specify that the algorithm should use -the Y-axis.

-
-
-

ColeKripke1992 -

-

The algorithm proposed by Cole et al. link, more -specifically GGIR uses the algortihm proposed in the paper for 10-second -non-overlapping epochs with counts expressed average per minute. We skip -the re-scoring steps as the paper showed marginal added value of this -added complexity. To use the GGIR implementation of this algortihm, -specify parameters HASIB.algo = "ColeKripke1992" and -Sadeh_axis = "Y" to indicate that the algorithm should use -the Y-axis of the sensor.

-
-
-
-

Dealing with expected or detected nonwear time segments -

-

Depending on study protocol we may want to interpret invalid data -(typically non-wear) differently. When you set parameter -ignorenonwear=TRUE (default) it will ignore any non-wear -period for the SIB detection. This is useful to prevent nonwear episodes -before going to bed or after waking up from contributing to sleep.

-
-
-
- - - -
-

Developed by Vincent T van Hees, Jairo H Migueles, Medical Research Council UK, Accelting, French National Research Agency.

-
- -
-

Site built with pkgdown 2.0.9.

-
- -
-
- - - - - - - diff --git a/docs/articles/chapter9_PhysicalBehavioursAnalysis.html b/docs/articles/chapter9_PhysicalBehavioursAnalysis.html deleted file mode 100644 index 8349ba460..000000000 --- a/docs/articles/chapter9_PhysicalBehavioursAnalysis.html +++ /dev/null @@ -1,229 +0,0 @@ - - - - - - - - -8. Physical behaviours analysis • GGIR - - - - - - - - - - - - - Skip to contents - - -
- - - - -
-
-

8. Physical behaviours analysis

- - - Source: vignettes/chapter9_PhysicalBehavioursAnalysis.Rmd -
chapter9_PhysicalBehavioursAnalysis.Rmd
-
- - - -

Work in progress…

-
-

Acceleration distribution -

-
-

Percentiles or MX metrics (Rowlands) -

-
-
-

Intensity levels -

-
-
-

Intensity gradient -

-
-
-

Key arguments -

-
-
- -
-
-
-

Physical activity intensities (or inactivity) -

-
-

Quantification of physical activity and inactivity in GGIR -

-
-
-

Using cut-points -

-
-
-

Bouts of activity/inactivity -

-
-
-

Key arguments -

-
-
- -
-
-
-

Fragmentation metrics -

-
-

What is a fragment -

-
-
-

When and how are they calculated in GGIR -

-
-
-

Fragmentation metrics available -

-
-
-

Key arguments -

-
-
-
- -
-
-
- - - -
-

Developed by Vincent T van Hees, Jairo H Migueles, Medical Research Council UK, Accelting, French National Research Agency.

-
- -
-

Site built with pkgdown 2.0.9.

-
- -
-
- - - - - - - diff --git a/docs/articles/chapter9_SleepFundamentalsGuiders.html b/docs/articles/chapter9_SleepFundamentalsGuiders.html deleted file mode 100644 index 52d877512..000000000 --- a/docs/articles/chapter9_SleepFundamentalsGuiders.html +++ /dev/null @@ -1,506 +0,0 @@ - - - - - - - - -9. Sleep Fundamentals: Guiding sleep detection • GGIR - - - - - - - - - - - - - Skip to contents - - -
- - - - -
-
-

9. Sleep Fundamentals: Guiding sleep detection

- - - Source: vignettes/chapter9_SleepFundamentalsGuiders.Rmd -
chapter9_SleepFundamentalsGuiders.Rmd
-
- - - -

Sleep analysis in GGIR comes at three stages:

-
    -

  1. The discrimination of sleep and wakefulness periods, discussed in -the previous chapter.

    2. -

  2. Identification of time windows that guide the eventual sleep -detection, discussed in this chapter.

    3. -

  3. Assess overlap between the windows identified in step 1 and 2, -which we use to define the Sleep Period Time window (SPT) or the time in -bed window (TimeInBed) as discussed in chapter 10.

    4. -
-

A key challenge with sleep detection is to ignore day time rest -periods and short periods of not wearing the accelerometer that were -missed by the non-wear detection.

-

To ease this process GGIR starts by identifying the main time window -where sleep is likely. We will refer to the methods for defining the -window as guiders. The following guiders are -available:

-

If a sleep log is provided, GGIR uses by default guider sleep log, if -the sleep log is not available it falls back on the algorithm as -specified by parameter HASPT.algo, which allows tps ecify -any of the algorithms are discussed below (default HDCZA). If that -algorithm is not successful GGIR will falls back on a 12 hour window -centered around the least active consecutive 5 hours in the day. So, -when we refer to guider we refer to any of these methods.

-
-

Time window used for sleep analyses -

-

By default the sleep analysis only considers the window noon-noon, -which is not ideal for shift workers who may go to bed early in the day -and wake up after noon. To address this, GGIR changes the window of -analysis if this seems to be the case:

-

If the sleep log indicates that the person woke up after noon, the -sleep analysis in part 4 is done on the window from 6pm-6pm. Similarly, -if any other guider indicates that the person woke up after 11 am, the -sleep analysis in part 3 and 4 is done on the window 6pm-6pm.

-

In this way our method is sensitive to individuals who have their -main sleep period starting before noon and ending after noon, referred -as daysleepers in the output. This is for example the -case with shift workers. Note that guider L5+/-12 (discussed below) is -not able to do this, it will only consider the noon-noon time -window.

-
-
-

Guiders -

-
-

Guider: Sleeplog -

-

A sleep log (diary) as already used in some studies. The way GGIR -uses sleeplog was first described in a 2015 article. -Two sleeplog file structures are supported: the so-called basic and -advanced sleeplog.

-

To use this guider set the location of your sleeplog as value to -parameter loglocation.

-
-

Basic sleep log -

-

Example of a basic sleeplog:

- ----------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
IDonset_N1wakeup_N1onset_N2wakeup_N2onset_N3wakeup_N3onset_N4…
12322:00:0009:00:0021:00:0008:00:0023:45:0006:30:0000:00:00…
34521:55:0008:47:0023:45:0006:30:0000:00:00…
-
    -

  • One column for participant id, this does not have to be the first -column. Specify which column it is with argument -colid.

    • -

  • Alternatingly one column for onset time and one column for waking -time. Specify which column is the column for the first night by argument -coln1, in the above example coln1=2.

    • -

  • Timestamps are to be stored without date as in hh:mm:ss with hour -values ranging between 0 and 23 (not 24). If onset corresponds to lights -out or intention to fall asleep, then it specify -sleepwindowType = "TimeInBed".

    • -

  • There can be multiple sleeplogs in the same spreadsheet. Each row -representing a single recording.

    • -

  • First row: The first row of the spreadsheet needs to be filled -with column names. For the basic sleep log format it does not matter -what these column names are.

    • -

  • The first night in the basic sleeplog is assumed to correspond to -the first recorded night in the accelerometer recording. If you know -that sleep log start on a later day then make sure then add columns with -labels but without timestamps. Note that by recorded night we mean that -there is data regardless of whether the data is valid. So, if the -participant does not wear the accelerometer the first night then that is -still the first night in the recording.

    • -
-
-
-

Advanced sleep log -

-

Example of an advanced sleeplog for two recordings:

- ------------ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
IDD1_dateD1_wakeupD1_inbedD1_nap_startD1_nap_endD1_nonwear1_offD1_nonwear1_onD2_date…
1232015-03-3009:00:0022:00:0011:15:0011:45:0013:35:0014:10:0031/03/2015…
5672015-04-2008:30:0023:15:0021/04/2015…
-

Relative to the basic sleeplog format the advanced sleep log format -comes with the following changes:

-
    -

  • Recording are stored in rows, while all information per days are -stored in columns.

    • -

  • Information per day is preceded by one columns that holds the -calendar date. GGIR has been designed to recognise and handle any date -format but assumes that you have used the same date format consistently -through the sleeplog.

    • -

  • Per calendar date there is a column for wakeup time and followed -by a column for onset or in-bed time. Note that this is different from -the basic sleep log, where wakeup time follows the column for onset or -in-bed time. So, the advanced sleep log is calendar date oriented: -asking the participant when they woke up and when the fell asleep on a -certain date. However, if the sleep onset time is at 2am, you should -still fill in the 02:00:00, even though it is the 02:00:00 of the next -calendar date.

    • -

  • You can add columns relating to self-reported napping time and -nonwear time. These are not used for the sleep analysis in g.part3 and -g.part4, but used in g.part5 to facilitate napping analysis, see -argument do.sibreport and the paragraph on naps. Multiple -naps and multiple nonwear periods can be entered per day.

    • -

  • Leave cells for missing values blank.

    • -

  • Column names are critical for the advanced sleeplog format: Date -columns are recognised by GGIR as any column name with the word “date” -in it. The advanced sleep log format is recognised by GGIR by looking -out for the occurrence of at least two column names with the word “date” -in their name. Wakeup times are recognised with the words “wakeup” in -the column name. Sleeponset, to bed or in bed times are recognised as -the columns with any of the following character combinations in their -name: “onset”, “inbed”, “tobed”, or “lightsout”. Napping times are -recognised by columns with the word “nap” in their name. Nonwear times -are recognised by columns with the word “nonwear” in their -name.

    • -

  • GGIR guesses the data format by looping over common date formats. -If the date falls within 30 days of the start date of the accelerometer -recording then the date format is assumed to be found. It starts with -attempting “Y-m-d” (as in 2015-06-25).

    • -
-
-
-
-

Guider: HDCZA -

-

The HDCZA algorithm is designed for studies with wrist-worn -accelerometer (raw) data where no sleep log is available. The algorithm -was first described in a 2018 article, -and has been modified slightly: Step 6 in Figure 1 has been replaced by -a single threshold (0.2 by default).

-

In short, step 1-6 attempt to classify time periods with limited -change in posture. Next, step 7 extracts time blocks longer than 30 -minutes, step 8 includes intermittent time periods that shorter than 60 -minutes, step 9 looks for the longest resulting block in the day, which -then in step 10 represents the guider window.

-

Note that step 10 of Figure 1 in the paper gives the false impression -that the step represents the final classification of the SPT window. The -way the guider is used to identify the SPT window is described in -chapter 10.

-

The time segment over which HDCZA is derived is by default from noon -to noon. However, if it ends between 11am and noon then it will be -applied again but to a 6pm-6pm time segment.

-

To use this guider set parameter -HASPT.algo = “HorAngle”.

-
-
-

Guider: L5+/-12 (LEGACY ALGORITHM) -

-

Disclaimer: This legacy algorithm was used in publications -and therefore kept inside GGIR. As performance is expected to be less -than other available algorithm, we do not recommend using -it.

-

This guider reflects the twelve hour window centred around the least -active 5 hours of the day. It is a very crude approach and likely to be -inferior to some of the other guiders, but easy to describe. It was -first presented in a 2018 -article.

-

To use this guider set parameter -def.noc.sleep = “c()”.

-
-
-

Guider: setwindow (LEGACY ALGORITHM) -

-

Disclaimer: This legacy algorithm was used in publications -and therefore kept inside GGIR. As performance is expected to be less -than other available algorithm, we do not recommend using -it.

-

This guider uses a set window for each day in the recording. Start -and end time are specified with argument def.noc.sleep. For -example, to use this guider with a window from 10pm to 8am set parameter -def.noc.sleep = “c(22, 8)”.

-
-
-

Guider: HorAngle (EXPERIMENTAL) -

-

Disclaimer: The status of this guider is experimental because -it has not been described and evaluated in a peer-reviewed publication -yet. This means revisions to the algorithm can be expected as the -algorithm matures.

-

This guider is designed for hip-worn accelerometer (raw) data, by -looking for the longest period with a horizontal trunk. To do this it -needs GGIR part 1 and 2 to have derived the angle for the longitudinal -axis.

-

Setting parameter sensor.location="hip" triggers the -identification of the longitudinal axis by looking for the angle with -the strongest 24-hour lagged correlation.

-

You can also force GGIR to use a specific axis as longitudinal axis -with parameter longitudinal_axis.

-

Next, the algorithm identifies when the horizontal axis is between --45 and 45 degrees and considers this a horizontal posture. Next, this -is used to identify the largest time in bed period, by only considering -horizontal time segments of at least 30 minutes, and then looking for -longest horizontal period in the day where gaps of less than 60 minutes -are ignored. Therefore, the last 4 steps in the algorithm are identical -to the last four steps in the HDCZA algorithm.

-

To use this guider set parameter -HASPT.algo = “HorAngle”

-
-
-

Guider: NotWorn (EXPERIMENTAL) -

-

Disclaimer: The status of this guider is experimental because -it has not been described and evaluated in a peer-reviewed publication -yet. This means revisions to the algorithm can be expected as the -algorithm matures.

-

This guider is primarily designed for externally derived epoch data -expressed in movement counts and used for studies where the instruction -was not to wear the accelerometer during the night. GGIR then searches -for the longest period with near-zero movement.

-

It does this by using the 5 minute rolling average of the -acceleration metric values and applying a threshold that is 20% of the -standard deviation in the resulting signal.

-

However, if this threshold is less than the minimum value in the -signal the threshold is set equal to the 10th percentile in the -distribution.

-

Next, this is used to identify the largest non-movement period, by -only considering segments of at least 30 minutes, and then looking for -longest segment in the day where gaps of less than 60 minutes are -ignored. Therefore, the last 4 steps in the algorithm are identical to -the last four steps in the HDCZA and HorAngle algorithms.

-

To use this guider set parameter -HASPT.algo = “NotWorn”

-
-
-
-

Dealing with expected or detect nonwear time segments -

-

Depending on study protocol we may want to interpret invalid data -(typically non-wear) differently:

-
    -

  1. If we want to rely on the available time series where invalid -time segments were imputed then leave parameter -HASPT.ignore.invalid = FALSE as default.

    2. -

  2. If we want to guider to ignore all invalid segment despite our -efforts to impute it, see HASPT.ignore.invalid = TRUE. This -approach may be helpful for studies where the accelerometer is often not -worn during the waking hour of the day.

    3. -

  3. If we want the guider to consider invalid segments as no movement -period set parameter HASPT.ignore.invalid = NA. This -approach may be helpful for studies where the accelerometer is often not -worn during the night.

    4. -
-
-
-
- - - -
-

Developed by Vincent T van Hees, Jairo H Migueles, Medical Research Council UK, Accelting, French National Research Agency.

-
- -
-

Site built with pkgdown 2.0.9.

-
- -
-
- - - - - - - diff --git a/docs/articles/chapter9_SleepFundamentalsSpt.html b/docs/articles/chapter9_SleepFundamentalsSpt.html deleted file mode 100644 index 3352037e0..000000000 --- a/docs/articles/chapter9_SleepFundamentalsSpt.html +++ /dev/null @@ -1,505 +0,0 @@ - - - - - - - - -9. Sleep Fundamentals: Guiding sleep detection • GGIR - - - - - - - - - - - - - Skip to contents - - -
- - - - -
-
-

9. Sleep Fundamentals: Guiding sleep detection

- - - Source: vignettes/chapter9_SleepFundamentalsSpt.Rmd -
chapter9_SleepFundamentalsSpt.Rmd
-
- - - -

Sleep analysis in GGIR comes at three stages:

-
    -

  1. The discrimination of sleep and wakefulness periods, discussed in -the previous chapter.

    2. -

  2. Identification of time windows that guide the eventual sleep -detection, discussed in this chapter.

    3. -

  3. Assess overlap between the windows identified in step 1 and 2, -which we use to define the Sleep Period Time window (SPT) or the time in -bed window (TimeInBed) as discussed in chapter 10.

    4. -
-

A key challenge with sleep detection is to ignore day time rest -periods and short periods of not wearing the accelerometer that were -missed by the non-wear detection.

-

To ease this process GGIR starts by identifying the main time window -where sleep is likely. We will refer to the methods for defining the -window as guiders. The following guiders are -available:

-

If a sleep log is provided, GGIR uses by default guider sleep log, if -the sleep log is not available it falls back on the algorithm as -specified by parameter HASPT.algo, which allows tps ecify -any of the algorithms are discussed below (default HDCZA). If that -algorithm is not successful GGIR will falls back on a 12 hour window -centered around the least active consecutive 5 hours in the day. So, -when we refer to guider we refer to any of these methods.

-
-

Time window used for sleep analyses -

-

By default the sleep analysis only considers the window noon-noon, -which is not ideal for shift workers who may go to bed early in the day -and wake up after noon. To address this, GGIR changes the window of -analysis if this seems to be the case:

-

If the sleep log indicates that the person woke up after noon, the -sleep analysis in part 4 is done on the window from 6pm-6pm. Similarly, -if any other guider indicates that the person woke up after 11 am, the -sleep analysis in part 3 and 4 is done on the window 6pm-6pm.

-

In this way our method is sensitive to individuals who have their -main sleep period starting before noon and ending after noon, referred -as daysleepers in the output. This is for example the -case with shift workers. Note that guider L5+/-12 (discussed below) is -not able to do this, it will only consider the noon-noon time -window.

-
-
-

Guiders -

-
-

Guider: Sleeplog -

-

A sleep log (diary) as already used in some studies. The way GGIR -uses sleeplog was first described in a 2015 article. -Two sleeplog file structures are supported: the so-called basic and -advanced sleeplog.

-

To use this guider set the location of your sleeplog as value to -parameter loglocation.

-
-

Basic sleep log -

-

Example of a basic sleeplog:

- ----------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
IDonset_N1wakeup_N1onset_N2wakeup_N2onset_N3wakeup_N3onset_N4…
12322:00:0009:00:0021:00:0008:00:0023:45:0006:30:0000:00:00…
34521:55:0008:47:0023:45:0006:30:0000:00:00…
-
    -

  • One column for participant id, this does not have to be the first -column. Specify which column it is with argument -colid.

    • -

  • Alternatingly one column for onset time and one column for waking -time. Specify which column is the column for the first night by argument -coln1, in the above example coln1=2.

    • -

  • Timestamps are to be stored without date as in hh:mm:ss with hour -values ranging between 0 and 23 (not 24). If onset corresponds to lights -out or intention to fall asleep, then it specify -sleepwindowType = "TimeInBed".

    • -

  • There can be multiple sleeplogs in the same spreadsheet. Each row -representing a single recording.

    • -

  • First row: The first row of the spreadsheet needs to be filled -with column names. For the basic sleep log format it does not matter -what these column names are.

    • -

  • The first night in the basic sleeplog is assumed to correspond to -the first recorded night in the accelerometer recording. If you know -that sleep log start on a later day then make sure then add columns with -labels but without timestamps. Note that by recorded night we mean that -there is data regardless of whether the data is valid. So, if the -participant does not wear the accelerometer the first night then that is -still the first night in the recording.

    • -
-
-
-

Advanced sleep log -

-

Example of an advanced sleeplog for two recordings:

- ------------ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
IDD1_dateD1_wakeupD1_inbedD1_nap_startD1_nap_endD1_nonwear1_offD1_nonwear1_onD2_date…
1232015-03-3009:00:0022:00:0011:15:0011:45:0013:35:0014:10:0031/03/2015…
5672015-04-2008:30:0023:15:0021/04/2015…
-

Relative to the basic sleeplog format the advanced sleep log format -comes with the following changes:

-
    -

  • Recording are stored in rows, while all information per days are -stored in columns.

    • -

  • Information per day is preceded by one columns that holds the -calendar date. GGIR has been designed to recognise and handle any date -format but assumes that you have used the same date format consistently -through the sleeplog.

    • -

  • Per calendar date there is a column for wakeup time and followed -by a column for onset or in-bed time. Note that this is different from -the basic sleep log, where wakeup time follows the column for onset or -in-bed time. So, the advanced sleep log is calendar date oriented: -asking the participant when they woke up and when the fell asleep on a -certain date. However, if the sleep onset time is at 2am, you should -still fill in the 02:00:00, even though it is the 02:00:00 of the next -calendar date.

    • -

  • You can add columns relating to self-reported napping time and -nonwear time. These are not used for the sleep analysis in g.part3 and -g.part4, but used in g.part5 to facilitate napping analysis, see -argument do.sibreport and the paragraph on naps. Multiple -naps and multiple nonwear periods can be entered per day.

    • -

  • Leave cells for missing values blank.

    • -

  • Column names are critical for the advanced sleeplog format: Date -columns are recognised by GGIR as any column name with the word “date” -in it. The advanced sleep log format is recognised by GGIR by looking -out for the occurrence of at least two column names with the word “date” -in their name. Wakeup times are recognised with the words “wakeup” in -the column name. Sleeponset, to bed or in bed times are recognised as -the columns with any of the following character combinations in their -name: “onset”, “inbed”, “tobed”, or “lightsout”. Napping times are -recognised by columns with the word “nap” in their name. Nonwear times -are recognised by columns with the word “nonwear” in their -name.

    • -

  • GGIR guesses the data format by looping over common date formats. -If the date falls within 30 days of the start date of the accelerometer -recording then the date format is assumed to be found. It starts with -attempting “Y-m-d” (as in 2015-06-25).

    • -
-
-
-
-

Guider: HDCZA -

-

The HDCZA algorithm is designed for studies with wrist-worn -accelerometer (raw) data where no sleep log is available. The algorithm -was first described in a 2018 article, -and has been modified slightly: Step 6 in Figure 1 has been replaced by -a single threshold (0.2 by default).

-

In short, step 1-6 attempt to classify time periods with limited -change in posture. Next, step 7 extracts time blocks longer than 30 -minutes, step 8 includes intermittent time periods that shorter than 60 -minutes, step 9 looks for the longest resulting block in the day, which -then in step 10 represents the guider window.

-

Note that step 10 of Figure 1 in the paper gives the false impression -that the step represents the final classification of the SPT window. The -way the guider is used to identify the SPT window is described in -chapter 10.

-

The time segment over which HDCZA is derived is by default from noon -to noon. However, if it ends between 11am and noon then it will be -applied again but to a 6pm-6pm time segment.

-

To use this guider set parameter -HASPT.algo = “HorAngle”.

-
-
-

Guider: L5+/-12 (LEGACY ALGORITHM) -

-

Disclaimer: This legacy algorithm was used in publications -and therefore kept inside GGIR. As performance is expected to be less -than other available algorithm, we do not recommend using -it.

-

This guider reflects the twelve hour window centred around the least -active 5 hours of the day. It is a very crude approach and likely to be -inferior to some of the other guiders, but easy to describe. It was -first presented in a 2018 -article.

-

To use this guider set parameter -def.noc.sleep = “c()”.

-
-
-

Guider: setwindow (LEGACY ALGORITHM) -

-

Disclaimer: This legacy algorithm was used in publications -and therefore kept inside GGIR. As performance is expected to be less -than other available algorithm, we do not recommend using -it.

-

This guider uses a set window for each day in the recording. Start -and end time are specified with argument def.noc.sleep. For -example, to use this guider with a window from 10pm to 8am set parameter -def.noc.sleep = “c(22, 8)”.

-
-
-

Guider: HorAngle (EXPERIMENTAL) -

-

Disclaimer: The status of this guider is experimental because -it has not been described and evaluated in a peer-reviewed publication -yet. This means revisions to the algorithm can be expected as the -algorithm matures.

-

This guider is designed for hip-worn accelerometer (raw) data, by -looking for the longest period with a horizontal trunk. To do this it -needs GGIR part 1 and 2 to have derived the angle for the longitudinal -axis.

-

Setting parameter sensor.location="hip" triggers the -identification of the longitudinal axis by looking for the angle with -the strongest 24-hour lagged correlation.

-

You can also force GGIR to use a specific axis as longitudinal axis -with parameter longitudinal_axis.

-

Next, the algorithm identifies when the horizontal axis is between --45 and 45 degrees and considers this a horizontal posture. Next, this -is used to identify the largest time in bed period, by only considering -horizontal time segments of at least 30 minutes, and then looking for -longest horizontal period in the day where gaps of less than 60 minutes -are ignored. Therefore, the last 4 steps in the algorithm are identical -to the last four steps in the HDCZA algorithm.

-

To use this guider set parameter -HASPT.algo = “HorAngle”

-
-
-

Guider: NotWorn (EXPERIMENTAL) -

-

Disclaimer: The status of this guider is experimental because -it has not been described and evaluated in a peer-reviewed publication -yet. This means revisions to the algorithm can be expected as the -algorithm matures.

-

This guider is primarily designed for externally derived epoch data -expressed in movement counts and used for studies where the instruction -was not to wear the accelerometer during the night. GGIR then searches -for the longest period with near-zero movement.

-

It does this by using the 5 minute rolling average of the -acceleration metric values and applying a threshold that is 20% of the -standard deviation in the resulting signal.

-

However, if this threshold is less than the minimum value in the -signal the threshold is set equal to the 10th percentile in the -distribution.

-

Next, this is used to identify the largest non-movement period, by -only considering segments of at least 30 minutes, and then looking for -longest segment in the day where gaps of less than 60 minutes are -ignored. Therefore, the last 4 steps in the algorithm are identical to -the last four steps in the HDCZA and HorAngle algorithms.

-

To use this guider set parameter -HASPT.algo = “NotWorn”

-
-
-
-

Dealing with expected or detect nonwear time segments -

-

Depending on study protocol we may want to interpret invalid data -(typically non-wear) differently:

-
    -

  1. If we want to rely on the available time series where invalid -time segments were imputed then leave parameter -HASPT.ignore.invalid = FALSE as default.

    2. -

  2. If we want to guider to ignore all invalid segment despite our -efforts to impute it, see HASPT.ignore.invalid = TRUE. This -approach may be helpful for studies where the accelerometer is often not -worn during the waking hour of the day.

    3. -

  3. If we want the guider to consider invalid segments as no movement -period set parameter HASPT.ignore.invalid = NA. This -approach may be helpful for studies where the accelerometer is often not -worn during the night.

    4. -
-
-
-
- - - -
-

Developed by Vincent T van Hees, Jairo H Migueles, Medical Research Council UK, Accelting, French National Research Agency.

-
- -
-

Site built with pkgdown 2.0.9.

-
- -
-
- - - - - - - diff --git a/docs/articles/copy-of-GGIR.html b/docs/articles/copy-of-GGIR.html deleted file mode 100644 index 1e2bde126..000000000 --- a/docs/articles/copy-of-GGIR.html +++ /dev/null @@ -1,3528 +0,0 @@ - - - - - - - - -Accelerometer data processing with GGIR • GGIR - - - - - - - - - - - - - Skip to contents - - -
- - - - -
-
-

Accelerometer data processing with GGIR

- - - Source: vignettes/copy-of-GGIR.Rmd -
copy-of-GGIR.Rmd
-
- - - -

-

You are now in the main GGIR vignette. See also the complementary -vignettes on: Cut-points, -Day -segment analyses, GGIR -parameters, Embedding -external functions (pdf), and Reading -ad-hoc csv file formats.

-
-

Introduction -

-
-

What is GGIR? -

-

GGIR is an -R-package to process multi-day raw accelerometer data for physical -activity and sleep research. The term raw -refers to data being expressed in m/s2 or gravitational -acceleration as opposed to the previous generation accelerometers which -stored data in accelerometer brand specific units. The signal processing -includes automatic calibration, detection of sustained abnormally high -values, detection of non-wear and calculation of average magnitude of -dynamic acceleration based on a variety of metrics. Next, GGIR uses this -information to describe the data per recording, per day of measurement, -and (optionally) per segment of a day of measurement, including -estimates of physical activity, inactivity and sleep. We published an -overview paper of GGIR in 2019 link.

-

This vignette provides a general introduction on how to use GGIR and -interpret the output, additionally you can find a introduction video and a mini-tutorial on YouTube. If you -want to use your own algorithms for raw data then GGIR facilitates this -with it’s external function embedding feature, documented in a separate -vignette: Embedding -external functions in GGIR. GGIR is increasingly being used by -research groups across the world. A non-exhaustive overview of academic -publications related to GGIR can be found here. R -package GGIR would not have been possible without the support of the -contributors listed in the author list at GGIR, with specific -code contributions over time since April 2016 (when GGIR development -moved to GitHub) shown here.

-

Cite GGIR:

-

When you use GGIR in publications do not forget to cite it properly -as that makes your research more reproducible and it gives credit to -it’s developers. See paragraph on Citing GGIR -for details.

-
-
-

Contributing, Support, and Keeping up to date -

-

How to contribute to the code?

-

The development version of GGIR can be found on github, which is also where -you will find guidance -on how to contribute.

-

How can I get service and support?

-

GGIR is open source software and does not come with service or -support guarantees. However, as user-community you can help each other -via the GGIR google -group or the GitHub -issue tracker. Please use these public platform rather than private -e-mails such that other users can learn from the conversations.

-

If you need dedicated support with the use of GGIR or need someone to -adapt GGIR to your needs then Vincent van Hees is available as independent consultant.

-

Training in R essentials and GGIR We offer frequent -online GGIR training courses. Check our dedicated training website with more -details and the option to book your training. Do you have questions -about the training or the booking process? Do not hesitate to contact us -via: .

-

Also of interest may be the brief free R -introduction tutorial.

-

Change log

-

Our log of main changes to GGIR over time can be found here.

-
-
-
-

Setting up your work environment -

-
-

Install R and RStudio -

-

Download and install R

-

Download and -install RStudio

-

Install GGIR with its dependencies from CRAN. You can do this with -one command from the console command line:

-
-install.packages("GGIR", dependencies = TRUE)
-

Alternatively, to install the latest development version with the -latest bug fixes use instead:

-
-install.packages("remotes")
-remotes::install_github("wadpac/GGIR")
-

Additionally, in some use-cases you will need to install one or -multiple additional packages:

-
    -
  • If you are working with Axivity, GENEActiv, or GENEA files, install -the GGIRread package with install.packages("GGIRread") -
    • -
  • If you are working with ActiGraph gt3x files, install the read.gt3x -package with install.packages("read.gt3x") -
    • -
  • If you want to derive Neishabouricounts (with -do.neishabouricounts = TRUE), install the actilifecounts -package with install.packages("actilifecounts") -
    • -
  • If you want to derive circadian rhythm indicators using the Cosinor analysis -and Extended Cosinor analysis (with cosinor = TRUE), -install the ActCR package with -install.packages("ActCR") -
    • -
-
-
-

Prepare folder structure -

-
    -
  1. GGIR works with the following accelerometer brands and formats: -
      -
    • -GENEActiv .bin
      • -
    • -Axivity AX3 and AX6 .cwa
      • -
    • -ActiGraph .csv and .gt3x -(.gt3x only the newer format generated with firmware versions above -2.5.0. Serial numbers that start with “NEO” or “MRA” and have firmware -version of 2.5.0 or earlier use an older format of the .gt3x file). Note -for Actigraph users: If you want to work with .csv exports via the -commercial ActiLife software then note that you have the option to -export data with timestamps. Please do not do this as this causes memory -issues for GGIR. To cope with the absence of timestamps GGIR will -calculate timestamps from the sample frequency, the start time and start -date as presented in the file header.
      • -
    • -Movisens with data stored -in folders.
      • -
    • Any other accelerometer brand that generates csv output, see -documentation for functions read.myacc.csv and argument -rmc.noise in the GGIR function -documentation (pdf). Note that functionality for the following file -formats was part of GGIR but has been deprecated as it required a -significant maintenance effort without a clear use case or community -support: (1) .bin for the Genea monitor by Unilever Discover, an -accelerometer that was used for some studies between 2007 and 2012) -.bin, and (2) .wav files as can be exported by the Axivity Ltd OMGUI -software. Please contact us if you think these data formats should be -facilitated by GGIR again and if you are interested in supporting their -ongoing maintenance.
      • -
    -
    2. -
  2. All accelerometer data that needs to be analysed should be stored in -one folder, or subfolders of that folder.
    3. -
  3. Give the folder an appropriate name, preferable with a reference to -the study or project it is related to rather than just ‘data’, because -the name of this folder will be used later on as an identifier of the -dataset.
    4. -
-
-
-

GGIR shell function -

-

GGIR comes with a large number of functions and optional settings -(arguments) per functions.

-

To ease interacting with GGIR there is one central function, named -GGIR, to talk to all the other functions. In the past this -function was called g.shell.GGIR, but we decided to shorten -it to GGIR for convenience. You can still use -g.shell.GGIR because g.shell.GGIR has become a -wrapper function around GGIR passing on all arguments to -GGIR and by that providing identical functionality.

-

In this paragraph we will guide you through the main arguments to -GGIR relevant for 99% of research. First of all, it is -important to understand that the GGIR package is structured in two -ways.

-

Firstly, it has a computational structure of five parts which are -applied sequentially to the data, and that GGIR controls -each of these parts:

-
    -
  • Part 1: Loads the data and stores derived features (aggregations) -needed for the other parts. This is the time-consuming part. Once this -is done, parts 2-5 can be run (or re-run with different parameters in -parts 2-5) relatively quickly.
    • -
  • Part 2: Data quality analyses and low-level description of signal -features per day and per file. At this point a day is defined from -midnight to midnight
    • -
  • Part 3: Estimation of sustained inactivity and sleep periods, needed -for input to Part 4 for sleep detection
    • -
  • Part 4: Labels the sustained inactive periods detected in Part 3 as -sleep, or daytime sustained inactivity, per night and per file
    • -
  • Part 5: Derives sleep and physical activity characteristics by -re-using information derived in part 2, 3 and 4. Total time in intensity -categories, the number of bouts, time spent in bouts and average -acceleration (overall activity) is calculated.
    • -
-

The reason why it split up in parts is that it avoids having the -re-do all analysis if you only want to make a small change in the more -downstream parts. The specific order and content of the parts has grown -for historical and computational reasons.

-

Secondly, the function arguments which we will refer to as input -parameters are structured thematically independently of the five parts -they are used in:

-
    -
  • params_rawdata: parameters related to handling the raw data such as -resampling or calibrating
    • -
  • params_metrics: parameters related to aggregating the raw data to -epoch level summary metrics
    • -
  • params_sleep: parameters related to sleep detection
    • -
  • params_physact: parameters related to physical activity
    • -
  • params_247: parameters related to 24/7 behaviours that do not fall -into the typical sleep or physical activity research category.
    • -
  • params_output: parameters relating to how and whether output is -stored.
    • -
  • params_general: general parameters not covered by any of the above -categories
    • -
-

This structure was introduced in GGIR version 2.5-6 to make the GGIR -code and documentation easier to navigate.

-

To see the parameters in each parameter category and their default -values do:

- -

If you are only interested in one specific category like sleep:

-
-library(GGIR)
-print(load_params()$params_sleep)
-

If you are only interested in parameter “HASIB.algo” from the -sleep_params object:

-
-library(GGIR)
-print(load_params()$params_sleep[["HASIB.algo"]])
-

Documentation for all arguments in the parameter objects can be found -the vignette: GGIR -configuration parameters.

-

All of these arguments are accepted as argument to function -GGIR, because GGIR is a shell around all GGIR -functionality. However, the params_ objects themselves can -not be provided as input to GGIR.

-
-

Key general arguments -

-

You will probably never need to think about most of the arguments -listed above, because a lot of arguments are only included to facilitate -methodological studies where researchers want to have control over every -little detail. See previous paragraph for links to the documentation and -how to find the default value of each parameter.

-

The bare minimum input needed for GGIR is:

-
-library(GGIR)
-GGIR(datadir="C:/mystudy/mydata",
- outputdir="D:/myresults")
-

Argument datadir allows you to specify where you have -stored your accelerometer data and outputdir allows you to -specify where you would like the output of the analyses to be stored. -This cannot be equal to datadir. If you copy paste the -above code to a new R script (file ending with .R) and Source it in -R(Studio) then the dataset will be processed and the output will be -stored in the specified output directory.

-

Below we have highlighted the key arguments you may want to be aware -of. We are not giving a detailed explanation, please see the package -manual for that.

-
    -
  • -mode - which part of GGIR to run, GGIR is constructed -in five parts.
    • -
  • -overwrite - whether to overwrite previously produced -milestone output. Between each GGIR part, GGIR stores milestone output -to ease re-running parts of the pipeline.
    • -
  • -idloc - tells GGIR where to find the participant ID -(default: inside file header)
    • -
  • -data_masking_strategy - informs GGIR how to consider -the design of the experiment. -
      -
    • If data_masking_strategy is set to value 1, then check -out arguments hrs.del.start and -hrs.del.end.
      • -
    • If data_masking_strategy is set to value 3 or 5, then -check out arguments ndayswindow, hrs.del.start -and hrs.del.end.
      • -
    -
    • -
  • -maxdur - maximum number of days you expect in a data -file based on the study protocol.
    • -
  • -desiredtz - time zone of the experiment.
    • -
  • -chunksize - a way to tell GGIR to use less memory, -which can be useful on machines with limited memory.
    • -
  • -includedaycrit - tell GGIR how many hours of valid data -per day (midnight-midnight) is acceptable.
    • -
  • -includenightcrit - tell GGIR how many hours of a valid -night (noon-noon) is acceptable.
    • -
  • -qwindow - argument to tell GGIR whether and how to -segment the day for day-segment specific analysis.
    • -
  • -mvpathreshold and boutcriter - -acceleration threshold and bout criteria used for calculating time spent -in MVPA (only used in GGIR part2).
    • -
  • -epochvalues2csv - to export epoch level magnitude of -acceleration to a csv files (in addition to already being stored as -RData file)
    • -
  • -dayborder - to decide whether the edge of a day should -be other than midnight.
    • -
  • -iglevels - argument related to intensity gradient -method proposed by A. Rowlands.
    • -
  • -do.report - specify reports that need to be -generated.
    • -
  • -viewingwindow and visualreport - to create -a visual report, this only works when all five parts of GGIR have -successfully run. Note that the visual report was initially developed to -provide something to show to study participants and not for data quality -checking purposes. Over time we have improved the visual report to also -be useful for QC-ing the data. however, some of the scorings as shown in -the visual report are created for the visual report only and may not -reflect the scorings in the main GGIR analyses as reported in the -quantitative csv-reports. Most of our effort in the past 10 years has -gone into making sure that the csv-report are correct, while the -visualreport has mostly been a side project. This is unfortunate and we -hope to find funding in the future to design a new report specifically -for the purpose of QC-ing the anlayses done by GGIR.
    • -
  • -maxRecordingInterval - if specified controls whether -neighboring or overlapping recordings with the same participant ID and -brand are appended at epoch level. This can be useful when the intention -is to monitor behaviour over larger periods of time but accelerometers -only allow for a few weeks of data collection. GGIR will never append or -alter the raw input file, this operation is preformed on the derived -data.
    • -
  • -study_dates_file - if specified trims the recorded data -to the first and last date in which the study took place. This is -relevant for studies that started the recording several days before the -accelerometers were actually worn by participants. This is used on the -top of data_masking_strategy, so that it may be combined with the -strategies in GGIR.
    • -
-
-
- -

For an explanation on how sleep is detected and the specific role of -the various function arguments see section Sleep analysis.

-
    -
  • Arguments related to configuring the sleep detection algorithm: -anglethreshold, timethreshold, -HASPT.algo, HASIB.algo, -Sadeh_axis, and HASPT.ignore.invalid.
    • -
  • -ignorenonwear if set to TRUE then ignore detected -monitor non-wear periods in the detection of sustained inactivity bouts -to avoid confusion between monitor non-wear time.
    • -
  • If you want to create a visualisation of how sleep period time and -sustained inactivity bouts match throughout a day then consider -arguments do.visual, outliers.only, and -criterror.
    • -
  • If you want to exclude the first and last night from the sleep -analysis then used excludefirstlast.
    • -
  • -def.noc.sleep specifies how the sleep period time -window should be estimated if no sleeplog is used.
    • -
  • -includenightcrit Minimum number of valid hours per -night (24 hour window between noon and noon or 6pm-6pm).
    • -
  • -data_cleaning_file to ginore specific nights for -specific individuals, see also section Data cleaning file.
    • -
  • If you want the sleep analysis to be guided by a sleeplog (diary) -then check out arguments loglocation which specifies the -location of the spreadsheet (csv) with sleep log information. Further, -use arguments colid and coln1 to specify the -details of your sleep log structure.
    • -
-

GGIR facilitates two possible sleeplog file structures:

-
-
Basic sleep log -
-

Example of a basic sleeplog:

- ----------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
IDonset_N1wakeup_N1onset_N2wakeup_N2onset_N3wakeup_N3onset_N4…
12322:00:0009:00:0021:00:0008:00:0023:45:0006:30:0000:00:00…
34521:55:0008:47:0023:45:0006:30:0000:00:00…
-
    -
  • One column for participant id, this does not have to be the first -column. Specify which column it is with argument -colid.
    • -
  • Alternatingly one column for onset time and one column for waking -time. Specify which column is the column for the first night by argument -coln1, in the above example coln1=2.
    • -
  • Timestamps are to be stored without date as in hh:mm:ss with hour -values ranging between 0 and 23 (not 24). If onset corresponds to lights -out or intention to fall asleep, then it specify -sleepwindowType = "TimeInBed".
    • -
  • There can be multiple sleeplogs in the same spreadsheet. Each row -representing a single recording.
    • -
  • First row: The first row of the spreadsheet needs to be filled with -column names. For the basic sleep log format it does not matter what -these column names are.
    • -
-
-
-
Advanced sleep log -
-

Example of an advanced sleeplog for two recordings:

- ------------ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
IDD1_dateD1_wakeupD1_inbedD1_nap_startD1_nap_endD1_nonwear1_offD1_nonwear1_onD2_date…
12330/03/201509:00:0022:00:0011:15:0011:45:0013:35:0014:10:0031/03/2015…
56720/04/201508:30:0023:15:0021/04/2015…
-

Relative to the basic sleeplog format the advanced sleep log format -comes with the following changes:

-
    -
  • Recording are stored in rows, while all information per days are -stored in columns.
    • -
  • Information per day is preceded by one columns that holds the -calendar date. GGIR has been designed to recognise and handle any date -format but assumes that you have used the same date format consistently -through the sleeplog.
    • -
  • Per calendar date there is a column for wakeup time and followed by -a column for onset or in-bed time. Note that this is different from the -basic sleep log, where wakeup time follows the column for onset or -in-bed time. So, the advanced sleep log is calendar date oriented: -asking the participant when they woke up and when the fell asleep on a -certain date. However, if the sleep onset time is at 2am, you should -still fill in the 02:00:00, even though it is the 02:00:00 of the next -calendar date.
    • -
  • You can add columns relating to self-reported napping time and -nonwear time. These are not used for the sleep analysis in g.part3 and -g.part4, but used in g.part5 to facilitate napping analysis, see -argument do.sibreport and the paragraph on naps. Multiple -naps and multiple nonwear periods can be entered per day.
    • -
  • Leave cells for missing values blank.
    • -
  • Column names are critical for the advanced sleeplog format: Date -columns are recognised by GGIR as any column name with the word “date” -in it. The advanced sleep log format is recognised by GGIR by looking -out for the occurrence of at least two columnnames with the word “date” -in their name. Wakeup times are recognised with the words “wakeup” in -the column name. Sleeponset, to bed or in bed times are recognised as -the columns with any of the following character combinations in their -name: “onset”, “inbed”, “tobed”, or “lightsout”. Napping times are -recognised by columns with the word “nap” in their name. Nonwear times -are recognised by columns with the word “nonwear” in their name.
    • -
-
-
-
- -

For an explanation on how time use analysis is performed see section -Waking-waking or 24 hour time-use -analysis.

-
    -
  • -excludefirstlast.part5 - whether to ignore the last and -first day.
    • -
  • -includedaycrit.part5 - tell GGIR what fraction of the -waking hours in a day (value below 1) is acceptable.
    • -
  • -minimum_MM_length.part5 - tell GGIR what the minimum -length (hours) should be of the MM window in part 5.
    • -
  • Configure thresholds for acceleration levels (some may want to -interpret this as intensity levels): threshold.lig, -threshold.mod, threshold.vig.
    • -
  • Configure what fraction of a bout needs to meet the threshold -(cut-point) crtieria boutcriter.in, -boutcriter.lig, boutcriter.mvpa. Note that -boutcriter.mvpa = 0.8 means that an MVPA bout can have interruptions -(i.e., the time out of MVPA intensity) that meet the following criteria: -
      -
    1. A single interruption can last < 1 min
      2. -
    2. Repeated interruptions are allowed provided that their total time -does not exceed 20% of the bout duration
      3. -
    3. The time spent in the interruptions is included in the duration of -the MVPA bout. For example: A 25-minute bout can have two 1 minute -interruption, but not a single 2-minute interruption. Here, the full 25 -minutes would count towards the duration of the MVPA bout.
      4. -
    -
    • -
  • -timewindow to specify whether days should be defined -from midnight to midnight "MM", from waking-up to waking-up -"WW", from sleep onset to sleep onset "OO", or -any combination of them.
    • -
  • Configure durations of bouts: boutdur.mvpa, -boutdur.in, and boutdur.lig. Note that this -can be a vector of multiple values indicating the minimum and maximum -duration of subsequent bout types, e.g. 1-5 minutes MVPA, 5-10 minutes -MVPA, and longer than 10 minutes MVPA.
    • -
-
-
-

Published cut-points and how to use them -

-

This section has been rewritten and moved. Please, visit the vignette -Published cut-points -and how to use them in GGIR for more details on the cut-points -available, how to use them, and some additional reflections on the use -of cut-points in GGIR.

-
-
-

Example call -

-

If you consider all the arguments above you me may end up with a call -to GGIR that could look as follows.

-
-library(GGIR)
-GGIR(mode=c(1,2,3,4,5),
-      datadir="C:/mystudy/mydata",
-      outputdir="D:/myresults",
-      do.report=c(2,4,5),
-      #=====================
-      # Part 2
-      #=====================
-      data_masking_strategy = 1,
-      hrs.del.start = 0,          hrs.del.end = 0,
-      maxdur = 9,                 includedaycrit = 16,
-      qwindow=c(0,24),
-      mvpathreshold =c(100),
-      excludefirstlast = FALSE,
-      includenightcrit = 16,
-      #=====================
-      # Part 3 + 4
-      #=====================
-      def.noc.sleep = 1,
-      outliers.only = TRUE,
-      criterror = 4,
-      do.visual = TRUE,
-      #=====================
-      # Part 5
-      #=====================
-      threshold.lig = c(30), threshold.mod = c(100),  threshold.vig = c(400),
-      boutcriter = 0.8,      boutcriter.in = 0.9,     boutcriter.lig = 0.8,
-      boutcriter.mvpa = 0.8, boutdur.in = c(1,10,30), boutdur.lig = c(1,10),
-      boutdur.mvpa = c(1),
-      includedaycrit.part5 = 2/3,
-      #=====================
-      # Visual report
-      #=====================
-      timewindow = c("WW"),
-      visualreport=TRUE)
-

Once you have used GGIR and the output directory -(outputdir) will be filled with milestone data and results.

-
-
-

Configuration file -

-

Function GGIR stores all the explicitly entered argument -values and default values for the argument that are not explicitly -provided in a csv-file named config.csv stored in the root of the output -folder. The config.csv file is accepted as input to GGIR -with argument configfile to replace the specification of -all the arguments, except datadir and -outputdir, see example below.

-
-library(GGIR)
-GGIR(datadir="C:/mystudy/mydata",
-             outputdir="D:/myresults", configfile = "D:/myconfigfiles/config.csv")
-

The practical value of this is that it eases the replication of -analysis, because instead of having to share you R script, sharing your -config.csv file will be sufficient. Further, the config.csv file -contribute to the reproducibility of your data analysis.

-

Note 1: When combining a configuration file with explicitly provided -argument values, the explicitly provided argument values will overrule -the argument values in the configuration file. Note 2: The config.csv -file in the root of the output folder will be overwritten every time you -use GGIR. So, if you would like to add annotations in the -file, e.g. in the fourth column, then you will need to store it -somewhere outside the output folder and explicitly point to it with -configfile argument.

-
-
-
-
-

Time for action: How to run your analysis? -

-
-

From the R console on your own desktop/laptop -

-

Create an R-script and put the GGIR call in it. Next, you can source -the R-script with the source function in R:

-

source("pathtoscript/myshellscript.R")

-

or use the Source button in RStudio if you use RStudio.

-
-
-

In a cluster -

-

GGIR by default support multi-thread processing, which can be turned -off by seting argument do.parallel = FALSE. If this is -still not fast enough then we advise using a GGIR on a computing -cluster. The way we did it on a Sun Grid Engine cluster is shown below, -please note that some of these commands are specific to the computing -cluster you are working on. Also, you may actually want to use an R -package like clustermq or snowfall, which avoids having to write bash -script. Please consult your local cluster specialist to tailor this to -your situation. In our case, we had three files for the SGE setting:

-

submit.sh

-
for i in {1..707}; do
-    n=1
-    s=$(($(($n * $[$i-1]))+1))
-    e=$(($i * $n))
-    qsub /home/nvhv/WORKING_DATA/bashscripts/run-mainscript.sh $s $e
-done
-

run-mainscript.sh

-
#! /bin/bash
-#$ -cwd -V
-#$ -l h_vmem=12G
-/usr/bin/R --vanilla --args f0=$1 f1=$2 < /home/nvhv/WORKING_DATA/test/myshellscript.R
-

myshellscript.R

-
-options(echo=TRUE)
-args = commandArgs(TRUE)
-if(length(args) > 0) {
-  for (i in 1:length(args)) {
-    eval(parse(text = args[[i]]))
-  }
-}
-GGIR(f0=f0,f1=f1,...)
-

You will need to update the ... in the last line with -the arguments you used for GGIR. Note that -f0=f0,f1=f1 is essential for this to work. The values of -f0 and f1 are passed on from the bash -script.

-

Once this is all setup you will need to call -bash submit.sh from the command line.

-

With the help of computing clusters GGIR has successfully been run on -some of the worlds largest accelerometer data sets such as UK Biobank -and German NAKO study.

-
-
-

Processing time -

-

The time to process a typical seven day recording should be anywhere -in between 3 and 10 minutes depending on the sample frequency of the -recording, the sensor brand, data format, the exact configuration of -GGIR, and the specifications of your computer. If you are observing -processing times of 20 minutes or longer for a 7 day recording then -probably you are slowed down by other factors.

-

Some tips on how you may be able to address this:

-
    -
  • Make sure the data you process is on the same machine as where GGIR -is run. Processing data located somewhere else on a computer network can -substantially slow software down.
    • -
  • Make sure your machine has 8GB or more RAM memory, using GGIR on old -machines with only 4GB is known to be slow. However, total memory is not -the only bottle neck, also consider the number of processes (threads) -your CPU can run relative to the amount of memory. Ending up with 2GB -per process seems a good target.
    • -
  • Avoid doing other computational activities with your machine while -running GGIR. For example, if you use DropBox or OneDrive make sure they -do not sync while you are running GGIR. When using GGIR to process large -datasets it is probably best to not use the machine, but make sure the -machine is configured not to fall asleep as that would terminate the -analyses.
    • -
-
-
-
-

Inspecting the results -

-

GGIR generates the following types of output. - csv-spreadsheets with -all the variables you need for physical activity, sleep and circadian -rhythm research - Pdfs with on each page a low resolution plot of the -data per file and quality indicators - R objects with milestone data - -Pdfs with a visual summary of the physical activity and sleep patterns -as identified (see example below)

-

-
-

Output part 2 -

-

Part 2 generates the following output:

-
    -
  • part2_summary.csv: Person level summary (see below)
    • -
  • part2_daysummary.csv: Day level summary (see below)
    • -
  • QC/data_quality_report.csv: Overview of calibration results and -whether or not a file was corrupt or too short to be processed,
    • -
  • QC/plots to check data quality 1.pdf: A pdf with visualisation of -the acceleration time series in 15 minute resolution and with invalid -data segments highlighted in colours (yellow: non-wear based on standard -deviation threshold, brown: non-wear after extra filtering step -(introduced in 2013), and purple: clipping)
    • -
-
-

Person level summary -

- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(Part of) variable nameDescription
IDParticipant id
device_snDevice serial number
bodylocationBody location extracted from file header
filenameName of the data file
start_timeTimestamp when recording started
startdayDay of the week on which recording started
samplefreqSample frequency (Hz)
deviceAccelerometer brand, e.g. GENEACtiv
clipping_scoreThe Clipping score: Fraction of 15 minute windows per file for which -the acceleration in one of the three axis was close to the maximum for -at least 80% of the time. This should be 0.
meas_dur_dysMeasurement duration (days)
complete_24hcycleCompleteness score: Fraction of 15 minute windows per 24 hours for -which no valid data is available at any day of the measurement.
meas_dur_def_proto_daymeasurement duration according to protocol (days): Measurement -duration (days) minus the hours that are ignored at the beginning and -end of the measurement motivated by protocol design
wear_dur_def_proto_daywear duration duration according to protocol (days): So, if the -protocol was seven days of measurement, then wearing the accelerometer -for 8 days and recording data for 8 days will still make that the wear -duration is 7 days
calib_errCalibration error (static estimate) Estimated based on all -‘non-movement’ periods in the measurement after applying the -autocalibration.
calib_statusCalibration status: Summary statement about the status of the -calibration error minimisation
ENMO_fullRecordingMeanENMO is the main summary measure of acceleration. The value -presented is the average ENMO over all the available data normalised per -24-hour cycles (diurnal balanced), with invalid data imputed by the -average at similar time points on different days of the week. In -addition to ENMO it is possible to extract other acceleration metrics -(i.e. BFEN, HFEN, HFENplus). We emphasize that it is calculated over the -full recording because the alternative is that a variable is only -calculated overmeasurement days with sufficient valid hours of -data.
ENMO(only available if set to true in part1.R) ENMO is the main summary -measure of acceleration. The value presented is the average ENMO over -all the available data normalised per 24 hour cycles, with invalid data -imputed by the average at similar timepoints on different days of the -week. In addition to ENMO it is possible to extract other acceleration -metrics in part1.R (i.e. BFEN, HFEN, HFENplus) See also van -Hees PLoSONE April 2013 for a detailed description and comparison of -these techniques.
pX_A_mg_0-24h_fullRecordingThis variable represents the Xth percentile in the distribution of -short epoch metric value A of the average day. The average day may not -be ideal for describing the distribution. Therefore, the code also -extracts the following variable.
AD_pX_A_mg_0-24hThis variable represents the Xth percentile in the distribution of -short epoch metric value A per day averaged across all days.
L5_A_mg_0-24Average of metric A during the least active five* hours in the day -that is the lowest rolling average value of metric A. (* window size is -modifiable by argument winhr)
M5_A_mg_0-24Average of metric A during the most active five* hours in the day -that is the lowest rolling average value of metric A. (* window size is -modifiable by argument winhr)
L5hr_A_mg_0-24Starting time in hours and fractions of hours of L5_A_mg_0-24
M5hr_A_mg_0-24Starting time in hours and fractions of hours of M5_A_mg_0-24
ig_gradient_ENMO_0 -24hr_fullRecordingIntensity gradient calculated over the full recording.
1to6am_ENMO_mgAverage metric value ENMO between 1am and 6am
N valid WEdaysNumber of valid weekend days
N valid WKdaysNumber of valid week days
IS_interdailystabilityinter daily stability. The movement count that is derived for this -was an attempt to follow the original approach by Eus J. W. Van Someren -(Chronobiology International. 1999. Volume 16, issue 4).
IV_in tradailyvariabilityintra daily variability. In contrast to the original paper, we -ignore the epoch transitions between the end of a day and the beginning -of the next day for the numerator of the equation, this to make it a -true measure of intradaily variability. Same note as for IS: The -movement count that is derived for this was an attempt to follow the -original approach.
IVIS_windowsize_minutesSizes of the windows based on which IV and IS are calculated (note -that this is modifiable)
IVIS_epochsize_secondsArgument has been deprecated
AD_All days (plain average of all available days, no weighting). The -variable was calculated per day and then averaged over all the available -days
WE_Weekend days (plain average of all available days, no weighting). -The variable was calculated per day and then averaged over weekend days -only
WD_Week days (plain average of all available days, no weighting). The -variable was calculated per day and then averaged over week days -only
WWE_Weekend days (weighted average) The variable was calculated per day -and then averaged over weekend days. Double weekend days are averaged. -This is only relevant for experiments that last for more than seven -days.
WWD_Week days (weighted average) The variable was calculated per day and -then averaged over week days. Double week days were averaged. This is -only relevant for experiments that last for more than seven days)
WWD_MVPA_E5S_T100_ENMOTime spent in moderate-to-vigorous based on 5 second epoch size and -an ENMO metric threshold of 100
WWE_MVPA_E5 S_B1M80%_T100_ENMOTime spent in moderate-to-vigorous based on 5 second epoch size and -an ENMO metric threshold of 100 based on a bout criteria of 100
WE_[100, 150)_mg_0-24h_ENMOTime spent between (and including) 100 mg and 150 (excluding 150 -itself) between 0 and 24 hours (the full day) using metric ENMO data -exclusion data_masking_strategy (value=1, ignore specific hours; -value=2, ignore all data before the first midnight and after the last -midnight)
_M VPA_E5S_B1M80_T100MVPA calculated based on 5 second epoch setting bout duration 1 -Minute and inclusion criterion of more than 80 percent. This is only -done for metric ENMO at the moment, and only if mvpa threshold is not -left blank
_ENMO_mgENMO or other metric was first calculated per day and then average -according to AD, WD, WWE, WWD
data exclusion data_masking_strategyA log of the decision made when calling g.impute: value=1 mean -ignore specific hours; value=2 mean ignore all data before the first -midnight and after the last midnight
n hours ignored at start of meas (if data_masking_strategy=1, 3 or -5)number of hours ignored at the start of the measurement (if -data_masking_strategy = 1) or at the start of the -ndayswindow (if data_masking_strategy = 3 or 5) A log of -decision made in part2.R
n hours ignored at end of meas (if data_masking_strategy=1, 3 or -5)number of hours ignored at the end of the measurement (if -data_masking_strategy = 1) or at the end of the ndayswindow -(if data_masking_strategy = 3 or 5). A log of decision made in -part2.R
n hours ignored at end of meas (if data_masking_strategy = 1, 3 or -5)number of days of measurement after which all data is ignored (if -data_masking_strategy = 1, 3 or 5) A log of decision made in -part2.R
epoch size to which acceleration was averaged (seconds)A log of decision made in part1.R
pdffilenumbIndicator of in which pdf-file the plot was stored
pdfpagecountIndicator of in which pdf-page the plot was stored
cosinor_Cosinor analysis estimates such as mes, amp, acrophase, and -acrotime, as documented in the Ac tCR package.
cosinorExt_Extended Cosinor analysis estimates such as minimum, amp, alpha, -beta, acrotime, UpMesor, DownMesor, MESOR, and F_pseudo, as documented -in the Ac tCR -package.
cosinorIVCosinor analysis compatible estimate of the Intradaily Variability -(IV)
cosinorISCosinor analysis compatible estimate of Interdaily Stability -(IS)
-
-
-

Day level summary -

-

This is a non-exhaustive list, because most concepts have been -explained in summary.csv

- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(Part of) variable nameDescription
IDParticipant id
filenameName of the data file
calender_dateTimestamp and date on which measurement started
bodylocationLocation of the accelerometer as extracted from file header
N valid hoursNumber of hours with valid data in the day
N hoursNumber of hours of measurement in a day, which typically is 24, -unless it is a day on which the clock changes (DST) resulting in 23 or -25 hours. The value can be less than 23 if the measurement started or -ended this day
weekdayName of weekday
measurementDay of measurement Day number relative to start of the -measurement
L5hr_ENMO_mg_0-24hHour on which L5 starts for these 24 hours (defined with metric -ENMO)
L5_ENMO_mg_0-24hAverage acceleration for L5 (defined with metric ENMO)
[A,B)_mg_0-24h_ENMOTime spent in minutes between (and including) acceleration value A -in mg and (excluding) acceleration value B in mg based on metric -ENMO
ig_gradient_ENMO_0-24hrGradient from intensity gradient analysis proposed by Rowlands -et al. 2018 based on metric ENMO for the time segment 0 to 24 -hours
ig_intercept_ENMO_0-24hrIntercept from intensity gradient analysis proposed by Rowlands -et al. 2018 based on metric ENMO for the time segment 0 to 24 -hours
ig_rsquared_ENMO_0-24hrr squared from intensity gradient analysis proposed by Rowlands -et al. 2018 based on metric ENMO for the time segment 0 to 24 -hours
-
-
-

Data_quality_report -

-

The data_quality_report.csv is stored in subfolder folder -results/QC.

- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(Part of) variable nameDescription
filenamefile name
file.corruptIs file corrupt? TRUE or FALSE (mainly tested for GENEActiv bin -files)
file.too.shortFile too short for processing? (definition) TRUE or FALSE
use.temperatureTemperature used for auto-calibration? TRUE or FALSE
scale.xAuto-calibration scaling coefficient for x-axis (same for y and z -axis, not shown here)
offset.xAuto-calibration offset coefficient for x-axis (same for y and z -axis, not shown here)
temperature.offset.xAuto-calibration temperature offset coefficient for x-axis (same for -y and z axis, not shown here)
cal.error.startCalibration error prior to auto-calibration
cal.error.endCalibration error after auto-calibration
n.10sec.windowsNumber of 10 second epochs used as sphere data in -auto-calibration
n.hours.consideredNumber of hours of data considered for auto-calibration
QCmessageCharacter QC message at the end of the auto-calibration
mean.tempMean temperature in sphere data
device.serial.numberDevice serial number
NFilePagesSkipped(Only for Axivity .cwa format) Number of raw data blocks -skipped
filehealth_totimp_min(Only for Axivity .cwa, ActiGraph gt3x, and ad-hoc csv format) Total -number of minutes of raw data imputed
filehealth_checksumfail_min(Only for Axivity .cwa format) Total number of minutes of raw data -where the checksum failed
filehealth_niblockid_min(Only for Axivity .cwa format) Total number of minutes of raw data -with non-incremental block ids
filehealth_fbias0510_min(Only for Axivity .cwa format) Total number of minutes with a -sampling frequency bias between 5 and 10%
filehealth_fbias1020_min(Only for Axivity .cwa format) Total number of minutes with a -sampling frequency bias between 10 and 20%
filehealth_fbias2030_min(Only for Axivity .cwa format) Total number of minutes with a -sampling frequency bias between 20 and 30%
filehealth_fbias30_min(Only for Axivity .cwa format) Total number of minutes with a -sampling frequency bias higher than 30%
filehealth_totimp_N(Only for Axivity .cwa, ActiGraph gt3x, and ad-hoc csv format) Total -number of data blocks that were imputed
filehealth_checksumfail_N(Only for Axivity .cwa format) Total number of blocks where the -checksum failed
filehealth_niblockid_N(Only for Axivity .cwa format) Total number of raw data blocks with -non-incremental block ids
filehealth_fbias0510_N(Only for Axivity .cwa format) Total number of raw data blocks with -a sampling frequency bias between 5 and 10%
filehealth_fbias1020_N(Only for Axivity .cwa format) Total number of raw data blocks with -a sampling frequency bias between 10 and 20%
filehealth_fbias2030_N(Only for Axivity .cwa format) Total number of raw data blocks with -a sampling frequency bias between 20 and 30%
filehealth_fbias30_N(Only for Axivity .cwa format) Total number of raw data blocks with -a sampling frequency bias higher than 30%
-
-
-
-

Output part 4 -

-

Part 4 generates the following output:

-
-

Night level summaries -

-
    -
  • part4_nightsummary_sleep_cleaned.csv
    • -
  • QC/part4_nightsummary_sleep_full.csv
    • -
-

The latter with ’_full’ in the name is intended to aid clarifying why -some nights (if any) are excluded from the cleaned summary report. -Although, nights where the accelerometer was not worn at all are -excluded from this. So, if you have a 30 day recording where the -accelerometer was not worn from day 7 onward then you will not find the -last 22 nights in either csv-report.

-

The csv. files contain the variables as shown below.

- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(Part of) variable nameDescription
IDParticipant ID extracted from file
nightNumber of the night in the recording
sleeponsetDetected onset of sleep expressed as hours since the midnight of the -previous night.
wakeupDetected waking time (after sleep period) expressed as hours since -the midnight of the previous night.
SptDurationDifference between onset and waking time.
sleepparamDefinition of sustained inactivity by accelerometer.
guiderguider used as discussed in paragraph Sleep analysis.
guider_onsetStart of Sleep Period Time window derived from the guider.
guider_wakeEnd of Sleep Period Time window derived guider.
guider_SptDurationTime SPT duration derived from guider_wake and guider_onset.
error_onsetDifference between sleeponset and guider_onset
error_wakeDifference between wakeup and guider_wake
fraction_night_invalidFraction of the night (noon-noon or 6pm-6pm) for which the data was -invalid, e.g. monitor not worn or no accelerometer measurement -started/ended within the night.
SleepDurationInSptTotal sleep duration, which equals the accumulated nocturnal -sustained inactivity bouts within the Sleep Period Time.
duration_sib_wakinghoursAccumulated sustained inactivity bouts during the day. These are the -periods we would label during the night as sleep, but during the day -they form a subclass of inactivity, which may represent day time sleep -or wakefulness while being motionless for a sustained period of time -number_sib_sleepperiod} Number of nocturnal sleep periods, with -nocturnal referring to the Sleep Period Time window.
duration_sib_wakinghours_atleast15minSame as duration_sib_wakinghours, but limited to SIBs that last at -least 15 minutes.
num ber_sib_wakinghoursNumber of sustained inactivity bouts during the day, with day -referring to the time outside the Sleep Period Time window.
sleeponset_tssleeponset formatted as a timestamp
wakeup_tswakeup formatted as a timestamp
guider_onset_tsguider_onset formatted as a timestamp
guider_wake_tsguider_wake formatted as a timestamp
pagepdf page on which the visualisation can be found
daysleeperIf 0 then the person is a nightsleeper (sleep period did not overlap -with noon) if value=1 then the person is a daysleeper (sleep period did -overlap with noon)
weekdayDay of the week on which the night started
calendardateCalendar date on which the night started in day/month/year -format.
filenameName of the accelerometer file
cleaningcodesee paragraph Cleaningcode -
sleeplog_usedWhether a sleep log was used (TRUE/FALSE)
acc_availableWhether accelerometer data was available (TRUE/FALSE).
WASOWake After Sleep Onset: SptDuration - SleepDurationInSpt
SptDurationSleep Period Time window duration: wakeup - sleeponset
error_onsetDifference between sleeponset and guider_onset (this variable is -only available in the full report as stored in the QC folder)
error_wakeDifference between wakeup and guider_wake (this variable is only -available in the full report as stored in the QC folder)
SleepRegularityIndexThe Sleep Regularity Index as proposed by Phillips et -al. 2017, but calculated per day-pair to enable user to study -patterns across days
SriFractionValidFraction of the 24 hour period that was valid in both current as -well as in matching timestamps for the next calendar day. See GGIR -function manual for details
nonwear_perc_sptNon-wear percentage during the spt hours of this day. This is a copy -of the nonwear_perc_spt calculated in part 5, -only included in part 4 reports if part 5 has been run with timewindow = -WW
-
-
Non-default variables in part 4 csv report -
-

These additional are only stored if you used a sleeplog that captures -time in bed, or when using guider HorAngle for hip-worn accelerometer -data. If either of these applies set argument -sleepwindowType to “TimeInBed”.

- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - -
(Part of) variable nameDescription
guider_guider_inbedStartTime of getting in bed
guider_guider_inbedEndTime of getting out of bed
guider_inbedDurationTime in Bed: guider_inbedEnd - guider_inbedStart
sleepefficiencySleep efficiency, calculated by one of two metrics as controlled by -argument sleepefficiency.metric: SleepDurationInSpt / -guider_inbedDuration (default) or SleepDurationInSpt / (SptDuration + -latency)
sleeplatencySleep latency, calculated as: sleeponset - guider_inbedStart
-
-
-
-

Person level summaries -

-
    -
  • part4_summary_sleep_cleaned.csv
    • -
  • QC/part4_summary_sleep_full.csv
    • -
-

In the person level report the variables are derived from the -variables in the night level summary. Minor extensions to the variable -names explain how variables are aggregated across the days. Please find -below extra clarification on a few of the variable names for which the -meaning may not be obvious:

- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(Part of) variable nameDescription
_mnmean across days
_sdstandard deviation across days
_ADAll days
_WEWeekend days
_WDWeek days
sleeplog_usedWhether a sleeplog was available (TRUE) or not (FALSE)
sleep_efficiencyAccelerometer derived sleep efficiency within the sleep period time -calculated as the ratio between acc_SleepDurationInSpt and -guider_SptDuration (denominator) or acc_SleepDurationInSpt and -acc_SptDuration + latency (denominator), as defined with -relyonguider_SleepEfficiency. Only available at person level, because at -night level the user can calculate this from existing variables.
n_nights_accNumber of nights of accelerometer data
n_nights_sleeplogNumber of nights of sleeplog data.
n_WE_nights_completeNumber of weekend nights complete which means both accelerometer and -estimate from guider.
n_WD_nights_completeNumber of weekday nights complete which means both accelerometer and -estimate from guider.
n_WEnights_daysleeperNumber of weekend nights on which the person slept until after -noon.
n_WDnights_daysleeperNumber of weekday nights on which the person slept until after -noon.
duration_sib_wakinghourTotal duration of sustained inactivity bouts during the waking -hours.
number_sib_wakinghoursNumber of sustained inactivity bouts during the waking hours.
average_dur_sib_wakinghoursAverage duration of the sustained inactivity bouts during the day -(outside the sleep period duration). Calculated as -duration_sib_wakinghour divided by number_sib_wakinghours per day, after -which the mean and standard deviation are calculated across days.
-
-
-

visualisation_sleep.pdf -

-

Visualisation to support data quality checks: - -visualisation_sleep.pdf (optional)

-

When input argument do.visual is set to TRUE GGIR can -show the following visual comparison between the time window of being -asleep (or in bed) according to the sleeplog and the detected sustained -inactivity bouts according to the accelerometer data. This visualisation -is stored in the results folder as -visualisation_sleep.pdf.

-

Explanation of the image: Each line represents one night. Colours are -used to distinguish definitions of sustained inactivity bouts (2 -definitions in this case) and to indicate existence or absence of -overlap with the sleeplog. When argument outliers.only is -set to FALSE it will visualise all available nights in the dataset. If -outliers.only is set to TRUE it will visualise only nights -with a difference in onset or waking time between sleeplog and sustained -inactivity bouts larger than the value of argument -criterror.

-

This visualisation with outliers.only set to TRUE and critererror set -to 4 was very powerful to identify entry errors in sleeplog data in van -Hees et al PLoSONE 2015. We had over 25 thousand nights of data, and -this visualisation allowed us to quickly zoom in on the most problematic -nights to investigate possible mistakes in GGIR or mistakes in data -entry.

-

-
-
-
-

Output part 5 -

-

The output of part 5 is dependent on the parameter configuration, it -will generate as many output files as there are unique combination of -the three thresholds provided.

-

For example, the following files will be generated if the threshold -configuration was 30 for light activity, 100 for moderate and 400 for -vigorous activity:

-
    -
  • part5_daysummary_MM_L30M100V400_T5A5.csv
    • -
  • part5_daysummary_WW_L30M100V400_T5A5.csv
    • -
  • part5_personsummary_MM_L30M100V400_T5A5.csv
    • -
  • part5_personsummary_WW_L30M100V400_T5A5.csv
    • -
  • file summary reports/Report_nameofdatafile.pdf
    • -
-
-

Day level summary -

- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(Term in) variable nameDescription
sleeponsetonset of sleep expressed in hours since the midnight in the night -preceding the night of interest, e.g. 26 is 2am.
wakeupwaking up time express in the same way as sleeponset.
sleeponset_tsonset of sleep expressed as a timestamp hours:minutes:seconds
daysleeperif 0 then the person woke up before noon, if 1 then the person woke -up after noon
cleaningcodeSee paragraph Cleaningcode.
dur_day_spt_minTotal length of daytime waking hours and spt combined (typically 24 -hours for MM report).
dur_duration of a behavioral class that will be specified int he rest of -the variable name
ACC_(average) acceleration according to default metric specific by -acc.metric
_spt_wake_Wakefulness within the Sleep period time window.
_spt_sleep_Sleep within the Sleep period time window.
_IN_Inactivity. Note that we use the term inactivity instead of -sedentary behaviour for the lowest intensity level of behaviour. The -reason for this is that GGIR does not attempt to classifying the -activity type sitting at the moment, by which we feel that using the -term sedentary behaviour would fail to communicate that.
_LIG_Light activity
_MOD_Moderate activity
_VIG_Vigorous activity
_MVPA_Moderate or Vigorous activity
_unbt_Unbouted
_bts_Bouts (also known as sojourns), which are segments that for which -the acceleration is within a specified range for a specified fraction of -the time.
_bts_1_10_Bouts lasting at least 1 minute and less than 10 minutes (1 and 9.99 -minutes are included, but 10 minutes is not).
Nblocknumber of blocks of a certain behavioral class, not these are not -bouts but a count of the number of times the behavioral class occurs -without interruptions.
WWin filename refers to analyses based on the timewindow from waking -to waking up
MMin filename refers to analyses done on windows between midnight and -midnight
calendar_datecalendar date on which the window started in day/month/year format. -So, for WW window this could mean that you have two windows starting on -the same date.
weekdayweekday on which the window started. So, for WW window this could -mean that you have two windows starting on the weekday.
_total_INtotal time spent in inactivity (no distinction between bouted or -unbouted behavior, this is a simple count of the number of epochs that -meet the threshold criteria.
_total_LIGtotal time spent in light activity.
nonwear_perc_dayNon-wear percentage during the waking hours of this day.
nonwear_perc_sptNon-wear percentage during the spt hours of this day.
nonwear_perc_day_sptNon-wear percentage during the whole day, including waking and -spt.
dur_day_minDuration of waking hours within this day window
dur_spt_minDuration of Sleep Period Time within this day window.
dur_day_spt_minDuration this day window, including both waking hours and SPT.
sleep_efficiencysleep_efficiency in part 5 is not the same as in part 4, but -calculated as the percentage of sleep within the sleep period time -window. The conventional approach is the approach used in part 4.
L5TIMETiming of least active 5hrs, expressed as timestamp in the day
M5TIMETiming of most active 5hrs
L5TIME_num, M5TIME_numTiming of least/most active 5hrs, expressed as hours in the day. -Note that L5/M5 timing variables are difficult to average across days -because 23:00 and 1:00 would average to noon and not to midnight. So, -caution is needed when interpreting person averages.
L5VALUEAcceleration value for least active 5hrs
M5VALUEAcceleration value for most active 5hrs
ig_All variables related to intensity gradient analysis
_gradientGradient from intensity gradient analysis proposed by Rowlands -et al. 2018 for the waking hours window (_day_) and for -the full window (_day_spt_)
_interceptIntercept from intensity gradient analysis proposed by Rowlands -et al. 2018 for the waking hours window (_day_) and for -the full window (_day_spt_)
_rsquaredr squared from intensity gradient analysis proposed by Rowlands -et al. 2018 for the waking hours window (_day_) and for -the full window (_day_spt_)
FRAG_All variables related to behavioural fragmentation analysis
TP_Transition probability
PA2INPhysical activity fragments followed by inactivity fragments
IN2PAPhysical inactivity fragments followed by activity fragments
NfragNumber of fragments
IN2LIPAInactivity fragments followed by LIPA
IN2MVPAInactivity fragments followed by MVPA
mean_durmean duration of a fragment category
Gini_durGini index
CoV_durCoefficient of Variation
alphaPower law exponent
x0.5Derived from power law exponent alpha, see Chastin et al. 201 -0 -
W0.5Derived from power law exponent alpha, see Chastin et al. 201 -0 -
nap_countTotal number of naps, only calculated when argument do.sibreport = -TRUE, currently optimised for 3.5-year olds. See function documentation -for function g.part5.classifyNaps in the GGIR function -documentation (pdf).
nap_totaldurationTotal nap duration, only calculated when argument do.sibreport = -TRUE, currently optimised for 3.5-year old. See function documentation -for function g.part5.classifyNaps in the GGIR function -documentation (pdf).
sibreport_n_itemsOnly created if do.sibreport = TRUE. Number of items in -the sibreport
sibreport_n_items_dayOnly created if do.sibreport = TRUE. Number of items in -the sibreport for this specific day
nbouts_day_XOnly created if do.sibreport = TRUE. Number of bouts in -a day of X where X can be sib (sustained inactivity bout), srnap -(self-reported nap) or srnonw (self-reported nonwear)
noverl_XOnly created if do.sibreport = TRUE. Number of -overlapping bouts in a day of X where X can be sib_srnap, sib_srnonw, -srnap_sib, or srnonw_sib
frag_mean_dur_X_dayOnly created if do.sibreport = TRUE. Mean duration of X -per day, where X can be sib, srnap or srnonw
dur_day_X_minOnly created if do.sibreport = TRUE. Total duration in -minutes of X per day, where X can be sib, srnap or srnonw
mdur_X_overl_YOnly created if do.sibreport = TRUE. Mean duration of -the overlap between X and Y, which are combinations of sib, srnap or -srnonw
tdur_X_overl_YOnly created if do.sibreport = TRUE. Total duration in -minutes of the overlap between X and Y, which are combinations of sib, -srnap or srnonw
perc_X_overl_YOnly created if do.sibreport = TRUE. Percentage of -overlap between X and Y, which are combinations of sib, srnap or -srnonw
-

Special note if you are working on compositional data -analysis:

-

The duration of all dur_ variables that have -_total_ in their name should add up to the total length of -the waking hours in a day. Similarly, the duration of all other -dur_ variables excluding the variables _total_ -in their name and excluding the variable with dur_day_min, -dur_spt_min, and dur_day_spt_min should also -add up to the length of the full day.

-

Motivation for default boutcriter.in = 0.9:

-

The idea is that if you allow for bouts of 30 minutes it would not -make sense to allow for breaks of 20 percent (6 minutes!) this is why I -used a more stringent criteria for the highest category. Please note -that you can change these criteria via arguments -boutcriter.mvpa, boutcriter.in, and -boutcriter.lig.

-
-
-

Person level summary -

-

Most variables in the person level summary are derived from the day -level summary, but extended with _pla to indicate that the -variable was calculated as the plain average across all valid days. -Variables extended with _wei represent the weighted average -of across all days where weekend days always weighted 2/5 relative to -the contribution of week days.

- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Variable nameDescription
NvaliddaysTotal number of valid days.
Nvaliddays_WDNumber of valid week days.
Nvaliddays_WENumber of valid weekend days, where the days that start on Saturday -or Sunday are considered weekend.
NcleaningcodeXNumber of days that had cleaning code X for the corresponding sleep -analysis in part 4. In case of MM analysis this refers to the night at -the end of the day.
Nvaliddays_AL10F_WDNumber of valid week days with at least 10 fragments (5 inactivity -or 5 inactive)
Nvaliddays_AL10F_WENumber of valid weekend days with at least 10 fragments (5 -inactivity or 5 inactive)
_weiweighted average of weekend and week days, using a 2/5 ratio, see -above.
_plaplain average of all days, see above
-
-
-
-
-

Motivation and clarification -

-

In this chapter we will try to collect motivations and clarification -behind GGIR which may not have been clear from the existing -publications.

-
-

Reproducibilty of GGIR analyses -

-

Some tips to increase reproducibility of your findings:

-
    -
  1. When you publish your findings, please remember to add the GGIR -package version number. All of GGIR are archived by CRAN and available -from the archive section on the package website. GGIR has -evolved over the years. To get a better understanding of how versions -differ you should check the NEWS sections from the package website -
    2. -
  2. Report how you configured the accelerometer
    3. -
  3. Report the study protocol and wear instructions given to the -participants
    4. -
  4. Report GGIR version
    5. -
  5. Report how GGIR was used: Share the config.csv file or your R -script
    6. -
  6. Report how you post-processed / cleaned GGIR output
    7. -
  7. Report how reported outcomes relate to the specific variable names -in GGIR
    8. -
-
-
-

Auto-calibration -

-

An acceleration sensor works on the principle that acceleration is -captured mechanically and converted into an electrical signal. The -relationship between the electrical signal and the acceleration is -usually assumed to be linear, involving an offset and a gain factor. We -shall refer to the establishment of the offset and gain factor as the -sensor calibration procedure. Accelerometers are usually calibrated as -part of the manufacturing process under non-movement conditions using -the local gravitational acceleration as a reference. The manufacturer -calibration can later be evaluated by holding each sensor axis parallel -(up and down) or perpendicular to the direction of gravity; readings for -each axis should be ±1 and 0 g, respectively. However, this procedure -can be cumbersome in studies with a high throughput. Furthermore, such a -calibration check will not be possible for data that have been collected -in the past and for which the corresponding accelerometer device does -not exist anymore. Techniques have been proposed that can check and -correct for calibration error based on the collected triaxial -accelerometer data in the participant’s daily life without additional -experiments, referred to as autocalibration. The general principle of -these techniques is that a recording of acceleration is screened for -nonmovement periods. Next, the moving average over the nonmovement -periods is taken from each of the three orthogonal sensor axes and used -to generate a three-dimensional ellipsoid representation that should -ideally be a sphere with radius 1 g. Here, deviations between the radius -of the three-dimensional ellipsoid and 1 g (ideal calibration) can then -be used to derive correction factors for sensor axis-specific -calibration error. This auto-calibration performed by GGIR uses this -technique and a more detailed description and demonstration can be found -in the published paper.

-

Reference:

-
    -
  • van Hees VT, Fang Z, Langford J, Assah F, Mohammad A, da Silva IC, -Trenell MI, White T, Wareham NJ, Brage S. Autocalibration of -accelerometer data for free-living physical activity assessment using -local gravity and temperature: an evaluation on four continents. J Appl -Physiol (1985). 2014 Oct 1;117(7):738-44. PMID: 25103964 link -
    • -
-

Key decisions to be made:

-
    -
  1. Whether to apply auto-calibration or not (default and recommended -setting is YES). You can turn this off by setting argument -do.call in GGIR to -do.call=FALSE.
    2. -
  2. Other variables are probably best left in their default setting
    3. -
-

Key output variables:

-
    -
  1. Variable value cal.error.end as stored in -data_quality_report.csv or variable value calib_err in summary.csv. -These should be less than 0.01 g (10mg).
    2. -
-
-
-

Non-wear detection -

-

Accelerometer non-wear time is detected on the basis of statistics -derived from a rolling time window. A step in time is classified as -non-wear if both of the following criteria are met for at least two out -of the three accelerometer axes:

-
    -
  • The standard deviation of the accelerations is less than -accelerometer brand specific reference values, which for most brands is -13.0 mg (\(1 mg = 0.00981 -m·s^−2\))
    • -
  • The range of accelerations (i.e., maximum value minus -minimum value) is less than 50 mg.
    • -
-

The size of the rolling time window and the size of the steps it -takes in time are defined by argument windowsizes, a vector -with length three. More specifically, the second value (mediumsize -window, default = 15 min) and the third value (longsize window, default -= 60 min) are used.

-

How it then labels the data depends on the non-wear approach taken as -discussed below, and specified with argument -nonwear_approach. At the moment there are two approaches to -detect non-wear: nonwear_approach = "2013" and -nonwear_approach = "2023".

-
-

Approaches to detect non-wear: 2013 and 2023 algorithms -

-

nonwear_approach = “2013”

-

The 2013 approach is a revision of the approach first described in -the 2011 -PLoSONE publication. It uses the criteria derived from the longsize -window centered around each mediumsize window (default = 15 minutes) to -classify each mediumsize window at its centre.

-

The modification of the algorithm in 2013 relative to 2011 -included:

-
    -
  • The longsize window changed from 30 minutes to 60 minutes to -decrease the chance of accidentally detecting short sedentary periods as -non-wear time.
    • -
  • The rolling window went from non-overlapping to overlapping (15 -minute steps of a 60 minute window results in a longsize window overlap -between step of 22.5 minutes) to improve the time resolution.
    • -
-

nonwear_approach = “2023”

-

The 2023 version of the algorithm uses the criteria applied to the -longsize window to assign a nonwear score to the entire longsize window -(default = 60 minutes) being tested. Instead of centering the longsize -window in the middle of the mediumsize window, the 2023 method aligns -the longsizewindow with its left edge to the left edge of the mediumsize -window. As a result, each point in time is classified multiple times -given that multiple steps of the rolling window classification will -overlap with it. If the nonwear criteria are met for any of these -windows that overlap with a point in time, it will be labelled as -nonwear.

-
-
-

Additional non-wear -

-

Inspection of unpublished data on non-wear classification by the -algorithm as described in our published work indicated that the -algorithm does not cope well with periods of monitor transportation per -post. Here, long periods of non-wear are briefly interrupted by periods -of movement, which are normally interpreted as monitor wear. Therefore, -the algorithm was expanded with an additional stage in which the -plausibility of “wear-periods” in-between non-wear periods is tested. -Short periods of detected wear-time in-between longer periods of -detected non-wear were classified as non-wear time based on the duration -and the proportion of the duration relative to the bordering periods of -detected non-wear-periods. The following criteria were derived from -visual observation of various datasets using knowledge about study -protocols. All detected wear-periods of less than six hours and less -than 30% of the combined duration of their bordering non-wear periods -were classified as non-wear. Additionally, all wear-periods of less than -three hours and which formed less than 80% of their bordering non-wear -periods were classified as non-wear. The motivation for selecting a -relatively high criteria (< 30%) in combination with a long period -(6hrs) and a low criteria (< 80%) in combination with a short period -(3 hrs) was that long period are more likely to be actually related to -monitor wear time. A visual model was created, see picture below. Here, -units of time are presented in squares and marked grey if detected as -non-wear time. Period C is detected as wear-time and borders to non-wear -periods B and D. If the length of C is less than six hours and C divided -by the sum of B and D is less than 0.3 then the first criteria is met -and block C is turned into a non-wear period.

-

-
-
-

Beginning and ending of the recording -

-

By visual inspection of >100 traces from a large observational -study it turned out that applying this stage in three iterative stages -allowed for improved classification of periods characterised by -intermittent periods of non-wear and apparent wear. Further, an -additional rule was introduced for the final 24 hours of each -measurement. The final 24 hours are often considered the period in which -the accelerometer is potentially taken off but moved because of -transportation, e.g. by the mail service. All wear-periods in the final -24 hrs of each measurement shorter than three hours and preceded by at -least one hour of non-wear time were classified as non-wear.

-

Finally, if the measurement starts or ends with a period of less than -three hours of wear followed by non-wear (any length) then this period -of wear is classified as non-wear. These additional criteria for -screening the beginning and end of the accelerometer file reflect the -likelihood of movements that are involved when starting the -accelerometer or downloading the data from the accelerometer. This final -check can be turned off with argument -nonWearEdgeCorrection.

-

Reference:

-
    -
  • van Hees VT, Gorzelniak L, Dean León EC, Eder M, Pias M, Taherian S, -Ekelund U, Renström F, Franks PW, Horsch A, Brage S. Separating movement -and gravity components in an acceleration signal and implications for -the assessment of human daily physical activity. PLoS -One. 2013 Apr 23.
    • -
-

Key decisions to be made:

-
    -
  1. Size of windows
    2. -
  2. Whether to utilize the non-wear detection
    3. -
  3. Non-wear approach (either 2013 or 2023)
    4. -
-

Key output variables:

-
    -
  1. Raw classification
    2. -
  2. Non-wear duration
    3. -
  3. Non-wear duration taking into account the protocol
    4. -
-
-
-
-

Clipping score -

-

GGIR also screens the acceleration signal for “clipping”. If more -than 50% of the data points in a mediumsize window (default = 15 -minutes) are close to the maximal dynamic range of this sensor the -corresponding time period is considered as potentially corrupt data, -which may be explained by the sensor getting stuck at its extreme value. -For example, for a dynamic range of 8g, accelerations over -7.5g would be marked as “clipping”.

-

Reference:

-
    -
  • van Hees VT, Gorzelniak L, Dean León EC, Eder M, Pias M, Taherian S, -Ekelund U, Renström F, Franks PW, Horsch A, Brage S. Separating movement -and gravity components in an acceleration signal and implications for -the assessment of human daily physical activity. PLoS -One. 2013 Apr 23 -
    • -
-
-
-

Why collapse information to epoch level? -

-

Although many data points are collected we decide to only work with -aggregated values (e.g. 1 or 5 second epochs) for the following -reasons:

-
    -

  1. Accelerometers are often used to describe patterns in metabolic -energy expenditure. Metabolic energy expenditure is typically defined -per breath or per minute (indirect calorimetry), per day (room -calorimeter), or per multiple days (doubly labelled water method). In -order to validate our methods against these reference standards we need -to work with a similar time resolution.

    2. -

  2. Collapsing the data to epoch summary measures helps to -standardise for differences in sample frequency between -studies.

    3. -

  3. There is little evidence that the raw data is an accurate -representation of body acceleration. All scientific evidence on the -validity of accelerometer data has so far been based on epoch -averages.

    4. -

  4. Collapsing the data to epoch summary measures may help to average -out different noise levels and make sensor brands more -comparable.

    5. -
-
-

Why does the first epoch not allign with the original start of the -recording -

-

GGIR uses short (default 5 seconds) and long epochs (default 15 -minutes). The epochs are aligned to the hour in the day, and to each -other. For example, if a recording starts at 9:52:00 then the GGIR will -work with epochs derived from 10:00:00 onward. If the recording starts -at 10:12 then GGIR will work with epochs derived from 10:15:00 -onward.

-

Motivation:

-
    -
  • This allows us to have a standardised time grid across recordings to -describe behaviour.
    • -
  • This allows us to calculate behaviour exactly per day or per -specified time interval in a day.
    • -
-

If the first 15 minute epochs would start at 9:52 then the next one -would start at 10:07, which makes it impossible to make statement about -behaviour between 10:00 and 13:00.

-
-
-
-

Sleep analysis -

-

In GGIR sleep analysis has been implemented in part 3 and 4. Sleep -analysis comes at two levels: The identification of the main Sleep -Period Time (SPT) window or the time in bed window (TIB), and the -discrimination of sleep and wakefulness periods. The term sleep is -somewhat controversial in the context of accelerometry, because -accelerometer only capture lack of movement. To acknowledge this -challenge GGIR refers to these classified sleep periods as -sustained inactivity bouts (abbreviated as SIB).

-

Current, GGIR offers the user the choice to identify SIB period using -any of the following algorithms:

-
    -
  • -vanHees2015: Heuristic algorithm proposed in 2015 -link which -looks for periods of time where the z-angle does not change by more than -5 degrees for at least 5 minutes. This in contrast to conventional sleep -detection algorithms such as Sadeh, Galland, and ColeKripke which rely -on acceleration to estimate sleep. The vanHees2015 algorithm is the -default.
    • -
  • -Sadeh1994: The algorithm proposed by Sadeh et al. -link. To use the -GGIR implementation of the zero-crossing counts and Sadeh algorithm, -specify argument HASIB.algo = "Sadeh1994" and argument -Sadeh_axis = "Y" to indicate that the algorithm should use -the Y-axis of the sensor.
    • -
  • -Galland2012: The count-scaled algorithm proposed by -Galland et al. link. To use -our implementation of the Galland2012 algorithm specify argument -HASIB.algo = "Galland2012". Further, set -Sadeh_axis = "Y" to specify that the algorithm should use -the Y-axis.
    • -
  • -ColeKripke1992: The algorithm proposed by Cole et -al. link, more -specifically GGIR uses the algortihm proposed in the paper for 10-second -non-overlapping epochs with counts e xpressed average per minute. We -skip the re-scoring steps as the paper showed marginal added value of -this added complexity. To use the GGIR implementation of the -zero-crossing counts and Sadeh algorithm, specify argument -HASIB.algo = "ColeKripke1992" and argument -Sadeh_axis = "Y" to indicate that the algorithm should use -the Y-axis of the sensor.
    • -
  • -NotWorn: This algorithm can be used if the study -protocol was to not wear the accelerometer at night. GGIR will then look -for hours with close to zero movement and treat those as sustained -inactivity bouts. It should be obvious that this does not facilitate any -meaningful sleep analysis but it does allow GGIR to then run GGIR part 5 -based on the assumption that this analysis helped to isolate night time -from daytime.
    • -
-
-

Notes on sleep classification algorithms designed for count -data -

-
-
Replication of the movement counts needed -
-

The implementation of the zero-crossing count in GGIR is not an exact -copy of the original approach as used in the AMA-32 Motionlogger -Actigraph by Ambulatory-monitoring Inc. (“AMI”) that was used in the -studies by Sadeh, Cole, Kripke and colleagues in late 1980s and 1990s. -No complete publicly accessible description of that approach exists. -From personal correspondence with AMI, we learnt that the technique has -been kept proprietary and has never been shared with or sold to other -actigraphy manufacturers (time of correspondence October 2021). -Therefore, if you would like to replicate the exact zero-crossing counts -calculation used by Sadeh and colleague’s consider using AMI’s actigraph -device (you will have to trust AMI that hardware has not changed since -the 1980s). However, if you prioritise openness over methodological -consistency with the original studies by Sadeh, Cole, and colleagues -then you may want to consider any of the open source techniques in this -library.

-
-
-
Missing information for replicating movement counts -
-

More specifically, the missing information about the calculation -includes: (1) Sadeh specified that calculations were done on data from -the Y-axis but the direction of the Y-axis was not clarified. Therefore, -it is unclear whether the Y-axis at the time corresponds to the Y-axis -of modern sensors, (2) Properties of the frequency filter are missing -like the filter order and more generally it is unclear how to simulate -original acceleration sensor behaviour with modern sensor data, and (3) -Sensitivity of the sensor, we are now guessing that the Motionlogger had -a sensitivity of 0.01 g but without direct proof.

-

The method proposed by Galland and colleagues in 2012 was designed -for counts captured with the Actical device (Mini Mitter Co, Inc Bend -OR). Based on the correspondence with AMI we can conclude that Actical -counts are not identical to AMI’s actigraph counts. Further, a publicly -accessible complete description of the Actical calculation does not -exist. Therefore, we can also conclude that methodological consistency -cannot be guaranteed for Actical counts.

-
-
-
An educated guess and how you can to help optimise the -implementation -
-

Following the above challenges the implementation of the -zero-crossing count in GGIR is based on an educated guess where we used -all information we could find in literature and product documentation. -In our own evaluation the zero-crossing count value range looks -plausible when compared to the value range in the original -publications.

-

How you can help to optimise the implementation:

-

Given the uncertainties surrounding the older sleep algorithm we -encourage GGIR users to evaluate and help optimise the algorithms. Here, -we have the following suggestions:

-
    -
  • For ActiGraph users, when comparing GGIR Cole-Kripke estimates with -ActiLife Cole Kripke estimate be aware that ActiLife may have adopted a -different Cole-Kripke algorithm as the original publication presented -four algorithms. Further, ActiLife may have used different educated -guesses about how Motionlogger counts are calculated.
    • -
  • Compare GGIR sleep estimate with Polysomnography or Motionlogger -output and try to optimise the zero crossing count parameters as -discussed below.
    • -
-

Input argument to aid in the optimisation:

-

To aid research in exploring count type algorithms, we also -implemented the brondcounts as proposed by Brønd and -Brondeel and available via R package activityCounts, as well as the -neishabouricounts that follows the algorithm implemented in -the close-source software ActiLife by ActiGraph and is available in the -R package actilifecounts. DISCLAIMER: the brondcounts option has been -deprecated as of October2022 due to issues with the activityCounts -package it relies on. We will reactivate brondcounts once the issues are -resolved. To extract these metrics in addition to the zero crossing -count, specify do.brondcounts = TRUE and/or -do.neishabouricounts = TRUE which is used in GGIR part 1 -and uses R packages activityCounts and actilifecounts in the background. -As a result, sleep estimates for Sadeh, Cole-Kripke or Galland will be -derived based on the zero crossing algorithm and additionally on the -brondcounts or/and actilifecounts algorithms -if requested by the user. Further, we have added parameters to help -modify the configuration of the zero-crossing count calculation, see -arguments: zc.lb, zc.hb, zc.sb, -zc/order, and zc.scale. As well as one -parameter to modify the neishabouricounts calculation, see argument: -actilife_LFE.

-
-
-
-

Guiders -

-

SIBs (explained above) can occur anytime in the day. In order to -differentiate SIBs that correspond to daytime rest/naps from SIBs that -correspond to the main Sleep Period Time window (abbreviated as SPT), a -guiding method referred as guider is used. All SIBs -that overlap with the window defined by guider are considered as sleep -within the SPT window. The start of the first SIB identified as sleep -period and the end of the last SIB identified as sleep period define the -beginning and the end of the SPT window. In this way the classification -relies on the accelerometer for detecting the timing of sleep onset and -waking up time, but the guider tells it in what part of the day it -should look, as SPT window will be defined only if SIB is detected -during the guider specified window.

-

If a guider reflects the Time in Bed the interpretation of the Sleep -Period Time, Sleep onset time and Wakeup time remains unchanged. -However, we can then also assess sleep latency and and sleep efficiency, -which will be included in the report.

-

The guiding method as introduced above can be one of the following -methods:

-
    -
  • -Guider = sleep log: As presented in before mentioned -2015 article.See section on sleep analysis -related arguments for a discussion fo sleep log data formats. -Specify argument sleepwindowType to clarify whether the -sleeplog capture “TimeInBed” or “SPT”. If it is set to “TimeInBed”, GGIR -will automatically expand its part 4 analyses with sleep latency and -sleep efficiency assessment.
    • -
  • -Guider = HDCZA: As presented in our 2018 -article. The HDCZA algorithm does not require access to a sleep log, -and is designed for studies where no sleep log is available. The time -segment over which the HDCZA is derived are by default from noon to -noon. However, if the HDCZA ends between 11am and noon then it will be -applied again but to a 6pm-6pm window.
    • -
  • -Guider = L5+/-12: As presented in our 2018 -article. Twelve hour window centred around the least active 5 hours -of the day.
    • -
  • -Guider = setwindow: Window times are specified by -user, constant at specific clock times with argument -def.noc.sleep.
    • -
  • -Guider = HorAngle: Only used if argument -sensor.location="hip", because this will trigger the -identification of the longitudinal axis based on 24-hour lagged -correlation. You can also force GGIR to use a specific axis as -longitudinal axis with argument longitudinal_axis. Next, it -identifies when the horizontal axis is between -45 and 45 degrees and -considers this a horizontal posture. Next, this is used to identify the -largest time in bed period, by only considering horizontal time segments -of at least 30 minutes, and then looking for longest horizontal period -in the day where gaps of less than 60 minutes are ignored. Therefore, it -is partially similar to the HDCZA algorithm. When “HorAngle” is used, -sleepwindowType is automatically set to “TimeInBed”.
    • -
  • -Guider = NotWorn: Used for studies where the -instruction was not to wear the accelerometer durating the night. GGIR -then searches for the longest period with zero movement.
    • -
-

For all guiders other than “HorAngle” and “sleep log” argument -sleepwindowType is automatically switched to “SPT”, such -that no attempt is made to estimate sleep latency or sleep -efficiency.

-

GGIR uses by default the sleep log, if the sleep log is not available -it falls back on the HDCZA algorithm (or HorAngle if -sensor.location="hip"). If HDCZA is not successful GGIR -will falls back on the L5+/-12 definition, and if this is not available -it will use the setwindow. The user can specify the priority with -argument def.noc.sleep. So, when we refer to guider then we -refer to one of these five methods.

-
-
-

Daysleepers (nights workers) -

-

If the guider indicates that the person woke up after noon, the sleep -analysis in part 4 is performed again on a window from 6pm-6pm. In this -way our method is sensitive to people who have their main sleep period -starting before noon and ending after noon, referred as daysleeper=1 in -daysummary.csv file, which you can interpret as night workers. Note that -the L5+/-12 algorithm is not configured to identify daysleepers, it will -only consider the noon-noon time window.

-
-
-

Cleaningcode -

-

To monitor possible problems with the sleep assessment, the variable -cleaningcode is recorded for each night. Cleaningcode -per night (noon-noon or 6pm-6pm as described above) can have one of the -following values:

-
    -
  • 0: no problem, sleep log available and SPT is identified;
    • -
  • 1: sleep log not available, thus HDCZA is used and SPT is -identified,
    • -
  • 2: not enough valid accelerometer data based on the non-wear and -clipping detection from part summarised over the present night where the -argument includenightcrit indicates the minimum number of -hours of valid data needed within those 24 hours.
    • -
  • 3: no accelerometer data available,
    • -
  • 4: there were no nights to be analysed for this person,
    • -
  • 5: SPT estimated based on guider only, because either no SIB was -found during the entire guider window, which complicates defining the -start and end of the SPT, or the user specified the ID number of the -recording and the night number in the data_cleaning_file to tell GGIR to rely -on the guider and not rely on the accelerometer data for this particular -night
    • -
  • 6: no sleep log available and HDCZA also failed for this specific -night then use average of HDCZA estimates from other nights in the -recording as guider for this night. If HDCZA estimates are not available -during the entire recording then use L5+/-12 estimate for this night. -The last scenario seems highly unlikely in a recording where the -accelerometer was worn for at least one day.
    • -
-
-
-

Difference between cleaned and full output -

-

All the information for each night is stored in the -results/QC folder allowing tracing of the data analysis and -night selection. The cleaned results stored in the results folder. In -part 4 a night is excluded from the ‘cleaned’ results based on the -following criteria:

-
    -
  • If the study proposed a sleep log to the individuals, then nights -are excluded for which the sleep log was not used as a guider (i.o.w. -nights with cleaningcode not equal to 0 or variable sleep log used -equals FALSE).
    • -
  • If the study did not propose a sleep log to the individuals, then -all nights are removed with cleaningcode higher than 1.
    • -
-

Be aware that if using the full output and working with wrist -accelerometer data, then missing entries in a sleep log that asks for -Time in Bed will be replaced by HDCZA estimates of SPT. Therefore, extra -caution should be taken when working with the full output.

-

Notice that part 4 is focused on sleep research, by which the cleaned -reported is the way it is. In the next section we will discuss the -analysis done by part 5. There, the choice of guider may be considered -less important, by which we use different criteria for including nights. -So, you may see that a night that is excluded from the cleaned results -in part 4 still appears in the cleaned results for part 5.

-
-
-

Data cleaning file -

-

The package allows some adjustments to be made after data quality -check. The data_cleaning_file argument allows you to -specify individuals and nights for whom part4 should entirely rely on -the guider (for example if we decide to use sleep log only information). -The first column of this file should have header ID and -there should be a column relyonguider_part4 to specify the -night. The data_cleaning_file allows you to tell GGIR which -person(s) and night(s) should be omitted in part 4. The the night -numbers to be excluded should be listed in a column -night_part4 as header.

-
-
-
-

Waking-waking or 24 hour time-use analysis -

-

In part 5 the sleep estimates from part 4 are used to describe -24-hour time use. Part 5 allows you to do this in two ways: Literally 24 -hours which start and end a calendar day (default midnight, but -modifiable with argument dayborder) or from waking up to -waking up. In GGIR we refer to the former as MM windows -and to the latter as WW windows. The onset and waking -times are guided by the estimates from part 4, but if they are missing -part 5 will attempt to retrieve the estimate from the guider method, -because even if the accelerometer was not worn during the night, or a -sleep log is missing in a study where sleep log was proposed to the -participants, estimates from a sleep log or HDCZA can still be -considered a reasonable estimate of the SPT window in the context of -24-hour time use analysis.

-

If WW is used in combination with ignoring the first and last -midnight, argument excludefirstlast, then the first wake-up -time (on the second recording day) needs to be extracted for the first -WW day. This is done with the guider method. This also means that the -last WW window ends on the before last morning of the recording.

-

A distinction is made between the full results stored in the -results/QC folder and the cleaned results stored in the -results folder.

-
-

Time series output files -

-

If you want to inspect the time series corresponding to these windows -then see argument save_ms5rawlevels, which allows you to -export the time series including behavioral classes and non-wear -information to csv files. The behavioral classes are included as -numbers, the legend for these classes is stored as a separate legend -file in the meta/ms5.outraw folder named “behavioralcodes2020-04-26.csv” -where the date will correspond to the date of analysis.

-

Additional input arguments that may be of -interest:

-
    -
  • -save_ms5raw_format is a character string to specify how -data should be stored: either “csv” (default) or “RData”. Only used if -save_ms5rawlevels=TRUE.
    • -
  • -save_ms5raw_without_invalid is Boolean to indicate -whether to remove invalid days from the time series output files. Only -used if save_ms5rawlevels=TRUE.
    • -
-

The time series output file comes with the following -columns:

- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Column nameDescription
timenumTime stamp in UTC time format (i.e., seconds since 1970-01-01). To -convert timenum to time stamp format, you need to specify your desired -time zone, e.g., -as.POSIXct(mdat$timenum, tz = "Europe/London").
ACCAverage acceleration metric selected by acc.metric, -default = “ENMO”.
SleepPeriodTimeIs 1 if SPT is detected, 0 if not. Note that this refers to the -combined usage of guider and detected sustained inactivity bouts (rest -periods).
invalidepochIs 1 if epoch was detect as invalid (e.g. non-wear), 0 if not.
guiderIs 1 if guider method detect epoch as SPT (e.g. sleeplog, HDCZA), 0 -if not. You will not find here which guider is used, for this see other -GGIR output.
windowNumeric indicator of the analysis window in the recording. If -timewindow = “MM” then these correspond to calendar days, if timewindow -= “WW” then these correspond to which wakingup-wakingup window in the -recording, if timewindow = “OO” then these correspond to which -sleeponset-sleeponset window in the recording. So, in a recording of one -week you may find window numbers 1, 2, 3, 4, 5 and 6.
class_idThe behavioural class codes are documented in the exported csv file -meta/ms5outraw/behaviouralcodes.csv. Class codes above class 8 will be -analysis specific, because it depends on the number time variants of the -bouts used. For example, if you look at MVPA lasting 1-10, 10-20, 30-40 -then all of them will have their own class_id.
invalid_fullwindowFraction of the window (see above) that represents invalid data. I -added this to make it easier to filter the timeseries based on whether -days are valid or not.
invalid_sleepperiodFraction of SPT within the current window that represents invalid -data.
invalid_wakinghoursFraction of SPT within the current window that represents invalid -data.
timestampTime stamp derived from converting the column timenum, only -available if save_ms5raw_format = TRUE.
-

To familiarize yourself with how the variables it can be helpful to -plot them yourself.

-

For users we also want to export the time serie sof multiple metric -values see argument epochvalues2csv which relates to the -storage of time series in GGIR part 2.

-
-
-

Day inclusion criteria -

-

The full part 5 output is stored in the results/QC -folder. The default inclusion criteria for days in the cleaned output -from part 5 (stored in the results folder) are:

-
    -
  • For both MM and WW defined days: The valid (sensor worn) time -fraction of the day needs to be above the fraction specified with -argument includedaycrit.part5 (default 2/3).
    • -
  • For MM defined days only: The length of the day needs to be at least -the number of hours as specified by minimum_MM_length.part5 -(default 23). Note that if your experiment started and ended in the -middle of the day then this default setting will exclude those -incomplete first and last days. If you think including these days is -still meaningful for your work then adjust the argument -minimum_MM_length.part5.
    • -
-

Important notes:

-
    -
  • No criteria is set for the amount of valid data during the SPT -window, because all we are interested in part 5 is knowing the borders -of the night and we trust that this was sufficiently estimated by part -4. If you disagree then please notice that all the days are included in -the full report available in results/QC folder.
    • -
  • This means that argument includenightcrit as used for -part 4 is not used in part 5.
    • -
-

The data_cleaning_file argument discussed in Data_cleaning_file also allows you to -tell GGIR which person(s) and day(s) should be omitted in part 5. The -the day numbers to be excluded should be listed in a column -day_part5 as header.

-
-
-

Fragmentation metrics -

-

When setting input argument as frag.metrics="all" GGIR -part 5 will perform behavioural fragmentation analysis for daytime and -(separately) for spt. Do this in combination with argument -part5_agg2_60seconds=TRUE as that will aggregate the time -series to 1 minute resolution as is common in behavioural fragmentation -literature.

-

In GGIR, a fragment for daytime is a defined as a sequence of epochs -that belong to one of the four categories:

-
    -
  1. Inactivity
    2. -
  2. Light Physical Activity (LIPA)
    3. -
  3. Moderate or Vigorous Physical Acitivty (MVPA)
    4. -
  4. Physical activity (can be either LIPA or MVPA)
    5. -
-

Each of these categories represents the combination of bouted and -unbouted time in the respective categories. Inactivity and physical -activity add up to a full day (outside SPT), as well as inactivity, LIPA -and MVPA. The fragmentation metrics are applied in function -g.fragmentation.

-

A fragment of SPT is defined as a sequence of epochs that belong to -one of the four categories: 1. Estimated sleep 2. Estimated wakefulness -3. Inactivity 4. Physical activity (can be either LIPA or MVPA)

-

Note that from the metrics below only fragmentation metrics TP and -NFrag are calculated for the SPT fragments.

-

Literature about these metrics:

-
    -
  • Coefficient of Variance (CoV) is calculated according -to Blikman et al. -2014.
    • -
  • Transition probability (TP) from Inactivity (IN) to -Physical activity (IN2PA) and from Physical activity to inactivity -(PA2IN) are calculated as 1 divided by the mean fragment duration. The -transition probability from Inactivity to LIPA and MVPA are calculated -as: (Total duration in IN followed by LIPA or MVPA, respectively, -divided by total duration in IN) divided by the average duration in -IN.
    • -
  • Gini index is calculated with function Gini from the -ineq R package, and with it’s argument corr -set to TRUE.
    • -
  • Power law exponent metrics: Alpha, x0.5, and W0.5 are calculated -according to Chastin et al. -2010.
    • -
  • Number of fragment per minutes (NFragPM) is calculated -identical to metric fragmentation in Chastin et -al. 2012, but it is renamed here to be a more specific reflection of -the calculation. The term fragmentation appears too generic -given that all fragmentation metrics inform us about fragmentation. -Please not that this is effectively the same metric as the transition -probability, because total number divided by total sum in duration -equals 1 divided by average duration. This is just different terminology -for the same construct.
    • -
-

Conditions for calculation and value when condition is not -met:

-
    -
  • Metrics Gini and CoV are only calculated -if there are at least 10 fragments (e.g. 5 inactive and 5 active). If -this condition is not met the metric value will be set to missing.
    • -
  • Metrics related to power law exponent alpha are also only calculated -when there are at least 10 fragments, but with the additional condition -that the standard deviation in fragment duration is not zero. If these -conditions are not met the metric value will be set to missing.
    • -
  • Other metrics related to binary fragmentation -(mean_dur_PA and mean_dur_IN), are calculated -when there are at least 2 fragments (1 inactive, 1 active). If this -condition is not met the value will is set to zero.
    • -
  • Metrics related to TP are calculated if: There is at -least 1 inactivity fragment AND (1 LIPA OR 1 MVPA fragment). If this -condition is not met the TP metric value is set to -zero.
    • -
-

To keep an overview of which recording days met the criteria for -non-zero standard deviation and at least ten fragments, GGIR part5 -stores variable Nvaliddays_AL10F at person level (=Number -of valid days with at least 10 fragments), and SD_dur -(=standard deviation of fragment durations) at day level as well as -aggregated per person.

-

Difference between fragments and blocks:

-

Elsewhere in the part5 we use the term block. A -block is a sequence of epochs that belong to the same -behavioural class. This may sound similar to the definition of a -fragment, but for blocks we distinguish every behavioural class, which -includes the subcategories such as bouted and unbouted behaviour. This -means that variables Nblock_day_total_IN and -Nblock_day_total_LIG are identical to -Nfrag_IN_day and Nfrag_LIPA_day, respectively. -In contrast, for fragments we may group LIPA and MVPA together when -refering to the fragmentation of PA.

-

Differences with R package ActFrag:

-

The fragmentation functionality is loosely inspired on the great work -done by Dr. Junrui Di and colleages in R package ActFrag, as described -in Junrui Di -et al. 2017.

-

However, we made a couple of a different decisions that may affect -comparability:

-
    -
  • GGIR derives fragmentation metrics per day. This allows us to avoid -the issue of gaps between days that need to be dealt with. Further, it -allows us to test for behavioural differences between days of the week. -It is well known that human behaviour can be driven by weekly rhythms, -e.g. work days versus weekend. Estimating fragmentation per day of the -week allows us to study and account for such possible variation. As with -all other GGIR variables we also report recording level aggregates of -the daily estimates.
    • -
  • Transition probability is according to Lim et al. 2011 -
    • -
  • Power law alpha exponent metrics were calculated according to Chastin et al. -2010 using the theoretical minimum fragment duration instead of the -observed minimum fragment duration.
    • -
-
-
-
-

Why use data metric ENMO as default? -

-

GGIR offers a range of acceleration metrics to choose from, but only -one metric can be the default. Acceleration metric ENMO (Euclidean Norm -Minus One with negative values rounded to zero) has been the default -metric in GGIR. In 2013 we wrote a paper in which we investigated -different ways of summarising the raw acceleration data. In short, -different metrics exist and there is very little literature to support -the superiority of any metric at the time. As long as different studies -use different metrics their findings will not be comparable. Therefore, -the choice for metric ENMO is partially pragmatic. GGIR uses ENMO as -default because:

-
    -
  1. ENMO has demonstrated value in describing variance in energy -expenditure, correlated with questionnaire data, able to describe -patterns in physical activity
    2. -
  2. ENMO is easy to describe mathematically and by that improves -reproducibility across studies and software tools
    3. -
  3. ENMO attempts to quantify the actual biomechanical acceleration in -universal units.
    4. -
  4. The 2013 paper showed that when ENMO is used in combination with -auto-calibration it has similar validity to filter-based metrics like -HFEN and BFEN, which are conceptually similar to metrics proposed later -such as MIMSunit, MAD, AI0.
    5. -
  5. Studies who have criticised ENMO consistently failed to apply -auto-calibration, or attempted to apply auto-calibration in a lab -setting, ignoring the fact that the auto-calibration is not designed for -short lasting lab settings. It needs free-living data to work properly. -Further, studies are often not clear about how the problematic zero -imputation during the idle sleep mode in ActiGraph devices is dealt -with. See for a more detailed discussion on this the paragraph: Published -cut-points and how to use them.
    6. -
-

See also this -blog post on this topic.

-
-
-

What does GGIR stand for? -

-

I wanted a short name and not to spend too much time finding it. At -the time I was primarily working with GENEActiv and GENEA data In R, and -that’s how the name GGIR was born: Short, easy to remember, and as -acronym sufficiently vague to not be tight up with a specific -functionality. However, later the functionality expanded to other sensor -brands, so the abbreviation has lost its functional meaning.

-
-
-

Circadian Rhythm analyses -

-
-

MXLX -

-

Detection of the continuous least (LX) and most (MX) active X hours -in a day, where X is defined by argument winhr. For both -GGIR calculates the average acceleration, the start time, and if -argument iglevels is specified also the intensity gradient. -If argument winhr is a vector then descriptive values for -LX and MX are derived per value in winhr. Within GGIR part -2 MXLX is calculated per calendar day and, if argument -qwindow is specified, per segment of the day. Within GGIR -part 5 MXLX is calculated per window, and if used in combination with -the GENEActiv or Axivity accelerometer brand LUX estimates per LX and MX -are included.

-

The MX metric describe here should not be confused by the MX metrics -as proposed by Rowlands et al. -which looks at accumulated most active time which may not always be -continuous in time. The MX metrics by Rowlands et all are discussed -further down.

-
-
-

Cosinor analysis and Extended Cosinor analysis -

-

The (Extended) Cosinor analysis quantifies the circadian 24 hour -cycle. To do this GGIR uses R package ActCR as a -dependency. Specify argument cosinor = TRUE to perform -these analysis.

-

The implementation within GGIR part 2 is as follows:

-
    -
  • Acceleration values are averaged per minute, and then log -transformation as -log(acceleration converted to _mg_ + 1).
    • -
  • Invalid data points such as caused by non-wear are set to missing -(NA) in order to prevent the imputation approach used elsewhere in GGIR -to influence the Cosinor analysis. We do this because imputation -technique generally come with some assumptions about circadian -rhythm.
    • -
  • GGIR looks for the first valid data point in the recording and then -selects the maximum integer number of recording days following this data -point and feeds these to the ActCosinor and ActExtendCosinor functions -of ActCR. The time offset between the start and the following midnight -is then used to reverse offset the ActCR results, to ensure that -acrophase and acrotime can be interpreted relative to midnight.
    • -
  • In relation to Day Saving Time: Duplicated time stamps when clock -moves backward are ignored and missing time stamps when clock moves -forward are inserted as missing values.
    • -
  • Time series corresponding to the fitted models are stored inside the -part 2 milestone data to facilitate visual inspection. For the moment -they are not used in any GGIR visualisation, but you may want to look -them up and try to plot them yourself.
    • -
-
-
-

Intradaily Variability (IV) and Interdaily Stability (IS) -

-
-
IV and IS - Default -
-

The original implementation (argument IVIS.activity.metric = 1) uses -the continuous numeric acceleration values. However, as we later -realised this is not compatible with the original approach by van -Someren and colleagues, which uses a binary distinction between active -and inactive. Therefore, a second option was added (argument -IVIS.activity.metric = 2), which needs to be used in combination with -accelerometer metric ENMO, and collapses the acceleration values into a -binary score of rest versus active. This is the current default.

-
-
-
IV and IS - Cosinor analysis compatible -
-

Disclaimer: The following has been implemented 2022, but is currently -undergoing critical evaluation. As a result, we may update this -algorithm during the course of 2023.

-

IS is sometimes used as a measure of behavioural robustness when -conducting Cosinor analysis. However, to work with the combination of -the two outcomes it seems important that IS is calculated from the same -time series. Therefore, when cosinor = TRUE IV and IS are -calculated twice: Once as part of the default IV and IS analysis as -discussed above, and once as part of the Cosinor analysis using the same -log transformed time series. More specifically, the IV and IS algorithm -is applied with IVIS.activity.metric = 2 and -IVIS_acc_threshold = log(20 + 1) to make the binary -distinction between active and inactive, and -IVIS_per_daypair = TRUE. The setting -IVIS_per_daypair was specifically designed for this context -to handle the potentially missing values in the time series as used for -Cosinor analysis. Applying the default IVIS algorithm would not be able -to handle the missing values and would result in a loss of information -if all non-matching epochs across the entire recording were excluded. -Instead, IV and IS are calculated as follows:

-
    -
  1. Per day pair based on matching valid epochs only IV and IS and -calculated. Here, a log is kept of the number of valid epoch per day -pair.
    2. -
  2. Omit day pairs where the fraction of valid epoch pairs is below 0.66 -(0.66 is hard-coded at the moment).
    3. -
  3. Calculate average IS across days weighted by fraction of valid -epochs per day pairs.
    4. -
-

The new Cosinor-compatible IV and IS estimates are stored as output -variables cosinorIV and cosinorIS.

-
-
-
-
-

ActiGraph’s idle sleep mode -

-

The idle sleep mode is explained -on the manufacturer’s website. In short, idle sleep mode is a setting -that can be turned on or off by the user. When it is turned on the -device will fall asleep during periods of no movement, resulting in time -gaps in the data. This functionality was probably introduced to safe -battery life and minimize data size. However, it also means that we end -up with time gaps that need to be accounted for.

-
-

Time gap imputation -

-

Studies done with ActiGraph devices when configured with ‘idle sleep -mode’ and with data exported to .csv by the commerical ActiLife software -will have imputed values in all three axes during periods of no -movement. Note that the imputation by the ActiLife software has changed -at some point in time. Initially the imputation was zeros but with more -recent versions of ActiLife the imputation uses the last recorded value -for each axes.

-

When processing gt3x files that have time gaps GGIR takes care of the -time gap imputation: Time gaps shorter than 90 minutes are imputed at -raw data level with the last known recorded value before the timeg gap, -while longer time gaps are imputed at epoch level. We do this to make -the data processing more memory efficient and faster.

-

Time gaps in the data are considered non-wear time in GGIR, this -implies that we trust the ActiGraph sleep mode to only be activated when -the device is not worn, although there is always a risk of -sleep/sedentary misclassification.

-
-
-

The importance of reporting idle.sleep.mode usage -

-

Studies often forget to clarify whether idle sleep mode was used and -if so, how it was accounted for in the data processing. Especially, the -insertion of zero strings is problematic as raw data accelerometers -should always measure the gravitational component when not moving. This -directly impacts metrics that rely on the presence of a gravitational -component such as ENMO, EN, ENMOa, SVMgs, and angles. Further, also -other metrics may be affected as the sudden disappearance of -gravitational acceleration will cause a spike at the start and end of -the idle sleep mode period. More generally speaking, we advise ActiGraph -users to:

-
    -
  • Disable the ‘idle sleep mode’ as it harms the transparency and -reproducibility since no mechanism exists to replicate it in other -accelerometer brands, and it is likely to challenge accurate assessment -of sleep and sedentary behaviour.
    • -
  • That data collected with ‘idle sleep mode’ turned on is not be -referred to as raw data accelerometry, because the data collection -process has involved proprietary pre-processing steps which violate the -core principle of raw data collection.
    • -
  • Report whether ‘idle sleep mode’ was used. If the choice was not -consistent within a study then try to account for idle mode sleep usage -in the statistical analyses.
    • -
-
-
-
-

MX metrics (minimum intensity of most active X minutes) -

-

The qlevels argument (the percentile in the distribution -of short epoch metric value) can be used to describe the accelerations -that participants spend “X” accumulated minutes a day above, described -as the MX metrics (e.g., Rowlands et -al).

-

The MX metrics should not be confused with the most active continuous -X hours, e.g. M10, as used in circadian rhythm research that also can be -derived with GGIR, see argument winhr.

-

Usage To use the MX metrics as proposed by Rowlands et al, -specify the durations of the 24h day that you wish to filter out the -accelerations for. For example, to generate the minimum acceleration -value for the most active 30 minutes you can call qlevels = (1410/1440), -which will filter out the lowest 1410 minutes of the day. This can also -be used as a nested term to generate multiple metrics, for example to -call M60, M30 and M10, you can use argument:

-

qlevels = c(c(1380/1440),c(1410/1440),c(1430/1440)).

-

Note: if your qwindow is less than 24 h, e.g. the school day (e.g. Fairclough et al 2020) the -denominator should be changed from 1440 (24h) accordingly, e.g. if an 8 -h window the denominator would be 480 rather than 1440.

-

Output The output in part2 summary files will refer -to this as a percentile of the day. Thus, for a 24 h day, M30 will -appear as “p 97.91666_ENMO_mg_0.24hr”. To graph the radar plots of these -MX metrics as first described by Rowlands et al, you -can access this github -repository which provides the R code and detailed instructions on how to -make the radar plots using your own data.

-
-
-

Minimum recording duration -

-

GGIR has been designed to process multi-day recordings. The minimum -recording duration considered by GGIR depends on the type of -analysis:

-

Running part 1 and 2

-
    -

  • File size; At least 2MB, where 2MB can be adjusted with argument -minimumFileSizeMB. This should not be changed unless you have good -reason to believe that a smaller file size is also acceptable.

    • -

  • Recording duration: At least two long epoch windows (default 60 -minutes) in g.readaccfile. The size of this epoch can be altered with -the second and third value of vector argument windowsizes, -where the third should not be smaller than the second. For example, in -short lasting lab-experiments you may find it easier to set this to -windowsizes = c(5, 600, 600) as non-wear detection is -usually not necessary in lab studies.

    • -
-

Running part 3 and 4

-
    -
  • At least one night of data is expected, where a night is expected to -have at least the timestamp for midnight. If midnight is not found the -sleep detection is skipped.
    • -
-

Running part 5

-
    -
  • Ideally two valid consecutive nights and the waking hours in -between.
    • -
-
-
-

LUX sensor data processing -

-

Although GGIR focuses on accelerometer data a few brands come with -LUX data.

-

In part 1 GGIR calculates the peak lux per long epoch at a default -resolution of 15 minutes, which can be modified with argument -windowsizes. Peak light offers a more reliable estimate of light -exposure per time window compared with taking the average. Further, LUX -is used in the auto-calibration.

-

In GGIR part 2 we visualise the LUX values in the qc plot. In part 3 -and 4 LUX is not used for sleep classification because relation between -light exposure and sleep is weak.

-

In part 5 we calculate the mean and maximum of the peak LUX per epoch -across all waking hours of the day. Here, the mean (peak per epoch) LUX -would then indicate average light exposure per time segment, while max -peak would indicate the maximum light exposure per day. Further, we -calculate the max and mean peak LUX per most active consecutive X hour -of the day. This is intended to offer an alternative to LUX exposure -during waking hours which relies on correct sleep classification. LUX -exposure during M10 may be seen as an alternative if you are unsure -whether you can trust the sleep classification in your data set.

-
-
-
-

Other Resources -

- -
-
-

Citing GGIR -

-

A correct citation of research software is important to make your -research reproducible and to acknowledge the effort that goes into the -development of open-source software.

-

To do so, please report the GGIR version you used in the text. -Additionally, please also cite:

-
    -
  1. Migueles JH, Rowlands AV, et al. GGIR: A Research Community–Driven -Open Source R Package for Generating Physical Activity and Sleep -Outcomes From Multi-Day Raw Accelerometer Data. Journal for the -Measurement of Physical Behaviour. 2(3) 2019. doi: -10.1123/jmpb.2018-0063.
    2. -
-

If your work depends on the quantification of physical -activity then also cite:

-
    -
  1. van Hees VT, Gorzelniak L, et al. Separating Movement and Gravity -Components in an Acceleration Signal and Implications for the Assessment -of Human Daily Physical Activity. PLoS ONE 8(4) 2013. link -
    2. -
  2. Sabia S, van Hees VT, Shipley MJ, Trenell MI, Hagger-Johnson G, -Elbaz A, Kivimaki M, Singh-Manoux A. Association between questionnaire- -and accelerometer-assessed physical activity: the role of -sociodemographic factors. Am J Epidemiol. 2014 Mar 15;179(6):781-90. -doi: 10.1093/aje/kwt330. Epub 2014 Feb 4. PMID: 24500862 link -
    3. -
-

If you used the auto-calibration functionality then -also cite:

-
    -
  1. van Hees VT, Fang Z, et al. Auto-calibration of accelerometer data -for free-living physical activity assessment using local gravity and -temperature: an evaluation on four continents. J Appl Physiol 2014. link -
    2. -
-

If you used the sleep detection then also cite:

-
    -
  1. van Hees VT, Sabia S, et al. A novel, open access method to assess -sleep duration using a wrist-worn accelerometer, PLoS ONE, 2015 link -
    2. -
-

If you used the sleep detection without relying on sleep -diary then also cite:

-
    -
  1. van Hees VT, Sabia S, et al. Estimating sleep parameters using an -accelerometer without sleep diary. Scientific Reports 2018. doi: -10.1038/s41598-018-31266-z. link -
    2. -
-

If you used the sleep regularity index then also -cite:

-
    -
  1. Andrew J. K. Phillips, William M. Clerx, et al. Irregular sleep/wake -patterns are associated with poorer academic performance and delayed -circadian and sleep/wake timing. Scientific Reports. 2017 June 12 link.
    2. -
-
- -

The copyright of the GGIR logo lies with Accelting (Almere, The -Netherlands), please contact to ask for permission to use -this logo.

-

-
-
-
-
- - - - -
- - - - - - - From 621f3827527bc1bdddfa8f8f332852ab3e9d1607 Mon Sep 17 00:00:00 2001 From: Vincent van Hees Date: Mon, 24 Jun 2024 11:24:06 +0200 Subject: [PATCH 12/18] Add cookbook vignette with illustration of how to use NotWorn #1137 --- .Rbuildignore | 3 +- _pkgdown.yml | 2 + man/GGIR.Rd | 6 ++- vignettes/Cookbook.Rmd | 103 +++++++++++++++++++++++++++++++++++++++++ 4 files changed, 111 insertions(+), 3 deletions(-) create mode 100644 vignettes/Cookbook.Rmd diff --git a/.Rbuildignore b/.Rbuildignore index 4f32cef62..e3986b988 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -19,4 +19,5 @@ RELEASE_CYCLE.md codecov.yml index.md ^inst/doc/*.html -^vignettes/HouseHoldCoanalysis.Rmd \ No newline at end of file +^vignettes/HouseHoldCoanalysis.Rmd +^vignettes/Cookbook.Rmd \ No newline at end of file diff --git a/_pkgdown.yml b/_pkgdown.yml index 760cb5bfc..a5e323b1b 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -84,6 +84,8 @@ navbar: href: articles/TutorialDaySegmentAnalyses.html - text: Household co-analysis href: articles/HouseHoldCoanalysis.html + - text: Cookbook + href: articles/Cookbook.html structure: left: [chapters, annexes, installation, intro, news, contributing, help] right: [search, github, twitter] diff --git a/man/GGIR.Rd b/man/GGIR.Rd index 641f4fd3f..f7bc4dc95 100755 --- a/man/GGIR.Rd +++ b/man/GGIR.Rd @@ -1143,8 +1143,10 @@ GGIR(mode = 1:5, the HDCZA algorithm by looking for time segments where the angle of the longitudinal sensor axis has an angle relative to the horizontal plane between -45 and +45 degrees. And "NotWorn" which is also the same as HDCZA - but looks for time segments when the 5 minute rolling average of counts is - below 20 per cent of its standard deviation.} + but looks for time segments when a rolling average of acceleration + magnitude is below 5 per cent of its standard deviation, see + Cookbook vignette in the Annexes of https://wadpac.github.io/GGIR/ + for more detailed guidance on how to use "NotWorn".} \item{HDCZA_threshold}{ Numeric (default = c()) diff --git a/vignettes/Cookbook.Rmd b/vignettes/Cookbook.Rmd new file mode 100644 index 000000000..631d1ac87 --- /dev/null +++ b/vignettes/Cookbook.Rmd @@ -0,0 +1,103 @@ +--- +title: "Cookbook" +output: + html_document: + toc: true + number_sections: true + toc_depth: 3 + toc_float: true +urlcolor: blue +vignette: > + %\VignetteIndexEntry{GGIR output} + \usepackage[utf8]{inputenc} + %\VignetteEngine{knitr::rmarkdown} +--- + +In this cook book you will find recipes for using GGIR in specific scenarios. + +# Handling externally derived data + +## Actiwatch data + +### in .AWD format + +``` +GGIR(datadir = "/media/actiwatch_awd", # folder with epoch level .AWD file + outputdir = "/media/myoutput", + dataFormat = "actiwatch_awd", + extEpochData_timeformat = "\%m/\%d/\%Y \%H:\%M:\%S", + windowsizes = c(60, 900, 3600), # 60 is the expected epoch length + HASIB.algo = "Sadeh1994", + def.noc.sleep = c()) # <= because we cannot use HDCZA for ZCY +``` + +### in .CSV format + +``` +GGIR(datadir = "/media/actiwatch_csv", # folder with epoch level .AWD file + outputdir = "/media/myoutput", + dataFormat = "actiwatch_csv", + extEpochData_timeformat = "\%m/\%d/\%Y \%H:\%M:\%S", + windowsizes = c(15, 900, 3600), # 15 is the expected epoch length + HASIB.algo = "Sadeh1994", + def.noc.sleep = c()) # <= because we cannot use HDCZA for ZCY +``` + +## UK Biobank data in .CSV format + +``` +GGIR(datadir = "/media/ukbiobank", + outputdir = "/media/myoutput", + dataFormat = "ukbiobank_csv", + extEpochData_timeformat = "\%m/\%d/\%Y \%H:\%M:\%S", + windowsizes = c(5, 900, 3600), # We know that data was stored in 5 second epoch + desiredtz = "Europe/London") # We know that data was collected in the UK +``` + +## ActiGraph count data in .CSV format + +``` +GGIR(datadir = "/examplefiles", + outputdir = "", + dataFormat = "actigraph_csv", + windowsizes = c(5, 900, 3600), + threshold.in = round(100 * (5/60), digits = 2), + threshold.mod = round(2500 * (5/60), digits = 2), + threshold.vig = round(10000 * (5/60), digits = 2), + extEpochData_timeformat = "\%m/\%d/\%Y \%H:\%M:\%S", + do.neishabouricounts = TRUE, + acc.metric = "NeishabouriCount_x") +``` + +## Senwear data in .xls format + +``` +GGIR(datadir = "C:/yoursenseweardatafolder", + outputdir = "D:/youroutputfolder", + windowsizes = c(60, 900, 3600), + threshold.in = 1.5, + threshold.mod = 3, + threshold.vig = 6, + dataFormat = "sensewear_xls", + extEpochData_timeformat = "\%d-\%b-\%Y \%H:\%M:\%S", + HASPT.algo = "NotWorn") +``` + +# Handling study protocol + +## Not worn during night + +Data type: Any +Study protocol: Worn during the day, taken off during the night +Wear location: Any + +``` +GGIR(HASPT.algo = "NotWorn", + HASIB.algo = "NotWorn", + do.imp = FALSE, # Do not impute nonwear because sensor was never worn 24/7 + HASPT.ignore.invalid = NA, # Treat nonwear as potential part of guider window + ignorenonwear = FALSE, # Consider nonwear as potential sleep + relyonguider = TRUE, # has minor influence + includenightcrit = 8, + includedaycrit = 8) +``` \ No newline at end of file From d6a4a34db516be89b8435c17e3a2b2abc1fcab1e Mon Sep 17 00:00:00 2001 From: Vincent van Hees Date: Mon, 24 Jun 2024 11:46:21 +0200 Subject: [PATCH 13/18] renaming chapter0_contributing to chapter0_Contributing --- .../{chapter0_contributing.Rmd => chapter0_Contributing.Rmd} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename vignettes/{chapter0_contributing.Rmd => chapter0_Contributing.Rmd} (100%) diff --git a/vignettes/chapter0_contributing.Rmd b/vignettes/chapter0_Contributing.Rmd similarity index 100% rename from vignettes/chapter0_contributing.Rmd rename to vignettes/chapter0_Contributing.Rmd From af8d6a19b01362b3dc1c7e82fc458be866d24908 Mon Sep 17 00:00:00 2001 From: Vincent van Hees Date: Mon, 24 Jun 2024 11:48:15 +0200 Subject: [PATCH 14/18] minor edits --- _pkgdown.yml | 2 +- vignettes/chapter0_Contributing.Rmd | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/_pkgdown.yml b/_pkgdown.yml index a5e323b1b..3fb795c1d 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -1,4 +1,4 @@ -url: ~ +url: https://wadpac.github.io/GGIR/ template: bootstrap: 5 bslib: diff --git a/vignettes/chapter0_Contributing.Rmd b/vignettes/chapter0_Contributing.Rmd index 88d92a944..2fc41ee40 100644 --- a/vignettes/chapter0_Contributing.Rmd +++ b/vignettes/chapter0_Contributing.Rmd @@ -23,7 +23,7 @@ knitr::opts_chunk$set(echo = TRUE) ## If you have coding skills… -We welcome contributions in the development, maintenance, and documentation of GGIR. Please find the GGIR’s contributing guidelines [here]( https://github.com/wadpac/GGIR/blob/master/CONTRIBUTING.md). +We welcome contributions in the development, maintenance, and documentation of GGIR. Please find the GGIR’s contributing guidelines [here](https://github.com/wadpac/GGIR/blob/master/CONTRIBUTING.md). ## If you do not have coding skills…. From b365067a376c7c01a1b3f5824423089db3169a12 Mon Sep 17 00:00:00 2001 From: Vincent van Hees Date: Mon, 24 Jun 2024 17:54:19 +0200 Subject: [PATCH 15/18] handle data before first noon correctly when recording has only 1 night --- R/g.sib.det.R | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/R/g.sib.det.R b/R/g.sib.det.R index b1d9535e6..c983b26ca 100644 --- a/R/g.sib.det.R +++ b/R/g.sib.det.R @@ -195,7 +195,7 @@ g.sib.det = function(M, IMP, I, twd = c(-12, 12), lastmidnight = midnights[length(midnights)] lastmidnighti = midnightsi[length(midnights)] firstmidnight = time[1] - firstmidnighti = 1 + firstmidnighti = midnightsi[length(midnights)] #1 } else { cut = which(as.numeric(midnightsi) == 0) if (length(cut) > 0) { From ea129639fa4f3d40e5481ca93449d8f745f1cd8b Mon Sep 17 00:00:00 2001 From: Vincent van Hees Date: Mon, 24 Jun 2024 18:08:43 +0200 Subject: [PATCH 16/18] tidy up fix related to #1160 --- R/g.sib.det.R | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/R/g.sib.det.R b/R/g.sib.det.R index c983b26ca..8c3db4bbd 100644 --- a/R/g.sib.det.R +++ b/R/g.sib.det.R @@ -195,7 +195,7 @@ g.sib.det = function(M, IMP, I, twd = c(-12, 12), lastmidnight = midnights[length(midnights)] lastmidnighti = midnightsi[length(midnights)] firstmidnight = time[1] - firstmidnighti = midnightsi[length(midnights)] #1 + firstmidnighti = midnightsi[1] } else { cut = which(as.numeric(midnightsi) == 0) if (length(cut) > 0) { From fa25fa5b1e37fefdb00a11318123768e70dad300 Mon Sep 17 00:00:00 2001 From: Vincent van Hees Date: Mon, 24 Jun 2024 18:10:16 +0200 Subject: [PATCH 17/18] Update NEWS.md --- NEWS.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/NEWS.md b/NEWS.md index 90a8de165..db9407099 100644 --- a/NEWS.md +++ b/NEWS.md @@ -16,6 +16,8 @@ - Vignette: Migrated many sections from main CRAN vignette to wadpac.github.io/GGIR/ +- Part 3: Fix handling of recordings with only 1 midnight that start before 4am, #1160 + # CHANGES IN GGIR VERSION 3.1-1 - Part 2: Corrected calculation of LXhr and MXhr which had one hour offset when timing was after midnight, #1117 From e1b0b8ef111e80c1ee7098f6d7c6434e8f71237a Mon Sep 17 00:00:00 2001 From: Vincent van Hees Date: Fri, 28 Jun 2024 15:21:51 +0200 Subject: [PATCH 18/18] Add option to specify second guider when working with NotWorn as primary guider, fixes #1156 --- NEWS.md | 2 +- R/check_params.R | 12 ++++++------ R/g.part4.R | 2 +- R/g.sib.det.R | 19 ++++++++++++++----- vignettes/Cookbook.Rmd | 9 +++++---- 5 files changed, 27 insertions(+), 17 deletions(-) diff --git a/NEWS.md b/NEWS.md index 85a4e4ba7..29e399db4 100644 --- a/NEWS.md +++ b/NEWS.md @@ -4,7 +4,7 @@ - Report part 5: fix bug that was introduced on 2024-Feb-19 in the calculation of wear percentage #1148 -- Part 3 and 4: Revise NotWorn algorithm to work with both count and raw data with varying degrees of nonwear. +- Part 3 and 4: Revise NotWorn algorithm to work with both count and raw data with varying degrees of nonwear. Further, when HASPT.algo is set to NotWorn then a second guider can optionally be specified in case the accelerometer unexpectedly worn by the participant. #1089 - Visualreport: Improve handling of recordings where the accelerometer was not worn. diff --git a/R/check_params.R b/R/check_params.R index 315dc7545..9a075a905 100644 --- a/R/check_params.R +++ b/R/check_params.R @@ -176,7 +176,7 @@ check_params = function(params_sleep = c(), params_metrics = c(), if (length(params_sleep) > 0) { if (length(params_sleep[["def.noc.sleep"]]) != 2) { - if (params_sleep[["HASPT.algo"]] %in% c("HorAngle", "NotWorn") == FALSE) { + if (params_sleep[["HASPT.algo"]][1] %in% c("HorAngle", "NotWorn") == FALSE) { params_sleep[["HASPT.algo"]] = "HDCZA" } } else if (length(params_sleep[["def.noc.sleep"]]) == 2) { @@ -200,13 +200,13 @@ check_params = function(params_sleep = c(), params_metrics = c(), if (length(params_general) > 0 & length(params_metrics) > 0 & length(params_sleep) > 0) { if (params_general[["sensor.location"]] == "hip" && - params_sleep[["HASPT.algo"]] %in% c("notused", "NotWorn") == FALSE) { + params_sleep[["HASPT.algo"]][1] %in% c("notused", "NotWorn") == FALSE) { if (params_metrics[["do.anglex"]] == FALSE | params_metrics[["do.angley"]] == FALSE | params_metrics[["do.anglez"]] == FALSE) { warning(paste0("\nWhen working with hip data all three angle metrics are needed,", "so GGIR now auto-sets arguments do.anglex, do.angley, and do.anglez to TRUE."), call. = FALSE) params_metrics[["do.anglex"]] = params_metrics[["do.angley"]] = params_metrics[["do.anglez"]] = TRUE } - if (params_sleep[["HASPT.algo"]] != "HorAngle") { + if (params_sleep[["HASPT.algo"]][1] != "HorAngle") { warning("\nChanging HASPT.algo value to HorAngle, because sensor.location is set as hip", call. = FALSE) params_sleep[["HASPT.algo"]] = "HorAngle"; params_sleep[["def.noc.sleep"]] = 1 } @@ -230,12 +230,12 @@ check_params = function(params_sleep = c(), params_metrics = c(), params_sleep[["def.noc.sleep"]] = 1 } - if (params_sleep[["HASPT.algo"]] == "HorAngle" & params_sleep[["sleepwindowType"]] != "TimeInBed") { + if (params_sleep[["HASPT.algo"]][1] == "HorAngle" & params_sleep[["sleepwindowType"]] != "TimeInBed") { warning("\nHASPT.algo is set to HorAngle, therefore auto-updating sleepwindowType to TimeInBed", call. = FALSE) params_sleep[["sleepwindowType"]] = "TimeInBed" } - if (length(params_sleep[["loglocation"]]) == 0 & params_sleep[["HASPT.algo"]] != "HorAngle" & params_sleep[["sleepwindowType"]] != "SPT") { + if (length(params_sleep[["loglocation"]]) == 0 & params_sleep[["HASPT.algo"]][1] != "HorAngle" & params_sleep[["sleepwindowType"]] != "SPT") { warning("\nAuto-updating sleepwindowType to SPT because no sleeplog used and neither HASPT.algo HorAngle used.", call. = FALSE) params_sleep[["sleepwindowType"]] = "SPT" } @@ -367,7 +367,7 @@ check_params = function(params_sleep = c(), params_metrics = c(), } if (length(params_general) > 0 & length(params_sleep) > 0) { - if (params_sleep[["HASPT.algo"]] == "HorAngle") { + if (params_sleep[["HASPT.algo"]][1] == "HorAngle") { # Not everywhere in the code we check that when HASPT.algo is HorAngle, sensor.location is hip. # However, the underlying assumption is that they are linked. Even if a study would # use a waist or chest worn sensor we refer to it as hip as the orientation and need diff --git a/R/g.part4.R b/R/g.part4.R index cf033db5c..89caf9e72 100644 --- a/R/g.part4.R +++ b/R/g.part4.R @@ -291,7 +291,7 @@ g.part4 = function(datadir = c(), metadatadir = c(), f0 = f0, f1 = f1, # explicitely asks for it defaultGuiderOnset = SPTE_start[j] defaultGuiderWake = SPTE_end[j] - guider = params_sleep[["HASPT.algo"]] # HDCZA, NotWorn, HorAngle (or plus invalid) + guider = params_sleep[["HASPT.algo"]][1] # HDCZA, NotWorn, HorAngle (or plus invalid) defaultGuider = part3_guider[j] if (is.null(defaultGuider)) defaultGuider = guider #this ensures compatibility with previous versions in which part3_guider was not stored if (is.na(defaultGuiderOnset) == TRUE) { diff --git a/R/g.sib.det.R b/R/g.sib.det.R index 8c3db4bbd..870605133 100644 --- a/R/g.sib.det.R +++ b/R/g.sib.det.R @@ -236,6 +236,15 @@ g.sib.det = function(M, IMP, I, twd = c(-12, 12), if (qqq1 < 1) qqq1 = 1 night[qqq1:qqq2] = sptei detection.failed = FALSE + # Calculate nonwear percentage for this window + nonwear_percentage = (length(which(invalid[qqq1:qqq2] == 1)) / (qqq2 - qqq1 + 1)) * 100 + guider_to_use = 1 + if (params_sleep[["HASPT.algo"]][1] == "NotWorn" && + nonwear_percentage < 25 && + length(params_sleep[["HASPT.algo"]]) == 2) { + # Nonwear percentage was low, so use alternative guider specified as second element + guider_to_use = 2 + } #------------------------------------------------------------------ # calculate L5 because this is used as back-up approach tmpACC = ACC[qqq1:qqq2] @@ -258,8 +267,8 @@ g.sib.det = function(M, IMP, I, twd = c(-12, 12), tmpANGLE = anglez[qqq1:qqq2] tmpTIME = time[qqq1:qqq2] daysleep_offset = 0 - if (do.HASPT.hip == TRUE & params_sleep[["HASPT.algo"]] != "NotWorn") { - params_sleep[["HASPT.algo"]] = "HorAngle" + if (do.HASPT.hip == TRUE & params_sleep[["HASPT.algo"]][1] != "NotWorn") { + params_sleep[["HASPT.algo"]][1] = "HorAngle" if (params_sleep[["longitudinal_axis"]] == 1) { tmpANGLE = anglex[qqq1:qqq2] } else if (params_sleep[["longitudinal_axis"]] == 2) { @@ -269,7 +278,7 @@ g.sib.det = function(M, IMP, I, twd = c(-12, 12), if (length(params_sleep[["def.noc.sleep"]]) == 1) { spt_estimate = HASPT(angle = tmpANGLE, ws3 = ws3, sptblocksize = sptblocksize, spt_max_gap = spt_max_gap, - HASPT.algo = params_sleep[["HASPT.algo"]], + HASPT.algo = params_sleep[["HASPT.algo"]][guider_to_use], invalid = invalid[qqq1:qqq2], # load only invalid time in the night of interest (i.e., qqq1:qqq2) HDCZA_threshold = params_sleep[["HDCZA_threshold"]], HASPT.ignore.invalid = params_sleep[["HASPT.ignore.invalid"]], @@ -287,7 +296,7 @@ g.sib.det = function(M, IMP, I, twd = c(-12, 12), if (newqqq2 > length(anglez)) newqqq2 = length(anglez) # only try to extract SPT again if it is possible to extract a window of more than 23 hour if (newqqq2 < length(anglez) & (newqqq2 - newqqq1) > (23*(3600/ws3)) ) { - if (do.HASPT.hip == TRUE & params_sleep[["HASPT.algo"]] != "NotWorn") { + if (do.HASPT.hip == TRUE & params_sleep[["HASPT.algo"]][1] != "NotWorn") { tmpANGLE = anglez[newqqq1:newqqq2] if (params_sleep[["longitudinal_axis"]] == 1) { tmpANGLE = anglex[newqqq1:newqqq2] @@ -297,7 +306,7 @@ g.sib.det = function(M, IMP, I, twd = c(-12, 12), } spt_estimate_tmp = HASPT(angle = tmpANGLE, ws3 = ws3, sptblocksize = sptblocksize, spt_max_gap = spt_max_gap, - HASPT.algo = params_sleep[["HASPT.algo"]], + HASPT.algo = params_sleep[["HASPT.algo"]][1], invalid = invalid[newqqq1:newqqq2], HDCZA_threshold = params_sleep[["HDCZA_threshold"]], HASPT.ignore.invalid = params_sleep[["HASPT.ignore.invalid"]], diff --git a/vignettes/Cookbook.Rmd b/vignettes/Cookbook.Rmd index 631d1ac87..9cdb0caaf 100644 --- a/vignettes/Cookbook.Rmd +++ b/vignettes/Cookbook.Rmd @@ -92,12 +92,13 @@ Study protocol: Worn during the day, taken off during the night Wear location: Any ``` -GGIR(HASPT.algo = "NotWorn", - HASIB.algo = "NotWorn", +GGIR(HASPT.algo = c("NotWorn", "HDCZA"), + HASIB.algo = "vanHees2015", do.imp = FALSE, # Do not impute nonwear because sensor was never worn 24/7 HASPT.ignore.invalid = NA, # Treat nonwear as potential part of guider window ignorenonwear = FALSE, # Consider nonwear as potential sleep - relyonguider = TRUE, # has minor influence includenightcrit = 8, includedaycrit = 8) -``` \ No newline at end of file +``` + +If "NotWorn" is specified then a second guider can be supplied to the same parameter as shown above. This second guider will be used if the accelerometer is worn for more than 75 percent of the night. The example above shows this for HDCZA. \ No newline at end of file