g.part4: Labels detected sustained inactivity periods by g.part3 as...
In ucl-cls/mcs-acc: Raw Accelerometer Data Analysis

Description Usage Arguments Value Author(s) References Examples

Loads output from g.part3 as stored in milestone data and sleep log information (if available) and then uses these information sources to define nocturnal sleep and daytime sustained inactivity.

g.part4(datadir=c(),metadatadir=c(),f0=f0,f1=f1,idloc=1,
loglocation = c(),colid = 1,coln1 = 9,nnights = 7,
sleeplogidnum=FALSE,do.visual=FALSE,outliers.only = FALSE,
    excludefirstlast=FALSE,criterror = 1,includenightcrit=4,
    relyonsleeplog=FALSE,def.noc.sleep=c(),
    storefolderstructure=FALSE,overwrite=FALSE)

`datadir`	Directory where the accelerometer files are stored or list of accelerometer filenames and directories
`metadatadir`	Directory that holds a folders 'meta' and inside this a folder 'basic' which contains the milestone data produced by g.part1. The folderstructure is normally created by g.part3. When using g.part4 via g.shell.GGIR then g.shell.GGIR will automatically recognise what the value of metadatadir is, so the user does not need to specify this.
`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)
`idloc`	If value = 1 (default) the code assumes that ID number is stored in the obvious header field. If value = 2 the code uses the character string preceding the character '_' in the filename as the ID number
`loglocation`	Location of the spreadsheet (csv) with sleep log information. The spreadsheet needs to have the following structure: one column for participant id, and then followed by alternatingly one column for onset time and one column for waking time. There can be multiple sleeplogs in the same spreadsheet. The first raw of the spreadsheet needs to be filled with column names, it does not matter what these column names are. Timestamps are to be stored without date as in hh:mm:ss. If onset corresponds to lights out or intention to fall asleep, then it is the end-users responsibility to account for this in the interpretation of the results.
`colid`	Column number in the sleep log spreadsheet in which the participant ID code is stored (default = 1)
`coln1`	Column number in the sleep log spreadsheet where the onset of the first night starts
`nnights`	Number of nights for which sleep log information should be available. It assumes that this is constant within a study. If sleep log information is missing for certain nights then leave these blank
`sleeplogidnum`	Should the participant identifier as stored in the sleeplog be interpretted as a number (TRUE=default) or a character (FALSE)?
`do.visual`	If g.part4 is run with do.visual == TRUE then the function will generate a pdf with a visual representation of the overlap between the sleeplog entries and the accelerometer detections. This can be used to visualy verify that the sleeplog entries do not come with obvious mistakes.
`outliers.only`	Relevant for do.visual == TRUE. Outliers.only == FALSE will visualise all available nights in the data. Outliers.only == TRUE will visualise only for nights with a difference in onset or waking time larger than the variable of argument criterror.
`excludefirstlast`	If TRUE then the first and last night of the measurement are ignored for the sleep assessment.
`criterror`	Relevant for do.visual == TRUE and outliers.only == TRUE. criterror specifies the number of minimum number of hours difference between sleep log and accelerometer estimate for the night to be included in the visualisation
`includenightcrit`	Minimum number of valid hours per night (24 hour window between noon and noon)
`relyonsleeplog`	If TRUE then sleep onset and waking time are defined based on timestamps derived from sleep log if FALSE (default) the sleep log is only used to guide the accelerometer-based detection. If participants were instructed NOT to wear the accelerometer during waking hours then set to TRUE, in all other scenarios set to FALSE (FALSE).
`def.noc.sleep`	The time window during which sustained inactivity will be assumed to represent sleep, e.g. def.noc.sleep=c(21,9). This is only used if no sleep log entry is available. If def.noc.sleep is left blank 'def.noc.sleep=c()' then the 12 hour window centred at the least active 5 hours of the 24 hour period will be used instead. Here, L5 is hardcoded and will not change by changing argument winhr in function g.part2
`storefolderstructure`	Store folder structure of the accelerometer data
`overwrite`	Overwrite previously generated milestone data by this function for this particular dataset. If FALSE then it will skip the previously processed files (default = FALSE).

The function does not produce values but generates an RData file in the milestone subfolder ms4.out which incudes a dataframe named nightsummary and comes with the following variables:

id Participant id extracted from file
night Night number
acc_onset Detected onset of sleep expressed as hours since the previous midnight
acc_wake Detected waking time (after sleep period) expressed as hours since the previous midnight
acc_timeinbed Difference between onset and waking time.
acc_def Definition of sustained inactivity by accelerometer
sleeplog_onset Sleep onset derived from sleep log or specified by researcher if not sleep log is available
sleeplog_wake Waking time derived from sleep log or specified by researcher if not sleep log is available
sleeplog_timeinbed Time in bed derived from sleep log or specified by researcher if not sleep log is available
error_onset Difference between sleep onset as estimated by accelerometer and estimated by sleeplog/defined by researcher
error_wake Difference between waking time as estimated by accelerometer and estimated by sleeplog/defined by researcher
fraction_night_invalid Fraction of the night for which the data was invalid, e.g. monitor not worn or no accelerometer measurement started/ended within the night
acc_dur_noc Total sleep duration, which equals the accumulated nocturnal sustained inactivity bouts. This is not the same as the time in bed, which only looks at time difference between falling asleep and waking up.
acc_dur_sibd Accumulated sustained inactivty 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
acc_n_noc Number of noturnal sleep periods
acc_n_sibd Number of sustained inactivity periods during the day
acc_onset_ts acc_onset formatted as a timestamp
acc_wake_ts acc_wake formatted as a timestamp
sleeplog_onset_ts sleeplog_onset formatted as a timestamp
sleeplog_wake_ts sleeplog_wake formatted as a timestamp
page pdf page on which the visualisation can be found
daysleeper If 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)
weekday Day of the week on which the night started
calendardate Calendar data which the night started
filename Name of the accelerometer file
cleaningcode 0: no problem; 1: sleeplog not available, 2: not enough valid accelerometer data, 3: no accelerometer data available, 4: there were no nights to be analysed for this person
sleeplog_used Whether a sleep log was used (TRUE/FALSE)
acc_available Whether accelerometer data was available (TRUE/FALSE). This dataframe is used in g.report.part4 to create two reports one per night and one per person.

Note that function g.shell.GGIR comes with the option for report generation. In relation to function g.part4 it is important to mention that these reports are effectively the variable names mentioned above or derivatives. Please fine below extra clarification on a few of the variable names for which the meaning may not be obvious:

sleeplog_used Whether a sleeplog was available (TRUE) or not (FALSE)
n_nights_acc Number of nights of accelerometer data
n_WE_nights_complete Number of weekend nights complete which means both accelerometer and sleeplog data
n_WD_nights_complete Number of weekday nights complete which means both accelerometer and sleeplog data
n_WEnights_daysleeper Number of weekend nights on which the person slept until after noon
n_WDnights_daysleeper Number of weekday nights on which the person slept until after noon
sleeplog_dur_AD_mn Mean sleep duration according to sleeplog accros all days
sleeplog_dur_AD_sd Standard deviation of sleep duration according to sleeplog accros all days
sleeplog_dur_WD_sd Standard deviation of sleep duration according to sleeplog accros weekdays
sleeplog_dur_WE_sd Standard deviation of sleep duration according to sleeplog accros weekend days

Vincent T van Hees <vincentvanhees@gmail.com>

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

## Not run: 
metadatadir = "C:/myfolder/meta" # assumes that there is a subfolder in
# metadatadir named 'ms3.out' containing the output from g.part3
g.part4(metadatadir=metadatadir)

## End(Not run)