Package: GGIR 3.3-7

Vincent T van Hees

GGIR: Raw Accelerometer Data Analysis

A tool to process and analyse data collected with wearable raw acceleration sensors as described in Migueles and colleagues (JMPB 2019), and van Hees and colleagues (JApplPhysiol 2014; PLoSONE 2015). The package has been developed and tested for binary data from 'GENEActiv' <https://activinsights.com/>, binary (.gt3x) and .csv-export data from 'Actigraph' <https://ametris.com/> devices, and binary (.cwa) and .csv-export data from 'Axivity' <https://axivity.com>. These devices are currently widely used in research on human daily physical activity. Further, the package can handle accelerometer data file from any other sensor brand providing that the data is stored in csv format. Also the package allows for external function embedding.

Authors:Vincent T van Hees [aut, cre], Jairo H Migueles [aut], Samuel T Afolabi [ctb], Severine Sabia [ctb], Matthew R Patterson [ctb], Zhou Fang [ctb], Joe Heywood [ctb], Joan Capdevila Pujol [ctb], Lena Kushleyeva [ctb], Mathilde Chen [ctb], Manasa Yerramalla [ctb], Patrick Bos [ctb], Taren Sanders [ctb], Chenxuan Zhao [ctb], Ian Meneghel Danilevicz [ctb], Victor Barreto Mesquita [ctb], Gaia Segantin [ctb], Xiaoyu Zong [ctb], Medical Research Council UK [cph, fnd], Accelting [cph, fnd], French National Research Agency [cph, fnd]

GGIR_3.3-7.tar.gz
GGIR_3.3-7.zip(r-4.7)GGIR_3.3-7.zip(r-4.6)GGIR_3.3-7.zip(r-4.5)
GGIR_3.3-7.tgz(r-4.6-any)GGIR_3.3-7.tgz(r-4.5-any)
GGIR_3.3-7.tar.gz(r-4.7-any)GGIR_3.3-7.tar.gz(r-4.6-any)
GGIR_3.3-7.tgz(r-4.6-emscripten)
manual.pdf |manual.html
DESCRIPTION |NEWS
card.svg |card.png
GGIR/json (API)

# Install 'GGIR' in R:
install.packages('GGIR', repos = c('https://wadpac.r-universe.dev', 'https://cloud.r-project.org'))

Bug tracker:https://github.com/wadpac/ggir/issues

Pkgdown/docs site:https://wadpac.github.io

Datasets:

On CRAN:

Conda:

accelerometeractivity-recognitioncircadian-rhythmmovement-sensorsleep

13.40 score 143 stars 3 packages 536 scripts 2.1k downloads 81 mentions 104 exports 118 dependencies

Last updated from:fb0fe1e169. Checks:9 OK. Indexed: yes.

TargetResultTimeFilesSyslog
linux-devel-x86_64OK301
source / vignettesOK257
linux-release-x86_64OK243
macos-release-arm64OK258
macos-oldrel-arm64OK182
windows-develOK137
windows-releaseOK208
windows-oldrelOK208
wasm-releaseOK172

Exports:ABIaddSplitNamesaggregateEventappendRecordsapply_cosinor_IS_IV_Analysesbuild_epoch_tableCalcSleepRegularityIndexcheck_logcheck_paramsconvertEpochDatacorrectOlderMilestoneDatacosinor_IS_IV_AnalysescreateConfigFiledatadir2fnamesdetect_nonwear_clippingDFAextract_paramsextractIDfilterNonwearNightg.abr.day.namesg.analyseg.applymetricsg.calibrateg.conv.actlogg.create.sp.matg.detecmidnightg.dotorcommag.extractheadervarsg.fragmentationg.getboutg.getM5L5g.getmetag.getstarttimeg.imputeg.imputeTimegapsg.inspectfileg.intensitygradientg.IVISg.loadlogg.part1g.part2g.part3g.part3_alignIndexVectorsg.part3_correct_guiderg.part4g.part4_extractidg.part5g.part5_analyseSegmentg.part5_initialise_tsg.part5.addfirstwakeg.part5.addsibg.part5.analyseRestg.part5.definedaysg.part5.fixmissingnightg.part5.handle_lux_extremesg.part5.lux_persegmentg.part5.onsetwaketimingg.part5.savetimeseriesg.part5.wakesleepwindowsg.part6g.plotg.plot5g.readaccfileg.readtemp_movisensg.report.part2g.report.part4g.report.part5g.report.part5_dictionaryg.report.part6g.shell.GGIRg.sib.detg.sib.plotg.sib.sumg.sibreportg.weardecget_nw_clip_block_paramsget_starttime_weekday_truncdatagetPart1BasicInfogetSplitNamesGGIRHASIBHASPTidentify_levelsinspect_binFile_brandis_this_a_dst_nightis.ISO8601isfilelistismovisensiso8601chartime2POSIXload_paramsmarkerButtonForRestparametersVignettepart6AlignIndividualspart6PairwiseAggregationPOSIXtime2iso8601read.myacc.csvShellDoc2VignettesplitRecordsSSPtidyup_dfupdateBlocksizevisualReportwrite_dashboard_parquetwrite_epoch_parquet

