GGIR release 2.9-0

In this blog post we will talk you through the main updates in the new GGIR 2.9-0 release. For a full list of updates since the previous CRAN release (version 2.8-2), see the [GGIR changelog]( https://cran.r-project.org/web/packages/GGIR/news.html).

Dependency on R package GENEAread deprecated

In the previous GGIR update we introduced R package GGIRread as a faster way to read GENEActiv binary (.bin) files within GGIR. As this seems to be working well we deprecated the dependency on R package GENEAread. R package GENEAread has been of high value for the development and success of GGIR. We would like to thank the GENEAread developers Joss Langford, Charles Sweetland and Zhou Fang for creating and maintaining GENEAread all those years.

Metric “brondcounts” replaced by “neishabouricounts”

We deprecated the “brondcounts”. This count metric was originally developed by Jan Brønd and implemented in R package activityCounts by Jan Brondeel and colleagues. Therefore, we called it brondcounts in GGIR. However, we had to deprecate them in GGIR as R package activityCounts was removed from CRAN because of a series of issues. Instead GGIR now uses the counts proposed by Neishabouri which we refer to in GGIR as the neishabouricounts. GGIR relies on R package actilifecounts for the calculation of the neishabouricounts. To tell GGIR to extract these counts you should use argument do.neishabouricounts = TRUE. Further, argument acc.metric is used to specify which axis is of interest, e.g. acc.metric = “NeishabouriCount_x”. The low-frequency extension of the algorithm can be activated by Boolean argument actilife_LFE (see documentation on argument do.neishabouricounts for details).

Ad-hoc formatted csv input files: Now possible to account for tz of device configuration

Ad-hoc csv files can be read by GGIR via the generic function read.myacc.csv. This already allowed for accounting for the timezone where the accelerometer is worn. This function has been expanded so that the user can now define the timezone in which the accelerometer was configured (argument rmc.configtz). Note that this was already available for various other data formats, but not yet for ad-hoc csv data. Note that argument configtz (without the “rmc.”) is currently not used for this data format. Our plan for later this year is to deprecate rmc.configtz and rmc.desiredtz and make configtz and desiredtz be the only timezone arguments used across all data formats.

This work has been sponsored by a pharmaceutical company based in the United States.

Non-wear detection algorithm: Now possible to skip last step

The last step of the nonwear detection algorithm entails labelling the first or last three hours of the time series as invalid if they contains any non-wear episode. We have added the Boolean argument nonWearEdgeCorrection (default FALSE). When set to TRUE this step of the algorithm is skipped. Skipping the last step can important when working with short recordings, such as laboratory experiments.

This work has been sponsored by Dr. Beets and the Arnold Childhood Obesity Initiative Research Group at the University of South Carolina.

Bout detection algorithm

We identified and fixed a couple of minor bugs in the existing code for bout detection:

• GGIR overestimated the bout length by 1 epoch if the epoch length was less than 30 seconds.
• The combination of bout length of 1 minute and epoch length of 1 minute caused bouts of 1 minute to be missed.

While addressing these bugs we deprecated input argument bout.metric that was used to select older versions of the algorithm. We have done this because we believe that the continued re-use of the older versions of the algorithm should be discouraged. To reproduce analysis from the past we recommend using older versions of GGIR. Subsequently argument closedbout has also been deprecated as this was only used in one of the older algorithm versions.

Handling of seconds in activity diary

Day segment analyses based on an activity diary used to only consider the hours and minutes of the time specified. This has been updated to also consider the seconds in the timestamps. For example, your can now define an interval from 10:30:25 to 11:15:40. If the timestamps are not a multiple of the epoch length, then GGIR would use the following epoch. For example, if epoch is 5 seconds and user defines 10:30:27 in the diary, then 10:30:30 would be considered.

Improved handling of DST in part 2

Previously GGIR part 2 considered the day saving time (DST) when extracting the start time of the recording, when deriving the number of (valid) hours in a recording day, and when splitting up the recordings in time series per day. However, within the analysis per day, GGIR did not account for DST. We have now addressed this: The day-level analyses in part 2 now standardises the number of hours in a day to create a fair comparison between days:

• When the day is 23 hours, we insert one hour of the average day at 2am
• When a day is 25 hours, we remove the deboul hour between 2am and 3am

As a result, this may affect day-specific analysis of MXLX (e.g. M5, M10, L5, and L10), quantiles (argument qlevels), intensity distribution (argument ilevels), intensity gradient (argument iglevels), and time spent in MVPA for the two days in the year in timezones where DST applies.

This work was sponsored by the University of Regensburg in Germany.

Including last incomplete day in part 5 (follow-up)

In our previous CRAN release 2.8-2 we introduced argument expand_tail_max_hours. However, after additional reflection we realised that this was not intuitive. Therefore, we have now replaced it by argument recordingEndSleepHour being the time (in hours) at which the researcher assumes the participant to be asleep. If the recording ends at or after this time GGIR part 1 will expand the time series with synthetic sleep-like data in order to trigger sleep detection for last night. As previously discussed this functionality should be used with caution. An error is produced if the value is set below 19 (7pm) as such values are not permitted.

The work on including the last day has been sponsored by the University Medicine Greifswald, German Center für Cardiovascular Research (DZHK), site Greifswald, Germany.

Improved determination of file directories in Windows OS

GGIR is now able to handle double backward slash in file paths for the determination of directories and file paths, i.e., datadir, outputdir, qwindow, loglocation and data_cleaning_file arguments. Primarily useful if you work with interactive directory selection via utils::choose.dir or utils::choose.files on a Windows OS.

Handling subfolders and skipped recordings

GGIR did have difficulty keeping track of filename-ID relation when recordings are skipped in parts of GGIR and when the original accelerometer data was stored across multiple subfolders of the data directory (argument datadir). Similarly, the code for the visual report had difficulty matching the right filename to the report when files were skipped in earlier steps of GGIR. These issues have now been addressed.

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

csv-reports

• GGIR now skips to create csv- and visual-report if the required milestone data is not available.
• When GGIR part 5 reports exclude first and last night (based on argument excludefirstlast.part5) the code now considers the window type selected (MM or WW).
• The output variable nonwear_perc_spt does now only appear in csv-reports part4_nightsummary and part4_summary when WW windows are used in GGIR part 5.  We do this to avoid inconsistencies in the definition of the night numbers and this is now also explained in the main vignette.

Other brief updates

• Verbose argument: User can now specify verbose = FALSE to simplify the messages printed to the console to warnings and errors only. (UPDATE: we have noticed that this currently fails to suppress some of the messages when do.parallel is set to FALSE. We aim to address this before the next release).
• Speed increase in GGIR part 5: GGIR part 5 speed has been increased for long multi-week recordings.
• Documentation MX metrics by Rowlands et al.: New section added in the main vignette regarding the MX-metrics. We would like to thank Alex Rowlands and Ben Maylor for providing this!
• Sleep diary handling: A bug was fixed causing the last night in the sleeplog to be ignored in the advanced sleeplog. Further, argument sleeplogidnum has been deprecated as GGIR should now automatically recognise whether the ID in a sleeplog is in numeric or character format.