GGIR release 3.0-0

Wednesday, October 25, 2023

In this blog post we will talk you through the main updates in the GGIR 3.0-0 release. For a full list of updates since the 2.9-0 CRAN release, see the GGIR changelog.

New version of non-wear detection

GGIR’s non-wear detection has been the same since its first release in 2013. It works as follows: The standard deviation of a rolling signal window needs to be close to the noise level of sensor. If the condition is met, GGIR labels the middle 15 minutes of that 60 minute window as non-wear. You can find a more elaborate description here. This last step of only labelled the middle 15 minutes was intended to make the method conservative in its classification. However, in practise we see that it often leads to missing the first and last 22.5 minutes of a non-wear period.

To address this we have implemented an alternative version of the algorithm to label the entire 60 minute window as non-wear if the threshold condition is met. If you want to keep using the older approach then set argument nonwear_approach to “2013”, but by default it will now be “2023” to label the full window as non-wear.

Onset-Onset (OO) windows in part 5

As you probably know GGIR part 5 facilitates two definitions of a day window:

From midnight to midnight referred to as MM.
From waking-up to waking-up, referred to as WW.

This functionality has now been extended with:

From sleep onset to sleep onset, referred to as OO.

To use this, specify argument timewindow = “OO”.

The addition of the OO window has been made possible with support from Dr. Séverine Sabia (ERC grant), Université de Paris, Inserm in Paris.

Sleep efficiency metric

For a while now, GGIR part 4 derives the sleep efficiency if time in bed is recorded in a sleep diary. The calculation assumes that the end of diary-based time in bed defines the end of the night. Pieter-Jan Marent pointed out to us that this may be incorrect if the person stays in bed after waking up. Therefore, GGIR now offers a new argument to specify how to deal with this: sleepefficiency.metric = 1 (default and consistent with previous GGIR versions) will calculate sleep efficiency as the total sleep duration during SPT divided by the diary-based duration in bed, while sleepefficiency.metric = 2 (new) will divide the total sleep duration in SPT by the accelerometer-detected duration in sleep period time plus the sleep latency (i.e., difference between diary-derived sleep onset and accelerometer-detected sleep onset).

The addition of sleepefficiency.metric option has been supported by Pieter-Jan Marent from KU Leuven

Readability of GGIR code

With GGIR being developed over many years with ever growing functionality it is tempting for us as developers to only focus on fixing bugs, adding new functionalities, and tidying up the old code we encounter during these efforts. Nevertheless, the fact that some parts of the code function well does not mean they are efficiently written. Lena Kushleyeva has been conducting a thorough review of some of the older parts of GGIR and has been proposing and implementing a number changes that have improved readability and efficiency. Thank you Lena!

Reading Axivity cwa files

The readAxivity function from the GGIRread package has been revised and is not only much faster now but also conducts an integrity check for each data block. If the integrity check does not pass for a block, which typically equals 2-3 seconds of data, the block is imputed with a constant value. A log is kept of the blocks that are imputed and incorporated in the data_quality_report.csv file. Corresponding new column names are now documented in the GGIR vignette in the section that discusses GGIR results.

These developments have been sponsored by Dr. Séverine Sabia (ERC grant), Université de Paris, Inserm in Paris, and we would like to thank Lena Kushleyeva for her help with optimising the implementation.

Bug fix in processing Actigraph .gt3x files

A bug was discovered in how .gt3x data (ActiGraph) where processed. More specifically, the autocalibration routine was performed but the calibration correction coefficients were not actually applied to the data. Importantly, this has affected all analysis done on gt3x data since the gt3x reading functionality was added to GGIR in version 2.5-4. We are sorry for not spotting this anytime sooner.

Deprecated functionality for reading .wav and old GENEA .bin files

We have deprecated functionality for processing file formats .wav (Axivity Ltd) and .bin (Unilever Discover). Keeping the corresponding code up to date with newer R versions is currently too time consuming. If you are interested in re-inserting this functionality and helping us to make a plan for ongoing maintenance then please contact us. Note that this does not affect processing .cwa (Axivity Ltd) and .bin (ActivInsights Ltd) files.

Day segment analysis in part 5

Argument qwindow that aids day segment analysis in part 2 now also works for part 5.

However, to do this meaningfully it only considers day segments that overlap for 90% with waking hours. This is controlled by argument segmentDAYSPTcrit.part5 which by default is set to c(0.9, 0) to require at least 90% of the window to overlap with daytime. Alternatively, to focus on overlap with SPT window change this to c(0, 0.9). The documentation for argument segmentDAYSPTcrit.part5 provides further clarifications.

This new functionality has been made possible with support from Marion Gasser and Elena Mathieu (University of Bern, Institute for Sports Science)

Intensity gradient over full window in part 5

