GGIR (version 2.3-0)

g.shell.GGIR: Shell function for analysing an accelerometer dataset.

Description

This function is designed to help users operate all steps of the analysis. It helps to generate and structure milestone data, produces user-friendly reports. The function acts as a shell with calls to g.part1, g.part2, g.part3 and g.part4. Please see these specific functions for clarification on optional input arguments.

Usage

g.shell.GGIR(mode=1:5,datadir=c(),outputdir=c(),studyname=c(),
f0=1,f1=0, do.report=c(2),overwrite=FALSE,visualreport=FALSE,
viewingwindow=1,configfile=c(),myfun=c(),...)

Arguments

mode

Specify which of the four parts need to be run, e.g. mode = 1 makes that g.part1 is run. Default setting, mode = c(1,2), makes that both part1 and part2 are ran. Note that if mode = c(1,3) then the code will also set do.anglez = TRUE in order to enable sleep detection. If you run part 1 and 3 seperatedly then you need to remember to set argument do.anglez to TRUE when running part1.

datadir

Directory where the accelerometer files are stored or list, e.g. "C:/mydata" of accelerometer filenames and directories, e.g. c("C:/mydata/myfile1.bin", "C:/mydata/myfile2.bin").

outputdir

Directory where the output needs to be stored. Note that this function will attempt to create folders in this directory and uses those folder to keep output

studyname

If the datadir is a folder then the study will be given the name of the data directory. If datadir is a list of filenames then the studyname as specified by this input argument will be used as name for the study

f0

File index to start with (default = 1). Index refers to the filenames sorted in increasing order

f1

File index to finish with (defaults to number of files available)

overwrite

Do you want to overwrite analysis for which milestone data exists? If overwrite=FALSE then milestone data from a previous analysis will be used if available and visual reports will not be created again.

do.report

For which parts to generate a summary spreadsheet: 2 and/or 4. Default is c(2). A report will be generated based on the available milestone data. When creating milestone data with multiple machines it is advisable to turn the report generation off when generating the milestone data, value = c(), and then to merge the milestone data and turn report generation back on while setting overwrite to FALSE.

visualreport

If TRUE then generate visual report based on combined output from part 2 and 4. This is in beta-version at the moment.

viewingwindow

Centre the day as displayed around noon (value = 1) or around midnight (value = 2)

configfile

Configuration file previously generated by g.shell.GGIR. See details.

myfun

External function object to be applied to raw data, see g.getmeta.

...

Any input arguments needed for functions g.part1, g.part2, g.part3 or g.part4. See respective function documentation for further clarification.

Value

The function provides no values, it only ensures that other functions are called and that their output is stored. Further, a configuration file is stored containing all the argument values used to facilitate reproducibility.

Details

Once you have used g.shell.GGIR and the output directory (outputdir) will be filled with milestone data and results. Function g.shell.GGIR stores all the explicitely entered argument values and default values for the argument that are not explicitely 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 g.shell.GGIR with argument `configfile` to replace the specification of all the arguments, except `datadir` and `outputdir`.

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: When combining a configuration file with explicitely provided argument values, the explicitely provided argument values will overrule the argument values in the configuration file.

References

• van Hees VT, Gorzelniak L, Dean Leon EC, Eder M, Pias M, et al. (2013) Separating Movement and Gravity Components in an Acceleration Signal and Implications for the Assessment of Human Daily Physical Activity. PLoS ONE 8(4): e61691. doi:10.1371/journal.pone.0061691

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

• van Hees VT, Sabia S, et al. (2015) A novel, open access method to assess sleep duration using a wrist-worn accelerometer, PLoS ONE, November 2015

Examples

# NOT RUN {
mode= c(1,2,3,4)
datadir= "C:/myfolder/mydata"
outputdir= "C:/myresults"
studyname="test"
f0 = 1 
f1 = 2
g.shell.GGIR(#-------------------------------
             # General parameters
             #-------------------------------
             mode=mode, 
             datadir=datadir, 
             outputdir=outputdir, 
             studyname=studyname, 
             f0=f0, 
             f1=f1,
             overwrite = FALSE, 
             do.imp=TRUE,
             idloc=1, 
             print.filename=FALSE,
             storefolderstructure = FALSE,
             #-------------------------------
             # Part 1 parameters:
             #-------------------------------
             windowsizes = c(5,900,3600),
             do.cal=TRUE, 
             do.enmo = TRUE,
             do.anglez=TRUE,
             chunksize=1,
             printsummary=TRUE,
             #-------------------------------
             # Part 2 parameters:
             #-------------------------------
             strategy = 1,
             ndayswindow=7,
             hrs.del.start = 1,
             hrs.del.end = 1, 
             maxdur = 9,
             includedaycrit = 16, 
             L5M5window = c(0,24),
             M5L5res = 10,
             winhr = c(5,10),
             qlevels = c(c(1380/1440),c(1410/1440)),
             qwindow=c(0,24), 
             ilevels = c(seq(0,400,by=50),8000), 
             mvpathreshold =c(100,120),
             #-------------------------------
             # Part 3 parameters:
             #-------------------------------
             timethreshold= c(5,10),
             anglethreshold=5,
             ignorenonwear = TRUE,
             #-------------------------------
             # Part 4 parameters:
             #-------------------------------
             excludefirstlast = FALSE,
             includenightcrit = 16,
             def.noc.sleep = 1,
             loglocation= "D:/sleeplog.csv",
             outliers.only = FALSE,
             criterror = 4,
             relyonsleeplog = FALSE,
             sleeplogidnum = TRUE,
             colid=1, 
             coln1=2, 
             do.visual = TRUE,
             nnights = 9,
             #-------------------------------
             # Part 5 parameters:
             #-------------------------------
             # Key functions: Merging physical activity with sleep analyses
             threshold.lig = c(30,40,50),
             threshold.mod = c(100,120),
             threshold.vig = c(400,500),
             excludefirstlast = FALSE,
             boutcriter = 0.8,
             boutcriter.in = 0.9,
             boutcriter.lig = 0.8,
             boutcriter.mvpa = 0.8,
             boutdur.in = c(10,20,30),
             boutdur.lig = c(1,5,10),
             boutdur.mvpa = c(1,5,10),
             timewindow = c("WW"),
             #-----------------------------------
             # Report generation
             #-------------------------------
             do.report=c(2,4,5))
# }