From 3ddd9d120d10c971a4dd3206aa1ef481bc375591 Mon Sep 17 00:00:00 2001 From: Josef Heidler Date: Fri, 26 Jan 2024 17:30:25 +0100 Subject: [PATCH] finished hbGPS page (code needs to be tested) --- docs/gps/index.md | 188 +++++++++++++++++++++++++++++++++++++++++++++- mkdocs.yml | 9 +++ 2 files changed, 195 insertions(+), 2 deletions(-) diff --git a/docs/gps/index.md b/docs/gps/index.md index ffffca8..7ba79b1 100644 --- a/docs/gps/index.md +++ b/docs/gps/index.md @@ -17,11 +17,195 @@ R package that processes GPS data collected on human behavior and merges time se ## Installation +``` r +install.packages("remotes") # (1)! +remotes::install_github("wadpac/GGIR") # (2)! +remotes::install_github("habitus-eu/hbGPS") # (3)! +``` + +1. R package for installation from remote repositories (Github). +2. Installing GGIR package from GitHub repository. +3. Installing hbGPS package from GitHub repository. + ## Usage -## Contributing +If you want to use hbGPS to merge accelerometer and GPS data, you need to process the accelerometer data first using the GGIR package. Once you have processed the accelerometer data, you can merge it with GPS data using hbGPS. + +### Processing accelerometer data with GGIR + +There are two pipelines available for processing accelerometer data with GGIR, depending on whether the data is in RAW accelerometer format or already in counts. + +For explanation of GGIR parameters and additional information on how to use the GGIR package, see the [documentation](https://cran.r-project.org/web/packages/GGIR/vignettes/GGIR.html). + +#### RAW data + +``` r +library(GGIR) + +GGIR(datadir = "C:/path/to/your/data/folder", + outputdir = "C:/path/to/your/output/folder", + mode = c(1:5), + overwrite = TRUE, + do.report = c(), + windowsizes = c(5, 900, 3600), + includedaycrit = 10, + includenightcrit = 10, + part5_agg2_60seconds = TRUE, + HASPT.algo = "NotWorn", + HASIB.algo = "NotWorn", + HASPT.ignore.invalid = FALSE, + threshold.mod = c(100, 120), + boutdur.in = c(25, 30), + ignorenonwear = FALSE, + save_ms5rawlevels = TRUE, + save_ms5raw_without_invalid = FALSE +``` + +#### Counts data + +``` r +library(GGIR) + +acc_thresholds = c(100, 2500, 10000, 15000) # (1)! +acc_thresholds = acc_thresholds * c(5/60) # (2)! +acc_thresholds = round(acc_thresholds, digits = 2) # (3)! + +GGIR(datadir = "C:/path/to/your/data/folder", + outputdir = "C:/path/to/your/output/folder", + dataFormat = "actigraph_csv", + mode = 1:5, + overwrite = FALSE, + do.report = c(2), + windowsizes = c(1, 900, 3600), + threshold.lig = AccThresholds[1], + threshold.mod = AccThresholds[2], + threshold.vig = AccThresholds[3], + extEpochData_timeformat = "%m/%d/%Y %H:%M:%S", + do.neishabouricounts = TRUE, + acc.metric = "NeishabouriCount_x", + HASPT.algo = "NotWorn", + HASIB.algo = "NotWorn", + boutdur.mvpa = 10, # (4)! + boutdur.in = 30, + boutdur.lig = 10, + do.visual = TRUE, + includedaycrit = 10, + includenightcrit = 10, + visualreport = FALSE, + outliers.only = FALSE, + save_ms5rawlevels = TRUE, + ignorenonwear = FALSE, + HASPT.ignore.invalid = FALSE, + save_ms5raw_without_invalid = FALSE +) +``` + +1. Light (2500), moderate (10000), and vigorous PA (15000) thresholds. +2. Assumes GGIR's default epoch length of 5 seconds. +3. Rounding thresholds to two decimal places. +4. Parameters *boutdur.mvpa*, *boutdur.in* and *boutdur.lig* can also be vectors. + + +### Merge GPS and accelerometer data with hbGPS + +If your accelerometer data were processed by the GGIR package, you can merge them with GPS files using the hbGPS package. + +``` r +library(hbGPS) + +acc_thresholds = c(100, 2500, 10000, 15000) # (1)! +acc_thresholds = acc_thresholds * c(5/60) # (2)! +acc_thresholds = round(acc_thresholds, digits = 2) # (3)! + +hbGPS(gps_file = "C:/path_to_your_input_file/or/folder_with_files", + outputDir = "C:/path_to_your_output_folder", + GGIRpath = "C:/path_to_your_GGIR_output_folder/meta/ms5.outraw", # (4)!, + outputFormat = "PALMS", + AccThresholds = acc_thresholds, # (5)! + tz = "Australia/Perth", # (6)! + time_format = "%Y/%m/%d %H:%M:%S", # (7)! + idloc = 2, + maxBreakLengthSeconds = 120, + minTripDur = 60, + minTripDist_m = 100, + threshold_snr = 225, + threshold_snr_ratio = 50) +``` + +1. Light (2500), moderate (10000), and vigorous PA (15000) thresholds. +2. Assumes GGIR's default epoch length of 5 seconds. +3. Rounding thresholds to two decimal places. +4. The assumption is that GGIR has already been executed, and an output folder has been created. +5. Please ensure that you provide the correct timezone identifier from the [TZ identifier list](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). +6. Instead of specifying a thresholds for the accelerometer, you can use the *"default"* option. +7. Please ensure that you provide the correct [date and time format](https://sparkbyexamples.com/r-programming/dates-and-times-in-r/). + + +### An example of a complete processing pipeline + +The example of processing pipeline relies on counts accelerometer data from ActiGraph (CSV) and GPS data from Qstarz (CSV). + +You can download the sample data by clicking on the link provided [here](). + +``` r +library(GGIR) +library(hbGPS) + +acc_input = "C:/path/to/your/data/acc/folder" +gps_input = "C:/path/to/your/data/gps/folder" +ggir_output = "C:/path/to/your/ggir/output/folder" +hb_output = "C:/path/to/your/hb/output/folder" + +acc_thresholds = c(100, 2500, 10000, 15000) +acc_thresholds = acc_thresholds * c(5/60) +acc_thresholds = round(acc_thresholds, digits = 2) + +GGIR(datadir = acc_input, + outputdir = ggir_output, + dataFormat = "actigraph_csv", + mode = 1:5, + overwrite = FALSE, + do.report = c(2), + windowsizes = c(1, 900, 3600), + threshold.lig = AccThresholds[1], + threshold.mod = AccThresholds[2], + threshold.vig = AccThresholds[3], + extEpochData_timeformat = "%m/%d/%Y %H:%M:%S", + do.neishabouricounts = TRUE, + acc.metric = "NeishabouriCount_x", + HASPT.algo = "NotWorn", + HASIB.algo = "NotWorn", + boutdur.mvpa = 10, # (4)! + boutdur.in = 30, + boutdur.lig = 10, + do.visual = TRUE, + includedaycrit = 10, + includenightcrit = 10, + visualreport = FALSE, + outliers.only = FALSE, + save_ms5rawlevels = TRUE, + ignorenonwear = FALSE, + HASPT.ignore.invalid = FALSE, + save_ms5raw_without_invalid = FALSE +) + +hbGPS(gps_file = gps_input, + outputDir = hb_output, + GGIRpath = ggir_output + "/meta/ms5.outraw", + outputFormat = "PALMS", + AccThresholds = acc_thresholds, + tz = "Australia/Perth", + time_format = "%Y/%m/%d %H:%M:%S", + idloc = 2, + maxBreakLengthSeconds = 120, + minTripDur = 60, + minTripDist_m = 100, + threshold_snr = 225, + threshold_snr_ratio = 50) + +``` ## License -## Changelog +This project is licensed under the terms of the Apache License 2.0. diff --git a/mkdocs.yml b/mkdocs.yml index d1b084c..ecbf0e4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -36,6 +36,8 @@ theme: - navigation.top - search.suggest - navigation.footer + - content.code.copy + - content.code.annotate nav: - Habitus: @@ -78,4 +80,11 @@ copyright: Copyright © 2024 The Department of Sports Science and Clinical B markdown_extensions: - attr_list - md_in_html + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences - pymdownx.magiclink