Merge pull request #4 from tscnlab/clean_up

Small bug fixes, updates to documention, Description and Readme to re…
tscnlab · Nov 10, 2023 · 2d3645c · 2d3645c
2 parents 5d50323 + 41e87a3
commit 2d3645c
Show file tree

Hide file tree

Showing 23 changed files with 264 additions and 73 deletions.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -8,8 +8,8 @@ Authors@R: c(
     person("Manuel", "Spitschan", 
       email = "[email protected]", role = "aut",
       comment = c(ORCID = "0000-0002-8572-9268")),
-    person("MeLiDos", role = "fnd"),
-    person("EURAMET", role = "fnd"),
+    person("EURAMET", role = "fnd", comment = "European Association of National Metrology Institutes. Website: www.euramet.org. Grant Number: 22NRM05 MeLiDos. Grant Statement: The project (22NRM05 MeLiDos) has received funding from the European Partnership on Metrology, co-financed from the European Union’s Horizon Europe Research and Innovation Programme and by the Participating States."),    
+    person("European Union", role = "fnd", comment = "Co-funded by the European Union. Views and opinions expressed are however those of the author(s) only and do not necessarily reflect those of the European Union or EURAMET. Neither the European Union nor the granting authority can be held responsible for them."),
     person("TSCN-Lab", comment = c(URL = "www.tscnlab.org"), role = "cph"))
 Description: LightLogR is a package under development as part of the MeLiDos 
     project aimed at developing a standard workflow for wearable light logger 

diff --git a/R/filter_Datetime.R b/R/filter_Datetime.R
@@ -161,7 +161,7 @@ filter_Datetime <- function(dataset,
       dataset %>% 
       dplyr::filter(
         {{ Datetime.colname }} >= lubridate::as_datetime(start, tz = tz),
-        {{ Datetime.colname }} <= lubridate::as_datetime(end, tz = tz)
+        {{ Datetime.colname }} < lubridate::as_datetime(end, tz = tz),
         )
     #possible extra filter step
     if(!is.null(filter.expr)) {
@@ -220,6 +220,7 @@ filter_Date <- function(...,
 #'   to be quoted with [quote()] or [rlang::expr()].
 #' @param filter_function The function to be used for filtering, either
 #'   `filter_Datetime` (the default) or `filter_Date`
+#' @param ... Additional arguments passed to the filter function
 #'
 #' @return A dataframe with the filtered data
 #' @export
@@ -236,9 +237,10 @@ filter_Date <- function(...,
 #'  gg_overview(Id.colname = Source)
 filter_Datetime_multiple <- function(dataset, 
                                      arguments, 
-                                     filter_function = filter_Datetime) {
+                                     filter_function = filter_Datetime,
+                                     ...) {
 
   purrr::reduce(arguments, function(dataset, params) {
-    do.call({{ filter_function }}, c(list(dataset = dataset), params))
+    do.call({{ filter_function }}, c(list(dataset = dataset), params, ...))
   }, .init = dataset)
 }
diff --git a/R/gg_day.r b/R/gg_day.r
@@ -164,7 +164,8 @@ gg_day <- function(dataset,
   if(jco_color) {
     jco_color_scheme <- 
       list(
-        ggsci::scale_color_jco()
+        ggsci::scale_color_jco(),
+        ggsci::scale_fill_jco()
       )
   }
 

diff --git a/R/import_LL.R b/R/import_LL.R
@@ -155,7 +155,11 @@ imports <- function(device,
                    dplyr::mutate(!!ID.colname :=
                                    basename(file.name) %>%
                                    tools::file_path_sans_ext() %>%
-                                   stringr::str_extract(auto.id),
+                                   stringr::str_extract(
+                                     auto.id,
+                                     group =  
+                                       if(stringr::str_detect(auto.id, "\\(")) 1
+                                     ),
                                  .before = 1)},
                "FALSE" =
                  {tmp <- tmp %>%
@@ -238,7 +242,8 @@ import_arguments <- list(
             skip = rows_to_skip,
             locale=locale,
             id = "file.name",
-            show_col_types = FALSE
+            show_col_types = FALSE,
+            col_types = c("iDtfdfccccfdf")
             ),
             dots)))
 
@@ -255,11 +260,12 @@ import_arguments <- list(
       dplyr::mutate(
         Datetime = lubridate::ymd_hms(Datetime),
         dplyr::across(
-          dplyr::where(is.character) & 
+          dplyr::where(is.character) &
             dplyr::where(~ any(stringr::str_detect(.x, ","), na.rm = TRUE)),
-          ~ stringr::str_replace(.x, ",", ".") %>% 
+          ~ stringr::str_replace(.x, ",", ".") %>%
               as.numeric()
-        ))
+        )
+        )
   })
 
 )

