Skip to content

Commit

Permalink
lot of fixes for gis, gps and progress with gui (stuck with testing)
Browse files Browse the repository at this point in the history
  • Loading branch information
@josefheidler
josefheidler committed Jan 29, 2024
1 parent 98cd54b commit c039654
Show file tree
Hide file tree
Showing 3 changed files with 106 additions and 88 deletions.
45 changes: 32 additions & 13 deletions docs/gis/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,15 +27,42 @@ remotes::install_github("habitus-eu/hbGIS") # (3)!

## Usage

TO-DO...Something like: Before you start you need to have linkage and configuration file with shape files...

### Linkage file

TO-DO...

### Configuration file

TO-DO...

### Configuration

| Parameter | Description |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `gisdir` | Option to find participant ID. More on methods of finding ID can be found in [GGIR documentation](https://cran.r-project.org/web/packages/GGIR/). |
| `gislinkfile` | Path to input file or folder. |
| `outputdir` | Path to output folder. |
| `dataset_name` | Path to GGIR output folder (ms5). |
| `configfile` | indoor-outdoor-vehicle. |
| `baselocation` | Correct [date and time format](https://sparkbyexamples.com/r-programming/dates-and-times-in-r/). |
| `groupinglocation` | Timezone in which experiments took place [TZ identifier list](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). |
| `write_shp` | Acceleration thresholds corresponding to the intensity levels. |
| `split_GIS` | Maximum trip break duration in seconds. |
| `sublocationID` | Minimum trip distance in meters. |

### Example

``` 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",
hbGIS(gisdir = "C:/path_to_input_gis_file/or/folder",
palmsdir = "C:/path_to_hbgps_or_palms_output_folder",
gislinkfile = "C:/path_to_linkage_file/participant_basis.csv", # (1)!
outputdir = "C:/path_to_output_folder",
dataset_name = "project_name",
configfile = "C:/path_to_your_config_file/participant_basis.csv", # (2)!
configfile = "C:/path_to_config_file/palmsplus.csv", # (2)!
baselocation = "home", # (3)!
groupinglocation = "school", # (4)!
write_shp = FALSE, # (5)!
Expand All @@ -55,14 +82,6 @@ hbGIS(gisdir = "C:/path_to_your_input_gis_file/or/folder_with_gis_files",

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.
Expand Down
104 changes: 30 additions & 74 deletions docs/gps/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ remotes::install_github("habitus-eu/hbGPS") # (3)!

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
### 1. 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).

Expand Down Expand Up @@ -102,101 +102,57 @@ GGIR(datadir = "C:/path/to/your/data/folder",
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
### 2. 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.

#### Configuration

| Parameter | Description |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `idloc` | Option to find participant ID. More on methods of finding ID can be found in [GGIR documentation](https://cran.r-project.org/web/packages/GGIR/). |
| `gps_file` | Path to input file or folder. |
| `outputDir` | Path to output folder. |
| `GGIRpath` | Path to GGIR output folder (ms5). |
| `outputFormat` | indoor-outdoor-vehicle. |
| `time_format` | Correct [date and time format](https://sparkbyexamples.com/r-programming/dates-and-times-in-r/). |
| `tz` | Timezone in which experiments took place ([TZ identifier list](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)). |
| `AccThresholds` | Acceleration thresholds corresponding to the intensity levels. |
| `maxBreakLengthSeconds` | Maximum trip break duration in seconds. |
| `minTripDist_m` | Minimum trip distance in meters. |
| `minTripDur` | Minimum trip duration seconds. |
| `threshold_snr` | Threshold for SNR. |
| `threshold_snr_ratio` | Threshold for SNR ratio. |

#### Example

``` 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)!,
hbGPS(idloc = 2,
gps_file = "C:/path_to_input_file/or/folder",
outputDir = "C:/path_to_output_folder",
GGIRpath = "C:/path_to_GGIR_output_folder/meta/ms5.outraw", # (4)!,
outputFormat = "PALMS",
time_format = "%Y/%m/%d %H:%M:%S",
tz = "Europe/Copenhagen",
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)
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).

``` 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 = 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",
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 = "Europe/Copenhagen",
time_format = "%Y/%m/%d %H:%M:%S",
idloc = 2,
maxBreakLengthSeconds = 120,
minTripDur = 60,
minTripDist_m = 100,
threshold_snr = 225,
threshold_snr_ratio = 50)
```
5. Instead of specifying a thresholds for the accelerometer, you can use the *"default"* option.

## License

Expand Down
45 changes: 44 additions & 1 deletion docs/gui/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,4 +3,47 @@ hide:
- navigation
---

TO-DO...
HabitusGUI simplifies movement behaviour data analysis by combining GGIR, hbGPS, and hbGIS in a user-friendly interface with several analysis options that perform the following:

1. Processing multi-day RAW accelerometer data for physical activity and sleep research (via [GGIR](https://cran.r-project.org/web/packages/GGIR/) package).
2. Analyzing spatiotemporal behaviour patterns using geospatial data (via [hbGPS](/gps), [hbGIS](/gis)).


## Installation

The [R language](https://cran.r-project.org/) must be installed as a prerequisite. We highly recommend using [RStudio](https://posit.co/downloads/), an IDE that simplifies working with R. The next step is to install the required R packages.

``` r
install.packages("remotes") # (1)!
remotes::install_github("habitus-eu/HabitusGUI", dependencies=TRUE) # (2)!
```

1. R package for installation from remote repositories (Github).
2. Installing the Habitus GUI package with all dependencies from the GitHub repository.

## Usage

In order to launch the HabitusGUI application, the user needs to execute the following lines of code:

``` r
library(HabitusGUI)

options("sp_evolution_status" = 2) # (1)!
HabitusGUI::myApp(homedir="C:/path_to_project/folder") # (2)!
```

1. Ignore evolution warnings.
2. A directory that contains all necessary data in its root or subdirectories.

Upon launching the HabitusGUI application, the user will be prompted to select the data sets they want to analyze. The user has the option to choose one or multiple input data sets.

Once the user selects the desired analyses, a help menu appears on the screen. Depending on the selected analysis, the menu recommends suitable packages that are required for the analysis. The user can then modify the packages per the recommendations before proceeding with the analysis.

In the following steps, the user must upload the required files, which may include datasets and [configuration files]() depending on the chosen analysis. Additionally, the user may be required to name the dataset.

## Configuration files
Examples of configuration files to download include:

1. GGIR (data in [RAW format](#) or in [counts](#))
2. [hbGPS](#)
3. [hbGIS](#)

0 comments on commit c039654

Please sign in to comment.