Key general arguments

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.
  • If data_masking_strategy is set to value 1, then check out arguments hrs.del.start and hrs.del.end.
  • If 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.

Key arguments related to sleep analysis

For an explanation on how sleep is detected and the specific role of the various function arguments see section Sleep analysis.

• Arguments related to configuring the sleep detection algorithm: anglethreshold, timethreshold, HASPT.algo, HASIB.algo, Sadeh_axis, and HASPT.ignore.invalid.
• ignorenonwear if set to TRUE then ignore detected monitor non-wear periods in the detection of sustained inactivity bouts to avoid confusion between monitor non-wear time.
• If you want to create a visualisation of how sleep period time and sustained inactivity bouts match throughout a day then consider arguments do.visual, outliers.only, and criterror.
• If you want to exclude the first and last night from the sleep analysis then used excludefirstlast.
• def.noc.sleep specifies how the sleep period time window should be estimated if no sleeplog is used.
• includenightcrit Minimum number of valid hours per night (24 hour window between noon and noon or 6pm-6pm).
• data_cleaning_file to ginore specific nights for specific individuals, see also section Data cleaning file.
• If you want the sleep analysis to be guided by a sleeplog (diary) then check out arguments loglocation which specifies the location of the spreadsheet (csv) with sleep log information. Further, use arguments colid and coln1 to specify the details of your sleep log structure.

GGIR facilitates two possible sleeplog file structures:

Key arguments related to time use analysis

For an explanation on how time use analysis is performed see section Waking-waking or 24 hour time-use analysis.

• excludefirstlast.part5 - whether to ignore the last and first day.
• includedaycrit.part5 - tell GGIR what fraction of the waking hours in a day (value below 1) is acceptable.
• minimum_MM_length.part5 - tell GGIR what the minimum length (hours) should be of the MM window in part 5.
• Configure thresholds for acceleration levels (some may want to interpret this as intensity levels): threshold.lig, threshold.mod, threshold.vig.
• Configure what fraction of a bout needs to meet the threshold (cut-point) crtieria boutcriter.in, boutcriter.lig, boutcriter.mvpa. Note that boutcriter.mvpa = 0.8 means that an MVPA bout can have interruptions (i.e., the time out of MVPA intensity) that meet the following criteria:
  1. A single interruption can last < 1 min
  2. Repeated interruptions are allowed provided that their total time does not exceed 20% of the bout duration
  3. The time spent in the interruptions is included in the duration of the MVPA bout. For example: A 25-minute bout can have two 1 minute interruption, but not a single 2-minute interruption. Here, the full 25 minutes would count towards the duration of the MVPA bout.
• timewindow to specify whether days should be defined from midnight to midnight "MM", from waking-up to waking-up "WW", from sleep onset to sleep onset "OO", or any combination of them.
• Configure durations of bouts: boutdur.mvpa, boutdur.in, and boutdur.lig. Note that this can be a vector of multiple values indicating the minimum and maximum duration of subsequent bout types, e.g. 1-5 minutes MVPA, 5-10 minutes MVPA, and longer than 10 minutes MVPA.

Published cut-points and how to use them

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.

Example call

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.

Configuration file

This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.

Why does the first epoch not allign with the original start of the recording

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:

• This allows us to have a standardised time grid across recordings to describe behaviour.
• This allows us to calculate behaviour exactly per day or per specified time interval in a day.

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.

Notes on sleep classification algorithms designed for count data

Guiders

This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.

Daysleepers (nights workers)

This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.

Cleaningcode

This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.

Difference between cleaned and full output

This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.

Data cleaning file

This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.

Time series output files

This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.

Day inclusion criteria

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:

• For both MM and WW defined days: The valid (sensor worn) time fraction of the day needs to be above the fraction specified with argument includedaycrit.part5 (default 2/3).
• For MM defined days only: The length of the day needs to be at least the number of hours as specified by 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:

• No criteria is set for the amount of valid data during the SPT window, because all we are interested in part 5 is knowing the borders of the night and we trust that this was sufficiently estimated by part 4. If you disagree then please notice that all the days are included in the full report available in results/QC folder.
• This means that argument 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.

Fragmentation metrics

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.

Time gap imputation

This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.

The importance of reporting idle.sleep.mode usage

This section has been migrated to this section in the GGIR github-pages, which is now the main documentation resource for GGIR.