diff --git a/R/import_helper.r b/R/import_helper.r
@@ -24,8 +24,8 @@ import.info <- function(tmp, device, tz, ID.colname) {
         "The system timezone is ",
         Sys.timezone(),
         ". Please correct if necessary!\n")},
-    "Start: ", format(tmp$Datetime[1]), "\n",
-    "End: ", format(max(tmp$Datetime)), "\n",
+    "Start: ", format(min.time), "\n",
+    "End: ", format(max.time), "\n",
     "Timespan: " , diff(c(min.time, max.time)) %>% format(digits = 2), "\n",
     "Observation intervals: \n",
     sep = "")

diff --git a/README.Rmd b/README.Rmd
@@ -21,12 +21,13 @@ knitr::opts_chunk$set(
 
 <!-- badges: end -->
 
-
 Personalized luminous exposure data is progressively gaining importance in various sectors, including research, occupational affairs, and fitness tracking. Data are collected through a proliferating selection of wearable loggers and dosimeters, varying in size, shape, functionality, and output format. Despite or maybe because of numerous use cases, the field lacks a unified framework for collecting, validating, and analyzing the accumulated data. This issue increases the time and expertise necessary to handle such data and also compromises the FAIRness (Findability, Accessibility, Interoperability, Reusability) of the results, especially in meta-analyses.
 
-##### Please note that LightLogR is work in progress! If you are interested in the project and want to know more, please give us a [message](mailto:[email protected])
+::: {style="text-align:center"}
+![Light logger data can powerfully convey insights into personal light exposure](man/figures/Day.png){width="90%"}
+:::
 
-**LightLogR** is a package under development as part of the [*MeLiDos*](https://www.melidos.eu) project to address these issues. MeLiDos is a joint, [EURAMET](https://www.euramet.org)-funded project involving sixteen partners across Europe, aimed at developing a metrology and a standard workflow for wearable light logger data and optical radiation dosimeters. Its primary contributions towards fostering FAIR data include the development of a common file format, robust metadata descriptors, and an accompanying open-source software ecosystem. **LightLogR** aims to provide tools for:
+**LightLogR** is a package under development as part of the [*MeLiDos*](https://www.melidos.eu) project to address these issues. The package aims to provide tools for:
 
 -   Generation of data and metadata files
 
@@ -42,8 +43,22 @@ Personalized luminous exposure data is progressively gaining importance in vario
 
 -   Integration of data into a unified database for cross-study analyses
 
+##### Please note that LightLogR is work in progress! If you are interested in the project and want to know more, please give us a [message](mailto:[email protected])
+
+Have a look at the **Example** section down below to get started, or dive into the [Articles](https://tscnlab.github.io/LightLogR/articles/index.html) to get more in depth information about how to work with the package and generate images such as the one above.
+
+## About the creation and funding of LightLogR
+
 **LightLogR** is developed by the [*Translational Sensory & Circadian Neuroscience*](https://www.tscnlab.org) lab, a joint group from the [Technical University of Munich](https://www.tum.de/en/) and the [Max Planck Institute for Biological Cybernetics](https://www.mpg.de/152075/biological-cybernetics).
 
+[*MeLiDos*](https://www.melidos.eu) is a joint, [EURAMET](https://www.euramet.org)-funded project involving sixteen partners across Europe, aimed at developing a metrology and a standard workflow for wearable light logger data and optical radiation dosimeters. Its primary contributions towards fostering FAIR data include the development of a common file format, robust metadata descriptors, and an accompanying open-source software ecosystem.
+
+![](man/figures/Co-Funded-By-the-EU.png){width="288"}
+
+[![](man/figures/Metrology_Partnership_LOGO.jpg){width="282"}](https://www.euramet.org)
+
+The project (22NRM05 MeLiDos) has received funding from the European Partnership on Metrology, co-financed from the European Union's Horizon Europe Research and Innovation Programme and by the Participating States. Views and opinions expressed are however those of the author(s) only and do not necessarily reflect those of the European Union or EURAMET. Neither the European Union nor the granting authority can be held responsible for them.
+
 ## Installation
 
 You can install the development version of LightLogR from [GitHub](https://github.com/) with:
@@ -65,50 +80,73 @@ library(dplyr)
 library(ggplot2)
 ```
 
-
 ### Import
+
 You can import a light logger dataset with ease. The import functions give quick, helpful feedback about the dataset.
 
 ```{r, out.width="50%", fig.align='center'}
 filename <- system.file("extdata/sample_data_LYS.csv", package = "LightLogR")
 dataset <- import$LYS(filename, tz = "Europe/Berlin")
 
-dataset %>% select(Datetime, lux, kelvin, MEDI) %>%  slice(8000:8005) %>% 
-  flextable() %>% autofit()
+dataset %>% ungroup() %>% select(Datetime, lux, kelvin, MEDI) %>%  
+  slice(8000:8005) %>% flextable() %>% autofit()
+```
+
+::: {style="color: white"}
+.
+:::
+
+For more complex data, there is the useful `gg_overview()` function to get an immediate grasp of your data. See it here in action for a dataset with multiple participants. It also indicates where data is missing, based on the measurement epochs found in the data.
+
+```         
+LLdata %>% gg_overview()
 ```
 
+::: {style="text-align:center"}
+![](man/figures/gg_overview2.png){width="50%"}
+:::
+
 ### Visualize
+
 Once imported, **LightLogR** allows you conveniently visualize the data.
 
-```{r, fig.retina=2}
-dataset %>% gg_overview()
+```{r, out.width= "50%", fig.align='center'}
 dataset %>% gg_day()
 ```
 
 There is a wide range of options to the `gg_day()` function to customize the output. Have a look at the reference page (`?gg_day`) to see all options. You can also override most of the defaults, e.g., for different `color`, `facetting`, `theme` options.
 
-```{r, fig.retina=2}
+```{r, out.width= "60%", fig.align='center'}
 dataset %>% 
-  gg_day(
-    aes_col = MEDI >= 250, scales = "fixed", size = 0.5) + 
-  scale_color_discrete(type = c("orange", "skyblue"))
+  gg_day(aes_col = MEDI < 250, size = 0.75) + 
+  theme(legend.position = "bottom")
 ```
 
 ### More than one dataset
 
 The built-in dataset `sample.data.environment` shows a combined dataset of light logger data and a second set of data - in this case unobstructed outdoor light measurements. Combined datasets can be easily visualized with `gg_day()`. The `col` parameter used on the `Source` column of the dataset allows for a color separation.
 
-```{r, fig.height= 6, fig.retina=2}
+```{r, out.width= "60%", fig.align='center', fig.height = 6}
 sample.data.environment %>% 
   gg_day(
     start.date = "2023-08-18",
     y.axis = `MELANOPIC EDI`,
     aes_col = Source,
     scales = "fixed",
-    geom = "line")
+    geom = "line") + theme(legend.position = "bottom")
 ```
+
+If you get a feeling for the data over the course of multiple days, the `gg_days()` function comes in handy. It works similar to `gg_day()`. It is also opinionated in terms of the scaling and linebreaks to only show whole days, all of which can be adjusted.
+
+```{r, fig.width = 10, warning=FALSE}
+sample.data.environment %>% group_by(Source) %>% 
+  gg_days(y.axis = `MELANOPIC EDI`, geom = "ribbon", alpha = 0.25, col = "black")
+```
+
+
 With the `cut_Datetime()` function, the data can further be broken up into arbitrary time intervals. This can be used to easily compare different datasets. Just put the function in between the dataset and `gg_day()`. This makes a new variable available for plotting: `Datetime.rounded`. Just make sure, that the `geom` parameter is set to *boxplot* and the `group` parameter uses both the info from the rounded time interval (`Datetime.rounded`) and the different datasets (`Source`). The `interaction` function can easily combine them. The default interval for `cut_Datetime()` is 3 hours.
-```{r, fig.retina=2}
+
+```{r, out.width= "60%", fig.align='center'}
 sample.data.environment %>% 
   cut_Datetime() %>% 
   gg_day(
@@ -121,3 +159,30 @@ sample.data.environment %>%
   theme(legend.position = "bottom")
 ```
 
+### Insights, Validation, and Processing
+
+**LightLogR** provides a range of functions to get insight into your light logger data. Most importantly, you can search for and eliminate implicit gaps.
+
+```{r}
+dataset %>% gap_finder()
+```
+
+The huge amount of gaps comes from the fact that the measurement intervals are somewhat irregular between 15 and 18 seconds in this case. This leaves very little intervals to start regularly. We got this information after import, but can still get to this info through `count.difftime()`.
+
+```{r}
+dataset %>% ungroup() %>% count.difftime()
+```
+
+We can eliminate this through teh `gap_handler()` function. This function will automatically fill in the gaps with NA values. As the most dominant interval in the dataset is now not 15 seconds anymore(because intermediate datapoints have been added), we need to specify the epoch for `gap_finder()`.
+
+```{r}
+dataset %>% gap_handler() %>% gap_finder(epoch = "15 sec")
+```
+
+If we want to force the data to be regular, we can use the `aggregate_Datetime()` function. This will aggregate the data to the specified epoch. There are sensible defaults on how to aggregate numeric, categorical, and logical data. You can also specify your own aggregation functions.
+
+```{r}
+dataset %>% aggregate_Datetime(unit = "15 sec") %>% gap_finder()
+```
+
+Now, very few gaps are left (every time the the lagged epochs lead to a completely skipped regular epoch). The function can also be used to conveniently change the interval to arbitrary values, e.g., `"5 mins"`, or `"1 hour"`.