GGIR release 2.7-1

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

File handling

  • Functionality for reading GENEA (Unilever Discover) binary files has been temporarily deprecated because one of it’s software dependencies has been temporarily offline. This has recently been resolved and we will restore the GENEA reading functionality in the next GGIR release on CRAN (probably in August/September). This does not affect GENEActiv (ActivInsight) data because that data is stored in a different binary data format.
  • Functionality for reading GENEActiv .csv files has been deprecated. You can still use GGIR’s read.myacc.csv functionality for reading the GENEActiv .csv files, and GGIR default settings for reading GENEActiv .bin files.
  • Functionality to read ActiGraph CentrePoint .GT3X files added.
  • Fixed bug that prohibited processing files in subfolders of the data directory. As a result, you should now again be able to process multiple sub-studies with a single GGIR command using only the parent folder to specify argument datadir.
  • Fixed bug relating to how the date format of an activity diary is interpreted.
  • A new vignette was added describing how to use GGIR function read.myacc.csv to process your ad-hoc .csv format data.
  • All GGIR input arguments are now documented as part of the GGIR function documentation. With ?GGIR on the R(Studio) command line and use the search field or scroll through the documentation.

Function g.shell.GGIR() simplified to GGIR()

Given that g.shell.GGIR() was difficult to pronounce we simplified it to just GGIR() as now clarified in the vignette. The underlying code is identical. Note that function g.shell.GGIR should still work, but please let us know if you have difficulties.

Cosinor analysis

Cosinor analysis entails the fitting of a cosine curve to the accelerometer data to estimate basic characteristics of the circadian rhythm. To enable this with GGIR, a dependency has been added to R package ActCR as developed by Dr. Junrui Di and colleagues. By specifying GGIR argument cosinor = TRUE, GGIR will now conduct both cosinor and extended cosinor analysis (as proposed by Marler et al. 2006) as part of the GGIR part 2. For specific implementation details see our new vignette paragraph on Circadian Rhythm analysis with GGIR.

The addition of the cosinor and extended cosinor analysis has been sponsored by Dr. Séverine Sabia (ANR grant), Université de Paris, Inserm in Paris. Also we would like to thank Dr. Junrui Di for making a new ActCR release to facilitate the integration with GGIR.

Advanced sleeplog

The advanced sleeplog was introduced in 2021 and allows for more information than the basic sleep log. Various updates and bug fixes were made in relation to the advanced sleeplog handling:

  • Better handling of dates in the sleeplog far beyond the accelerometer recording dates.
  • Unnecessary warnings omitted to make console output more informative.
  • Bug fixed when start of the accelerometer recording does not match the start of the advanced sleeplog.
  • Bug fixed when first night is missing in the log.

The improvements to the advanced sleeplog handling have been sponsored by Dr. Beets and the Arnold Childhood Obesity Initiative Research Group at the University of South Carolina.

Output files

  • The pdf QC visualisation that has been part of GGIR for years now automatically scales the horizontal axis to the length of the recording. Previously the user had to specify the axis length with argument maxdur. Note that argument maxdur is still used for specifying the maximum number of days to consider as valid days, but no longer affects the axis length of the QC plot.
  • The output column names related to segmented day analysis are now logically ordered. Previously it ordered the columns alphabetically, as in 1, 10, 11, 2, 20 which has become 1, 2, 10, 11, 20.
  • GGIR .csv reports are now saved with a maximum of 3 decimal places for numeric variables. We do this to improve readability of the csv files, to reduce file size, and to avoid the false impression of super accuracy.

Macos 11 with arm64 architecture not updated yet

We are having difficulties getting the GGIR version 2.7-1 approved for MacOS 11 on arm64 architecture . If this affects you, then you can install the latest GGIR release via GitHub with R package devtools (or the remotes package) instead if you are not using sleeplogs or you could stick with version 2.6-0 as available on CRAN. If you have access to such a machine and are in interested in helping us fix the issue then please let us know via this thread on GitHub.

 

GGIR release 2.6-0

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.5-0

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

(NEW) Tutorial on segmented day analysis

Day segment specific analysis are valuable when studying context specific physical activity. A new tutorial vignette has been added on how to perform an analysis per segment of the day. The tutorial discusses how to segment the day based on clock hours of the day, but also how to use an activity log to tailor the segmentation per participant.

