DOCSEARCHbyAlgolia
Submit Docs

GGIR R Package

repository·main·Indexed 40 days ago

https://github.com/wadpac/ggir

An R package for the automated processing of polysomnography (PSG) and raw accelerometer data. GGIR provides tools for analyzing physical activity, sleep, and circadian rhythms, featuring raw data processing, epoch-level analysis, and metric calculation. It supports various output time resolutions and specialized sleep analysis scenarios, such as Sleep Period Time (SPT) and Time in Bed.

Tokens
117.7K
Snippets
286
Records
590
Agent score
99%

What's inside GGIR

  1. Overview of GGIR functionality and data processing

    main

    GGIR is an R package designed to process multi-day raw accelerometer data (expressed in gravitational units, 1 g) for research into physical activity, sleep, and circadian rhythms. While optimized for raw data, it also supports previous-generation accelerometer data (epoch-level data in brand-specific units).

    Core Signal Processing Steps

    1. Raw Data Processing: Automatic calibration to gravity, detection of abnormally high values, imputation of raw-level time gaps (for specific brands), and calculation of orientation angles and average magnitude acceleration.
    2. Epoch-level Processing: Detection of non-wear periods and epoch-level imputation.
    3. Metric Calculation: Generation of data quality and summary metrics used to estimate physical activity, inactivity, sleep, and circadian rhythms.

    Output Time Resolutions

    GGIR provides data at several temporal granularities:

    • Per recording: Typically one per participant ID.
    • Calendar day: Defaulted to midnight borders.
    • Night: A period centered around the main daily sleep period (defaulting to noon-to-noon or 6pm-to-6pm).
    • Day segment: Defined via code (standardized) or a diary file (variable per recording/day).
    • Waking-up windows: Defined from waking after main sleep to the next waking event, or from sleep onset to the next sleep onset.
    • Epoch-level time series: User-defined epoch lengths (e.g., 5 seconds).

  2. License information for GGIR

    main

    GGIR is licensed under the Apache License, Version 2.0.

    This license allows you to use, reproduce, modify, and distribute the software and any derivative works. Key permissions and conditions include:

    • Permissions: Perpetual, worldwide, non-exclusive, no-charge, royalty-free, and irrevocable copyright and patent licenses.
    • Redistribution Requirements:
      • You must provide a copy of the license to recipients.
      • You must include prominent notices in modified files stating that you changed them.
      • You must retain all original copyright, patent, trademark, and attribution notices.
      • If a NOTICE file is included in the original distribution, you must include a readable copy of those attribution notices in your derivative works.
    • Trademarks: This license does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor (except for describing the origin of the work).
    • Disclaimer: The work is provided on an "AS IS" BASIS, without warranties or conditions of any kind.

  3. Understand GGIR Part 2 output files

    main

    GGIR Part 2 generates several summary and quality control files to help you analyze processed accelerometer data:

    • part2_summary.csv: A person-level summary containing aggregated metrics (e.g., mean ENMO, MVPA, circadian rhythm indicators).
    • part2_daysummary.csv: A day-level summary providing granular data for each day of measurement.
    • QC/data_quality_report.csv: An overview of calibration results and file integrity (e.g., whether files were corrupt or too short).
    • QC/plots_part2/: A directory containing .png files that visualize acceleration time series in 15-minute resolutions, with color-coded invalid segments:
      • Yellow: Non-wear based on standard deviation threshold.
      • Brown: Non-wear after extra filtering steps.
      • Purple: Clipping.

  4. Use GGIR user scripts

    main
    The user-scripts/ directory contains standalone R scripts that provide useful functionality for GGIR users but are not currently integrated into the core GGIR package. These scripts are useful for specific tasks that may not be relevant to the broader community or are still undergoing development (e.g., lacking full documentation or unit tests).

  5. Understand the types of GGIR output generated

    main

    GGIR produces several types of output files depending on the processing stage and analysis requirements:

    • CSV spreadsheets: Contain variables required for physical activity, sleep, and circadian rhythm research. Specific summaries include:
      • Person level summary
      • Day level summary
      • Data quality reports
    • PNG images: Low time resolution plots of the data per file, including quality indicators.
    • RData files: Contain milestone data used internally between GGIR processing stages.
    • PDFs: Provide a visual summary of identified physical activity and sleep patterns.

  6. What is the g.part5.analyseRest function?

    main

    The g.part5.analyseRest function is an internal GGIR utility used to analyze the overlap between self-reported napping, non-wear periods, and Sleep Intensity Behavior (SIB).

    Note: This is an internal function and is not intended for direct use by GGIR end-users. Most users should interact with the high-level g.part5 function instead.

  7. Understand the GGIR shell function parameter structure

    main

    The GGIR shell function organizes input arguments into specific parameter objects based on which 'part' of the GGIR pipeline they are used in. Understanding this structure helps in identifying which parameters are available for specific processing stages (Parts 1 through 6).

    Key Concepts:

    • Direct Arguments: Some parameters (like datadir, f0, f1, outputdir, and studyname) are passed directly to the shell function and are not contained within a parameter object.
    • Parameter Objects: Most optional arguments are grouped into objects (e.g., params_general, params_metrics, params_cleaning) that are populated during the execution of specific GGIR parts.
    • GGIR Parts: The pipeline is divided into sequential parts (1, 2, 3, 4, 5, and 6), each performing different levels of data processing (e.g., raw data processing, cleaning, sleep analysis, physical activity analysis).

  8. Append recordings using maxRecordingInterval

    main

    GGIR can automatically append recordings from the same ID if they are separated by a gap, provided they belong to the same accelerometer brand.

    • Set maxRecordingInterval to a numeric value (in hours) representing the maximum allowable gap between recordings to be appended.
    • The maximum allowed value is 504 (21 days).
    • If maxRecordingInterval is NULL (default), recordings are not appended.
    • Behavior:
      • If recordings overlap, GGIR uses data from the latest recording.
      • If recordings are separated by a gap, the gap is filled with data points representing 'monitor not worn'.
    • The idloc parameter must be correctly configured so GGIR can match IDs across files.
    • Results of the appending process (number of appended files, sampling rates, gaps, etc.) are reported in the part 2 CSV report.

  9. Understand MXLX (Most/Least Active X-hour window)

    main

    MXLX identifies the continuous least (LX) and most (MX) active X-hour windows in a day.

    Key Parameters & Behavior:

    • winhr: Defines the window size (X). If provided as a vector, MX and LX are derived for each value in the vector.
    • iglevels: If specified, GGIR also calculates the intensity gradient for LX and MX.
    • qwindow: In part 2, if specified, MXLX is calculated per segment of the day instead of per calendar day.

    Implementation Details:

    • Part 2: Calculated per calendar day.
    • Part 6: Calculated per time window (as defined by part6Window).
    • Hardware specific: If using GENEActiv or Axivity accelerometers in part 6, LUX estimates per LX and MX are included in the CSV reports.

  10. Understand the `g.plot5` visual report

    main

    The g.plot5 function generates a user-friendly visual report of movement and sleep data. The report consists of two main parts:

    1. Summary Page: A first page (if dofirstpage = TRUE) containing bar plots that summarize important daily metrics.
    2. 24-hour Period Plots: Detailed plots showing raw data and annotations in 24-hour windows:
      • Angle-z: Displayed with sleep annotations during the Sleep Period Time (SPT) window.
      • ENMO: Displayed with daytime inactivity and Physical Activity (PA) annotations in the lower section of each 24-hour plot.

    Physical Activity (PA) Logic:

    • PA annotations are based on a 10-minute bout metric.
    • MVPA (Moderate-to-Vigorous Physical Activity): Requires 80% of a 10-minute bout.
    • Vigorous PA: Short windows of time above threshold.vig that are part of an MVPA bout.
    • Light PA: Short windows of time above threshold.lig that are part of a light PA bout.

  11. Optimize memory usage with chunksize

    main

    The chunksize parameter controls the amount of data loaded into memory at once. This is critical for preventing out-of-memory errors, especially when using parallel processing.

    • Definition: A fraction of an approximately 12-hour period (for auto-calibration) and a 24-hour period (for metric calculation).
    • Example: chunksize = 0.5 results in 6-hour and 12-hour chunks respectively.
    • Recommendation: For machines with < 4GB RAM (or < 2GB per process when using do.parallel = TRUE), use a value below 1.
    • Constraints: The minimum allowed value is 0.05.

    Warning: Setting chunksize = 0.05 will not produce output if the windowsizes parameter's 3rd value is 3600.

    # Recommended for low-memory systems
chunksize = 0.5

  12. Choose between 2013 and 2023 non-wear detection approaches

    main

    The nonwear_approach argument allows you to choose between two algorithmic versions:

    • "2013" (Default): Uses the long-size window (windowsizes[3], default 1 hour) to check non-wear conditions. It flags the medium-size window (windowsizes[2], default 15 min) located in the center of the long-size window as non-wear.
    • "2023": Flags the full long-size window as non-wear. In this version, the long-size window is aligned by its left edge with the left edge of the medium-size window.