GGIR release 3.1-0

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

Major review and tidy up of GGIR part 1 code

Lena Kushleyeva conducted a thorough review and tidy-up of all code related to GGIR part 1. Small differences can be expected in the part 1 output compared with prior versions. This is due to small improvements in the management of timestamps and input data block boundaries. The influence on calibration coefficients may be larger as a bug was fixed. To account for this we have changed default value for parameter minloadcrit to 168 hours to improve the quality of the auto-calibration procedure.

We would like to thank Lena Kushleyeva for the enormous amount of effort she has put into this!

Revisions to handling of externally derived epoch data

The code and algorithm have been simplified to better match expected non-wear detection behaviour. Further, the window length used for non-wear detection for externally derived epoch is now modifiable with the third value of parameters windowsizes (in seconds). As a result, this functionality is now consistent with how it is used for raw data. For example child behaviour research may like to set this to 20 minute as is common in the literature.

Further, we now also facilitates handle of Sensewear xls file format. The Sensewear is an accelerometer brand that no longer exists but for which some research groups still have historical data. To use this set dataFormat = “sensewear_xls” .

The addition of the Sensewear xls format has been made possible with support from researchers at the University of Pittsburgh.

Option to specify study date range per individual

Newly added parameters study_dates_file and study_dateformat allow to specify respectively a csv file with start and end dates when accelerometer is expected to be worn and corresponding date format. This can be useful for studies where accelerometers were sent to participants by mail.

This work has been made possible with support from Nancy W Glynn from University of Pittsburgh.

Logging of encountered time gaps

Time gaps are automatically accounted for in GGIR and this is now also logged for quality assurance purposes. More specifically, we log the number of timegaps and total time imputed for ad-hoc csv and ActiGraph data.

Keeping track of GGIR version numbers

So far, GGIR has stored its version number in the config.csv file. However, we realised that this is ambiguous when using different GGIR versions for different GGIR parts. You would then only find the GGIR version number for the latest run. To address this the GGIR version is now always stored inside each individual milestone file and in each csv report to allow for tracking the version used at each stage of the process for each individual data file.

Implemented and removed update to HDCZA algorithm

In 3.0-7 (28 February 2024) an experimental change was made to the HDCZA algorithm, which was reversed in sub-release 3.0-10 (19 April 2024) . The change was assumed not to cause problems, but we then discovered that it did cause problems and reversed it. Therefore, it is advised not to use GGIR part 3, 4 and 5 output from releases 3.0-7 (28 February 2024), 3.0-8 (5 March 2024), and 3.0-9 (19 March 2024).

GGIR is now more friendly towards users without UK/US computer

• Parameters dec_reports and dec_config were added to configure how GGIR stores csv reports and the csv config file. You may for example want to set this with “;” column separator and “,” decimal separator if you have a computer configured in France or The Netherlands.
• Further, we noticed that in some parts of GGIR the naming of days can switch to the local computer language. To address this, GGIR now consistently forces the language used for refering to week days to UK/US English.

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

Day segment analysis able to handle fraction of minutes

Parameter qwindow can now also handle fraction of minutes, which is primarily useful when qwindow is used with activity diaries.

This work has been made possible with support from Marion Gasser and Elena Mathieu from University of Bern

Key updates to GGIR part 5

• The behaviour of parameter includedaycrit.part5 has been changed for values above 1, these are now interpreted as minimum number of valid waking hours during the waking hours of a day. If you prefer to keep old functionality then divide your old value by 24. The resulting number is the fraction of expected valid data during the waking ours of the day.
• Automatically stores a dictionary for all variable names in part 5 csv reports.
• Fragmentation: The computation for fragmentation metric CoV (Coefficient of Variance) was incorrect has now been fixed.
• Timing of LX is now expressed on a scale between 12 and 36 to allow for meaningful person level summary of this value.
• Parameter HASPT.ignore.invalid can now take value NA, which means that invalid periods are automatically considered candidate sleep periods when working with algorithms HDCZA, HorAngle, or NotWorn. Note that the default value for parameter HASPT.ignore.invalid is still FALSE which means that invalid time periods are imputed at metric level and then used for the deriving the guider. This is the approach used in our publications, but the new approach might be preferable. More research is needed before we can make this the new default.
• We have reverted the original decision to prohibit segmentDAYSPTcrit.part5 to be set to c(0, 0). The default remains unchanged and the documentation for segmentDAYSPTcrit.part5 now emphasizes the downside of using c(0, 0).

The  updates to CoV, includedaycrit.part5, and LX have been made possible with support from an ERC grant project led by Dr. Séverine Sabia, Université de Paris, Inserm in Paris. The automated storage of a variable dictionary has been made possible with support from Nancy W Glynn from University of Pittsburgh.

GGIR part 5 inclusion criteria for the entire day

So far, GGIR part 5 only had inclusion criteria for waking hours of the window. This was motivated by the fact that daytime behaviours are the most important aspect of part 5 and need to be representative. However, on top of this you can now also specify inclusion criteria for the entire window. Remember that in part 5 the definition of a window depends on parameter timewindow, which can be OO (sleep onset – sleep onset), WW (waking up – waking up), or MM (midnight to midnight).

To use this new functionality you need to specify parameter includdaycrit with a vector of two values, e.g. `c(16, 16)`. The first value will be used in part 2 and the second value will be used in part 5. If the second value is not specified then it will default to 0 hours, which means that no inclusion criteria is used.

This work has been made possible with support from Nancy W Glynn from University of Pittsburgh.