The creation of this tutorial has been sponsored by Dr. Beets and the Arnold Childhood Obesity Initiative Research Group at the University of South Carolina.

(NEW) Sleep Regularity Index

Another addition in GGIR 2.5-0 is the Sleep Regularity Index (SRI). This is a measure of sleep regularity between successive days, as first described by Phillips and colleagues. The SRI can have a value between -100 and 100, where 100 reflects perfect regularity (identical days), 0 reflects random pattern, and -100 reflects perfect reversed regularity. The SRI is proposed to only be calculated based on seven, or a multitude of seven, consecutive days of data without missing values. This to avoid a possible role of imbalanced data to the final estimate. However, this renders many datasets unsuitable for analysis and leads to a painful loss in sample size and statistical power.

Sleep Regularity Index – Dealing with unbalanced data

To address this, I implemented the SRI in GGIR per day-pair. Per day-pair GGIR now stores the SRI value and the fraction of the 30 second epoch-pairs between both days that are valid. This fraction can be found in the output under the variable name SriFractionValid. By default, day-pairs are excluded if this fraction is below 0.66. For those familiar with GGIR this threshold is coupled with the 16-hour default value for argument “includenightcrit”. For example, if you set argument “includenightcrit = 12”, the fraction threshold will be: 12 / 24 = 0.5. Note that I have implemented the SRI calculation such that it accounts for the missing values in the denominator. As a result, the SRI value interpretation remains unchanged.

The 30 second epoch setting is automatically applied, even if the rest of the GGIR process works with a different epoch duration.

The day-pair level estimates are stored as variable SleepRegularityIndex in the .csv-report on sleep (GGIR part4 for those familiar with GGIR). Further, GGIR also stores the person-level aggregates such as: the plain average over all valid days, the average of all valid weekend days, and the average of all valid week days. No GGIR input arguments are needed to invoke the SRI calculation. The calculation is automatically performed after updating GGIR and processing your data.

Sleep Regularity Index – Benefits of the revised approach
  • It enables the user to study the day-pair to day-pair variation in SRI, and the role of day-pair inclusion criteria.
  • The access to SRI at day-pair level makes it possible to account for an imbalanced datasets via multi-level regression analysis applied to the output of GGIR, with day-pair as one of the model levels.

The implementation of the Sleep Regularity Index has been sponsored by Dr. Beets and the Arnold Childhood Obesity Initiative Research Group at the University of South Carolina.

(REMOVED) Sensor fusion functionality

In GGIR version 2.2-2 (early 2021), a new functionality was added to facilitate the fusion of accelerometer and gyroscope signals at raw data level. This work was done as an expertise development project, but it has become clear that there is no major added value of this functionality for GGIR. Please note that the code is still in the GitHub and CRAN history, such that it can be revived if ever needed.

(NEW) Advanced sleeplog format now facilitated

For a long time, GGIR only facilitated one specific type of sleeplog format. The format assumed that the first night in the accelerometer recording corresponds with the first night in the sleeplog. As you can imagine, this complicates the analyses of accelerometer recordings that are not aligned with sleeplog entries.

In the newly added advanced sleep log format, recording dates are stored per night and used by GGIR to ensure correct alignment of each single night in the sleeplog with corresponding night in the accelerometer data. Additionally, the advanced sleeplog format allows for optional storing of information such as non-wear and napping behaviour. At the moment, GGIR extracts and stores these additional types of information in the GGIR milestone data. Integration in the GGIR reports is work in progress. See GGIR vignette paragraph on sleep analysis for further details.

The addition of the advanced sleeplog format has been sponsored by Dr. Plancoulaine and Dr. Bernard from the Research Team on Early life origins of health (EAROH) at the Centre for Research in Epidemiology and Statistics, Université de Paris, Inserm in Paris.

(NEW) Sadeh and Galland sleep classification

An attempt has been made to implement the sleep classification algorithms proposed by Sadeh et al. 1994 and Galland et al. 2012. I am calling it an attempt, because both algorithms rely on summary measures of the data produced by proprietary wearable sensor technology, referred to as ‘counts’.