Dependencies:ActCRarrowassertthatbackportsbase64encbitbit64bitopsbslibcachemcellrangercheckmatecliclustercodetoolscolorspacecommonmarkcosinorcosinor2cowplotcpp11crayondata.tabledigestdoParalleldplyrevaluatefarverfastmapfontawesomeforeachforeignFormulafsgenericsGGIRreadggplot2glueGPArotationgridExtragtablehexViewhighrHmischmshtmlTablehtmltoolshtmlwidgetshttpuvineqirrisobanditeratorsjquerylibjsonliteknitrlabelinglaterlatticelifecyclelpSolvelubridatemagrittrMASSmatlabmatrixStatsmemoisemimeminpack.lmmnormtnlmennetotelpillarpkgconfigprettyunitsprogresspromisespsychpurrrR.methodsS3R.ooR.utilsR6rappdirsRColorBrewerRcppread.gt3xreadxlrematchrlangrmarkdownrpartrstudioapiS7sassscalesshinysignalsourcetoolsstringistringrtibbletidyselecttimechangetinytextzdbunisensRutf8vctrsviridisLitevroomwithrxfunXMLxtableyamlzoo

GGIR output
GGIR Part 1 | GGIR Part 2 | Person level summary (csv) | Letter codes to indicate aggregation type | Distribution of acceleration | Circadian rhythm: MXLX, IV, and IS | Circadian rhythm: Cosinor | Day level summary (csv) | Data_quality_report (csv) | GGIR Part 3 | GGIR Part 4 | Night level summaries (csv) | Person level summaries (csv) | Visualisation (pdf) | GGIR Part 5 | Fragmentation | GGIR Part 6 | MXLX output variables | Cosinor output variables | Other output variables in part 6

Last update: 2026-05-01
Started: 2024-06-13

GGIR configuration parameters
Input arguments/parameters overview | Arguments/parameters description | GGIR function input arguments | mode | datadir | outputdir | studyname | f0 | f1 | do.report | configfile | myfun | General Parameters | Raw Data Parameters | Metrics Parameters | Cleaning Parameters | Sleep Parameters | Physical activity Parameters | 24/7 Parameters | Output Parameters

Last update: 2026-05-01
Started: 2022-09-19

Embedding external functions in GGIR
Introduction | Example with external R function | Write external function | Provide external function to GGIR | Example with external Python function | Integration in GGIR output | Part 1 | Part 2 | External functions released by GGIR collaborators:

Last update: 2026-04-21
Started: 2020-04-30

Reading csv files with raw data in GGIR
Introduction | The read.myacc.csv function | Input arguments | General arguments | Arguments for files containing a header | Arguments for files including timestamps | Arguments for files with acceleration stored in bits | Arguments for files including temperature | Arguments for files including wear time information | Arguments to find time gaps and resampling | Usage of the read.myacc.csv function | Example using the shell function

Last update: 2026-04-21
Started: 2022-05-05

Step and Cadence Analysis
Verisense algorithm | How to use the Verisense algorithm? | Time resolution for deriving statistics | Per day or groups of days | Per day segment | Step count and cadence summary statistics | Stratified by acceleration and/or cadence level | Per acceleration level | Per cadence level with absolute thresholds | Per cadence level with relative thresholds | Per most and least active consecutive cadence time window | Walking bouts

Last update: 2026-04-21
Started: 2025-12-22

Published cut-points and how to use them in GGIR
Considerations | Cut-points expressed in gravitational units (this vignette) | Cut-points NOT expressed in gravitational units (not in this vignette) | Relevant arguments to use cut-points in GGIR | Summary of published cut-points | Cut-points for preschoolers | Cut-points for children/adolescents | Cut-points for adults | Cut-points for older adults | Notes on cut-point validity | References

Last update: 2026-01-27
Started: 2022-09-19

Nap Detection
Algorithm description | Output related to nap detection | Disclaimer

Last update: 2025-08-29
Started: 2025-08-29

