GGIR release 3.1-5

The GGIR 3.1-5 release is now on CRAN. In this blog post I will talk you through the main updates since the 3.1-0 CRAN release from May 2024. For a full overview see the GGIR changelog, where # numbers refer to specific issues in the GGIR GitHub repository.

Reverted non-wear detection change from release 3.1-3

In GitHub-only GGIR release 3.1-3 (14th of August 2024), I added a new parameter named nonwear_range_threshold. This new parameter controls the allowed range in raw acceleration values as part of accelerometer nonwear detection. While adding this parameter it seemed a good idea to change the default from 150 to 50 mg. However, I soon realised that it was a bad idea as it actually prevents non-wear detection in some recordings. Therefore, I reversed this to what it has been for years (150 mg) in the 3.1-5 release.

Thanks to Michael Reuschman (Boston) for spotting the issue and bringing it to my attention.

Controlling inclusion of incomplete last night in GGIR part 5

Parameter require_complete_lastnight_part5 has been added. It controls whether the last window in GGIR part 5 should be included when it ends early. Effectively, this helps us to avoid the risk that recording endings bias the sleep estimates. Parameter require_complete_lastnight_part5  is turned off (FALSE) by default.

As you may remember, GGIR part 5 is not day or night oriented but window oriented. GGIR allows us to define a window in one of the following ways:

• From waking up to waking up the following day (WW)
• From sleep onset to sleep onset the following day (OO)
• From midnight to midnight (MM).

When require_complete_lastnight_part5  is set to TRUE:

• The last WW window in the recording is excluded if the recording ends between midnight and 3pm, and starts on a date that is on or one day before the recording end date.
• The last OO and MM window are excluded if the recording ends between midnight and 9am, and starts on a date that is on or one day before the recording end date.

Motivation

The idea for this new parameter originated in a project where the recordings ended around 1am. GGIR is triggered to run the sleep analyses on the last night when it includes the midnight timestamp. In GGIR part 4 output this night is likely to be skipped as it has less than 16 hours of valid data. However, part 5 GGIR still uses the estimates from part4_nightsummary_sleep_full.csv in order to define the end of the final window. One could argue that this is not trustworthy as the person may have fallen asleep after the ending of the recording. Similarly, a recording ending at 9am could be argued to complicate reliable assessment of wakeup time. Additionally, there could be concerns that the algorithms have not been demonstrated to work reliable in nights that are cut short by the recording end.

For now I have set it to FALSE by default considering the negative impact on the number of windows included. However, maybe in the future we can decide to set it to TRUE by default.

As a side note – It seems inevitable that we always end up with partial days at the beginning and/or end of a recording that are hard to use for time-use analysis. Therefore, it seems best to aim for more than 7 days of data collection and wear instruction, even if you are only interested in 7 days of data.

This work was sponsored by the University of Regensburg in Germany and I would to thank Jairo Migueles for testing the new functionality.

Handling study protocol where accelerometer is not worn at night

GGIR’s sleep detection is by design split up in algorithms to classify sustained inactivity bouts (sib) and algorithms or diaries to guide the labelling of those ‘sib’ as sleep. For study protocols where participants are asked to take off the accelerometer during the night we now offer the guider “NotWorn”. This will consider the main non-wear or continuous lack of movement period as the SPT window, see documentation for details. Use HASPT.algo = “NotWorn” to use it. This, thus far experimental, algorithm underwent some updates:

1. Value of parameter HASPT.ignore.invalid is automatically set to NA to ensure that truly all non-wear is forced to be a potential part of the guider.
2. Issue fixed which caused that the use of guider “NotWorn” was not correctly logged
3. When “NotWorn” is used the corresponding nights are now automatically skipped in the GGIR part 4 csv report for sleep analyses as we know that no meaningful sleep analyses can be derived from these.
4. Algorithm itself revised to work with both count and raw data.
5. Option added to specify a second guider next to “NotWorn” via parameter HASPT.algo. This second guider will be used when the accelerometer is unexpectedly worn by the participant for more than 75% of the noon-noon time window. For example, HASPT.algo = c(“NotWorn”, “HDCZA”).

This work was made possible via support from Dr. Verswijveren at Deakin University, Australia, and the University of Regensburg, Germany.

Migration of package vignettes to GitHub-pages

Various sections from the main package vignette have been migrated to the GGIR GitHub-pages: wadpac.github.io/GGIR/. The new location offers a number of advantages:

• Easier navigation for the visitor. The documentation is now split up in chapters that can be navigated via tabs and search bar. Additionally, all existing CRAN vignettes can be found via the Annexes-tab.
• Easier to maintain as minor updates can be made without the need to create a new package release.

I created most of the new documentation but would like to thank a few people. Gaia Segastin, PhD-student in Amsterdam, provided detailed feedback on the first four chapters. Further, Fabian Schwendinger and Jairo Migueles proofread all chapters.

Other updates worth highlighting:

• External csv data: Timegap imputation option enabled for ad-hoc csv data.
• Sleep efficiency: GGIR part 5 output variable sleep_efficiency was renamed to sleep_efficiency_after_onset. This was done to better reflect its calculation and to avoid misinterpretation with other definitions of sleep efficiency as used in sleep research.
• Continuous LXMX window analyses in part 2: LXhr and MXhr which had one hour offset when timing was after midnight, this has now been fixed.
• Bug fixed in data_cleaning_file functionality: Bug fixed causing night_part4 column to not be used from the data_cleaning_file.