GGIR configuration parameters
The GGIR shell function takes the input arguments and groups them into parameter objects. The first section below displays all optional GGIR input argument names, the GGIR part (1, 2, 3, 4 and/or 5) they are used in, and the parameter object they are stored in. As you will see, a few parameters are not part of any parameter object because they are direct arguments of the GGIR shell function.
In the second section of this vignette you will find a description and default value for all the arguments.
1 Input arguments/parameters overview
| Argument (parameter) | Used in GGIR part | Parameter object |
|---|---|---|
| datadir | 1, 2, 4, 5 | not in parameter objects |
| f0 | 1, 2, 3, 4, 5 | not in parameter objects |
| f1 | 1, 2, 3, 4, 5 | not in parameter objects |
| windowsizes | 1, 5 | params_general |
| desiredtz | 1, 2, 3, 4, 5 | params_general |
| overwrite | 1, 2, 3, 4, 5 | params_general |
| do.parallel | 1, 2, 3, 5 | params_general |
| maxNcores | 1, 2, 3, 5 | params_general |
| myfun | 1, 2, 3 | not in parameter objects |
| outputdir | 1 | not in parameter objects |
| studyname | 1 | not in parameter objects |
| chunksize | 1 | params_rawdata |
| do.enmo | 1 | params_metrics |
| do.lfenmo | 1 | params_metrics |
| do.en | 1 | params_metrics |
| do.bfen | 1 | params_metrics |
| do.hfen | 1 | params_metrics |
| do.hfenplus | 1 | params_metrics |
| do.mad | 1 | params_metrics |
| do.anglex | 1 | params_metrics |
| do.angley | 1 | params_metrics |
| do.angle | 1 | params_metrics |
| do.enmoa | 1 | params_metrics |
| do.roll_med_acc_x | 1 | params_metrics |
| do.roll_med_acc_y | 1 | params_metrics |
| do.roll_med_acc_z | 1 | params_metrics |
| do.dev_roll_med_acc_x | 1 | params_metrics |
| do.dev_roll_med_acc_y | 1 | params_metrics |
| do.dev_roll_med_acc_z | 1 | params_metrics |
| do.lfen | 1 | params_metrics |
| do.lfx | 1 | params_metrics |
| do.lfy | 1 | params_metrics |
| do.lfz | 1 | params_metrics |
| do.hfx | 1 | params_metrics |
| do.hfy | 1 | params_metrics |
| do.hfz | 1 | params_metrics |
| do.bfx | 1 | params_metrics |
| do.bfy | 1 | params_metrics |
| do.bfz | 1 | params_metrics |
| do.zcx | 1 | params_metrics |
| do.zcy | 1 | params_metrics |
| do.zcz | 1 | params_metrics |
| lb | 1 | params_metrics |
| hb | 1 | params_metrics |
| n | 1 | params_metrics |
| do.cal | 1 | params_rawdata |
| spherecrit | 1 | params_rawdata |
| minloadcrit | 1 | params_rawdata |
| printsummary | 1 | params_rawdata |
| print.filename | 1 | params_general |
| backup.cal.coef | 1 | params_rawdata |
| rmc.noise | 1 | params_rawdata |
| rmc.dec | 1 | params_rawdata |
| rmc.firstrow.acc | 1 | params_rawdata |
| rmc.firstrow.header | 1 | params_rawdata |
| rmc.col.acc | 1 | params_rawdata |
| rmc.col.temp | 1 | params_rawdata |
| rmc.col.time | 1 | params_rawdata |
| rmc.unit.acc | 1 | params_rawdata |
| rmc.unit.temp | 1 | params_rawdata |
| rmc.origin | 1 | params_rawdata |
| rmc.header.length | 1 | params_rawdata |
| mc.format.time | 1 | params_rawdata |
| rmc.bitrate | 1 | params_rawdata |
| rmc.dynamic_range | 1 | params_rawdata |
| rmc.unsignedbit | 1 | params_rawdata |
| rmc.desiredtz | 1 | params_rawdata |
| rmc.sf | 1 | params_rawdata |
| rmc.headername.sf | 1 | params_rawdata |
| rmc.headername.sn | 1 | params_rawdata |
| rmc.headername.recordingid | 1 | params_rawdata |
| rmc.header.structure | 1 | params_rawdata |
| rmc.check4timegaps | 1 | params_rawdata |
| rmc.col.wear | 1 | params_rawdata |
| rmc.doresample | 1 | params_rawdata |
| imputeTimegaps | 1 | params_rawdata |
| selectdaysfile | 1, 2 | params_cleaning |
| dayborder | 1, 2, 5 | params_general |
| dynrange | 1 | params_rawdata |
| configtz | 1 | params_general |
| minimumFileSizeMB | 1 | params_rawdata |
| interpolationType | 1 | params_rawdata |
| expand_tail_max_hours | 1 | params_general |
| metadatadir | 2, 3, 4, 5 | not in parameter objects |
| minimum_MM_length.part5 | 5 | params_cleaning |
| strategy | 2, 5 | params_cleaning |
| hrs.del.start | 2, 5 | params_cleaning |
| hrs.del.end | 2, 5 | params_cleaning |
| maxdur | 2, 5 | params_cleaning |
| max_calendar_days | 2 | params_cleaning |
| includedaycrit | 2 | params_cleaning |
| L5M5window | 2 | params_247 |
| M5L5res | 2, 5 | params_247 |
| winhr | 2, 5 | params_247 |
| qwindow | 2 | params_247 |
| qlevels | 2 | params_247 |
| ilevels | 2 | params_247 |
| mvpathreshold | 2 | params_phyact |
| boutcriter | 2 | params_phyact |
| ndayswindow | 2 | params_cleaning |
| idloc | 2, 4 | params_general |
| do.imp | 2 | params_cleaning |
| storefolderstructure | 2, 4, 5 | params_output |
| epochvalues2csv | 2 | params_output |
| do.part2.pdf | 2 | params_output |
| mvpadur | 2 | params_phyact |
| window.summary.size | 2 | params_247 |
| bout.metric | 2, 5 | params_phyact |
| closedbout | 2 | params_phyact |
| IVIS_windowsize_minutes | 2 | params_247 |
| IVIS_epochsize_seconds | 2 | params_247 |
| IVIS.activity.metric | 2 | params_247 |
| iglevels | 2, 5 | params_247 |
| TimeSegments2ZeroFile | 2 | params_cleaning |
| qM5L5 | 2 | params_247 |
| MX.ig.min.dur | 2 | params_247 |
| qwindow_dateformat | 2 | params_247 |
| anglethreshold | 3 | params_sleep |
| timethreshold | 3 | params_sleep |
| acc.metric | 3, 5 | params_general |
| ignorenonwear | 3 | params_sleep |
| constrain2range | 3 | params_sleep |
| do.part3.pdf | 3 | params_output |
| sensor.location | 3, 4 | params_general |
| HASPT.algo | 3 | params_sleep |
| HASIB.algo | 3 | params_sleep |
| Sadeh_axis | 3 | params_sleep |
| longitudinal_axis | 3 | params_sleep |
| HASPT.ignore.invalid | 3 | params_sleep |
| loglocation | 4, 5 | params_sleep |
| colid | 4 | params_sleep |
| coln1 | 4 | params_sleep |
| nnights | 4 | params_sleep |
| sleeplogidnum | 4, 5 | params_sleep |
| do.visual | 4 | params_output |
| outliers.only | 4 | params_output |
| excludefirstlast | 4 | params_cleaning |
| criterror | 4 | params_output |
| includenightcrit | 4 | params_cleaning |
| relyonguider | 4 | params_sleep |
| relyonsleeplog | 4 | not in parameter objects |
| def.noc.sleep | 4 | params_sleep |
| data_cleaning_file | 4, 5 | params_cleaning |
| excludefirst.part4 | 4 | params_cleaning |
| excludelast.part4 | 4 | params_cleaning |
| sleeplogsep | 4 | params_cleaning |
| sleepwindowType | 4 | params_cleaning |
| excludefirstlast.part5 | 5 | params_cleaning |
| boutcriter.mvpa | 5 | params_phyact |
| boutcriter.in | 5 | params_phyact |
| boutcriter.lig | 5 | params_phyact |
| threshold.lig | 5 | params_phyact |
| threshold.mod | 5 | params_phyact |
| threshold.vig | 5 | params_phyact |
| timewindow | 5 | params_output |
| boutdur.mvpa | 5 | params_phyact |
| boutdur.in | 5 | params_phyact |
| boutdur.lig | 5 | params_phyact |
| save_ms5rawlevels | 5 | params_output |
| part5_agg2_60seconds | 5 | params_general |
| save_ms5raw_format | 5 | params_output |
| save_ms5raw_without_invalid | 5 | params_output |
| includedaycrit.part5 | 5 | params_cleaning |
| frag.metrics | 5 | params_phyact |
| LUXthresholds | 5 | params_247 |
| LUX_cal_constant | 5 | params_247 |
| LUX_cal_exponent | 5 | params_247 |
| LUX_day_segments | 5 | params_247 |
| do.sibreport | 5 | params_output |
2 Arguments/parameters description
All information as shown below has been auto-generated and is identical to the information provided in the GGIR package pdf manual.
2.1 GGIR function input arguments
mode
Numeric (default = 1:5). Specify which of the five parts need to be run, e.g., mode = 1 makes that g.part1 is run; or mode = 1:5 makes that the whole GGIR pipeline is run, from g.part1 to g.part5.
datadir
Character (default = c()). Directory where the accelerometer files are stored, e.g., ‘C:/mydata’, or list of accelerometer filenames and directories, e.g. c(‘C:/mydata/myfile1.bin’, ‘C:/mydata/myfile2.bin’).
outputdir
Character (default = c()). Directory where the output needs to be stored. Note that this function will attempt to create folders in this directory and uses those folder to keep output.
studyname
Character (default = c()). If the datadir is a folder, then the study will be given the name of the data directory. If datadir is a list of filenames then the studyname as specified by this input argument will be used as name for the study.
f0
Numeric (default = 1). File index to start with (default = 1). Index refers to the filenames sorted in alphabetical order.
f1
Numeric (default = 0). File index to finish with (defaults to number of files available).
do.report
Numeric (default = c(2, 4, 5)). For which parts to generate a summary spreadsheet: 2, 4, and/or 5. Default is c(2, 4, 5). A report will be generated based on the available milestone data. When creating milestone data with multiple machines it is advisable to turn the report generation off when generating the milestone data, value = c(), and then to merge the milestone data and turn report generation back on while setting overwrite to FALSE.
configfile
Character (default = c()). Configuration file previously generated by function GGIR. See details.
myfun
List (default = c()). External function object to be applied to raw data. See package vignette for detailed tutorial with examples on how to use the function embedding: https://cran.r-project.org/package=GGIR/vignettes/ExternalFunction.pdf
2.2 General Parameters
overwrite
Boolean (default = FALSE). Do you want to overwrite analysis for which milestone data exists? If overwrite = FALSE, then milestone data from a previous analysis will be used if available and visual reports will not be created again.
acc.metric
Boolean (default = ENMO). Which one of the metrics do you want to consider to analyze L5. The metric of interest need to be calculated in M (see g.part1).
maxNcores
Numeric (default maxNcores= ). Maximum number of cores to use when argument do.parallel is set to true. GGIR by default uses either the maximum number of available cores or the number of files to process (whichever is lower), but this argument allows you to set a lower maximum.
print.filename
Boolean (default = FALSE). Whether to print the filename before before analysing it (in case do.parallel = FALSE). Printing the filename can be useful to investigate problems (e.g., to verify that which file is being read).
do.parallel
Boolean (default = TRUE). Whether to use multi-core processing (only works if at least 4 CPU cores are available).
windowsizes
Numeric vector, three values (default = c(5, 900, 3600)). To indicate the lengths of the windows as in c(window1, window2, window3): window1 is the short epoch length in seconds, by default 5, and this is the time window over which acceleration and angle metrics are calculated; window2 is the long epoch length in seconds for which non-wear and signal clipping are defined, default 900 (expected to be a multitude of 60 seconds); window3 is the window length of data used for non-wear detection and by default 3600 seconds. So, when window3 is larger than window2 we use overlapping windows, while if window2 equals window3 non-wear periods are assessed by non-overlapping windows.
desiredtz
Character (default = ’’, i.e., system timezone). Timezone in which device was configured and experiments took place. If experiments took place in a different timezone, then use this argument for the timezone in which the experiments took place and argument configtz to specify where the device was configured. See also https://en.wikipedia.org/wiki/Zone.tab
configtz
Character (default = ’’, i.e., system timezone). Only functional for AX3 cwa and ActiGraph .gt3x data at the moment. Timezone in which the accelerometer was configured. Only use this argument if the timezone of configuration and timezone in which recording took place are different. See also https://en.wikipedia.org/wiki/Zone.tab
idloc
Numeric (default = 1). If idloc = 1 the code assumes that ID number is stored in the obvious header field. Note that for ActiGraph data the ID is never stored in the file header. For value set to 2, 5, 6, and 7, GGIR looks at the filename and extracts the character string preceding the first occurance of a ’_’ (idloc = 2), ’ ’ (space, idloc = 5), ‘.’ (dot, idloc = 6), and ‘-’ (idloc = 7), respectively. You may have noticed that idloc 3 and 4 are skipped, they were used for one study in 2012, and not actively maintained anymore, but because it is legacy code not omitted.
dayborder
Numeric (default = 0). Hour at which days start and end (dayborder = 4 would mean 4 am).
part5_agg2_60seconds
Boolean (default = FALSE). Wether to use aggregate epochs to 60 seconds as part of the GGIR g.part5 analysis.
sensor.location
Character (default = ‘wrist’). To indicate sensor location, default is wrist. If it is hip, the HDCZA algorithm for sleep detection also requires longitudinal axis of sensor to be between -45 and +45 degrees.
expand_tail_max_hours
Numeric (default = 0). Number hours to expand the g.part1 output with synthetic data to trigger sleep detection for last night. The synthetic data for metashort entails: timestamps continuing regularly, zeros for acceleration metrics other than EN, one for EN. Angle columns are created in a way that it triggers the sleep detection using the equation: round(sin((1:length_expansion) / (900/epochsize))) * 15. To keep track of the tail expansion g.part1 stores the lenght of the expansion in the RData files, which is then passed via g.part2, g.part3, and g.part4 to g.part5. In g.part5 it is then included as an additional variable in the csv-reports. In the g.part4 report the last nigth is omitted, because we know that sleep estimates from the last night will not be trustworthy. In the g.part5 output most columns related to the sleep assessment will be omitted for the last window to avoid biassing the averages. Using argument expand_tail_max_hours implies the assumption that the participant fell asleep at or before the end of the recording if the recording ended less than expand_tail_max_hours before midnight. This assumption may not always hold true and should be used with caution.
2.3 Raw Data Parameters
chunksize
Numeric (default = 1). Value between 0.2 and 1 to specificy the size of chunks to be loaded as a fraction of a 12 hour period, e.g., 0.5 equals 6 hour chunks, 1 equals 12 hour chunks. For machines with less than 4Gb of RAM memory a value below 1 is recommended.
spherecrit
Numeric (default = 0.3). The minimum required acceleration value (in g) on both sides of 0 g for each axis. Used to judge whether the sphere is sufficiently populated
minloadcrit
Numeric (default = 72). The minimum number of hours the code needs to read for the autocalibration procedure to be effective (only sensitive to multitudes of 12 hrs, other values will be ceiled). After loading these hours only extra data is loaded if calibration error has not been reduced to under 0.01 g.
printsummary
Boolean (default = FALSE). If TRUE will print a summary of the calibration procedure in the console when done.
do.cal
Boolean (default = TRUE). Whether to apply auto-calibration or not by g.calibrate. Recommended setting is TRUE.
backup.cal.coef
Character (default = ‘retrieve’). Option to use backed-up calibration coefficient instead of deriving the calibration coefficients when analysing the same file twice. Argument backup.cal.coef has two usecase. Use case 1: If the auto-calibration fails then the user has the option to provide back-up calibration coefficients via this argument. The value of the argument needs to be the name and directory of a csv-spreadsheet with the following column names and subsequent values: ‘filename’ with the names of accelerometer files on which the calibration coefficients need to be applied in case auto-calibration fails; ‘scale.x’, ‘scale.y’, and ‘scale.z’ with the scaling coefficients; ‘offset.x’, ‘offset.y’, and ‘offset.z’ with the offset coefficients, and; ‘temperature.offset.x’, ‘temperature.offset.y’, and ‘temperature.offset.z’ with the temperature offset coefficients. This can be useful for analysing short lasting laboratory experiments with insufficient sphere data to perform the auto-calibration, but for which calibration coefficients can be derived in an alternative way. It is the users responsibility to compile the csv-spreadsheet. Instead of building this file the user can also Use case 2: The user wants to avoid performing the auto-calibration repeatedly on the same file. If backup.cal.coef value is set to ‘retrieve’ (default) then GGIR will look out for the ‘data_quality_report.csv’ file in the outputfolder QC, which holds the previously generated calibration coefficients. If you do not want this happen, then deleted the data_quality_report.csv from the QC folder or set it to value ‘redo’.
dynrange
Numeric (default = NULL). Provide dynamic range for accelerometer data to overwrite hardcoded 6 g for GENEA and 8 g for other brands.
minimumFileSizeMB
Numeric (default = 2). Minimum File size in MB required to enter processing. This argument can help to avoid having short uninformative files to enter the analyses. Given that a typical accelerometer collects several MBs per hour, the default setting should only skip the very tiny files.
rmc.dec
Character (default = ‘.’). Decimal used for numbers, same as dec argument in [utils]read.csv and in [data.table]fread.
rmc.firstrow.acc
Numeric (default = NULL). First row (number) of the acceleration data.
rmc.firstrow.header
Numeric (default = NULL). First row (number) of the header. Leave blank if the file does not have a header.
rmc.header.length
Numeric (default = NULL). If file has header, specify header length (number of rows).
rmc.col.acc
Numeric, three values (default = c(1, 2, 3)). Vector with three column (numbers) in which the acceleration signals are stored.
rmc.col.temp
Numeric (default = NULL). Scalar with column (number) in which the temperature is stored. Leave in default setting if no temperature is avaible. The temperature will be used by g.calibrate.
rmc.col.time
Numeric (default = NULL). Scalar with column (number) in which the timestamps are stored. Leave in default setting if timestamps are not stored.
rmc.unit.acc
Character (default = ‘g’). Character with unit of acceleration values: ‘g’, ‘mg’, or ‘bit’.
rmc.unit.temp
Character (default = ‘C’). Character with unit of temperature values: (K)elvin, (C)elsius, or (F)ahrenheit.
rmc.unit.time
Character (default = ‘POSIX’). Character with unit of timestamps: ‘POSIX’, ‘UNIXsec’ (seconds since origin, see argument rmc.origin), ‘character’, or ‘ActivPAL’ (exotic timestamp format only used in the ActivPAL activity monitor).
rmc.format.time
Character (default = ‘%Y-%m-%d %H:%M:%OS’). Character giving a date-time format as used by [base]strptime. Only used for rmc.unit.time: character and POSIX.
rmc.bitrate
Numeric (default = NULL). If unit of acceleration is a bit then provide bit rate, e.g., 12 bit.
rmc.dynamic_range
Numeric or character (default = NULL). If unit of acceleration is a bit then provide dynamic range deviation in g from zero, e.g., +/-6g would mean this argument needs to be 6. If you give this argument a character value the code will search the file header for elements with a name equal to the character value and use the corresponding numeric value next to it as dynamic range.
rmc.unsignedbit
Boolean (default = TRUE). If unsignedbit = TRUE means that bits are only positive numbers. if unsignedbit = FALSE then bits are both positive and negative.
rmc.origin
Character (default = ‘1970-01-01’). Origin of time when unit of time is UNIXsec, e.g., 1970-1-1.
rmc.desiredtz
Character (default = ’’, i.e., system timezone). Timezone in which device was configured and experiments took place. If experiments took place in a different timezone, then use this argument for the timezone in which the experiments took place and argument configtz to specify where the device was configured (not implemented yet). See also https://en.wikipedia.org/wiki/Zone.tab
rmc.sf
Numeric (default = NULL). Sample rate in Hertz, if this is stored in the file header then that will be used instead (see argument rmc.headername.sf).
rmc.headername.sf
Character (default = NULL). If file has a header: Row name under which the sample frequency can be found.
rmc.headername.sn
Character (default = NULL). If file has a header: Row name under which the serial number can be found.
rmc.headername.recordingid
Character (default = NULL). If file has a header: Row name under which the recording ID can be found.
rmc.header.structure
Character (default = NULL). Used to split the header name from the header value, e.g., ‘:’ or ’ ’.
rmc.check4timegaps
Boolean (default = FALSE). To indicate whether gaps in time should be imputed with zeros. Some sensing equipment provides accelerometer with gaps in time. The rest of GGIR is not designed for this, by setting this argument to TRUE the gaps in time will be filled with zeros.
rmc.noise
Numeric (default = 13). Noise level of acceleration signal in m-units, used when working ad-hoc .csv data formats using read.myacc.csv. The read.myacc.csv does not take rmc.noise as argument, but when interacting with GGIR or g.part1 rmc.noise is used.
rmc.col.wear
Numeric (default = NULL). If external wear detection outcome is stored as part of the data then this can be used by GGIR. This argument specifies the column in which the wear detection (Boolean) is stored.
rmc.doresample
Boolean (default = FALSE). To indicate whether to resample the data based on the available timestamps and extracted sample rate from the file header.
interpolationType
Integer (default = 1). To indicate type of interpolation to be used when resampling time series (mainly relevant for Axivity sensors), 1=linear, 2=nearest neighbour.
imputeTimegaps
Boolean (default = TRUE). To indicate whether timegaps larger than 1 sample should be imputed. Currently only used for .gt3x data and ActiGraph .csv format, where timegaps can be expected as a result of Actigraph’s idle sleep.mode configuration.
loadGENEActiv
Character (default = GGIRread). To indicate which package should be used to read GENEActiv .bin files: either GENEAread or GGIRread
2.4 Metrics Parameters
do.anglex
Boolean (default = FALSE). If TRUE, calculates the angle of the X axis relative to the horizontal: = (^-1_rollmedian(x)acc_rollmedian(y) + acc_rollmedian(z)) * 180/
do.angley
Boolean (default = FALSE). If TRUE, calculates the angle of the Y axis relative to the horizontal: = (^-1_rollmedian(y)acc_rollmedian(x) + acc_rollmedian(z)) * 180/
do.anglez
Boolean (default = TRUE). If TRUE, calculates the angle of the Z axis relative to the horizontal: = (^-1_rollmedian(z)acc_rollmedian(x) + acc_rollmedian(y)) * 180/
do.zcx
Boolean (default = FALSE). If TRUE, calculates metric zero-crossing count for x-axis. For computation specifics see source code of function g.applymetrics
do.zcy
Boolean (default = FALSE). If TRUE, calculates metric zero-crossing count for y-axis. For computation specifics see source code of function g.applymetrics
do.zcz
Boolean (default = FALSE). If TRUE, calculates metric zero-crossing count for z-axis. For computation specifics see source code of function g.applymetrics
do.enmo
Boolean (default = TRUE). If TRUE, calculates the metric: = _x^2 + acc_y^2 + acc_z^2 - 1 (if ENMO < 0, then ENMO = 0).
do.lfenmo
Boolean (default = FALSE). If TRUE, calculates the metric ENMO over the low-pass filtered accelerations (for computation specifics see source code of function g.applymetrics). The filter bound is defined by the parameter hb.
do.en
Boolean (default = FALSE). If TRUE, calculates the Euclidean Norm of the raw accelerations: = _x^2 + acc_y^2 + acc_z^2
do.mad
Boolean (default = FALSE). If TRUE, calculates the Mean Amplitude Deviation: = 1n|r_i - |
do.enmoa
Boolean (default = FALSE). If TRUE, calculates the metric: = _x^2 + acc_y^2 + acc_z^2 - 1 (if ENMOa < 0, then ENMOa = |ENMOa|).
do.roll_med_acc_x
Boolean (default = FALSE). If TRUE, calculates the metric. For computation specifics see source code of function g.applymetrics.
do.roll_med_acc_y
Boolean (default = FALSE). If TRUE, calculates the metric. For computation specifics see source code of function g.applymetrics.
do.roll_med_acc_z
Boolean (default = FALSE). If TRUE, calculates the metric. For computation specifics see source code of function g.applymetrics.
do.dev_roll_med_acc_x
Boolean (default = FALSE). If TRUE, calculates the metric. For computation specifics see source code of function g.applymetrics.
do.dev_roll_med_acc_y
Boolean (default = FALSE). If TRUE, calculates the metric. For computation specifics see source code of function g.applymetrics.
do.dev_roll_med_acc_z
Boolean (default = FALSE). If TRUE, calculates the metric. For computation specifics see source code of function g.applymetrics.
do.bfen
Boolean (default = FALSE). If TRUE, calculates the metric. For computation specifics see source code of function g.applymetrics.
do.hfen
Boolean (default = FALSE). If TRUE, calculates the metric. For computation specifics see source code of function g.applymetrics.
do.hfenplus
Boolean (default = FALSE). If TRUE, calculates the metric. For computation specifics see source code of function g.applymetrics.
do.lfen
Boolean (default = FALSE). If TRUE, calculates the metric. For computation specifics see source code of function g.applymetrics.
do.lfx
Boolean (default = FALSE). If TRUE, calculates the metric. For computation specifics see source code of function g.applymetrics.
do.lfy
Boolean (default = FALSE). If TRUE, calculates the metric. For computation specifics see source code of function g.applymetrics.
do.lfz
Boolean (default = FALSE). If TRUE, calculates the metric. For computation specifics see source code of function g.applymetrics.
do.hfx
Boolean (default = FALSE). If TRUE, calculates the metric. For computation specifics see source code of function g.applymetrics.
do.hfy
Boolean (default = FALSE). If TRUE, calculates the metric. For computation specifics see source code of function g.applymetrics.
do.hfz
Boolean (default = FALSE). If TRUE, calculates the metric. For computation specifics see source code of function g.applymetrics.
do.bfx
Boolean (default = FALSE). If TRUE, calculates the metric. For computation specifics see source code of function g.applymetrics.
do.bfy
Boolean (default = FALSE). If TRUE, calculates the metric. For computation specifics see source code of function g.applymetrics.
do.bfz
Boolean (default = FALSE). If TRUE, calculates the metric. For computation specifics see source code of function g.applymetrics.
do.brondcounts
Boolean (default = FALSE). THIS OPTION HAS BEEN DEPRECATED (October2022) DUE TO ISSUES WITH THE ACTIVITYCOUNTS PACKAGE, WE WILL ADD THIS BACK IN ONCE THE ISSUES WITH THE ACTIVITYCOUNTS PACKAGE ARE ADDRESSED. If TRUE, calculates the metric via R package activityCounts. We call them BrondCounts because there are large number of acitivty counts in the physical activity and sleep research field. By calling them brondcounts we clarify that these are the counts proposed by Jan Brønd and implemented in R by Ruben Brondeel. The brondcounts are intended to be an imitation of the counts produced by one of the closed source ActiLife software by ActiGraph.
do.neishabouricounts
Boolean (default = FALSE). If TRUE, calculates the metric via R package actilifecounts, which is an implementation of the algorithm used in the closed-source software ActiLife by ActiGraph (methods published in doi: 10.1038/s41598-022-16003-x). We use the name of the first author (instead of ActiLifeCounts) of the paper and call them NeishabouriCount under the uncertainty that ActiLife will implement this same algorithm over time.
hb
Numeric (default = 15). Higher boundary of the frequency filter (in Hertz) as used in the filter-based metrics.
lb
Numeric (default = 0.2). Lower boundary of the frequency filter (in Hertz) as used in the filter-based metrics.
n
Numeric (default = 4). Order of the frequency filter as used in the filter-based metrics.
zc.lb
default = 0.25) Used for zero-crossing counts only. Lower boundery of cut-off frequency filter.
zc.hb
default = 3) Used for zero-crossing counts only. Higher boundery of cut-off frequencies in filter.
zc.sb
default = 0.01) Stop band used for calculation of zero crossing counts. Value is the acceleration threshold in g units below which acceleration will be rounded to zero.
zc.order
default = 2) Used for zero-crossing counts only. Order of frequency filter.
zc.scale
default = 1) Used for zero-crossing counts only. Scaling factor to be applied after counts are calculated (GGIR part 3).
actilife_LFE
Boolean (default = FALSE). If TRUE, calculates the NeishabouriCount metric with the low-frequency extension filter as proposed in the closed source ActiLife software by ActiGraph. Only applicable to the metric NeishabouriCount.
2.5 Cleaning Parameters
includedaycrit
Numeric (default = 16). Minimum required number of valid hours in day specific analysis (NOTE: there is no minimum required number of hours per day in the summary of an entire measurement, every available hour is used to make the best possible inference on average metric value per average day).
ndayswindow
Numeric (default = 7). If strategy is set to 3 then this is the size of the window as a number of days.
strategy
Numeric (default = 1). How to deal with knowledge about study protocol. strategy = 1 means select data based on hrs.del.start and hrs.del.end. strategy = 2 makes that only the data between the first midnight and the last midnight is used. strategy = 3 only selects the most active X days in the file where X is specified by argument ndayswindow. strategy = 4 to only use the data after the first midnight.
maxdur
Numeric (default = 0). How many DAYS after start of experiment did experiment definitely stop? (set to zero if unknown).
hrs.del.start
Numeric (default = 0). How many HOURS after start of experiment did wearing of monitor start? Used in GGIR g.part2 when strategy = 1.
hrs.del.end
Numeric (default = 0). How many HOURS before the end of the experiment did wearing of monitor definitely end? Used in GGIR g.part2 when strategy = 1.
includedaycrit.part5
Numeric (default = 0.667). Inclusion criteria for number of valid hours, either as expressed as a ratio of 1 or as the number of hours in a 24 hour day.
excludefirstlast.part5
Boolean (default = FALSE). If TRUE then the first and last window (waking-waking or midnight-midnight) are ignored in g.part5.
TimeSegments2ZeroFile
Data frame (default = NULL). Optional data.frame to specify which time segments need to be ignored for the imputation, and acceleration metrics to be imputed by zeros. The data.frame is expected to contain two columns named windowstart and windowend, with the start- and end time of the time segment in POSIXlt class.
do.imp
Boolean (default = TRUE). Whether to impute missing values (e.g., suspected of monitor non-wear or clippling) or not by g.impute in GGIR g.part2. Recommended setting is TRUE.
data_cleaning_file
Character (default = NULL). Optional path to a csv file you create that holds four columns: ID, day_part5, relyonguider_part4, and night_part4. ID should hold the participant ID. Columns day_part5 and night_part4 allow you to specify which day(s) and night(s) need to be excluded from g.part5 and g.part4, respectively. So, this will be done regardless of whether the rest of GGIR thinks those day(s)/night(s) are valid. Column relyonguider_part4 allows you to specify for which nights g.part4 should fully rely on the guider. See also package vignette.
minimum_MM_length.part5
Numeric (default = 23). Minimum length in hours of a MM day to be included in the cleaned g.part4 results.
excludefirstlast
Boolean (default = FALSE). If TRUE then the first and last night of the measurement are ignored for the sleep assessment in g.part4.
includenightcrit
Numeric (default = 16). Minimum number of valid hours per night (24 hour window between noon and noon), used for sleep assessment in g.part4.
excludefirst.part4
Boolean (default = FALSE). If TRUE then the first night of the measurement are ignored for the sleep assessment in g.part4.
excludelast.part4
Boolean (default = FALSE). If TRUE then the last night of the measurement are ignored for the sleep assessment in g.part4.
max_calendar_days
Numeric (default = 0). The maximum number of calendar days to include (set to zero if unknown).
2.6 Sleep Parameters
anglethreshold
Numeric (default = 5). Angle threshold (degrees) for sustained inactivity periods detection. The algorithm will look for periods of time (timethreshold) in which the angle variability is lower than anglethreshold. This can be specified as multiple thresholds, each of which will be implemented, e.g., anglethreshold = c(5,10).
timethreshold
Numeric (default = 5). Time threshold (minutes) for sustained inactivity periods detection. The algorithm will look for periods of time (timethreshold) in which the angle variability is lower than anglethreshold. This can be specified as multiple thresholds, each of which will be implemented, e.g., timethreshold = c(5,10).
ignorenonwear
Boolean (default = TRUE). If TRUE then ignore detected monitor non-wear periods to avoid confusion between monitor non-wear time and sustained inactivity.
constrain2range
Boolean (default = TRUE). Whether or not to constrain the range of threshold used in the diary free sleep period time window detection.
HASPT.algo
Character (default = ‘HDCZA’). To indicate what algorithm should be used for the sleep period time detection. Default ‘HDCZA’ is Heuristic algorithm looking at Distribution of Change in Z-Angle as described in van Hees et al. 2018. Other options included: ‘HorAngle’, which is based on HDCZA but replaces non-movement detection of the HDCZA algorithm by looking for time segments where the angle of the longitudinal sensor axis has an angle relative to the horizontal plane between -45 and +45 degrees.
HASIB.algo
Character (default = ‘vanHees2015’). To indicate which algorithm should be used to define the sustained inactivity bouts (i.e., likely sleep). Options: ‘vanHees2015’, ‘Sadeh1994’, ‘Galland2012’.
Sadeh_axis
Character (default = ‘Y’). To indicate which axis to use for the Sadeh1994 algorithm, and other algortihms that relied on count-based Actigraphy such as Galland2012.
longitudinal_axis
Integer (default = NULL). To indicate which axis is the longitudinal axis. If not provided, the function will estimate longitudinal axis. Only used when sensor.location = ‘hip’ or HASPT.algo = ‘HorAngle’.
HASPT.ignore.invalid
Boolean (default = FALSE). To indicate whether invalid time segments should be ignored in the Sleep Period Time detection.
loglocation
Character (default = NULL). Path to csv file with sleep log information. See package vignette for how to format this file.
colid
Numeric (default = 1). Column number in the sleep log spreadsheet in which the participant ID code is stored.
coln1
Numeric (default = 2). Column number in the sleep log spreadsheet where the onset of the first night starts.
nnights
Numeric (default = NULL). Number of nights for which sleep log information should be available. It assumes that this is constant within a study. If sleep log information is missing for certain nights then leave these blank.
relyonguider
Boolean (default = FALSE). If TRUE, then sleep onset and waking time are defined based on timestamps derived from the guider. If participants were instructed NOT to wear the accelerometer during waking hours then set to TRUE, in all other scenarios set to FALSE.
sleeplogidnum
Boolean (default = TRUE). Should the participant identifier as stored in the sleeplog be interpretted as a number (TRUE) or character (FALSE)?
def.noc.sleep
Numeric (default = 1). The time window during which sustained inactivity will be assumed to represent sleep, e.g., def.noc.sleep = c(21, 9). This is only used if no sleep log entry is available. If left blank def.noc.sleep = c() then the 12 hour window centred at the least active 5 hours of the 24 hour period will be used instead. Here, L5 is hardcoded and will not change by changing argument winhr in function g.part2. If def.noc.sleep is filled with a single integer, e.g., def.noc.sleep=c(1) then the window will be detected with based on built in algorithms. See argument HASPT.algo from HASPT for specifying which of the algorithms to use.
sleeplogsep
Character (default = ‘,’). Value used as sep argument in [utils]read.csv for reading sleeplog csv file, usually ‘,’ or ‘;’.
sleepwindowType
Character (default = ‘SPT’). To indicate type of information in the sleeplog, ‘SPT’ for sleep period time. Set to ‘TimeInBed’ if sleep log recorded time in bed to enable calculation of sleep latency and sleep efficiency.
possible_nap_window
Numeric (default = c(9, 18)). Numeric vector of length two with range in clock hours during which naps are assumed to take place, e.g., possible_nap_window = c(9, 18).
possible_nap_dur
Numeric (default = c(15, 240)). Numeric vector of length two with range in duration (minutes) of a nap, e.g., possible_nap_dur = c(15, 240).
nap_model
Character (default = NULL). To specify classification model. Currently the only option is ‘hip3yr’, which corresponds to a model trained with hip data in 3-3.5 olds trained with parent diary data.
2.7 Physical activity Parameters
mvpathreshold
Numeric (default = 100). Acceleration threshold for MVPA estimation in GGIR g.part2. This can be a single number or an array of numbers, e.g., mvpathreshold = c(100, 120). In the later case the code will estimate MVPA seperately for each threshold. If this variable is left blank, e.g., mvpathreshold = c(), then MVPA is not estimated.
boutcriter
Numeric (default = 0.8). A number between 0 and 1, it defines what fraction of a bout needs to be above the mvpathreshold, only used in GGIR g.part2.
mvpadur
Numeric (default = c(1, 5, 10)). The bout duration(s) for which MVPA will be calculated. Only used in GGIR g.part2.
closedbout
Boolean (default = FALSE). TRUE if you want breaks in bouts to be counted towards time spent in bouts (argument only active for bout.metric 1 and 2).
boutcriter.in
Numeric (default = 0.9). A number between 0 and 1, it defines what fraction of a bout needs to be below the threshold.lig.
boutcriter.lig
Numeric (default = 0.8). A number between 0 and 1, it defines what fraction of a bout needs to be between the threshold.lig and the threshold.mod.
boutcriter.mvpa
Numeric (default = 0.9). A number between 0 and 1, it defines what fraction of a bout needs to be above the threshold.mod.
threshold.lig
Numeric (default = 40). In g.part5: Threshold for light physical activity to separate inactivity from light. Value can be one number or an array of multiple numbers, e.g., threshold.lig =c(30,40). If multiple numbers are entered then analysis will be repeated for each combination of threshold values. Threshold is applied to the first metric in the milestone data, so if you have only specified do.enmo = TRUE then it will be applied to ENMO.
threshold.mod
Numeric (default = 100). In g.part5: Threshold for moderate physical activity to separate light from moderate. Value can be one number or an array of multiple numbers, e.g., threshold.mod = c(100, 120). If multiple numbers are entered then analysis will be repliced for each ombination of threshold values. Threshold is applied to the first metric in the milestone data, so if you have only specified do.enmo = TRUE then it will be applied to ENMO.
threshold.vig
Numeric (default = 400). In g.part5: Threshold for vigorous physical activity to separate moderate from vigorous. Value can be one number or an array of multiple numbers, e.g., threshold.vig =c(400,500). If multiple numbers are entered then analysis will be repliced for each combination of threshold values. Threshold is applied to the first metric in the milestone data, so if you have only specified do.enmo = TRUE then it will be applied to ENMO.
boutdur.mvpa
Numeric (default = c(1, 5, 10)). Duration(s) of MVPA bouts in minutes to be extracted. It will start with the identification of the longest to the shortest duration. In the default setting, it will start with the 10 minute bouts, followed by 5 minute bouts in the rest of the data, and followed by 1 minute bouts in the rest of the data.
boutdur.in
Numeric (default = c(10, 20, 30)). Duration(s) of inactivty bouts in minutes to be extracted. Inactivity bouts are detected in the segments of the data which were not labelled as sleep or MVPA bouts. It will start with the identification of the longest to the shortest duration. In the default setting, it will start with the identification of 30 minute bouts, followed by 20 minute bouts in the rest of the data, and followed by 10 minute bouts in the rest of the data.
boutdur.lig
Numeric (default = c(1, 5, 10)). Duration(s) of light activty bouts in minutes to be extracted. Light activity bouts are detected in the segments of the data which were not labelled as sleep, MVPA, or inactivity bouts. It will start with the identification of the longest to the shortest duration. In the default setting, this will start with the identification of 10 minute bouts, followed by 5 minute bouts in the rest of the data, and followed by 1 minute bouts in the rest of the data.
frag.metrics
Character (default = NULL). Fragmentation metric to exract. Can be ‘mean’, ‘TP’, ‘Gini’, ‘power’, or ‘CoV’, ‘NFragPM’, or all the above metrics with ‘all’. See package vignette for description of fragmentation metrics.
bout.metric
Numeric (default = 6). Specify a metric for bout detection (recommended setting is bout.metric = 6 since it is the most updated version of the bout calculation in GGIR). If bout.metric = 1 the code uses the MVPA bout definition as has been available since 2014 (see papers by Sabia AJE 2014 and da Silva IJE 2014). Here, the algorithm looks for 10 minute windows in which more than XX percent of the epochs are above mvpathreshold, and then counts the entire window as mvpa. If bout.metric = 2 the code looks for groups of epochs with a bout.metric above mvpathreshold that span a time window of at least mvpadur minutes in which more than boutcriter percent of the epochs are above the threshold. The motivation for the defition 1 was: A person who spends 10 minutes in MVPA with a 2 minute break in the middle is equally active as a person who spends 8 minutes in MVPA without taking a break. Therefore, both should be counted equal and counted as 10 minute MVPA bout. The motivation for the definition 2 is: not counting breaks towards MVPA may simplify interpretation and still counts the two persons in the example as each others equal. If bout.metric = 3, using sliding window across the data to test bout criteria per window and do not allow for breaks larger than 1 minute and with fraction of time larger than the boutcriter threshold. If bout.metric = 4, same as 3 but also requires the first and last epoch to meet the threshold criteria. If bout.metric = 5, same as 4, but now looks for breaks larger than a minute such that 1 minute breaks are allowe, and the fraction of time that meets the threshold should be equal than or greater than the bout.criter threshold. If bout.metric = 6, algorithm improved (2021) to check for first and last epoch.
2.8 24/7 Parameters
qwindow
Numeric or character (default = c(0, 24)). To specify windows over which all variables are calculated, e.g., acceleration distirbution, number of valid hours, LXMX analysis, MVPA. If numeric, qwindow should have length two, e.g., qwindow = c(0, 24), all variables will only be calculated over the full 24 hours in a day. If qwindow = c(8, 24) variables will be calculated over the window 0-8, 8-24 and 0-24. All days in the recording will be segmented based on these values. If you want to use a day specific segmentation in each day then you can set qwindow to be the full path to activity diary file (character). Expected format of the activity diary is: First column headers followed by one row per recording, first column is recording ID, which needs to match with the ID GGIR extracts from the accelerometer file. Followed by date column in format ‘23-04-2017’, where date format is specified by argument qwindow_dateformat (below). Use the character combination date, Date or DATE in the column name. This is followed by one or multiple columns with start times for the activity types in that day format in hours:minutes:seconds. The header of the column will be used as label for each activity type. Insert a new date column before continuing with activity types for next day. Leave missing values empty. If an activitylog is used then individuals who do not appear in the activitylog will still be processed with value qwindow = c(0, 24). Dates with no activiy log data can be skipped, no need to have a column with the date followed by a column with the next date.
qlevels
Numeric (default = NULL). Array of percentiles for which value needs to be extracted. These need to be expressed as a fraction of 1, e.g., c(0.1, 0.5, 0.75). There is no limit to the number of percentiles. If left empty then percentiles will not be extracted. Distribution will be derived from short epoch metric data.
qwindow_dateformat
Character (default = ‘%d-%m-%Y’). To specify the date format used in the activity log as used by [base]strptime.
ilevels
Numeric (default = NULL). Levels for acceleration value frequency distribution in m, e.g., ilevels = c(0,100,200). There is no limit to the number of levels. If left empty then the intensity levels will not be extracted. Distribution will be derived from short epoch metric data.
IVIS_windowsize_minutes
Numeric (default = 60). Window size of the Intradaily Variability (IV) and Interdaily Stability (IS) metrics in minutes, needs to be able to add up to 24 hours.
IVIS_epochsize_seconds
Numeric (default = NULL). This argument is deprecated.
IVIS.activity.metric
Numeric (default = 2). Metric used for activity calculation. Value = 1, uses continuous scaled acceleration. Value = 2, tries to collapse acceleration into a binary score of rest versus active to try to similate the original approach.
IVIS_acc_threshold
Numeric (default = 20). Acceleration threshold to distinguish inactive from active.
qM5L5
Numeric (default = NULL). Percentiles (quantiles) to be calculated over L5 and M5 window.
MX.ig.min.dur
Numeric (default = 10). Minimum MX duration needed in order for intensity gradient to be calculated.
M5L5res
Numeric (default = 10). Resolution of L5 and M5 analysis in minutes.
winhr
Numeric (default = 5). Vector of window size(s) (unit: hours) of L5 and M5 analysis.
iglevels
Numeric (default = NULL). Levels for acceleration value frequency distribution in mused for intensity gradient calculation (according to the method by Rowlands 2018). By default this is argument is empty and the intensity gradient calculation is not done. The user can either provide a single value (any) to make the intensity gradient use the bins iglevels = c(seq(0,4000,by=25), 8000) or the user could specify their own distribution. There is no constriction to the number of levels.
LUXthresholds
Numeric (default = c(0, 100, 500, 1000, 3000, 5000, 10000)). Vector with numeric sequece corresponding to the thresholds used to calculate time spent in LUX ranges.
LUX_cal_constant
Numeric (default = NULL). If both LUX_cal_constant and LUX_cal_exponent are provided LUX values are converted based on formula y = constant * exp(x * exponent)
LUX_cal_exponent
Numeric (default = NULL). If both LUX_cal_constant and LUX_cal_exponent are provided LUX LUX values are converted based on formula y = constant * exp(x * exponent)
LUX_day_segments
Numeric (default = NULL). Vector with hours at which the day should be segmented for the LUX analysis.
window.summary.size
Numeric (default = 10). Functionality designed for the London Centre of Longidutinal studies. Size in minutes of the summary window
L5M5window
Argument depricated after version 1.5-24. This argument used to define the start and end time, in 24 hour clock hours, over which L5M5 needs to be calculated. Now this is done with argument qwindow.
cosinor
Argument depricated after version 1.5-24. Boolean (default = FALSE). Whether to apply the cosinor analysis from the ActCR package.
2.9 Output Parameters
epochvalues2csv
Boolean (default = FALSE). In g.part2: If TRUE then epoch values are exported to a csv file. Here, non-wear time is imputed where possible.
save_ms5rawlevels
Boolean (default = FALSE). In g.part5: Whether to save the time series classification (levels) as csv or RData files (as defined by save_ms5raw_format).
save_ms5raw_format
Character (default = ‘csv’). In g.part5: To specify how data should be stored: either ‘csv’ or ‘RData’. Only used if save_ms5rawlevels = TRUE.
save_ms5raw_without_invalid
Boolean (default = TRUE). In g.part5: To indicate whether to remove invalid days from the time series output files. Only used if save_ms5rawlevels = TRUE.
storefolderstructure
Boolean (default = FALSE). Store folder structure of the accelerometer data.
timewindow
Character (default = c(‘MM’, ‘WW’)). In g.part5: Timewindow over which summary statistics are derived. Value can be ‘MM’ (midnight to midnight), ‘WW’ (waking time to waking time), or both c(‘MM’,‘WW’).
viewingwindow
Numeric (default = 1). Centre the day as displayed around noon (viewingwindow = 1) or around midnight (viewingwindow = 2) in the visual report generated with visualreport = TRUE.
dofirstpage
Boolean (default = TRUE). To indicate whether a first page with histograms summarizing the whole measurement should be added in the file summary reports generated with visualreport = TRUE.
visualreport
Boolean (default = TRUE). If TRUE, then generate visual report based on combined output from g.part2 and g.part4.
week_weekend_aggregate.part5
Boolean (default = FALSE). In g.part5: To indicate whether week and weekend-days aggregates should be stored. This is turned off by default as it generates a large number of extra columns in the output report.
do.part3.pdf
Boolean (default = TRUE). In g.part3: Whether to generate a pdf for g.part3.
outliers.only
Boolean (default = FALSE). In g.part4: Only used if do.visual = TRUE. If FALSE, all available nights are included in the visual representation of the data and sleeplog. If TRUE, then only nights with a difference in onset or waking time larger than the variable of argument criterror will be included.
criterror
Numeric (default = 3). In g.part4: Only used if do.visual = TRUE and outliers.only = TRUE. criterror specifies the number of minimum number of hours difference between sleep log and accelerometer estimate for the night to be included in the visualisation.
do.visual
Boolean (default = TRUE). In g.part4: If TRUE, the function will generate a pdf with a visual representation of the overlap between the sleeplog entries and the accelerometer detections. This can be used to visually verify that the sleeplog entries do not come with obvious mistakes.
do.sibreport
Boolean (default = FALSE). In g.part4: To indicate whether to generate report for the sustained inactivity bouts (SIB).
do.part2.pdf
Boolean (default = TRUE). In g.part2: Whether to generate a pdf for g.part2.