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.
LightLogR is a package under development as part of the MeLiDos project to address these issues. The package aims to provide tools for:
Generation of data and metadata files
Conversion of common file formats
Validation of light logging data
Verification of crucial metadata
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
Have a look at the Example section down below to get started, or dive into the Articles 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.
LightLogR is developed by the Translational Sensory & Circadian Neuroscience lab, a joint group from the Technical University of Munich and the Max Planck Institute for Biological Neuroscience Unit (MPS/TUM/TUMCREATE)*, a joint group based at the Technical University of Munich, TUMCREATE, the Max Planck Institute for Biological Cybernetics.
MeLiDos is a joint, EURAMET-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.
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.
You can install LightLogR from CRAN with:
install.packages("LightLogR")You can install the latest development version of LightLogR from GitHub with:
# install.packages("devtools")
devtools::install_github("tscnlab/LightLogR")Here is a quick starter on how do use LightLogR.
library(LightLogR)
#these packages are needed for the examples as shown below.
library(flextable)
library(dplyr)
library(ggplot2)You can import a light logger dataset with ease. The import functions give quick, helpful feedback about the dataset.
filename <- system.file("extdata/sample_data_LYS.csv", package = "LightLogR")
dataset <- import$LYS(filename, tz = "Europe/Berlin")
#>
#> Successfully read in 11'422 observations across 1 Ids from 1 LYS-file(s).
#> Timezone set is Europe/Berlin.
#>
#> First Observation: 2023-06-21 02:00:12
#> Last Observation: 2023-06-23 01:59:48
#> Timespan: 2 days
#>
#> Observation intervals:
#> Id interval.time n pct
#> 1 sample_data_LYS 15s 10015 87.689%
#> 2 sample_data_LYS 16s 1367 11.969%
#> 3 sample_data_LYS 17s 23 0.201%
#> 4 sample_data_LYS 18s 16 0.140%
dataset %>% ungroup() %>% select(Datetime, lux, kelvin, MEDI) %>%
slice(8000:8005) %>% flextable() %>% autofit()
.
For more complex data, there is the useful gg_overview()
function to get an immediate grasp of your data. It was automatically
called during import (set auto.plot = FALSE to suppress
this), but really shines for datasets with multiple participants. It
also indicates where data is missing, based on the measurement epochs
found in the data.
LLdata %>% gg_overview()
Once imported, LightLogR allows you conveniently visualize the data.
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.
dataset %>%
gg_day(aes_col = MEDI < 250, size = 0.75) +
theme(legend.position = "bottom")
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 Id column of the dataset allows for a
color separation.
sample.data.environment %>%
gg_day(
start.date = "2023-08-18",
aes_col = Id,
scales = "fixed",
geom = "line") + theme(legend.position = "bottom")
#> Only Dates will be used from start.date and end.date input. If you also want to set Datetimes or Times, consider using the `filter_Datetime()` function instead.
If you want to 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.
sample.data.environment %>%
gg_days(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 base::interaction() function can
easily combine them. The default interval for
cut_Datetime() is 3 hours.
sample.data.environment %>%
cut_Datetime() %>%
gg_day(
end.date = "2023-08-15",
aes_col = Id,
scales = "fixed",
geom = "boxplot",
group = interaction(Id, Datetime.rounded)) +
theme(legend.position = "bottom")
#> Only Dates will be used from start.date and end.date input. If you also want to set Datetimes or Times, consider using the `filter_Datetime()` function instead.
LightLogR provides a range of functions to get insight into your light logger data. Most importantly, you can search for and eliminate implicit gaps.
dataset %>% gap_finder()
#> Found 10758 gaps. 761 Datetimes fall into the regular sequence.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().
dataset %>% ungroup() %>% count_difftime()
#> # A tibble: 4 × 2
#> difftime n
#> <Duration> <int>
#> 1 15s 10015
#> 2 16s 1367
#> 3 17s 23
#> 4 18s 16We can eliminate this through the 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().
dataset %>% gap_handler() %>% gap_finder(epoch = "15 sec")
#> No gaps foundIf 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.
dataset %>% aggregate_Datetime(unit = "15 sec") %>% gap_finder()
#> Found 97 gaps. 11422 Datetimes fall into the regular sequence.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".