---
title: "wrictools"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{wrictools}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
```
```{r setup}
library(wrictools)
```
Welcome!
This document serves as a guided tutorial to help you get started using the WRIC_preprocessing package.
**Click here if this is your first time programming in R**
If this is your first time programming in R please make sure you have the following installed:
- **R**: The programming language we’ll be using for data analysis and visualization.
- **A Programming Environment (RStudio)**: I recommend using RStudio, but feel free to use a different IDE.
- **[Install R](https://cran.r-project.org/mirrors.html)**
- **[Install RStudio](https://posit.co/download/rstudio-desktop)**
## FAQ and "Programming Terms"
### What is the difference between R and RStudio?
**R** is a programming language, while **RStudio** is a, so called, integrated development environment (IDE) designed specifically for R, offering a user-friendly interface for coding, plotting, and managing projects. You can think of R like a language, like English, where RStudio is Word - a program you can write English inside. But you could also use other programs for example LibreOffice or LaTeX.
### R vs Rmd
There are different types of files where you can write R code. A file ending in **.R** is a standard R script for writing and running R code, while in **.Rmd (R Markdown)** you can combine code and text for dynamic reports, or for example this tutorial/vignette.
# Getting Started
We are in the process of submitting `wrictools` to CRAN, so for now you can install the current wrictools **development** version via GitHub:
```{r eval = FALSE}
library(remotes)
install_github("NinaZiegenbein/wrictools")
```
Once the package is on CRAN you can install the `wrictools` package from CRAN as normal:
```{r eval = FALSE}
install.packages("wrictools")
```
Once installed, load the package:
```{r}
library(wrictools)
```
## Preprocess WRIC data
Now let's preprocess the txt files, that are created by the WRIC (Omnical Software from Maastricht Instruments). The function `preprocess_wric_file()` disentangles the meta-data at the top of the file (ID, comment etc) and creates DataFrames and csv-files with the actual data, separated between both rooms and summarized between the two measurements for each room. This works both for files created using the "old" software version 1.x that returned multiple rooms in one file, as well as files created using the current software version 2.x.
```{r}
data_txt <- system.file("extdata", "data.txt", package = "wrictools") # loading example data
result <- preprocess_wric_file(data_txt)
r1_metadata <- result$metadata$r1
r2_metadata <- result$metadata$r2
df_room1 <- result$dfs$room1
df_room2 <- result$dfs$room2
```
The function returns a named list with the elements `metadata` and `df`.
For software version 1, `metadata` contains `r1` and `r2`, and `df` contains `room1` and `room2`.
For version 2, `metadata` and `df` each contain a single data frame `metadata`and `data`.
If ´save_csv` is True, then the data.frames will be saved as csv files with "id_comment_WRIC_data.csv" or "id_comment_WRIC_metadata.csv".
The example above uses data generated by software version 1, which is why it returns metadata and data.frames for both room 1 and room 2.
Let's look at the output really quick for room 1:
```{r}
head(r1_metadata)
head(df_room1)
```
Let's see what the output would look like for data from software version 2:
```{r}
data_v2_txt <- system.file("extdata", "data_v2.txt", package = "wrictools") # loading example data
result <- preprocess_wric_file(data_v2_txt)
# For version 2 we only have data from one of the rooms, so only one metadata and one wric-data data.frame
metadata <- result$metadata$metadata
df<- result$dfs$data
# Let's look at the first rows (head) of the data.frame
head(df)
```
But the `preprocess_wric_file` function can do a lot more and has a lot of extra parameters you can specify. The following is the exact same function call, but mentioning all optional parameters you can call with their default values. Default means, that if you do not specify this parameter, this is the value that the parameter has by default.
```{r}
result <- preprocess_wric_file(
filepath = data_txt,
code = "id",
manual = NULL,
save_csv = FALSE,
path_to_save = NULL,
combine = TRUE,
method = "mean",
start = NULL,
end = NULL,
notefilepath = NULL,
keywords_dict = NULL,
entry_exit_dict = NULL
)
```
Here are explanations and options to all parameters you can specify:
- **filepath:** [String, filepath] Directory path to the WRIC .txt file.
- **code** [String] Method for generating subject IDs. Default is "id", also possible to specify "id+comment", where both ID and comment values are combined or "manual", where you can specify your own.
- **manual** [String] Custom codes for subjects in Room 1 and Room 2 if `code` is "manual".
- **save_csv** [Logical], whether to save extracted metadata and data to CSV files or not. Default is True
- **path_to_save** [String] Directory path for saving CSV files, NULL uses the current directory, NULL is Deafult.
- **combine** [Logical], whether to combine S1 and S2 measurements. Default is True
- **method** [String] Method for combining measurements ("mean", "median", "s1", "s2", "min", "max").
- **start** [character or POSIXct or NULL], rows before this will be removed, if NULL takes first row e.g "2023-11-13 11:43:00"
- **end** [character or POSIXct or NULL], rows after this will be removed, if NULL takes last rows e.g "2023-11-13 11:43:00"
- **notefilepath:**
If you specify a path to the corresponding notefile, the code will try to automatically extract the datetime and current protocol specification (sleeping, exercising, eating etc). If possible please read the [How To Note File]https://github.com/hulmanlab/wrictools/blob/main/HowToNoteFile.pdf), before you start your study for consistent note taking. If there is a TimeStamp in the note e.g "Participants starts eating at 16:10", the time of the creation of the note will be overwritten with the time specified in the free-text of the note. The "protocol" is extracted by keyword search. You can check currently included keywords and extend them by checking the keywords_dict in the extract_note_info() function of the preprocessing.R file.
- **keywords_dict:** [Nested List] A "dictionary" with keywords for extracting protocol information out of the notefile.
To explore the available functionality and arguments for key functions, simply call:
```{r}
?preprocess_wric_file
```
### Your Turn
So now it is your turn. Using the `preprocess_wric_file()` method create a csv file using "data.txt" in folder example_data.
1) create a csv with the name "XXXX_WRIC_data.csv" combining S1 and S2 measurements by taking the mean between them.
2) create a csv, but cut-off the start to 22:45 on 13/11/2023 and the end to 23:45 on the same day. The csv should be saved as "testing_start_end_parameter_WRIC_data.csv".
3) _Optional:_ Try out the `notefilepath` parameter and see what happens.
## Automatic note file extraction - adaptation to your notes
One helpful feature of the `preprocess_wric_file()` method is to automatically extract the protocol from the note_file, that is filled in manually during the experiment. With "protocol" I mean coding whether the participant is currently sleeping, eating, exercising etc. This enables quick processing and easy access to extract and compare various e.g. eating periods. Let's try it:
```{r}
note_txt <- system.file("extdata", "note.txt", package = "wrictools") # loading example data
result <- preprocess_wric_file(data_txt,
notefilepath=note_txt)
head(result$dfs$room1)
```
When looking at `room1` now, we can see a new column called "protocol". We can see the file starts with 0 and at 22:41:21 changes to 1.
### Your Turn
1) Look into the `note.txt` file and find out why there is a change at 22:41:21 and what 0 and 1 might represent. Are there more numbers? What do they represent?
2) When comparing with previous results, notice that the file now starts at a later time and stops at an earlier one. Why might that be?
_Attention:_Since we keep reusing variable names (result, room1 etc) and use the same data.txt file to create csv_files, we overwrite those files and variables. That is completely fine for this tutorial, where we are focused on how to use it and not the results. But be careful in your own work!
## A bit more information about extracting data from the notefile
When specifying a notefilepath, the function will
1) Check whether there is a time in the first row. If there is, this will be used to calculate the drift of the system. This drift will be added to all further datetimes you specify within the notefile.
2) Check whether there is information about the participant entering or exiting the chamber. If yes, the data is cut to only include times in which the participant is in the chamber.
**What are the keywords for entering/exiting?**
start = c("enter", "entry", "ind i kammer", "ind")
This is only checked in the first three rows. Reasoning behind it, is that the first shows the time drift and then there might be two rows - one for each participant - detailing their entry into the chamber.
end = c("ud", "exit", "out")
This is only checked for the two last rows.
This package was developed in Denmark, which is why it includes danish signal words. If your notefile is in another language besides English or Danish you can specify your own keywords (or simply replace all with the english words):
```{r}
# Example how to specify your own keywords in German
entry_exit_dict <- list(
end = c("aus", "raus", "Ausgang", "Ende"),
start = c("rein", "in der Kammer", "innen", "hinein")
)
preprocess_wric_file(data_txt, entry_exit_dict = entry_exit_dict)
```