9. Sleep Fundamentals: Guiding sleep detection • GGIR

Sleep analysis in GGIR comes at three stages:

The discrimination of sleep and wakefulness periods, discussed in the previous chapter.
Identification of time windows that guide the eventual sleep detection, discussed in this chapter.
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.

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.

General notes on how GGIR uses sleeplogs as guider:

GGIR expects both the start and end of the sleep window to be specified. If one of them is missing then the sleeplog data is assumed to be missing for the entire night.
GGIR does not impute sleeplog data. If you feel that imputation is desirable then do this yourself before running GGIR.

Basic sleep log

Example of a basic sleeplog:

ID	onset_N1	wakeup_N1	onset_N2	wakeup_N2	onset_N3	wakeup_N3	onset_N4	…
123	22:00:00	09:00:00	21:00:00	08:00:00	23:45:00	06:30:00	00:00:00	…
345	21:55:00	08:47:00			23:45:00	06:30:00	00: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:

ID	D1_date	D1_wakeup	D1_inbed	D1_nap_start	D1_nap_end	D1_nonwear1_off	D1_nonwear1_on	D2_date	…
123	2015-03-30	09:00:00	22:00:00	11:15:00	11:45:00	13:35:00	14:10:00	31/03/2015	…
567	2015-04-20	08:30:00	23:15:00					21/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.
If no timestamps are known for a certain date, you can skip this date from the sleep log. Note that this is different from the basic format sleep log where columns will have to be left empty for missing night(s).
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 times are recognised as columns with the word “onset” in the column name. Time of going to bed is recognised by column names “lightsout”, “inbed”, “tobed”, or “bedstart”. Time of getting up is recognised by column names “lightson”, “outbed”, or “bedend”. 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)

As already referenced in the previous chapter the NotWorn guider is designed for studies where the instruction is to not wear the accelerometer during the night. It should be obvious that this does not facilitate any meaningful sleep analysis. Nonetheless we need a crude estimate of night time versus day time in order for GGIR part 5 to characterise day time behaviours.

First the NotWorn algorithm calculates the 5 minute rolling average of the acceleration metric values (i.e., acceleration metric defined with parameter acc.metric) and applies a threshold that is 5% 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.

The algorithm is expected to work with any acceleration metric, so both count-type metrics and metrics in gravitational units.

To use this guider set parameter HASPT.algo = "NotWorn". Further, we recommend combining the using of “NotWorn” with: do.imp = FALSE and ignorenonwear = FALSE. Internally HASPT.ignore.invalid is always set to NA when “NotWorn” is used.

If this is used it will also define the resulting window as SIB period and ignore all other identified SIB window to ensure the entire window is treated as sleep. So, all SIB periods detected are ignored.

However, we know from experience that participants occasionally wear the accelerometer during the night even when they are told not to. GGIR offers a solution for this if you are not working with count data but with accelerometer metrics in gravitational units. In that case, it is possible to specify a second guider to use when the accelerometer has been worn for less than 25% of the time in the detection window (noon-noon or 6pm-6pm). If this happens then it will check whether parameter HASPT.algo has two guiders specified. If it does it will use the second one. For example, HASPT.algo = c("NotWorn", "HDCZA") or HASPT.algo = c("NotWorn", "HorAngle").

Dealing with expected or detect nonwear time segments

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

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.
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.
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. If this is used, the guider name in the output will be shown with “+invalid” at the end, e.g. “HDCZA+invalid”, to reflect that the guider was enhanced.