In short, Sadeh and colleagues detailed that their counts were generated by the Motionlogger actigraph by Ambulatory Monitoring Inc, and explained that the ‘counts’ represented a zero-crossing count of the acceleration signal. However, critical parts of the calculation to support scientific reproducibility were not published. The lack of transparency has been typical for many wearable sensor manufacturers from the late 20th century. Consequently, it has complicated comparisons of research findings in both the sleep and physical activity research communities.

Sadeh and Galland sleep classification – Brønd(eel)Counts to the rescue?

To facilitate backward comparability of modern accelerometer data with count-technology, Jan Brønd et al. proposed an algorithm to estimate the count values produced by one of the other manufacturers, and Ruben Brondeel released the algorithm as open source R package. Their counts, let’s call them the Brønd(eel)Counts, do not count zero-crossings but calculate the area under the filtered acceleration signal. Despite this fundamental difference in calculation, there are preliminary hints now that the Brønd(eel)Counts are possibly more suitable for use with the Sadeh algrotihm then the zero-crossing counts. If this would be true than that would indicate that the description given by Sadeh in 1994 did not reflect the actual proprietary calculation done by the Motionlogger actigraph at the time.

My plan is to embed the combination of Brønd(eel)Counts and Sadeh and Galland algorithm in the next GGIR release to facilitate a direct comparison. For details on how to use the current approach see vignette paragraph on sleep analysis arguments.

The implementation of the Sadeh and Galland algorithms has been sponsored by Dr. Plancoulaine and Dr. Bernard from the Research Team on Early life origins of health (EAROH) at the Centre for Research in Epidemiology and Statistics, Université de Paris, Inserm in Paris.

(NEW) sleepwindowType

Until now the GGIR-based sleep analysis came with the assumption that the either of the following conditions is true:

  • The user has not collected sleeplog data to guide the accelerometer-based sleep analysis.
  • The user collected sleeplog data, which asked for sleep onset and waking-up time (Sleep Period Time window).

The disadvantage of both scenarios is that sleep latency and sleep efficiency cannot be estimated. GGIR version 2.5-0 addresses this for the two scenarios described below. In both scenario 1 and 2, sleep latency and sleep efficiency will be estimated and included in the .csv-report on sleep (GGIR part 4).

Scenario 1: The sleeplog records time in bed

To inform GGIR about this scenario specify input argument: sleepwindowType = “TimeInBed”. Note that the default value is “SPT” (Sleep Period Time window).

Scenario 2: Accelerometer worn on the hip

In this scenario we can attempt to detect lying down based on estimating the accelerometer orientation. To use this functionality specify argument: sensor.location=”hip”.  For a more elaborate description see vignette paragraph on guiders.

Note: The sleepwindowType feature was accidentally disabled in the 2.5-0 release on CRAN. This has now been corrected in the development version of GGIR on GitHub. To install the updated development version use the following commands in the R(Studio) console:

install.packages(remotes)
library(remotes)
remotes::install_github("wadpac/GGIR", ref = "2.5-1")
library(GGIR)

The addition of the sleepwindowType option has been sponsored by Dr. Plancoulaine and Dr. Bernard from the Research Team on Early life origins of health (EAROH) at the Centre for Research in Epidemiology and Statistics, Université de Paris, Inserm in Paris.

Accelting: New name, logo, and website

Getting started

When I started my independent consultancy work in early 2018 I did it for no more than 1 day per week. So, it did not seem necessary to actively invest in my branding with a fancy website or logo. My work was mainly a practical solution to the growing demand for my time as developer of a popular R package. Therefore, a simple website that I built myself and a logo created in Paint felt sufficient. In May 2019 I made the step to full-time independence. As the work is going well, I have decided to finally improve on my branding.

Deciding on a name

An important step in this process was to come up with a catchy trading name. My old trading name was ‘Human Movement Data Consulting’. Except from being boring, it may also give the false impression that I trade in data. My new trading name ‘Accelting’ stands for my consultancy services around accelerometry. Accelerometry is the technology at the core of all my work. I have experience with other data types, but in general accelerometry has been and will remain my focus. Next, the subtitle “Advancing movement and sleep research” should clarify the central goal of my work.

New logo and website

For the design of the new logo I worked with Yellowinq, Mindworkz designed and built the website, and Sociaal Kapitaal helped me with the branding story. I hope the new website will make it easy to understand what I can do for you and helps to keep you informed about my activities.