Accelerometer data processing with GGIR
Introduction | What is GGIR? | Contributing, Support, and Keeping up to date | Setting up your work environment | Install R and RStudio | Prepare folder structure | GGIR shell function | Key general arguments | Key arguments related to sleep analysis | Basic sleep log | Advanced sleep log | Key arguments related to time use analysis | Published cut-points and how to use them | Example call | Configuration file | Time for action: How to run your analysis? | From the R console on your own desktop/laptop | In a cluster | Processing time | Inspecting the results | Output part 2 | Person level summary | Day level summary | Data_quality_report | Output part 4 | Night level summaries | Non-default variables in part 4 csv report | visualisation_sleep.pdf | Output part 5 | Day level summary | Output part 6 | Motivation and clarification | Reproducibilty of GGIR analyses | Auto-calibration | Non-wear detection | Clipping score | Why collapse information to epoch level? | Why does the first epoch not allign with the original start of the recording | Sleep analysis | Notes on sleep classification algorithms designed for count data | Replication of the movement counts needed | Missing information for replicating movement counts | An educated guess and how you can to help optimise the implementation | Guiders | Daysleepers (nights workers) | Cleaningcode | Difference between cleaned and full output | Data cleaning file | Waking-waking or 24 hour time-use analysis | Time series output files | Day inclusion criteria | Fragmentation metrics | Why use data metric ENMO as default? | What does GGIR stand for? | Circadian Rhythm analyses | ActiGraph's idle sleep mode | Time gap imputation | The importance of reporting idle.sleep.mode usage | MX metrics (minimum intensity of most active X minutes) | Minimum recording duration | LUX sensor data processing | Other Resources | Citing GGIR | Copyright for GGIR logo

Last update: 2025-06-23
Started: 2017-04-28

Day segment analyses with GGIR
Introduction | Clock hour-based segmentation | Segmentation guided by activity log | Implementation in GGIR | Examples | Clock-hour based segmentation: | Activity log based segmentation: | Cleaning parameters for day segments (in part 5): | Analyses performed per day segment

Last update: 2024-11-25
Started: 2021-10-20

Readme and manuals

Help Manual

Help pageTopics
A package to process multi-day raw accelerometer dataGGIR-package
Activity balance index (ABI)ABI
Apply Cosinor Analyses to time seriesapply_cosinor_IS_IV_Analyses
Creates csv data file for testing purposescreate_test_acc_csv
Creates csv sleeplog file for testing purposescreate_test_sleeplog_csv
Example output from g.calibratedata.calibrate
Example output from g.getmetadata.getmeta
Example output from g.inspectfiledata.inspectfile
Metalong object as part of part 1 milestone datadata.metalong
Time series data.frame stored by part 5data.ts
Detrended Fluctuation AnalysisDFA
function to estimate calibration error and make recommendation for addressing itg.calibrate
function to calculate bouts from vector of binary classesg.getbout
Function to extract meta-data (features) from data in accelerometer fileg.getmeta
Impute gaps in three axis raw accelerometer datag.imputeTimegaps
function to inspect accelerometer file for brand, sample frequency and headerg.inspectfile
Load and clean sleeplog informationg.loadlog
function to load and pre-process acceleration filesg.part1
function to analyse and summarize pre-processed output from g.part1g.part2
Detection of sustained inactivity periods as needed for sleep detection in g.part4.g.part3
Labels detected sustained inactivity periods by g.part3 as either part of the Sleep Period Time window or notg.part4
Merge output from physical activity and sleep analysis into one reportg.part5
Perform temporal pattern analysesg.part6
Generate user-friendly visual report. The first part of the report summarizes important daily metrics in bar plot format. The second part of the report shows the raw data and annotations in 24-hr periods. Angle-z is shown with sleep annotations during the SPT (sleep period time) window. ENMO is shown with daytime inactivity and PA (physical activity) annotations in the lower section of each 24-hr plot. The PA annotations are based on a 10 minute bout metric and 80 of a 10 minute bout of MVPA. Vigorous PA is a short window of time above threshold.vig that is part of a bout of MVPA. Light PA is a short window of time above threshold.lig that is part of a bout of light PA.g.plot5
Generate report from milestone data produced by g.part2g.report.part2
Generate report from milestone data produced by g.part4g.report.part4
Generate report from milestone data produced by g.part5g.report.part5
Generate data dictionary for reports from milestone data produced by g.part5g.report.part5_dictionary
Generate report from milestone data produced by g.part6g.report.part6
Wrapper function around function GGIRg.shell.GGIR
Shell function for analysing an accelerometer dataset.GGIR
Identify the Device Brand from a Binary Fileinspect_binFile_brand
Check whether character timestamp is in iso8601 format.is.ISO8601
Convert iso8601 timestamps to POSIX timestampiso8601chartime2POSIX
Load default parametersload_params
part6AlignIndividualspart6AlignIndividuals
part6PairwiseAggregationpart6PairwiseAggregation
Convert POSIX to iso8601 timestampPOSIXtime2iso8601
Read custom csv files with accelerometer dataread.myacc.csv
Estimated self-similarity parameterSSP
Generate visualisation of time series produced by part 5.visualReport
Write consolidated dashboard Parquet outputwrite_dashboard_parquet