Merge pull request #23 from tscnlab/dev_general

Dev general

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: LightLogR
 Title: Work With Data from Wearable Light Loggers and Optical Radiation Dosimeters
-Version: 0.3.6
+Version: 0.3.7
 Authors@R: c(
     person("Johannes", "Zauner", 
       email = "[email protected]", role = c("aut", "cre"),

NEWS.md

@@ -1,4 +1,10 @@
-# LightLogR 0.3.6
+# LightLogR 0.3.7 "Astronomical dawn"
+
+* Changes to the tutorial articles on the website
+
+* Integration of a community survey on the website and Github Readme.
+
+# LightLogR 0.3.6 
 
 * `bright_dark_period()` now maintains the date when looping the data.
 

README.Rmd

@@ -30,25 +30,27 @@ Personalized luminous exposure data is progressively gaining importance in vario
 
 -   Generation of data and metadata files
 
--   Conversion of popular file formats
+-   Conversion of common file formats
 
 -   Validation of light logging data
 
 -   Verification of crucial metadata
 
--   Calculation of common parameters
+-   Calculation of common analysis parameters
 
 -   Semi-automated analysis and visualization (both command-line and GUI-based)
 
 -   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:johannes.zauner@tum.de)
+##### Please note that LightLogR is work in progress! If you are interested in the project and want to know more, you can subscribe to the [LightLogR mailing list](https://lists.lrz.de/mailman/listinfo/lightlogr-users). If you find a bug, please open an issue on the [GitHub repository](https://github.com/tscnlab/LightLogR/issues).
 
-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.
+##### To maximaze LightLogRs utility, we want to hear from you! What features would you like to see, what are common issues you face when working with wearable data, and what kind of analysis are you performing? Let us now in the [LightLogR community survey](https://lists.lrz.de/mailman/listinfo/lightlogr-users)!
+
+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, import data, visualization, and metric calculation.
 
 ## 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).
+**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 Neuroscience Unit (MPS/TUM/TUMCREATE)*](https://www.tscnlab.org), a joint group based at the [Technical University of Munich](https://www.tum.de/en/), [TUMCREATE](https://www.tum-create.edu.sg/), 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.
 

README.md

@@ -50,21 +50,27 @@ package aims to provide tools for:
 
 - 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 send us an [email ([email protected])](mailto:[email protected])!
+##### Please note that LightLogR is work in progress! If you are interested in the project and want to know more, you can subscribe to the [LightLogR mailing list](https://lists.lrz.de/mailman/listinfo/lightlogr-users). If you find a bug, please open an issue on the [GitHub repository](https://github.com/tscnlab/LightLogR/issues).
+
+##### To maximaze LightLogRs utility, we want to hear from you! What features would you like to see, what are common issues you face when working with wearable data, and what kind of analysis are you performing? Let us now in the [LightLogR community survey](https://lists.lrz.de/mailman/listinfo/lightlogr-users)!
 
 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.
+generate images such as the one above, import data, visualization, and
+metric calculation.
 
 ## About the creation and funding of LightLogR
 
 **LightLogR** is developed by the [*Translational Sensory & Circadian
-Neuroscience Unit (MPS/TUM/TUMCREATE)*](https://www.tscnlab.org), a joint group based at the
-[Technical University of Munich](https://www.tum.de/en/), [TUMCREATE](https://www.tum-create.edu.sg/),
-the [Max Planck Institute for Biological
-Cybernetics](https://www.mpg.de/152075/biological-cybernetics).
+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 Neuroscience Unit
+(MPS/TUM/TUMCREATE)\*](https://www.tscnlab.org), a joint group based at
+the [Technical University of Munich](https://www.tum.de/en/),
+[TUMCREATE](https://www.tum-create.edu.sg/), 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

inst/CITATION

@@ -12,6 +12,6 @@ bibentry(
   url      = "https://github.com/tscnlab/LightLogR",
   doi      = "10.5281/zenodo.11562600",
   textVersion = paste(
-  "Zauner, J.; Hartmeyer, S.L.; Spitschan, M. (2023): LightLogR: Working With Wearable Light Logger Data. R Package, Available on https://github.com/tscnlab/LightLogR, doi:10.5281/zenodo.11562600"
+  "Zauner, J.; Hartmeyer, S.L.; Spitschan, M. (2023): LightLogR: Working With Wearable Light Logger Data. R Package, Available on https://github.com/tscnlab/LightLogR, doi:10.5281/zenodo.11562600, RRID:SCR_025408"
   )
 )

vignettes/articles/Import.Rmd

@@ -19,7 +19,7 @@ library(gghighlight)
 
 # Importing Data
 
-The first step in every analysis is data import. We will work with data collected as part the Master Thesis *Insights into real-world human light exposure: relating self-report with eye-level light logging* by Carolina Guidolin (2023). The data is stored in 17 text files in the *data/* folder. You can access the data yourself through the [LightLogR GitHub repository](https://github.com/tscnlab/LightLogR/tree/main/vignettes/articles/data).
+The first step in every analysis is data import. We will work with data collected as part of the Master Thesis *Insights into real-world human light exposure: relating self-report with eye-level light logging* by Carolina Guidolin (2023). The data is stored in 17 text files in the *data/* folder. You can access the data yourself through the [LightLogR GitHub repository](https://github.com/tscnlab/LightLogR/tree/main/vignettes/articles/data).
 
 ```{r, files}
 path <- "data"
@@ -65,7 +65,7 @@ data <-
                   auto.plot = FALSE, silent = TRUE)
 ```
 
-The second problem requires the filtering of certain Ids. The `filter_Datetime_multiple()` function is ideal for this. We can provide a length (1 week), starting from the end of data collection and backwards. The variable `arguments provide variable arguments to the filter function, they have to be provided in list form and expressions have to be quoted through`quote()`. Fixed arguments, like the length and`length_from_start\` are provided as named arguments and only have to be specified once, as they are the same for all Ids.
+The second problem requires the filtering of certain Ids. The `filter_Datetime_multiple()` function is ideal for this. We can provide a length (1 week), starting from the end of data collection and backwards. The variable `arguments` provide variable arguments to the filter function, they have to be provided in list form and expressions have to be quoted through`quote()`. Fixed arguments, like the length and`length_from_start\` are provided as named arguments and only have to be specified once, as they are the same for all Ids.
 
 ```{r, start shift}
 data <- 

vignettes/articles/Metrics.Rmd

@@ -36,7 +36,7 @@ data %>% gg_overview()
 
 There are a lot of metrics associated with personal light exposure. You can find the function reference to all of them in the appropriate [reference section](https://tscnlab.github.io/LightLogR/reference/index.html#metrics). There are a few important distinctions between metrics that are important to understand:
 
-* Some metrics require or work best with a specific time frame, usually one day, while others are calculated over an arbitrary length of time. For example, the function `interdaily_stability()` calculates a metric over multiple days, while a function like `midpointCE()` calculates the midpoint of the cumulative light exposure within the given time series - this is less useful for multiple days, where the midpoint is just a time point during these days. E.g., for two similar light exposure patterns across two days, the cumulative light exposure across those two days will be around midnight, which is not particularly informative. Much more sensible is the midpoint of the light exposure for each day. To enable this, data has to be grouped within days (or other relevant time frames, like sleep/wake-phase).
+* Some metrics require or work best with a specific time frame, usually one day, while others are calculated over an arbitrary length of time. For example, the function `interdaily_stability()` calculates a metric over multiple days, while a function like `midpointCE()` calculates the midpoint of the cumulative light exposure within the given time series - this is less useful for multiple days, where the midpoint is just a time point during these days. E.g., for two similar light exposure patterns across two days, the midpoint of cumulative light exposure across those two days will be around midnight, which is not particularly informative. Much more sensible is the midpoint of the light exposure for each day. To enable this, data has to be grouped within days (or other relevant time frames, like sleep/wake-phase).
 
 * Some metrics are submetrics within a family and have to be actively chosen through the arguments of the function. An example is `duration_above_threshold()` that, despite its name also provides the metrics `duration below threshold` and `duration within threshold`. Depending on its `comparison` argument, and whether one or two `threshold`s are provided, the function will calculate different metrics.
 
@@ -46,7 +46,7 @@ We will cover the practical considerations following from these aspects in the f
 
 # Metric calculation: basics
 
-All metric functions are by default agnostic to the type of data. They require vectors of light data and commonly also of datetimes. This means that the functions can be used outside of the LightLogR framework, if applied correctly. Let us try this with a simple example for a days worth of light data for one participant across two functions.
+All metric functions are by default agnostic to the type of data. They require vectors of numeric data (e.g., light data) and commonly also of datetimes. This means that the functions can be used outside of the LightLogR framework, if applied correctly. Let us try this with a simple example for a days worth of light data for one participant across two functions.
 
 ```{r, Id 201}
 data_Id201 <- data %>% filter(Id == 201 & date(Datetime) == "2023-08-15")
@@ -219,7 +219,7 @@ TAT_250 %>% head(12) %>% gt()
 
 ## Metric statistics
 
-With the dataframe `TAT_250`, we can easily calculate statistics for each participant. This can be done manually, e.g., with another call to `dplyr::summarize()`, or semi-automatic, e.g., with packages like `gtsummary`. In the following example, we will calculate the mean and standard deviation of the TAT 250 lx MEDI for each participant, formatted as `HH:SS` through a styling function.
+With the dataframe `TAT_250`, we can easily calculate statistics for each participant. This can be done manually, e.g., with another call to `dplyr::summarize()`, or semi-automatic, e.g., with packages like `gtsummary`. In the following example, we will calculate the mean and standard deviation of the TAT 250 lx MEDI for each participant, formatted as `HH:MM` through a styling function.
 
 ```{r}
 #styling formula for time
@@ -238,7 +238,7 @@ TAT_250 %>%
 
 # Metric calculation: batch
 
-In the final section, we will add more metrics to the analysis, including ones with multiple submetrics. Further, the let us imagine we wand to know how these metrics change from the first half of the experiment (August/September) to the second half (October/November). Finally, we will include a column `Time.data` to the data set, which will be used to calculate the metrics. This avoids 
+In the final section, we will add more metrics to the analysis, including ones with multiple sub-metrics. Further, we imagine we want to know how these metrics change from the first half of the experiment (August/September) to the second half (October/November). Finally, we will include a column `Time.data` in the data set, which will be used to calculate the metrics. This column format excludes the `day` information from the `Datetime` column, which avoids `date`-related issues when calculating the `mean` of the metrics. Finally, the `unnest()` call is used to flatten the table from the `dataframe` substructure that is created by `MLIT250` and `TAT250`.
 
 ```{r}
 data <- data %>% 
@@ -269,7 +269,7 @@ metrics %>% head() %>% gt()
 
 ```
 
-The operation above yields a dataframe with 6 metrics across 102 participant days (6 days for 17 participants). The grouping for `Month` did not add additional groups, as each participant day is already solely either in the `"Aug/Sep"` or `"Oct/Nov"` group. Next we will regroup the data by `Month` and look at a summary table similar to above, but for more metrics.
+The operation above yields a data frame with six metrics across 102 participant days (6 days for 17 participants). The grouping for `Month` did not add additional groups, as each participant day is already solely in the `"Aug/Sep"` or `"Oct/Nov"` group. Next, we will regroup the data by `Month` and look at a summary table similar to the above, but for more metrics.
 
 ```{r}
 metrics <- metrics %>% group_by(Month) %>% select(-Id, -wDay)
@@ -297,4 +297,4 @@ metrics %>%
               )
 ```
 
-And that is all you need to work with metrics in `LightLogR`. Be sure to look at the documentation for each function to understand the parameters and outputs, and at the [reference section](https://tscnlab.github.io/LightLogR/reference/index.html#metrics) to get an overview of all available metrics.
+And that is all you need to work with metrics in `LightLogR`. Be sure to look at the documentation for each function to understand the parameters and outputs and at the [reference section](https://tscnlab.github.io/LightLogR/reference/index.html#metrics) to get an overview of all available metrics.

vignettes/articles/Visualizations.Rmd

@@ -54,7 +54,7 @@ data %>%
 # gg_day()
 
 ## Basics
-`gg_day()` compares days within a dataset. By default it will use the `date`. Let`s call it on a subset of our data. To distinguish between different Ids, we can set the `aes_col` argument to `Id`.
+`gg_day()` compares days within a dataset. By default it will use the `date`. Let's call it on a subset of our data. To distinguish between different Ids, we can set the `aes_col` argument to `Id`.
 
 ```{r, fig.width=7, fig.height = 10}
 data %>%