<!-- README.md is generated from README.Rmd. Please edit that file -->

LightLogR <img src="man/figures/logo.png" align="right" height="139"/>

<!-- badges: start -->

<!-- [](https://app.codecov.io/gh/tscnlab/LightLogR) -->

<!-- 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.

<div style="text-align:center"> <figure> <img src="man/figures/Day.png" style="width:90.0%" alt="Light logger data can powerfully convey insights into personal light exposure" /> <figcaption aria-hidden="true">Light logger data can powerfully convey insights into personal light exposure</figcaption> </figure> </div>

LightLogR is a package under development as part of the MeLiDos project to address these issues. The package aims to provide tools for:

• Import from common measurement devices (see below for a list of Supported devices)

• Cleaning and processing of light logging data

• Visualization of light exposure data, both exploratory and publication ready

• Calculation of common analysis parameters (see below for a list of Metrics)

To come:

• Import, creation, and verification of crucial metadata

• 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, you can subscribe to the LightLogR mailing list. If you find a bug or would like to see new or improved features, please open an issue on the GitHub repository.

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.

Installation

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")

Example

Here is a quick starter on how to use LightLogR.

library(LightLogR)
#the following packages are needed for the examples as shown below.
library(flextable)
library(dplyr)
library(ggplot2)

Import

You can import a light logger dataset with ease. The import functions give quick, helpful feedback about the dataset.

filename <- 
  system.file("extdata/205_actlumus_Log_1020_20230904101707532.txt.zip", 
              package = "LightLogR")
dataset <- import$ActLumus(filename, "Europe/Berlin", manual.id = "P1")
#> Multiple files in zip: reading '205_actlumus_Log_1020_20230904101707532.txt'
#> 
#> Successfully read in 61'016 observations across 1 Ids from 1 ActLumus-file(s).
#> Timezone set is Europe/Berlin.
#> 
#> First Observation: 2023-08-28 08:47:54
#> Last Observation: 2023-09-04 10:17:04
#> Timespan: 7.1 days
#> 
#> Observation intervals: 
#>   Id    interval.time     n pct  
#> 1 P1    10s           61015 100%

<img src="man/figures/README-unnamed-chunk-3-1.png" width="60%" style="display: block; margin: auto;" />

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.

<div style="text-align:center"> <figure> <img src="man/figures/gg_overview2.png" style="width:60.0%" alt="Example for gg_overview() from a large data collection effort over many months" /> <figcaption aria-hidden="true">Example for <code>gg_overview()</code> from a large data collection effort over many months</figcaption> </figure> </div>

note: the above example image requires a large dataset, not included in the package. It is available, however, in the article on Import & cleaning.

#example code, on how to use gg_overview():
dataset %>% gg_overview()

Visualize

Once imported, LightLogR has many convenient visualization options.

dataset %>% gg_days()

<img src="man/figures/README-unnamed-chunk-4-1.png" width="100%" />

There is a wide range of options to the gg_days() function to customize the output. Have a look at the reference page (?gg_days) to see all options. You can also override most of the defaults, e.g., for different color, facetting, theme options. Helper functions can prepare the data (e.g. to aggregate it to coarser intervals), or to add to the plot (e.g., to add conditions, such as nighttime)

dataset |> 
  #change the interval from 10 seconds to 15 minutes:
  aggregate_Datetime("15 min") |> 
  #create groups of 3-hour intervals:
  cut_Datetime("3 hours") |> 
  #plot creation, with a boxplot:
  gg_days(geom = "boxplot", group = Datetime.rounded) |> 
  #adding nighttime indicators:
  gg_photoperiod(c(47.9,9)) + 
  # the output is a standard ggplot, and can be manipulated that way
  geom_line(col = "red", linewidth = 0.25) + 
  labs(title = "Personal light exposure across a week", 
       subtitle = "Boxplot in 3-hour bins")

<img src="man/figures/README-unnamed-chunk-5-1.png" width="100%" />

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 Id column of the dataset allows for a color separation.

sample.data.environment %>% 
  gg_day(
    start.date = "2023-09-01",
    aes_col = Id,
    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.

<img src="man/figures/README-unnamed-chunk-6-1.png" width="70%" style="display: block; margin: auto;" /> `gg_day()` will show plots always facetted by day, whereas `gg_days()` shows a timeline of days for each group. Both functions are opinionated in terms of the scaling and linebreaks to only show whole days, all of which can be adjusted.

There are many ways to enhance the plots - if, e.g., we look for periods of at least 1 hour above 250 lx, we can add and then visualize these periods easily

sample.data.environment %>% 
  #search for these conditions:
  add_clusters(MEDI > 250, cluster.duration = "30 min") |> 
  #base plot + add the condition
  gg_days() |> 
  gg_states(state, fill = "red") + 
  #standard ggplot:
  geom_hline(yintercept = 250, col = "red", linetype = "dashed") + 
  labs(title = "Periods > 250 lx mel EDI for more than 30 minutes")

<img src="man/figures/README-unnamed-chunk-7-1.png" width="100%" />

There are more visualizations to try - the article on Visualizations dives into them in-depths.

sample.data.environment |> gg_heatmap(doubleplot = "next")

<img src="man/figures/README-unnamed-chunk-8-1.png" width="100%" />

Metrics

There are many Metrics used in literature for condensing personalized light exposure time series to singular values. LightLogR has a rather comprehensive number of these metrics with a consistent, easy-to-use interface.

sample.data.environment |> # two groups: participant and environment
  filter_Date(length = "2 days") |> #filter to three days each for better overview
  group_by(Day = lubridate::date(Datetime), .add = TRUE) |>  #add grouping per day
  summarize(
    #time above 250 lx mel EDI:
    duration_above_threshold(MEDI, Datetime, threshold = 250, as.df = TRUE),
    #intradaily variability (IV):
    intradaily_variability(MEDI, Datetime, as.df = TRUE),
    #... as many more metrics as are desired
    .groups = "drop"
  )
#> # A tibble: 4 × 4
#>   Id          Day        duration_above_250    intradaily_variability
#>   <fct>       <date>     <Duration>                             <dbl>
#> 1 Environment 2023-08-29 48240s (~13.4 hours)                   0.248
#> 2 Environment 2023-08-30 49350s (~13.71 hour