HomeGGIR release 2.6-0

GGIR release 2.6-0

Monday,  February 7, 2022

In this blog post I will talk you through the main updates in the new GGIR 2.6-0 release. For a full list of updates since the previous CRAN release (version 2.5-0), see the GGIR changelog.

GGIR now able to read .gt3x files via R package read.gt3x

GGIR now also accepts as input .gt3x files from the accelerometer brand ActiGraph with device firmware version 2.5.0 or higher. This will take away the need to convert .gt3x files to .csv format with ActiLife software and speeds up the data processing of ActiGraph data. To create this new functionality, I added a GGIR dependency to the R package read.gt3x as developed by Dr. Tuomo Nieminen and co-maintained by John Muschelli. Next, Dr. Patrick Bos helped me to modify the read.gt3x code to read the .gt3x files in batches needed to facilitate memory management in GGIR. Memory management is critical when processing multiple files in parallel as GGIR can do.

The addition of gt3x compatibility has been sponsored by the University Medicine Greifswald, German Center für Cardiovascular Research (DZHK), site Greifswald, Germany.

Handling ActiGraph data collected with Idle Sleep Mode

Accelerometers from the ActiGraph brand come with a configuration option called Idle Sleep Mode (ISM). ISM is turned on by default and causes the recording of acceleration to stop when the sensor is not moved for 10 seconds. The idea behind ISM is to preserve battery life and by that allow for longer recordings, but it also results in time gaps in the data. To address these time gaps the Actilife software imputes them with zeros in all three axis when converting the .gt3x file to .csv. Both the ISM and the zero-imputation are problematic.

Why ISM and zero-imputation are problematic:
  • Time gaps caused by ISM make data harder to compare with other accelerometer brands who do not have the ISM functionality. Note that there is no open-source software to reproduce the ISM behaviour across accelerometer brands.
  • The imputation by zeros is physically not plausible. An accelerometer should always capture the gravitational acceleration when in rest. Various acceleration metrics, such as SVMgs and ENMO, come with the assumption that they are applied to plausible acceleration signals. The imputation by zeros violates this assumption and by that will lead to biased estimates.
  • The disappearance and reappearance of gravitational acceleration causes a spike at the beginning and the end of the non-movement period when the signal is high-pass frequency filtered. For example, this applies to acceleration metrics such as MAD, BFEN, HFEN, AI0, or MIMSunits.
  • The lack of non-movement periods will complicate investigating and improving the acceleration sensor calibration, which depends on access to data from non-movement periods. Further, the imputation of the time gaps with non-plausible zeros will bias efforts to improve the calibration of the signals if not omitted.
  • Time gaps and the imputation by zeros will complicate estimating sleep and sedentary behaviour because small magnitudes of acceleration are replaced by zeros and information about the orientation of the accelerometer is lost.

To address the problematic imputation by zeros, GGIR now automatically re-imputes time gaps lasting longer than 2 samples. For this, GGIR uses the last XYZ acceleration value from before the time gap and normalizes it to a vector of 1 g. In other words, GGIR assumes that the orientation of the accelerometer during the non-movement period is identical to the last known recorded point in time. However, ideally the ISM should not be used in the first place and I advise all researchers who use ActiGraph devices to always disable the ISM when starting a new recording and to report clearly in publications whether the ISM was turned on or off.

Methodological consistency:

The new imputation as described above can break methodological consistency with ActiGraph data analysis with the previous approach to zero impute the data. However, the discontinuation is essential as the old approach is not justifiable.

This new functionality was sponsored by the University Medicine Greifswald, German Center für Cardiovascular Research (DZHK), site Greifswald, Germany.

Maximum number of days to consider

GGIR argument maxdur has been part of GGIR for a long time and aids the user in masking all data recorded after an integer number of 24 hour windows relative to the start of a recording. However, some studies may prefer this to be focused around calendar days rather than 24 hour windows. Therefore, GGIR now offers argument max_calendar_days, which is the number of calendar days relative to the beginning of the recording to be included in the analysis.

This new functionality was sponsored by the University of Regensburg in Germany.

BrondCounts added

As announced in my previous blog post about the 2.5-0 release, GGIR 2.6-0 has been expanded with the option to estimate sleep via the Sadeh algorithm and the counts calculated with the R package activityCounts. R package activityCounts was developed by Dr. Brondeel and colleagues. Please note that I refer to the counts inside GGIR as BrondCounts since ‘activity counts’ feels too generic and may lead to confusion when put next to other count metrics. The BrondCounts are calculated in GGIR by setting input argument do.brondcounts = TRUE. Next, they will be available in the time series output and used for sleep analysis when argument HASIB.algo = “Sadeh1994″.

Call for validation studies

Please note that the implementation of both the BrondCounts and the zero-crossing counts are only an attempt to imitate the count measures produced by the Actigraph Motionlogger and the ActiGraph as I discussed in my previous blog post. There is no certainty that the calculations are identical to the original, that the calculations have remained consistent over the past 30 years (almost certainly not), or that this approach provides any level of accuracy for estimating sleep. Therefore, it would be valuable if future studies can be carried out to evaluate the performance of these implementations for sleep assessment.

The implementation of the BrondCounts in GGIR has been sponsored by groups from Paris and South Carolina (see previous blog post for details).

Internal structure of parameters

The functionality of GGIR has grown over the years and with that the number of input arguments (parameters). As a result, the code readability got worse and with that the ease of making updates to the code. To address this I refactored the GGIR code such that arguments are internally grouped in parameter objects. The parameter objects are structured thematically, e.g. all parameters related to sleep are stored in the object “params_sleep”. As a user you will be able to continue using the same R scripts and input arguments for GGIR as before. The parameter objects are only used by GGIR internally. However, you may notice some changes in the structure of the package documentation.

GGIR release 2.6-0