Add cookbook vignette with illustration of how to use NotWorn #1137

.Rbuildignore

@@ -19,4 +19,5 @@ RELEASE_CYCLE.md
 codecov.yml
 index.md
 ^inst/doc/*.html
-^vignettes/HouseHoldCoanalysis.Rmd
+^vignettes/HouseHoldCoanalysis.Rmd
+^vignettes/Cookbook.Rmd

_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]

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())

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)
+```