Intensity gradient is now also calculated for the full window in part 5 and column names now indicate the window (i.e., “_day_” or “_day_spt_”). Subsequently, the functionality has been investigated in a recent publication.

These developments have been sponsored by Dr. Séverine Sabia (ERC grant), Université de Paris, Inserm in Paris.

Inclusion of first day in part 5 midnight-midnight (MM) analysis

When recording starts after midnight and before 4am, GGIR used to skip the wake-up time detection of this first window and classify the full window as awake. Now, parts 3-4 ensure that this first wake-up time is derived to be used in part 5. This first night starting between midnight and 4am is skipped in the part 4 csv reports as it might be biased, yet the wake-up time is used in part 5 to better define the awake and sleep windows.

Identification of column names in advanced sleeplog format is now case insensitive. Further, arguments sleeplogsep and nnigths are now deprecated as the separator and number of nights are detected automatically in sleep logs without the need for user input.

Appending accelerometer recordings

Some studies use multiple consecutive accelerometer recordings in order to monitor a person for longer periods of time. However, GGIR did not offer a clear strategy for handling such study designs. To address this, GGIR now facilitates appending recordings with matching ID and within a specified maximum time interval in between recordings. To do this it first processes the individual files in GGIR part 1 and then appends the resulting time series in the milestone data, imputes time gaps or uses the newer recording in case of overlap. For more information see documentation for argument maxRecordingInterval.

This additional functional has been made possible with support from Dr. Spilsbury at the Dept. of Population & Quantitative Health Sciences within Case School of Medicine, Ohio, US

Handling of externally derived epoch data

Although GGIR focussed on the processing of raw data, some groups are still in the possession of older epoch level data produced by external software or firmware such as Actiwatch and ActiGraph. To support these groups, GGIR is now also able to process these epoch data. This involves the following arguments:

dataFormat, which can be set to “actigraph_csv”, “ukbiobank_csv”, “actiwatch_csv”, “actiwatch_awd”
extEpochData_timeformat to specify format of the timestamps

For more information see argument documentation page.

This functionality has been made possible with support from Dr. Mylène Bohmer at Erasmus MC in The Netherlands and additional feedback from Chris King based in Cincinnati, US.

Updated OSS license

Open-Source Software License for GGIR changed to Apache 2.0 as discussed in our previous blog post.

Comma separator handling

You can now specify the separator used by GGIR to write csv-report files with argument sep_reports. This is used for reports in part 2, part 4 and part 5, data_quality_report.
You can now specify the separator used by GGIR to write the .csv config file with argument sep_config.
GGIR further has increased flexibility to read csv files related to sleeplog, activity log, data cleaning file, and csv containing calibration coefficients, by automatically detecting any separator argument from the set of [,\t |;] with function data.table::fread.

Visual report

Various bug fixes in the “visualreport” which is a pdf files with plots of the data and classification (argument visualreport). Further, a new Boolean argument was added visualreport_without_invalid which allows you to only visualise the days that are considered valid by GGIR part 5.

The work has been sponsored by the Program in Sleep Medicine Epidemiology at Brigham and Women’s Hospital, Boston, United States

New guidance on how to use count cut-points in GGIR

The vignette on cut-points has been expanded with guidance on how to work with count metrics and corresponding cut-points.

New options to account for study protocol in the masking of data

Argument ‘strategy=3’, that already existed before, looks for the most active continuous window of X days. This window can start at any time in a day. We have now added the option ‘strategy=5’. Strategy 5 facilitates selecting the most active X calendar days. Further, strategy 3 and 5 can now be used in combination with arguments hrs.del.start and hrs.del.end which then ignores the specified number of hours at the start and/or end of the derived window, respectively.

The first half of the work has been made possible with support from Nina Vansweevelt from KU Leuven. The second half of the work has been made possible with support from Nancy W Glynn from University of Pittsburgh.

Planned GGIR documentation enhancements

We are planning to partially migrate and revise the GGIR documentation to a new location https://wadpac.github.io/GGIR/. At the moment this is only an empty framework and the exact URL may change. Advantages of this effort should be:

Opportunity to revisit the documentation structure and readability, of the explanations currently given in the CRAN vignettes.
Easier for the user to navigate.
Easier for us to maintain.

The existing CRAN vignettes will not disappear, but parts of it will eventually migrate to this new documentation framework.

To develop this free resource for the community we are looking for volunteers to help us with:

Review and provide feedback on current draft table of contents.
Review and provide feedback on chapter drafts.
Create of visualisations to support the text.
Find funding to hire editor and/or graphics artists to help optimise the documentation.

What we expect from you:

Experience with GGIR and the functionalities you will help us to document.

Advantages for you:

By interacting with us you will test and possibly expand your own GGIR knowledge.
Opportunity to learn R markdown or advance your existing R markdown skills.
You will be listed as documentation contributor.