The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.
NOTE: With the growing amount of functionality in GGIR we have decided to migrate the narrative documentation to the GitHub pages of GGIR. This to ease maintenance and accessibility. Therefore, many of the sections in this vignette have been replaced by a link to their new location.
GGIR is an R-package to process multi-day raw accelerometer data for physical activity and sleep research. The term raw refers to data being expressed in m/s2 or gravitational acceleration as opposed to the previous generation accelerometers which stored data in accelerometer brand specific units. The signal processing includes automatic calibration, detection of sustained abnormally high values, detection of non-wear and calculation of average magnitude of dynamic acceleration based on a variety of metrics. Next, GGIR uses this information to describe the data per recording, per day of measurement, and (optionally) per segment of a day of measurement, including estimates of physical activity, inactivity and sleep. We published an overview paper of GGIR in 2019 link.
This vignette provides a general introduction on how to use GGIR and interpret the output, additionally you can find a introduction video and a mini-tutorial on YouTube. If you want to use your own algorithms for raw data then GGIR facilitates this with it’s external function embedding feature, documented in a separate vignette: Embedding external functions in GGIR. GGIR is increasingly being used by research groups across the world. A non-exhaustive overview of academic publications related to GGIR can be found here. R package GGIR would not have been possible without the support of the contributors listed in the author list at GGIR, with specific code contributions over time since April 2016 (when GGIR development moved to GitHub) shown here.
Cite GGIR:
When you use GGIR in publications do not forget to cite it properly as that makes your research more reproducible and it gives credit to it’s developers. See paragraph on Citing GGIR for details.
How to contribute to the code?
The development version of GGIR can be found on github, which is also where you will find guidance on how to contribute.
How can I get service and support?
GGIR is open source software and does not come with service or support guarantees. However, as user-community you can help each other via the GGIR google group or the GitHub issue tracker. Please use these public platform rather than private e-mails such that other users can learn from the conversations.
If you need dedicated support with the use of GGIR or need someone to adapt GGIR to your needs then Vincent van Hees is available as independent consultant.
Training in R essentials and GGIR We offer frequent online GGIR training courses. Check our dedicated training website with more details and the option to book your training. Do you have questions about the training or the booking process? Do not hesitate to contact us via: training@accelting.com.
Also of interest may be the brief free R introduction tutorial.
Change log
Our log of main changes to GGIR over time can be found here.
Install GGIR with its dependencies from CRAN. You can do this with one command from the console command line:
install.packages("GGIR", dependencies = TRUE)
Alternatively, to install the latest development version with the latest bug fixes use instead:
install.packages("remotes")
remotes::install_github("wadpac/GGIR")
Additionally, in some use-cases you will need to install one or multiple additional packages:
install.packages("GGIRread")
install.packages("read.gt3x")
do.neishabouricounts = TRUE
), install the actilifecounts
package with install.packages("actilifecounts")
cosinor = TRUE
),
install the ActCR package with
install.packages("ActCR")
read.myacc.csv
and argument
rmc.noise
in the GGIR function
documentation (pdf). Note that functionality for the following file
formats was part of GGIR but has been deprecated as it required a
significant maintenance effort without a clear use case or community
support: (1) .bin for the Genea monitor by Unilever Discover, an
accelerometer that was used for some studies between 2007 and 2012)
.bin, and (2) .wav files as can be exported by the Axivity Ltd OMGUI
software. Please contact us if you think these data formats should be
facilitated by GGIR again and if you are interested in supporting their
ongoing maintenance.This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.
You will probably never need to think about most of the arguments listed above, because a lot of arguments are only included to facilitate methodological studies where researchers want to have control over every little detail. See previous paragraph for links to the documentation and how to find the default value of each parameter.
The bare minimum input needed for GGIR
is:
library(GGIR)
GGIR(datadir="C:/mystudy/mydata",
outputdir="D:/myresults")
Argument datadir
allows you to specify where you have
stored your accelerometer data and outputdir
allows you to
specify where you would like the output of the analyses to be stored.
This cannot be equal to datadir
. If you copy paste the
above code to a new R script (file ending with .R) and Source it in
R(Studio) then the dataset will be processed and the output will be
stored in the specified output directory.
Below we have highlighted the key arguments you may want to be aware of. We are not giving a detailed explanation, please see the package manual for that.
mode
- which part of GGIR to run, GGIR is constructed
in five parts with a sixth part under development.overwrite
- whether to overwrite previously produced
milestone output. Between each GGIR part, GGIR stores milestone output
to ease re-running parts of the pipeline.idloc
- tells GGIR where to find the participant ID
(default: inside file header)data_masking_strategy
- informs GGIR how to consider
the design of the experiment.
data_masking_strategy
is set to value 1, then check
out arguments hrs.del.start
and
hrs.del.end
.data_masking_strategy
is set to value 3 or 5, then
check out arguments ndayswindow
, hrs.del.start
and hrs.del.end
.maxdur
- maximum number of days you expect in a data
file based on the study protocol.desiredtz
- time zone of the experiment.chunksize
- a way to tell GGIR to use less memory,
which can be useful on machines with limited memory.includedaycrit
- tell GGIR how many hours of valid data
per day (midnight-midnight) is acceptable.includenightcrit
- tell GGIR how many hours of a valid
night (noon-noon) is acceptable.qwindow
- argument to tell GGIR whether and how to
segment the day for day-segment specific analysis.mvpathreshold
and boutcriter
-
acceleration threshold and bout criteria used for calculating time spent
in MVPA (only used in GGIR part2).epochvalues2csv
- to export epoch level magnitude of
acceleration to a csv files (in addition to already being stored as
RData file)dayborder
- to decide whether the edge of a day should
be other than midnight.iglevels
- argument related to intensity gradient
method proposed by A. Rowlands.do.report
- specify reports that need to be
generated.viewingwindow
and visualreport
- to create
a visual report, this only works when all five parts of GGIR have
successfully run. Note that the visual report was initially developed to
provide something to show to study participants and not for data quality
checking purposes. Over time we have improved the visual report to also
be useful for QC-ing the data. however, some of the scorings as shown in
the visual report are created for the visual report only and may not
reflect the scorings in the main GGIR analyses as reported in the
quantitative csv-reports. Most of our effort in the past 10 years has
gone into making sure that the csv-report are correct, while the
visualreport has mostly been a side project. This is unfortunate and we
hope to find funding in the future to design a new report specifically
for the purpose of QC-ing the anlayses done by GGIR.maxRecordingInterval
- if specified controls whether
neighboring or overlapping recordings with the same participant ID and
brand are appended at epoch level. This can be useful when the intention
is to monitor behaviour over larger periods of time but accelerometers
only allow for a few weeks of data collection. GGIR will never append or
alter the raw input file, this operation is preformed on the derived
data.study_dates_file
- if specified trims the recorded data
to the first and last date in which the study took place. This is
relevant for studies that started the recording several days before the
accelerometers were actually worn by participants. This is used on the
top of data_masking_strategy, so that it may be combined with the
strategies in GGIR.This section has been rewritten and moved. Please, visit the vignette Published cut-points and how to use them in GGIR for more details on the cut-points available, how to use them, and some additional reflections on the use of cut-points in GGIR.
If you consider all the arguments above you me may end up with a call
to GGIR
that could look as follows.
library(GGIR)
GGIR(mode=c(1,2,3,4,5),
datadir="C:/mystudy/mydata",
outputdir="D:/myresults",
do.report=c(2,4,5),
#=====================
# Part 2
#=====================
data_masking_strategy = 1,
hrs.del.start = 0, hrs.del.end = 0,
maxdur = 9, includedaycrit = 16,
qwindow=c(0,24),
mvpathreshold =c(100),
excludefirstlast = FALSE,
includenightcrit = 16,
#=====================
# Part 3 + 4
#=====================
def.noc.sleep = 1,
outliers.only = TRUE,
criterror = 4,
do.visual = TRUE,
#=====================
# Part 5
#=====================
threshold.lig = c(30), threshold.mod = c(100), threshold.vig = c(400),
boutcriter = 0.8, boutcriter.in = 0.9, boutcriter.lig = 0.8,
boutcriter.mvpa = 0.8, boutdur.in = c(1,10,30), boutdur.lig = c(1,10),
boutdur.mvpa = c(1),
includedaycrit.part5 = 2/3,
#=====================
# Visual report
#=====================
timewindow = c("WW"),
visualreport=TRUE)
Once you have used GGIR
and the output directory
(outputdir) will be filled with milestone data and results.
This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.
Create an R-script and put the GGIR call in it. Next, you can source
the R-script with the source
function in R:
source("pathtoscript/myshellscript.R")
or use the Source button in RStudio if you use RStudio.
This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.
This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.
GGIR generates the following types of output. - csv-spreadsheets with all the variables you need for physical activity, sleep and circadian rhythm research - Pdfs with on each page a low resolution plot of the data per file and quality indicators - R objects with milestone data - Pdfs with a visual summary of the physical activity and sleep patterns as identified (see example below)
This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.
This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.
This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.
This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.
This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.
This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.
This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.
This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.
This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.
This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.
This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.
In this chapter we will try to collect motivations and clarification behind GGIR which may not have been clear from the existing publications.
Some tips to increase reproducibility of your findings:
This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.
This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.
This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.
Although many data points are collected we decide to only work with aggregated values (e.g. 1 or 5 second epochs) for the following reasons:
Accelerometers are often used to describe patterns in metabolic energy expenditure. Metabolic energy expenditure is typically defined per breath or per minute (indirect calorimetry), per day (room calorimeter), or per multiple days (doubly labelled water method). In order to validate our methods against these reference standards we need to work with a similar time resolution.
Collapsing the data to epoch summary measures helps to standardise for differences in sample frequency between studies.
There is little evidence that the raw data is an accurate representation of body acceleration. All scientific evidence on the validity of accelerometer data has so far been based on epoch averages.
Collapsing the data to epoch summary measures may help to average out different noise levels and make sensor brands more comparable.
GGIR uses short (default 5 seconds) and long epochs (default 15 minutes). The epochs are aligned to the hour in the day, and to each other. For example, if a recording starts at 9:52:00 then the GGIR will work with epochs derived from 10:00:00 onward. If the recording starts at 10:12 then GGIR will work with epochs derived from 10:15:00 onward.
Motivation:
If the first 15 minute epochs would start at 9:52 then the next one would start at 10:07, which makes it impossible to make statement about behaviour between 10:00 and 13:00.
This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.
This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.
This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.
This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.
This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.
This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.
This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.
This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.
This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.
This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.
This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.
The full part 5 output is stored in the results/QC
folder. The default inclusion criteria for days in the cleaned output
from part 5 (stored in the results
folder) are:
includedaycrit.part5
(default 2/3).minimum_MM_length.part5
(default 23). Note that if your experiment started and ended in the
middle of the day then this default setting will exclude those
incomplete first and last days. If you think including these days is
still meaningful for your work then adjust the argument
minimum_MM_length.part5
.Important notes:
results/QC
folder.includenightcrit
as used for
part 4 is not used in part 5.The data_cleaning_file
argument discussed in Data_cleaning_file also allows you to
tell GGIR which person(s) and day(s) should be omitted in part 5. The
the day numbers to be excluded should be listed in a column
day_part5
as header.
This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.
Difference between fragments and blocks:
Elsewhere in the part5 we use the term block
. A
block
is a sequence of epochs that belong to the same
behavioural class. This may sound similar to the definition of a
fragment, but for blocks we distinguish every behavioural class, which
includes the subcategories such as bouted and unbouted behaviour. This
means that variables Nblock_day_total_IN
and
Nblock_day_total_LIG
are identical to
Nfrag_IN_day
and Nfrag_LIPA_day
, respectively.
In contrast, for fragments we may group LIPA and MVPA together when
refering to the fragmentation of PA.
Differences with R package ActFrag:
This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.
This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.
I wanted a short name and not to spend too much time finding it. The abbreviation has lost its functional meaning, which is why we now only use GGIR as the name.
Detection of the continuous least (LX) and most (MX) active X hours
in a day, where X is defined by argument winhr
. For both
GGIR calculates the average acceleration, the start time, and if
argument iglevels
is specified also the intensity gradient.
If argument winhr
is a vector then descriptive values for
LX and MX are derived per value in winhr
. Within GGIR part
2 MXLX is calculated per calendar day and, if argument
qwindow
is specified, per segment of the day. Within GGIR
part 5 MXLX is calculated per window, and if used in combination with
the GENEActiv or Axivity accelerometer brand LUX estimates per LX and MX
are included.
The MX metric describe here should not be confused by the MX metrics as proposed by Rowlands et al. which looks at accumulated most active time which may not always be continuous in time. The MX metrics by Rowlands et all are discussed further down.
The (Extended) Cosinor analysis quantifies the circadian 24 hour
cycle. To do this GGIR uses R package ActCR as a
dependency. Specify argument cosinor = TRUE
to perform
these analysis.
The implementation within GGIR part 2 is as follows:
log(acceleration converted to _mg_ + 1)
.The original implementation (argument IVIS.activity.metric = 1) uses the continuous numeric acceleration values. However, as we later realised this is not compatible with the original approach by van Someren and colleagues, which uses a binary distinction between active and inactive. Therefore, a second option was added (argument IVIS.activity.metric = 2), which needs to be used in combination with accelerometer metric ENMO, and collapses the acceleration values into a binary score of rest versus active. This is the current default.
Disclaimer: The following has been implemented 2022, but is currently undergoing critical evaluation. As a result, we may update this algorithm during the course of 2023.
IS is sometimes used as a measure of behavioural robustness when
conducting Cosinor analysis. However, to work with the combination of
the two outcomes it seems important that IS is calculated from the same
time series. Therefore, when cosinor = TRUE
IV and IS are
calculated twice: Once as part of the default IV and IS analysis as
discussed above, and once as part of the Cosinor analysis using the same
log transformed time series. More specifically, the IV and IS algorithm
is applied with IVIS.activity.metric = 2
and
IVIS_acc_threshold = log(20 + 1)
to make the binary
distinction between active and inactive, and
IVIS_per_daypair = TRUE
. The setting
IVIS_per_daypair
was specifically designed for this context
to handle the potentially missing values in the time series as used for
Cosinor analysis. Applying the default IVIS algorithm would not be able
to handle the missing values and would result in a loss of information
if all non-matching epochs across the entire recording were excluded.
Instead, IV and IS are calculated as follows:
The new Cosinor-compatible IV and IS estimates are stored as output
variables cosinorIV
and cosinorIS
.
The idle sleep mode is explained on the manufacturer’s website. In short, idle sleep mode is a setting that can be turned on or off by the user. When it is turned on the device will fall asleep during periods of no movement, resulting in time gaps in the data. This functionality was probably introduced to safe battery life and minimize data size. However, it also means that we end up with time gaps that need to be accounted for.
This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.
This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.
This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.
GGIR has been designed to process multi-day recordings. The minimum recording duration considered by GGIR depends on the type of analysis:
Running part 1 and 2
File size; At least 2MB, where 2MB can be adjusted with argument minimumFileSizeMB. This should not be changed unless you have good reason to believe that a smaller file size is also acceptable.
Recording duration: At least two long epoch windows (default 60
minutes) in g.readaccfile. The size of this epoch can be altered with
the second and third value of vector argument windowsizes
,
where the third should not be smaller than the second. For example, in
short lasting lab-experiments you may find it easier to set this to
windowsizes = c(5, 600, 600)
as non-wear detection is
usually not necessary in lab studies.
Running part 3 and 4
Running part 5
Although GGIR focuses on accelerometer data a few brands come with LUX data.
In part 1 GGIR calculates the peak lux per long epoch at a default resolution of 15 minutes, which can be modified with argument windowsizes. Peak light offers a more reliable estimate of light exposure per time window compared with taking the average. Further, LUX is used in the auto-calibration.
In GGIR part 2 we visualise the LUX values in the qc plot. In part 3 and 4 LUX is not used for sleep classification because relation between light exposure and sleep is weak.
In part 5 we calculate the mean and maximum of the peak LUX per epoch across all waking hours of the day. Here, the mean (peak per epoch) LUX would then indicate average light exposure per time segment, while max peak would indicate the maximum light exposure per day. Further, we calculate the max and mean peak LUX per most active consecutive X hour of the day. This is intended to offer an alternative to LUX exposure during waking hours which relies on correct sleep classification. LUX exposure during M10 may be seen as an alternative if you are unsure whether you can trust the sleep classification in your data set.
A correct citation of research software is important to make your research reproducible and to acknowledge the effort that goes into the development of open-source software.
To do so, please report the GGIR version you used in the text. Additionally, please also cite:
If your work depends on the quantification of physical activity then also cite:
If you used the auto-calibration functionality then also cite:
If you used the sleep detection then also cite:
If you used the sleep detection without relying on sleep diary then also cite:
If you used the sleep regularity index then also cite:
The copyright of the GGIR logo lies with Accelting (Almere, The Netherlands), please contact v.vanhees@acceleting.com to ask for permission to use this logo.
These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.