example finished

habitus-eu · Aug 2, 2024 · 41b6457 · 41b6457
1 parent 2cc3100
commit 41b6457
Show file tree

Hide file tree

Showing 10 changed files with 66 additions and 19 deletions.
diff --git a/docs/assets/acl.zip b/docs/assets/acl.zip
diff --git a/docs/assets/gps.zip → docs/assets/example.zip b/docs/assets/gps.zip → docs/assets/example.zip
diff --git a/docs/assets/images/analyses.png b/docs/assets/images/analyses.png
diff --git a/docs/assets/images/configs.png b/docs/assets/images/configs.png
diff --git a/docs/assets/images/data_selection.png b/docs/assets/images/data_selection.png
diff --git a/docs/assets/images/data_selection_filled.png b/docs/assets/images/data_selection_filled.png
diff --git a/docs/assets/images/hbgis_summaries.png b/docs/assets/images/hbgis_summaries.png
diff --git a/docs/examples/spatiotemporal_behaviour_analysis.md b/docs/examples/spatiotemporal_behaviour_analysis.md
@@ -8,26 +8,21 @@ When we use the term "where," we refer to the summarized information that shows
 total wear and non-wear;
 total physical activity in intensity categories (light, moderate, vigorous);
 total sedentary behaviour.
-The researcher specifies these domains ("where's") as GIS (Geographic Information System) data information, including geometry polygons and paths for homes, neighbourhoods, schools, and other relevant locations. This means, for example, that we can obtain information about how much light activity a participant engages in at school, home, neighbourhood, or during transport. The {==[exported results](#)==} are always calculated as total values for each participant and their corresponding day.
+The researcher specifies these domains ("where's") as GIS (Geographic Information System) data information, including geometry polygons and paths for homes, neighbourhoods, schools, and other relevant locations. This means, for example, that we can obtain information about how much light activity a participant engages in at school, home, neighbourhood, or during transport. The exported results are always calculated as total values for each participant and their corresponding day.
 
 ## 2. Example data
 
 The example is derived from the data collected through the ActiGraph accelerometer and GPS sensors manufactured by Qstarz. The accelerometer data is available in CSV format and measured in counts metric, exported by Actilife software. Similarly, GPS data is available in CSV format and exported by Qstarz's official software.
 
-GIS data was prepared in QGIS and exported as shapefiles in the WGS84 CRS (Coordinate Reference System), the default format for GPS sensors. {==Additional information on how to prepare these files can be found below.==}
+GIS data was prepared in QGIS and exported as shapefiles in the WGS84 CRS (Coordinate Reference System), the default format for GPS sensors.
 
-The data provided are based on three participants who attend the same school but live in different neighbourhoods. Here are the links to download the sample data:
+The data provided are based on three participants who attend the same school but live in different neighbourhoods. Here is the link to download the [sample data](../assets/example.zip).
 
 *[different neighbourhoods]: Two of the participants actually have the same home address.
 
-- [Accelerometer (Actigraph, counts, CSV)](../assets/acl.zip)
-- [GPS (Qstarz, WSG84, CSV)](../assets/gps.zip)
-- {==[GIS (QGIS, shapely + additional files)](#)==}
-- [Linkage file (CSV)](../assets/linkage.csv)
-
 ## 3. Working directory
 
-After downloading the example files, we recommend unzipping them and organizing them into a directory structure as shown below ([Figure 1](#figure-1)). Configuration files in "configs" folder will be downloaded and added later. The "output" folder will contain processed files. Other files follow the structure of the example data.
+After downloading the example files and unzipping them, you are going to see a structure of directories as shown below ([Figure 1](#figure-1)). The "output" folder will contain processed files. Other files follow the structure of the example data.
 
 <figure markdown="span" id="figure-1">
   ![Directory structure](../assets/images/habitus_example_folder.svg){ width="500" }
@@ -67,4 +62,57 @@ HabitusGUI::myApp(homedir="C:/study")
   <figcaption><strong>Figure 2</strong> Selecting analysis type and required packages</figcaption>
 </figure>
 
-## 6. Data selection
+## 6. Data selection
+The next step is to choose the relevant data for analysis, providing and matching multiple directories and files (refer to [Figure 3](#figure-3)).
+
+#### Accelerometry and GPS data
+The first files to be mapped are self-explanatory: data from sensors (accelerometer and GPS).
+
+- Accelerometry - ActiGraph counts in CSV format.
+- GPS - Qstarz (CRS: WSG84) in CSV format.
+
+It's crucial to maintain consistency in file names. For example, a participant's accelerometry file should have the same name as their corresponding GPS file. Various methods exist for extracting IDs from files. For more details, refer to the [GGIR documentation](https://wadpac.github.io/GGIR/reference/GGIR.html).
+
+#### GIS data and linkage file
+Geometry files created with QGIS contain information about the locations of homes and schools, along with details about their neighbourhoods. These files must have a Coordinate Reference System (CRS) set and include information in the attribute table for matching participant IDs with the corresponding polygons. For each home and its neighbourhood, an attribute called "identifier" needs to be set for every polygon, and the same goes for schools (using the "school_id" attribute). After that, a linkage file matches participants' IDs with the corresponding polygons.
+
+#### Output and dataset name
+Finally, provide where the processed data should be saved and how to name the processed dataset.
+
+
+<figure markdown="span" id="figure-3">
+  ![Data selection](../assets/images/data_selection_filled.png){ width="500" }
+  <figcaption><strong>Figure 3</strong> Data selection</figcaption>
+</figure>
+
+## 7. Parameter configuration
+The next step involves parameter configuration, specifically loading configuration files for the following processes:
+
+1. GGIR – configuration for processing accelerometry data with GGIR.
+2. hbGPS – parameters for processing GPS data and then combining it with accelerometry data processed from GGIR. It is essential to provide the correct date and time format and timezone and specify parameters for trip identification.
+3. hbGIS – parameters and rules for GIS processing to obtain contextual information on participants' behaviour, focusing on "what" and "where".
+
+
+<figure markdown="span" id="figure-4">
+  ![Data selection](../assets/images/configs.png){ width="500" }
+  <figcaption><strong>Figure 4</strong> Parameter configuration</figcaption>
+</figure>
+
+## 8. Analyses
+Now is the time to perform the analysis. Execute each analysis in the specified order, and the results will be generated in the output file ([Figure 5](#figure-5)).
+
+<figure markdown="span" id="figure-5">
+  ![Data selection](../assets/images/analyses.png){ width="500" }
+  <figcaption><strong>Figure 5</strong> Analyses</figcaption>
+</figure>
+
+After the processing is completed without any errors, you will find the following directories and files in your output folder:
+
+- **output_acl** – This contains processed data by GGIR.
+- **hbGPSoutput** – Includes individual participant files and a combined file of all participants in a legacy PALMS format, combining accelerometry and GPS data with contextual information about trips.
+- **hbGIS_output** – Contains files processed by hbGIS with contextual information about locations – what, where ([Figure 6](#figure-6)).
+
+<figure markdown="span" id="figure-6">
+  ![Data selection](../assets/images/hbgis_summaries.png){ width="500" }
+  <figcaption><strong>Figure 6</strong> Proccessed (daily summaries)</figcaption>
+</figure>
diff --git a/docs/gis/index.md b/docs/gis/index.md
@@ -49,15 +49,15 @@ An example of a linkage file can be downloaded [here](../assets/linkage.csv).
 
 #### Configuration file
 
-TODO: Added some text.
+To use hbGIS, a configuration file must be provided. Further information on processing and the configuration file can be found [here](https://github.com/habitus-eu/hbGIS/blob/main/documentation.md).
 
 | Column             | Description                                                                                                                                       |
 | -------------------| ------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `context`          | palmplusr fields tables (TO-DO: List of contexts...)                                                                                              |
 | `name`             | User specified name of formula                                                                                                                    |
 | `formula`          | Formula (see more at [palmsplur](https://thets.github.io/palmsplusr/articles/article-3-building-formulas.html))                                   |
-| `is_where_field`   | {== TO-DO ==}                                                                                                                                           |
-| `after_conversion` | {== TO-DO ==}                                                                                                                                           |
+| `is_where_field`   |                                                                                                                                         |
+| `after_conversion` |                                                                                                                                          |
 
 An example of a configuration file can be downloaded [here](../assets/configs/config_hbGIS.csv).
 

diff --git a/docs/gui/index.md b/docs/gui/index.md
@@ -43,13 +43,12 @@ 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.
+Upon launching the HabitusGUI application, the user will be prompted to select the desired analyses ([Figure 1](#figure-1)). For more information on how to use HabitusGUI, please refer to the provided [example](../examples/spatiotemporal_behaviour_analysis.md).
 
-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.
-
-{== TO-DO: Pictures, finish information usage section. ==}
+<figure markdown="span" id="figure-1">
+  ![Selecting analysis type and required packages](../assets/images/selecting_analysis.png){ width="500" }
+  <figcaption><strong>Figure 1</strong> Selecting analysis type and required packages</figcaption>
+</figure>
 
 ## Configuration files