From 1b60cbb5390af92bf4fe5294de78a1c8bedc13fd Mon Sep 17 00:00:00 2001 From: Josef Heidler Date: Sat, 27 Jan 2024 19:52:17 +0100 Subject: [PATCH] init hbGIS --- docs/examples/complete.md | 1 + docs/examples/index.md | 3 -- docs/gis/index.md | 89 ++++++++++++++++++++++++++++++++++++++- docs/gps/index.md | 24 +++++------ docs/gui/index.md | 7 ++- docs/index.md | 6 +-- mkdocs.yml | 6 ++- 7 files changed, 112 insertions(+), 24 deletions(-) create mode 100644 docs/examples/complete.md delete mode 100644 docs/examples/index.md diff --git a/docs/examples/complete.md b/docs/examples/complete.md new file mode 100644 index 0000000..b3a5554 --- /dev/null +++ b/docs/examples/complete.md @@ -0,0 +1 @@ +TO-DO... \ No newline at end of file diff --git a/docs/examples/index.md b/docs/examples/index.md deleted file mode 100644 index 4c3ee9d..0000000 --- a/docs/examples/index.md +++ /dev/null @@ -1,3 +0,0 @@ -# TO-DO Examples... - -TO-DO examples... \ No newline at end of file diff --git a/docs/gis/index.md b/docs/gis/index.md index 9a07c45..b594293 100644 --- a/docs/gis/index.md +++ b/docs/gis/index.md @@ -1,3 +1,88 @@ -# TO-DO hbGIS... +--- +hide: + - navigation +--- -hbGIS examples... +R package for analyzing spatiotemporal behaviour patterns using geospatial data and output from hbGPS or PALMS. Inspired by [palmsplusr](https://thets.github.io/palmsplusr), hbGIS offers features to answer questions about when, where, and what: + +- How much time participants spend in parks? +- How much moderate to vigorous physical activity (MVPA) is accumulated in parks? +- What proportion of sedentary time is accumulated during vehicular travel? +- What is the average distance of home-to-school trips? +- How much MVPA is accumulated inside the schoolyard during school time? +- What proportion of commuters use different travel modes in their trip chain (e.g., walk-bus-walk)? +- What is the average speed of bicycle trips during peak travel times? + +## Installation + +``` r +install.packages("remotes") # (1)! +remotes::install_github("wadpac/GGIR") # (2)! +remotes::install_github("habitus-eu/hbGIS") # (3)! +``` + +1. R package for installation from remote repositories (Github). +2. Installing GGIR package from GitHub repository. +3. Installing hbGIS package from GitHub repository. + +## Usage + +``` r +library(hbGIS) + +hbGIS(gisdir = "C:/path_to_your_input_gis_file/or/folder_with_gis_files", + palmsdir = "C:/path_to_your_hbgps_or_palms_output_folder", + gislinkfile = "C:/path_to_your_linkage_file/participant_basis.csv", # (1)! + outputdir = "C:/path_to_your_output_folder", + dataset_name = "project_name", + configfile = "C:/path_to_your_config_file/participant_basis.csv", # (2)! + baselocation = "home", # (3)! + groupinglocation = "school", # (4)! + write_shp = FALSE, # (5)! + split_GIS = TRUE, # (6)! + sublocationID = "ID_NR") # (7)! +``` + +1. See more below (Linkage file). +2. See more below (Config file). +3. Base for individuals (leave empty if not available). +4. Grouping for individuals (leave empty if not available). +5. Option to store shape files as output. +6. Option to split GIS files in sublocations (only for public places). +7. Column name in GIS file to identify sublocation. + +!!! note + + GIS filenames are used as location names and at the moment the code can only handle names that are shorter than 6 characters. + +### Linkage file + +TO-DO... + +### Config file + +TO-DO... + +## Output files + +hbGIS will generate four output files. + +| Filename | Description | +| --------------------------- | ------------------------------------------------------------------ | +| `datasetname_whenwhatwhere` | Time series with information about when and where things happened. | +| `datasetname_days.csv` | Day-level summaries. | +| `datasetname_trajectories` | Trajectory-based summaries. | +| `datasetname_multimodal` | Breakdown of trajectories by mode of transport. | + +### Used abbrevations + +| Abbrevation | Description | +| ------------- | -------------- | +| `mot` | mode of transport | +| `iov` | indoor-outdoor-vehicle | +| `nbh` | neighbourhood | +| `dow` | day of week | + +## License + +This project is licensed under the terms of the Apache License 2.0. \ No newline at end of file diff --git a/docs/gps/index.md b/docs/gps/index.md index 7ba79b1..0fcd68d 100644 --- a/docs/gps/index.md +++ b/docs/gps/index.md @@ -3,7 +3,7 @@ hide: - navigation --- -R package that processes GPS data collected on human behavior and merges time series with GGIR package for accelerometer data. The package provides a pipeline that performs the following: +R package for GPS data processing and merging with accelerometer data. The package provides a pipeline that performs the following: - Loading GPS CSV files, with the aim of making this process flexible to most common formats. - Taking timezone into account when interpreting timestamps. @@ -33,9 +33,7 @@ If you want to use hbGPS to merge accelerometer and GPS data, you need to proces ### 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). +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 @@ -77,9 +75,9 @@ GGIR(datadir = "C:/path/to/your/data/folder", overwrite = FALSE, do.report = c(2), windowsizes = c(1, 900, 3600), - threshold.lig = AccThresholds[1], - threshold.mod = AccThresholds[2], - threshold.vig = AccThresholds[3], + threshold.lig = acc_thresholds[1], + threshold.mod = acc_thresholds[2], + threshold.vig = acc_thresholds[3], extEpochData_timeformat = "%m/%d/%Y %H:%M:%S", do.neishabouricounts = TRUE, acc.metric = "NeishabouriCount_x", @@ -145,8 +143,6 @@ hbGPS(gps_file = "C:/path_to_your_input_file/or/folder_with_files", 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) @@ -167,10 +163,10 @@ GGIR(datadir = acc_input, 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", + threshold.lig = acc_thresholds[1], + threshold.mod = acc_thresholds[2], + threshold.vig = acc_thresholds[3], + extEpochData_timeformat = "%Y/%m/%d %H:%M:%S", do.neishabouricounts = TRUE, acc.metric = "NeishabouriCount_x", HASPT.algo = "NotWorn", @@ -194,7 +190,7 @@ hbGPS(gps_file = gps_input, GGIRpath = ggir_output + "/meta/ms5.outraw", outputFormat = "PALMS", AccThresholds = acc_thresholds, - tz = "Australia/Perth", + tz = "Europe/Copenhagen", time_format = "%Y/%m/%d %H:%M:%S", idloc = 2, maxBreakLengthSeconds = 120, diff --git a/docs/gui/index.md b/docs/gui/index.md index 0ce0e24..f1d045d 100644 --- a/docs/gui/index.md +++ b/docs/gui/index.md @@ -1 +1,6 @@ -# TO-DO... \ No newline at end of file +--- +hide: + - navigation +--- + +TO-DO... \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index bec9eec..77cd4db 100644 --- a/docs/index.md +++ b/docs/index.md @@ -19,6 +19,6 @@ The core functionality for merging and processing accelerometer and GPS data use ## HABITUS consists of three separate packages -1. hbGPS -2. hbGIS -3. HabitusGUI \ No newline at end of file +1. **hbGPS** – package for GPS data processing and merging with accelerometer data. +2. **hbGIS** – package for analyzing spatiotemporal behaviour patterns using geospatial data and data from hbGPS/PALMS. +3. **HabitusGUI** – TO-DO... \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index ecbf0e4..8ad8ca5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -47,7 +47,8 @@ nav: - HabitusGUI: gui/index.md - hbGPS: gps/index.md - hbGIS: gis/index.md - - Examples: examples/index.md + - Examples: + - A complete example: examples/complete.md plugins: - search @@ -78,6 +79,7 @@ extra: copyright: Copyright © 2024 The Department of Sports Science and Clinical Biomechanics, University of Southern Denmark markdown_extensions: + - admonition - attr_list - md_in_html - pymdownx.highlight: @@ -88,3 +90,5 @@ markdown_extensions: - pymdownx.snippets - pymdownx.superfences - pymdownx.magiclink + - pymdownx.details + - tables