GGIR release 3.2-0

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

Bug fixes:

• A bug caused some files to be unnecessarily excluded from the part 2 csv report, when there are files in a dataset that cannot be processed with GGIR part 2 but can be processed with GGIR part 1. This bug must have existed for at least 3 years, but was not discovered until recently.

User experience:

• The existence of two parameter sets to specify MVPA bout definition in part 2 and 5 serves no clear purpose as typically users want the same definition in both parts. To address this, I have now simplified the specification of the MVPA-related parameters in part 2. When parameters mvpathreshold and boutcriter are not specified, GGIR copies the values from the corresponding part 5 parameter values (threshold.mod and boutcriter.mvpa).
• Part 2 and 4: Both activity diary and sleep diary are now always reloaded if the derived copy of it (as stored in .RData format) is older than the diary itself or if the diary name has changed, but skipped if this is not the case, which saves processing time for larger diaries.
• Part 5: Default values for parameters do.sibreport and save_ms5rawlevels changed to TRUE and for save_ms5raw_format changed to “RData” in order to ease generating visual reports and working with part 6. You can still get the “csv” time series output by setting save_ms5raw_format = “csv”.
• Part 5 and 6: part6_threshold_combi when not specified now defaults to first threshold as specified for light, moderate and vigorous intensity, respectively.

Algorithms:

• Part 4: Parameter sib_must_fully_overlap_with_TimeInBed added to control whether sustained inactivity bouts (sib) must overlap fully with the start and/or end of time in bed to be considered sleep (default TRUE), this is consistent with functionality in the past, but offers the freedom to experiment with alternative settings.
• Part 2: Added parameters nonwearFiltermaxHours and nonwearFilterWindow to give user the option to filter short lasting nighttime nonwear.
• Part 2: Increase sensitivity clipping detection from 80% to 30% of a window. If the long epoch has more than 30% of its values close to the dynamic range of the sensor then it will be labelled as clipping.
• Part 6 expanded with more circadian rhythm outcomes:
  • Added DFA functionality (credits: Ian Meneghel Danilevicz and Victor Barreto Mesquita for developing the code)
  • Added fragmentation metrics, same function as in part 5 but now applied at recording level as opposed to day levels.
  • Circadian rhythm analysis now ignores invalid nights controlled with new parameter includecrit.part6.
• Part 2 + 6: Revised and simplified IV and IS calculation which now ignores invalid timestamps and also comes with phi statistic (credits: Ian Meneghel Danilevicz). In part 2 we used to have 2 calculations, which is now replaced by just one and applied to all valid data points in the recordings. In part 6 this is repeated for the time window as specified with parameter part6Window. Further, IVIS now uses argument threshold.lig as threshold to distinguish inactivity from active, instead of a hardcoded threshold of 20 mg.
• part5 added to allow for controlling inclusion of windows in part 5 based on their amount of valid data during spt window. Default remains the same.

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

Reports:

• A new visualreport was added that is automatically generated when visualreport = TRUE (default) and stored as “report_…”. This pdf reports is intended to eventually replace the problematic legacy .pdf report which is now stored with new names starting with “old_report_”. Further, I have added Boolean parameter old_visualreport to turn off the generation of the old visualreport. The new report shows the time series exactly as how they are present inside GGIR part 5 and by that allows for quality checking and understanding results.
• All LX and MX variables were moved from part 5 to part 6 as these are circadian rhythm outcomes, which are now exclusive to GGIR part 2 and 6.

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

Other:

• Due to updates to R, GGIR was no longer backward compatible with R 4.2.0 (2022) and before. I have now fixed this.
• I have added the Verisense step detection R script to the GGIR GitHub repository folder ‘user-scripts‘. Verisense does not actively maintain the Verisense code at the moment, which has been causing confusion for users. For example, their version of the script does not include the updated parameter set as recommended by Rowlands et al. in “Stepping up with GGIR 2022”. By having the script inside GGIR it allows us to maintain it.