Adds a state column to a dataset from interval data

This function can make use of Interval data that contain States (like "sleep", "wake", "wear") and add a column to a light logger dataset, where the State of every Datetime is specified, based on the participant's Id.

Usage

interval2state(
  dataset,
  State.interval.dataset,
  Datetime.colname = Datetime,
  State.colname = State,
  Interval.colname = Interval,
  Id.colname.dataset = Id,
  Id.colname.interval = Id,
  overwrite = FALSE,
  output.dataset = TRUE
)

Arguments

dataset: A light logger dataset. Expects a dataframe. If not imported by LightLogR, take care to choose a sensible variable for the Datetime.colname.
State.interval.dataset: Name of the dataset that contains State and Interval columns. Interval data can be created, e.g., through sc2interval().
Datetime.colname: column name that contains the datetime. Defaults to "Datetime" which is automatically correct for data imported with LightLogR. Expects a symbol. Needs to be part of the dataset.
State.colname, Interval.colname: Column names of the State and Interval in the State.interval.dataset. Expects a symbol. State can't be in the dataset yet or the function will give an error. You can also set overwrite = TRUE.
Id.colname.dataset, Id.colname.interval: Column names of the participant's Id in both the dataset and the State.interval.dataset. On the off-chance that there are inconsistencies, the names can be different. If the datasets where imported and preprocessed with LightLogR, this just works. Both datasets need an Id, because the states will be added based not only on the Datetime, but also depending on the dataset.
overwrite: If TRUE (defaults to FALSE), the function will overwrite the State.colname column if it already exists.
output.dataset: should the output be a data.frame (Default TRUE) or a vector with hms (FALSE) times? Expects a logical scalar.

Value

One of

a data.frame object identical to dataset but with the state column added
a vector with the states

Examples

#create a interval dataset
library(tibble)
library(dplyr)
library(lubridate)
library(rlang)
library(purrr)
#> 
#> Attaching package: ‘purrr’
#> The following objects are masked from ‘package:rlang’:
#> 
#>     %@%, flatten, flatten_chr, flatten_dbl, flatten_int, flatten_lgl,
#>     flatten_raw, invoke, splice
states <- tibble::tibble(Datetime = c("2023-08-15 6:00:00",
                                      "2023-08-15 23:00:00",
                                      "2023-08-16 6:00:00",
                                      "2023-08-16 22:00:00",
                                      "2023-08-17 6:30:00",
                                      "2023-08-18 1:00:00",
                                      "2023-08-18 6:00:00",
                                      "2023-08-18 22:00:00",
                                      "2023-08-19 6:00:00",
                                      "2023-08-19 23:00:00",
                                      "2023-08-20 6:00:00",
                                      "2023-08-20 22:00:00"),
                         State = rep(c("wake", "sleep"), 6),
                         Wear = rep(c("wear", "no wear"), 6),
                         Performance = rep(c(100, 0), 6),
                         Id = "Participant")
intervals <- sc2interval(states)

#create a dataset with states
dataset_with_states <-
sample.data.environment %>%
interval2state(State.interval.dataset = intervals)

#visualize the states - note that the states are only added to the respective ID in the dataset
library(ggplot2)
ggplot(dataset_with_states, aes(x = Datetime, y = MEDI, color = State)) +
 geom_point() +
 facet_wrap(~Id, ncol = 1)


#import multiple State columns from the interval dataset
#interval2state will only add a single State column to the dataset, 
#which represents sleep/wake in our case
dataset_with_states[8278:8283,]
#> # A tibble: 6 × 4
#> # Groups:   Id [1]
#>   Datetime             MEDI Id          State
#>   <dttm>              <dbl> <chr>       <chr>
#> 1 2023-08-15 22:59:31  2.38 Participant wake 
#> 2 2023-08-15 22:59:41  2.34 Participant wake 
#> 3 2023-08-15 22:59:51  2.25 Participant wake 
#> 4 2023-08-15 23:00:01  1.95 Participant sleep
#> 5 2023-08-15 23:00:11  2.6  Participant sleep
#> 6 2023-08-15 23:00:21  2.36 Participant sleep

#if we want to add multiple columns we can either perfom the function 
#multiple times with different states:
dataset_with_states2 <- 
dataset_with_states %>%
interval2state(State.interval.dataset = intervals, State.colname = Wear)
dataset_with_states2[8278:8283,]
#> # A tibble: 6 × 5
#> # Groups:   Id [1]
#>   Datetime             MEDI Id          State Wear   
#>   <dttm>              <dbl> <chr>       <chr> <chr>  
#> 1 2023-08-15 22:59:31  2.38 Participant wake  wear   
#> 2 2023-08-15 22:59:41  2.34 Participant wake  wear   
#> 3 2023-08-15 22:59:51  2.25 Participant wake  wear   
#> 4 2023-08-15 23:00:01  1.95 Participant sleep no wear
#> 5 2023-08-15 23:00:11  2.6  Participant sleep no wear
#> 6 2023-08-15 23:00:21  2.36 Participant sleep no wear

#or we can use `purrr::reduce` to add multiple columns at once
dataset_with_states3 <-
syms(c("State", "Wear", "Performance")) %>% 
reduce(\(x,y) interval2state(x, State.interval.dataset = intervals, State.colname = !!y), 
.init = sample.data.environment)

#Note: 
# - the State.colnames have to be provided as symbols (`rlang::syms`)
# - the reduce function requires a two argument function `\(x,y)`, where `x` 
#   is the dataset to be continiously modified and `y` is the symbol of the
#   State column name to be added
# - the `!!` operator from `rlang` is used to exchange `y` with each symbol
# - the `.init` argument is the initial dataset to be modified

#this results in all states being applied
dataset_with_states3[8278:8283,]
#> # A tibble: 6 × 6
#> # Groups:   Id [1]
#>   Datetime             MEDI Id          State Wear    Performance
#>   <dttm>              <dbl> <chr>       <chr> <chr>         <dbl>
#> 1 2023-08-15 22:59:31  2.38 Participant wake  wear            100
#> 2 2023-08-15 22:59:41  2.34 Participant wake  wear            100
#> 3 2023-08-15 22:59:51  2.25 Participant wake  wear            100
#> 4 2023-08-15 23:00:01  1.95 Participant sleep no wear           0
#> 5 2023-08-15 23:00:11  2.6  Participant sleep no wear           0
#> 6 2023-08-15 23:00:21  2.36 Participant sleep no wear           0