Package 'LightLogR'

Description

Create a Date column in the dataset

Usage

add_Date_col(
  dataset,
  Date.colname = Date,
  group.by = FALSE,
  as.wday = FALSE,
  as.count = FALSE,
  Datetime.colname = Datetime
)

Arguments

Value

a data.frame object identical to dataset but with the added column of Date data

Examples

sample.data.environment %>% add_Date_col()
#days of the week
sample.data.environment %>% 
  add_Date_col(as.wday = TRUE, group.by = TRUE) |> 
  summarize_numeric(remove = c("Datetime"))

Description

add_states() brings states to a time series dataset. It uses the States.dataset to add states to the dataset. The States.dataset must at least contain the same variables as the dataset grouping, as well as a start and end time (or an interval column). Beware if both datasets operate on different time zones and consider to set force.tz = TRUE.

Usage

add_states(
  dataset,
  States.dataset,
  Datetime.colname = Datetime,
  start.colname = start,
  end.colname = end,
  force.tz = FALSE,
  bounds = c("[)", "[]", "(]", "()"),
  leave.out = c("duration", "epoch")
)

Arguments

Details

Beware if columns in the dataset and States.dataset have the same name (other then grouping variables). The underlying function, dplyr::left_join() will mark the columns in the dataset with a suffix .x, and in the States.dataset with a suffix .y.

Also be careful if grouping variables have the same name, but a different class - usually, this will result in an error that can be fixed by making sure the classes are identical. This is especially an issue with labelled variables (e.g., a labelled Id factor-variable in the main dataset, and a factor variable Id in the state dataset) - in those cases, either the unlabelled variable has to be labelled as well, or the other one unlabelled.

Value

a modified dataset with the states added. The states are added as new columns to the dataset. The columns are named after the columns in the States.dataset, except for the start and end times, which are removed.

Examples

states <-
sample.data.environment |>
  filter_Date(length = "1 day") |>
  extract_states(Daylight, MEDI > 1000)

states |> head(2)

#add states to a dataset and plot them - as we only looked for states on the
# first day (see above), only the first day will show up in the plot
sample.data.environment |>
 filter_Date(length = "2 day") |>
 add_states(states) |>
 gg_days() |>
 gg_states(Daylight)

Description

Create a Time-of-Day column in the dataset

Usage

add_Time_col(
  dataset,
  Datetime.colname = Datetime,
  Time.colname = Time,
  output.dataset = TRUE
)

Arguments

Value

a data.frame object identical to dataset but with the added column of Time-of-Day data, or a vector with the Time-of-Day-data

Examples

sample.data.environment %>% add_Time_col()

Description

Condenses a dataset by aggregating the data to a single day per group, with a resolution of choice unit. aggregate_Date() is opinionated in the sense that it sets default handlers for each data type of numeric, character, logical, and factor. These can be overwritten by the user. Columns that do not fall into one of these categories need to be handled individually by the user (... argument) or will be removed during aggregation. If no unit is specified the data will simply be aggregated to the most common interval (dominant.epoch) in every group. aggregate_Date() is especially useful for summary plots that show an average day.

Usage

aggregate_Date(
  dataset,
  Datetime.colname = Datetime,
  unit = "none",
  type = c("round", "floor", "ceiling"),
  date.handler = stats::median,
  numeric.handler = mean,
  character.handler = function(x) names(which.max(table(x, useNA = "ifany"))),
  logical.handler = function(x) mean(x) >= 0.5,
  factor.handler = function(x) factor(names(which.max(table(x, useNA = "ifany")))),
  datetime.handler = stats::median,
  duration.handler = function(x) lubridate::duration(mean(x)),
  time.handler = function(x) hms::as_hms(mean(x)),
  ...
)

Arguments

Details

Summary values for type POSIXct are calculated as the median, because the mean can be nonsensical at times (e.g., the mean of Day1 18:00 and Day2 18:00, is Day2 6:00, which can be the desired result, but if the focus is on time, rather then on datetime, it is recommended that values are converted to times via hms::as_hms() before applying the function (the mean of 18:00 and 18:00 is still 18:00, not 6:00). Using the median as a default handler ensures a more sensible datetime.

aggregate_Date() splits the Datetime column into a Date.data and a Time column. It will create subgroups for each Time present in a group and aggregate each group into a single day, then remove the sub grouping.

Use the ... to create summary statistics for each group, e.g. maximum or minimum values for each time point group.

Performing aggregate_Datetime() with any unit and then aggregate_Date() with a unit of "none" is equivalent to just using aggregate_Date() with that unit directly (provided the other arguments are set the same between the functions). Disentangling the two functions can be useful to split the computational cost for very small instances of unit in large datasets. It can also be useful to apply different handlers when aggregating data to the desired unit of time, before further aggregation to a single day, as these handlers as well as ... are used twice if the unit is not set to "none".

Value

A tibble with aggregated Datetime data, at maximum one day per group. If the handler arguments capture all column types, the number of columns will be the same as in the input dataset.

Examples

library(ggplot2)
#gg_days without aggregation
sample.data.environment %>%
 gg_days()

#with daily aggregation
sample.data.environment %>%
 aggregate_Date() %>%
 gg_days()

#with daily aggregation and a different time aggregation
sample.data.environment %>%
 aggregate_Date(unit = "15 mins", type = "floor") %>%
 gg_days()

#adding further summary statistics about the range of MEDI
 sample.data.environment %>%
 aggregate_Date(unit = "15 mins", type = "floor",
                MEDI_max = max(MEDI),
                MEDI_min = min(MEDI)) %>%
 gg_days() +
 geom_ribbon(aes(ymin = MEDI_min, ymax = MEDI_max), alpha = 0.5)

Description

Condenses a dataset by aggregating the data to a given (shorter) interval unit. aggregate_Datetime() is opinionated in the sense that it sets default handlers for each data type of numeric, character, logical, factor, duration, time, and datetime. These can be overwritten by the user. Columns that do not fall into one of these categories need to be handled individually by the user (... argument) or will be removed during aggregation. If no unit is specified the data will simply be aggregated to the most common interval (dominant.epoch), which is most often not an aggregation but a rounding.)

Usage

aggregate_Datetime(
  dataset,
  unit = "dominant.epoch",
  Datetime.colname = Datetime,
  type = c("round", "floor", "ceiling"),
  numeric.handler = mean,
  character.handler = function(x) names(which.max(table(x, useNA = "ifany"))),
  logical.handler = function(x) mean(x) >= 0.5,
  factor.handler = function(x) factor(names(which.max(table(x, useNA = "ifany")))),
  datetime.handler = mean,
  duration.handler = function(x) lubridate::duration(mean(x)),
  time.handler = function(x) hms::as_hms(mean(x)),
  ...
)

Arguments

Details

Summary values for type POSIXct are calculated as the mean, which can be nonsensical at times (e.g., the mean of Day1 18:00 and Day2 18:00, is Day2 6:00, which can be the desired result, but if the focus is on time, rather then on datetime, it is recommended that values are converted to times via hms::as_hms() before applying the function (the mean of 18:00 and 18:00 is still 18:00, not 6:00).

Value

A tibble with aggregated Datetime data. Usually the number of rows will be smaller than the input dataset. If the handler arguments capture all column types, the number of columns will be the same as in the input dataset.

Examples

#dominant epoch without aggregation
sample.data.environment %>%
 dominant_epoch()

#dominant epoch with 5 minute aggregation
sample.data.environment %>%
 aggregate_Datetime(unit = "5 mins") %>%
 dominant_epoch()

#dominant epoch with 1 day aggregation
sample.data.environment %>%
 aggregate_Datetime(unit = "1 day") %>%
 dominant_epoch()

Description

A dataframe of alphaopic action spectra plus the photopic action spectrum. The alphaopic action spectra are according to the CIE S 026/E:2018 standard. The alphaopic action spectra are for a 32-year-old standard observer. The photopic action spectrum is for a 2° standard observer.

Usage

alphaopic.action.spectra

Format

alphaopic.action.spectra A datafram with 471 rows and 7 columns:

wavelength

integer of wavelength, from 360 to 830 nm. Unit is nm

melanopic

numeric melanopic action spectrum

l_cone_opic

numeric L-cone opic action spectrum

m_cone_opic

numeric M-cone opic action spectrum

s_cone_opic

numeric S-cone opic action spectrum

rhodopic

numeric rhodopic action spectrum

photopic

numeric photopic action spectrum

Source

https://www.cie.co.at/publications/cie-system-metrology-optical-radiation-iprgc-influenced-responses-light-0

https://cie.co.at/datatable/cie-spectral-luminous-efficiency-photopic-vision

<https://files.cie.co.at/CIE S 026 alpha-opic Toolbox.xlsx>

References

CIE (2019). ISO/CIE 11664-1:2019(E). Colorimetry — Part 1: CIE standard colorimetric observers. Vienna, CIE

CIE (2018). CIE S 026/E:2018. CIE system for metrology of optical radiation for ipRGC-influenced responses of light. Vienna, CIE

Description

This function calculates the metrics proposed by Barroso et al. (2014) for light-dosimetry in the context of research on the non-visual effects of light. The following metrics are calculated:

Usage

barroso_lighting_metrics(
  Light.vector,
  Time.vector,
  epoch = "dominant.epoch",
  loop = FALSE,
  na.rm = FALSE,
  as.df = FALSE
)

Arguments

Details

bright_threshold

The maximum light intensity for which at least six hours of measurements are at the same or higher level.

dark_threshold

The minimum light intensity for which at least eight hours of measurements are at the same or lower level.

bright_mean_level

The 20% trimmed mean of all light intensity measurements equal or above the bright_threshold.

dark_mean_level

The 20% trimmed mean of all light intensity measurements equal or below the dark_threshold.

bright_cluster

The longest continuous time interval above the bright_threshold.

dark_cluster

The longest continuous time interval below the dark_threshold.

circadian_variation

A measure of periodicity of the daily lighting schedule over a given set of days. Calculated as the coefficient of variation of input light data.

Value

List or dataframe with the seven values: bright_threshold, dark_threshold, bright_mean_level, dark_mean_level, bright_cluster, dark_cluster, circadian_variation. The output type of bright_cluster, dark_cluster, is a duration object.

References

Barroso, A., Simons, K., & Jager, P. de. (2014). Metrics of circadian lighting for clinical investigations. Lighting Research & Technology, 46(6), 637–649. doi:10.1177/1477153513502664

Hartmeyer, S.L., Andersen, M. (2023). Towards a framework for light-dosimetry studies: Quantification metrics. Lighting Research & Technology. doi:10.1177/14771535231170500

Examples

dataset1 <-
  tibble::tibble(
    Id = rep("B", 60 * 24),
    Datetime = lubridate::as_datetime(0) + lubridate::minutes(0:(60*24-1)),
    MEDI = c(rep(sample(seq(0,1,0.1), 60*8, replace = TRUE)), 
             rep(sample(1:1000, 16, replace = TRUE), each = 60))
  )

dataset1 %>%
  dplyr::reframe(barroso_lighting_metrics(MEDI, Datetime, as.df = TRUE))

Description

This function finds the brightest or darkest continuous period of a given timespan and calculates its mean light level, as well as the timing of the period's onset, midpoint, and offset. It is defined as the period with the maximum or minimum mean light level. Note that the data need to be regularly spaced (i.e., no gaps) for correct results.

Usage

bright_dark_period(
  Light.vector,
  Time.vector,
  period = c("brightest", "darkest"),
  timespan = "10 hours",
  epoch = "dominant.epoch",
  loop = FALSE,
  na.rm = FALSE,
  as.df = FALSE
)

Arguments

Details

Assumes regular 24h light data. Otherwise, results may not be meaningful. Looping the data is recommended for finding the darkest period.

Value

A named list with the mean, onset, midpoint, and offset of the calculated brightest or darkest period, or if as.df == TRUE a data frame with columns named ⁠{period}_{timespan}_{metric}⁠. The output type corresponds to the type of Time.vector, e.g., if Time.vector is HMS, the timing metrics will be also HMS, and vice versa for POSIXct.

References

Hartmeyer, S.L., Andersen, M. (2023). Towards a framework for light-dosimetry studies: Quantification metrics. Lighting Research & Technology. doi:10.1177/14771535231170500

See Also

Other metrics: centroidLE(), disparity_index(), dose(), duration_above_threshold(), exponential_moving_average(), frequency_crossing_threshold(), interdaily_stability(), intradaily_variability(), midpointCE(), nvRC(), nvRD(), nvRD_cumulative_response(), period_above_threshold(), pulses_above_threshold(), threshold_for_duration(), timing_above_threshold()

Examples

# Dataset with light > 250lx between 06:00 and 18:00
dataset1 <-
  tibble::tibble(
    Id = rep("A", 24),
    Datetime = lubridate::as_datetime(0) + lubridate::hours(0:23),
    MEDI = c(rep(1, 6), rep(250, 13), rep(1, 5))
  )

dataset1 %>%
  dplyr::reframe(bright_dark_period(MEDI, Datetime, "brightest", "10 hours",
    as.df = TRUE))
dataset1 %>%
  dplyr::reframe(bright_dark_period(MEDI, Datetime, "darkest", "7 hours",
    loop = TRUE, as.df = TRUE))

# Dataset with duration as Time.vector
dataset2 <-
  tibble::tibble(
    Id = rep("A", 24),
    Datetime = lubridate::dhours(0:23),
    MEDI = c(rep(1, 6), rep(250, 13), rep(1, 5))
  )

dataset2 %>%
  dplyr::reframe(bright_dark_period(MEDI, Datetime, "brightest", "10 hours",
                                    as.df = TRUE))
dataset2 %>%
  dplyr::reframe(bright_dark_period(MEDI, Datetime, "darkest", "5 hours",
                                    loop = TRUE, as.df = TRUE))

Description

This is a lower level function. It checks a given value against a threshold for the states given by Brown et al. (2022). The function is vectorized. For day the threshold is a lower limit, for evening and night the threshold is an upper limit.

Usage

Brown_check(
  value,
  state,
  Brown.day = "day",
  Brown.evening = "evening",
  Brown.night = "night",
  Brown.day.th = 250,
  Brown.evening.th = 10,
  Brown.night.th = 1
)

Arguments

Value

A logical vector with the same length as value that indicates whether the value is within the recommended illuminance levels.

References

https://journals.plos.org/plosbiology/article?id=10.1371/journal.pbio.3001571

See Also

Other Brown: Brown2reference(), Brown_cut(), Brown_rec(), sleep_int2Brown()

Examples

states <- c("day", "evening", "night", "day")
values <- c(100, 10, 1, 300)
Brown_check(values, states)
Brown_check(values, states, Brown.day.th = 100)

Description

This is a convenience wrapper arount cut() and dplyr::mutate(). It creates a state column dividing a light column into recommended levels by Brown et al. (2022). Cuts can be adjusted or extended with vector_cuts and vector_labels

Usage

Brown_cut(
  dataset,
  MEDI.colname = MEDI,
  New.state.colname = state,
  vector_cuts = c(-Inf, 1, 10, 250, Inf),
  vector_labels = "default",
  overwrite = TRUE
)

Arguments

Value

The input dataset with an additional (or overwritten) column containing a cut light vector

References

https://journals.plos.org/plosbiology/article?id=10.1371/journal.pbio.3001571

See Also

Other Brown: Brown2reference(), Brown_check(), Brown_rec(), sleep_int2Brown()

Examples

sample.data.environment |>
Brown_cut(vector_labels = c("0-1lx", "1-10lx", "10-250lx", "250lx-Inf")) |>
dplyr::count(state)

Description

This is a lower level function. It sets the recommended illuminance/MEDI levels by Brown et al. (2022) for a given state. The function is vectorized.

Usage

Brown_rec(
  state,
  Brown.day = "day",
  Brown.evening = "evening",
  Brown.night = "night",
  Brown.day.th = 250,
  Brown.evening.th = 10,
  Brown.night.th = 1
)

Arguments

Value

A dataframe with the same length as state that contains the recommended illuminance/MEDI levels.

References

https://journals.plos.org/plosbiology/article?id=10.1371/journal.pbio.3001571

See Also

Other Brown: Brown2reference(), Brown_check(), Brown_cut(), sleep_int2Brown()

Examples

states <- c("day", "evening", "night")
Brown_rec(states)
Brown_rec(states, Brown.day.th = 100)

Description

Adds several columns to a light logger dataset. It requires a column that contains the Brown states, e.g. "daytime", "evening", and "night". From that the function will add a column with the recommended illuminance, a column that checks if the illuminance of the dataset is within the recommended illuminance levels, and a column that gives a label to the reference.

Usage

Brown2reference(
  dataset,
  MEDI.colname = MEDI,
  Brown.state.colname = State.Brown,
  Brown.rec.colname = Reference,
  Reference.label = "Brown et al. (2022)",
  overwrite = FALSE,
  ...
)

Arguments

Details

On a lower level, the function uses Brown_rec() and Brown_check() to create the required information.

Value

A dataframe on the basis of the dataset that contains the added columns.

References

https://journals.plos.org/plosbiology/article?id=10.1371/journal.pbio.3001571

See Also

Other Brown: Brown_check(), Brown_cut(), Brown_rec(), sleep_int2Brown()

Examples

#add Brown reference illuminance to some sample data
testdata <- tibble::tibble(MEDI = c(100, 10, 1, 300),
                  State.Brown = c("day", "evening", "night", "day"))
Brown2reference(testdata)

Description

This function calculates the centroid of light exposure as the mean of the time vector weighted in proportion to the corresponding binned light intensity.

Usage

centroidLE(
  Light.vector,
  Time.vector,
  bin.size = NULL,
  na.rm = FALSE,
  as.df = FALSE
)

Arguments

Value

Single column data frame or vector.

References

Phillips, A. J. K., Clerx, W. M., O’Brien, C. S., Sano, A., Barger, L. K., Picard, R. W., Lockley, S. W., Klerman, E. B., & Czeisler, C. A. (2017). Irregular sleep/wake patterns are associated with poorer academic performance and delayed circadian and sleep/wake timing. Scientific Reports, 7(1), 3216. doi:10.1038/s41598-017-03171-4

Hartmeyer, S.L., Andersen, M. (2023). Towards a framework for light-dosimetry studies: Quantification metrics. Lighting Research & Technology. doi:10.1177/14771535231170500

See Also

Other metrics: bright_dark_period(), disparity_index(), dose(), duration_above_threshold(), exponential_moving_average(), frequency_crossing_threshold(), interdaily_stability(), intradaily_variability(), midpointCE(), nvRC(), nvRD(), nvRD_cumulative_response(), period_above_threshold(), pulses_above_threshold(), threshold_for_duration(), timing_above_threshold()

Examples

# Dataset with POSIXct time vector
dataset1 <-
  tibble::tibble(
    Id = rep("A", 24),
    Datetime = lubridate::as_datetime(0) + lubridate::hours(0:23),
    MEDI = c(rep(1, 6), rep(250, 13), rep(1, 5))
  )
dataset1 %>%
  dplyr::reframe(
    "Centroid of light exposure" = centroidLE(MEDI, Datetime, "2 hours")
  )

# Dataset with hms time vector
dataset2 <-
  tibble::tibble(
    Id = rep("A", 24),
    Time = hms::as_hms(lubridate::as_datetime(0) + lubridate::hours(0:23)),
    MEDI = c(rep(1, 6), rep(250, 13), rep(1, 5))
  )
dataset2 %>%
  dplyr::reframe(
    "Centroid of light exposure" = centroidLE(MEDI, Time, "2 hours")
  )

# Dataset with duration time vector
dataset3 <-
  tibble::tibble(
    Id = rep("A", 24),
    Hour = lubridate::duration(0:23, "hours"),
    MEDI = c(rep(1, 6), rep(250, 13), rep(1, 5))
  )
dataset3 %>%
  dplyr::reframe(
    "Centroid of light exposure" = centroidLE(MEDI, Hour, "2 hours")
  )

Description

Convert circular time columns to hms

Usage

Circular2Time(
  dataset,
  cols = dplyr::where(circular::is.circular),
  silent = FALSE
)

Arguments

Value

The input dataset with converted circular columns as time (hms) columns. With the default settings, if no circular column exists, input and output will be identical.

Examples

times <- lubridate::as_datetime("2023-01-01 10:00:00") + lubridate::hours(0:2)
times
circular_times <- Datetime2Time(tibble::tibble(Timestamp = times), circular = TRUE)
circular_times
Circular2Time(circular_times)

#if times are not circular, then an averaging can be problematic across midnight:
selected_times <- 
sample.data.environment |> 
sample_groups() |> 
dplyr::slice(c(40:43, 51838:51840))
selected_times

#a simple averaging will lead to a nonsensical value, e.g. if this should 
#calculate average sleep timing: ~10:00 in the morning
selected_times |> summarize_numeric()

#by converting it to a circular beforehand, averaging works as expected: 
#~3 minutes after midnight
selected_times |> 
summarize_numeric(Datetime2Time.circular = TRUE) |> 
Circular2Time()

Description

Counts the Time differences (epochs) per group (in a grouped dataset)

Usage

count_difftime(dataset, Datetime.colname = Datetime)

Arguments

Value

a tibble with the number of occurences of each time difference per group

Examples

#count_difftime returns the number of occurences of each time difference
#and is more comprehensive in terms of a summary than `gap_finder` or 
#`dominant_epoch`
count_difftime(sample.data.irregular)
dominant_epoch(sample.data.irregular)
gap_finder(sample.data.irregular)

#irregular data can be regularized with `aggregate_Datetime`
sample.data.irregular |> 
 aggregate_Datetime(unit = "15 secs") |> 
 count_difftime()

Description

create_Timedata

Usage

create_Timedata(...)

Arguments

Value

a data.frame object identical to dataset but with the added column of Time-of-Day data, or a vector with the Time-of-Day-data

Examples

sample.data.environment %>% create_Timedata()

Description

cut_Datetime is a wrapper around lubridate::round_date() (and friends) combined with dplyr::mutate(), to create a new column in a light logger dataset with a specified binsize. This can be "3 hours", "15 secs", or "0.5 days". It is a useful step between a dataset and a visualization or summary step.

Usage

cut_Datetime(
  dataset,
  unit = "3 hours",
  type = c("round", "floor", "ceiling"),
  Datetime.colname = Datetime,
  New.colname = Datetime.rounded,
  group_by = FALSE,
  ...
)

Arguments

Value

a data.frame object identical to dataset but with the added column of binned datetimes.

Examples

#compare Datetime and Datetime.rounded
sample.data.environment %>%
  cut_Datetime() %>%
  dplyr::slice_sample(n = 5)

Description

Create reference data from almost any other data that has a datetime column and a data column. The reference data can even be created from subsets of the same data. Examples are that one participant can be used as a reference for all other participants, or that the first (second,...) day of every participant data is the reference for any other day. This function needs to be carefully handled, when the reference data time intervals are shorter than the data time intervals. In that case, use aggregate_Datetime() on the reference data beforehand to lengthen the interval.

Usage

data2reference(
  dataset,
  Reference.data = dataset,
  Datetime.column = Datetime,
  Data.column = MEDI,
  Id.column = Id,
  Reference.column = Reference,
  overwrite = FALSE,
  filter.expression.reference = NULL,
  across.id = FALSE,
  shift.start = FALSE,
  length.restriction.seconds = 60,
  shift.intervals = "auto",
  Reference.label = NULL
)

Arguments

Details

To use subsets of data, use the filter.expression.reference argument to specify the subsets of data. The across.id argument specifies whether the reference data should be used across all or some grouping variables (e.g., across participants). The shift.start argument enables a shift of the reference data start time to the start of the respective group.

and @examples for more information. The expression is evaluated within dplyr::filter().

Value

A dataset with a new column Reference that contains the reference data.

Examples

library(dplyr)
library(lubridate)
library(ggplot2)

gg_reference <- function(dataset) {
dataset %>%
ggplot(aes(x = Datetime, y = MEDI, color = Id)) +
geom_line(linewidth = 1) +
geom_line(aes(y = Reference), color = "black", size = 0.25, linetype = "dashed") +
theme_minimal() + facet_wrap(~ Id, scales = "free_y")
}

#in this example, each data point is its own reference
sample.data.environment %>%
  data2reference() %>%
  gg_reference()

#in this example, the first day of each ID is the reference for the other days
#this requires grouping of the Data by Day, which is then specified in across.id
#also, shift.start needs to be set to TRUE, to shift the reference data to the
#start of the groupings
sample.data.environment %>% group_by(Id, Day = as_date(Datetime)) %>%
data2reference(
  filter.expression.reference =  as_date(Datetime) == min(as_date(Datetime)),
  shift.start = TRUE,
  across.id = "Day") %>%
  gg_reference()

#in this example, the Environment Data will be used as a reference
sample.data.environment %>%
data2reference(
  filter.expression.reference =  Id == "Environment",
  across.id = TRUE) %>%
  gg_reference()

Description

Take a vector of Datetimes and create a sequence of Datetimes with a given shift and interval. This is a helper function to create breaks for plotting, e.g. in gg_days(), and is best used in conjunction with Datetime_limits(). The function is a thin wrapper around seq().

Usage

Datetime_breaks(x, shift = lubridate::duration(12, "hours"), by = "1 day")

Arguments

Value

a vector of Datetimes

Examples

dataset <- c("2023-08-15", "2023-08-20")
Datetime_breaks(dataset)
Datetime_breaks(dataset, shift = 0)
Datetime_breaks(dataset, by = "12 hours")

Description

Take a vector of Datetimes and return the start of the first and end of the last day of data. The start and the length can be adjusted by durations, like lubridate::ddays(). It is used in the gg_days() function to return a sensible x-axis. This function is a thin wrapper around lubridate::floor_date() and lubridate::ceiling_date().

Usage

Datetime_limits(
  x,
  start = NULL,
  length = NULL,
  unit = "1 day",
  midnight.rollover = FALSE,
  ...
)

Arguments

Value

a 2 item vector of Datetimes with the (adjusted) start and end of the input vector.

Examples

dataset <- c("2023-08-15", "2023-08-20")
breaks <- Datetime_breaks(dataset)
Datetime_limits(breaks)
Datetime_limits(breaks, start = lubridate::ddays(1))
Datetime_limits(breaks, length = lubridate::ddays(2))

Description

Convert Datetime columns to Time columns

Usage

Datetime2Time(
  dataset,
  cols = dplyr::where(lubridate::is.POSIXct),
  circular = FALSE,
  silent = FALSE
)

Arguments

Value

The input dataset with converted POSIXct columns as time (hms) columns. With the default settings, if no POSIXct column exists, input and output will be identical.

Examples

sample.data.environment |> Datetime2Time()
#more than one POSIX col
sample.data.environment |>
  dplyr::mutate(Datetime2 = lubridate::POSIXct(1)) |>
  Datetime2Time()
#only converting one of them
sample.data.environment |>
  dplyr::mutate(Datetime2 = lubridate::POSIXct(1)) |>
  Datetime2Time(Datetime)
#if uncertain whether column exists
sample.data.environment |>
  Datetime2Time(dplyr::any_of("Datetime3"))

Description

This function calculates the continuous disparity index as described in Fernández-Martínez et al. (2018).

Usage

disparity_index(Light.vector, na.rm = FALSE, as.df = FALSE)

Arguments

Value

Single column data frame or vector.

References

Fernández-Martínez, M., Vicca, S., Janssens, I. A., Carnicer, J., Martín-Vide, J., & Peñuelas, J. (2018). The consecutive disparity index, D: A measure of temporal variability in ecological studies. Ecosphere, 9(12), e02527. doi:10.1002/ecs2.2527

Hartmeyer, S.L., Andersen, M. (2023). Towards a framework for light-dosimetry studies: Quantification metrics. Lighting Research & Technology. doi:10.1177/14771535231170500

See Also

Other metrics: bright_dark_period(), centroidLE(), dose(), duration_above_threshold(), exponential_moving_average(), frequency_crossing_threshold(), interdaily_stability(), intradaily_variability(), midpointCE(), nvRC(), nvRD(), nvRD_cumulative_response(), period_above_threshold(), pulses_above_threshold(), threshold_for_duration(), timing_above_threshold()

Examples

dataset1 <-
  tibble::tibble(
    Id = rep("A", 24),
    Datetime = lubridate::as_datetime(0) + lubridate::hours(0:23),
    MEDI = sample(0:1000, 24),
  )
dataset1 %>%
  dplyr::reframe(
    "Disparity index" = disparity_index(MEDI)
  )

Description

Calculate the dominant epoch/interval of a dataset. The dominant epoch/interval is the epoch/interval that is most frequent in the dataset. The calculation is done per group, so that you might get multiple variables. If two or more epochs/intervals are equally frequent, the first one (shortest one) is chosen.

Usage

dominant_epoch(dataset, Datetime.colname = Datetime)

Arguments

Value

A tibble with one row per group and a column with the dominant.epoch as a lubridate::duration(). Also a column with the group.indices, which is helpful for referencing the dominant.epoch across dataframes of equal grouping.

See Also

Other regularize: extract_gaps(), gap_finder(), gap_handler(), gapless_Datetimes(), has_gaps(), has_irregulars()

Examples

dataset <-
tibble::tibble(Id = c("A", "A", "A", "B", "B", "B"),
              Datetime = lubridate::as_datetime(1) +
                         lubridate::days(c(0:2, 4, 6, 8)))
dataset
#get the dominant epoch by group
dataset %>%
dplyr::group_by(Id) %>%
dominant_epoch()

#get the dominant epoch of the whole dataset
dataset %>%
dominant_epoch()

Description

This function calculates the dose from a time series. For light, this is equal to the actual definition of light exposure (CIE term luminous exposure). Output will always be provided in value·hours (e.g., for light, lx·hours).

Usage

dose(
  Light.vector,
  Time.vector,
  epoch = "dominant.epoch",
  na.rm = FALSE,
  as.df = FALSE
)

Arguments

Details

The time series does not have to be regular, however, it will be aggregated to a regular timeseries of the given epoch. Implicit gaps (i.e., no observations), will be converted to NA values (which can be ignored with na.rm = TRUE).

Value

A numeric object as single value, or single column data frame with the dose in value·hours

References

Hartmeyer, S.L., Andersen, M. (2023). Towards a framework for light-dosimetry studies: Quantification metrics. Lighting Research & Technology. doi:10.1177/14771535231170500

See Also

Other metrics: bright_dark_period(), centroidLE(), disparity_index(), duration_above_threshold(), exponential_moving_average(), frequency_crossing_threshold(), interdaily_stability(), intradaily_variability(), midpointCE(), nvRC(), nvRD(), nvRD_cumulative_response(), period_above_threshold(), pulses_above_threshold(), threshold_for_duration(), timing_above_threshold()

Examples

dose(c(1,1,1,1), lubridate::dhours(c(1:4)), na.rm = TRUE)
#with gaps
dose(c(1,1,1), lubridate::dhours(c(1,3:4)), na.rm = TRUE)
#gaps can be aggregated to a coarser interval, which can be sensibe
#if they are still representative
dose(c(1,1,1), lubridate::dhours(c(1,3:4)), na.rm = TRUE, epoch = "2 hours")

Description

When data is imported through LightLogR and a timezone applied, it is assumed that the timestamps are correct - which is the case, e.g., if timestamps are stored in UTC, or they are in local time. Some if not most measurement devices are set to local time before a recording interval starts. If during the recording a daylight savings jump happens (in either direction), the device might not adjust timestamps for this change. This results in an unwanted shift in the data, starting at the time of the DST jump and likely continues until the end of a file. dst_change_handler is used to detect such jumps within a group and apply the correct shift in the data (i.e., the shift that should have been applied by the device).

important Note that this function is only useful if the time stamp in the raw data deviates from the actual date-time. Note also, that this function results in a gap during the DST jump, which should be handled by gap_handler() afterwards. It will also result in potentially double the timestamps during the jum back from DST to standard time. This will result in some inconsistencies with some functions, so we recommend to use aggregate_Datetime() afterwards with a unit equal to the dominant epoch. Finally, the function is not equipped to handle more than one jump per group. The jump is based on whether the group starts out with DST or not. the function will remove datetime rows with NA values.

Usage

dst_change_handler(
  dataset,
  Datetime.colname = Datetime,
  filename.colname = NULL
)

Arguments

Details

The detection of a DST jump is based on the function lubridate::dst() and jumps are only applied within a group. During import, this function is used if dst_adjustment = TRUE is set and includes by default the filename as the grouping variable, additionally to Id.

Value

A tibble with the same columns as the input dataset, but shifted

See Also

Other DST: dst_change_summary()

Examples

#create some data that crosses a DST jump
data <- 
 tibble::tibble(
 Datetime = seq.POSIXt(from = as.POSIXct("2023-03-26 01:30:00", tz = "Europe/Berlin"),
                     to = as.POSIXct("2023-03-26 03:00:00", tz = "Europe/Berlin"),
                     by = "30 mins"),
                     Value = 1)
 #as can be seen next, there is a gap in the data - this is necessary when
 #using a timezone with DST. 
 data$Datetime
 #Let us say now, that the device did not adjust for the DST - thus the 03:00 
 #timestamp is actually 04:00 in local time. This can be corrected for by:
 data %>% dst_change_handler() %>% .$Datetime

Description

Get a summary of groups where a daylight saving time change occurs.

Usage

dst_change_summary(dataset, Datetime.colname = Datetime)

Arguments

Value

a tibble with the groups where a dst change occurs. The column dst_start is a boolean that indicates whether the start of this group occurs during daylight savings.

See Also

Other DST: dst_change_handler()

Examples

sample.data.environment %>% 
  dplyr::mutate(Datetime = 
  Datetime + lubridate::dweeks(8)) %>%
  dst_change_summary()

Description

This function calculates the duration spent above/below a specified threshold light level or within a specified range of light levels.

Usage

duration_above_threshold(
  Light.vector,
  Time.vector,
  comparison = c("above", "below"),
  threshold,
  epoch = "dominant.epoch",
  na.rm = FALSE,
  as.df = FALSE
)

Arguments

Value

A duration object as single value, or single column data frame.

References

Hartmeyer, S.L., Andersen, M. (2023). Towards a framework for light-dosimetry studies: Quantification metrics. Lighting Research & Technology. doi:10.1177/14771535231170500

See Also

Other metrics: bright_dark_period(), centroidLE(), disparity_index(), dose(), exponential_moving_average(), frequency_crossing_threshold(), interdaily_stability(), intradaily_variability(), midpointCE(), nvRC(), nvRD(), nvRD_cumulative_response(), period_above_threshold(), pulses_above_threshold(), threshold_for_duration(), timing_above_threshold()

Examples

N <- 60
# Dataset with epoch = 1min
dataset1 <-
  tibble::tibble(
    Id = rep("A", N),
    Datetime = lubridate::as_datetime(0) + lubridate::minutes(1:N),
    MEDI = sample(c(sample(1:249, N / 2), sample(250:1000, N / 2))),
  )
# Dataset with epoch = 30s
dataset2 <-
  tibble::tibble(
    Id = rep("B", N),
    Datetime = lubridate::as_datetime(0) + lubridate::seconds(seq(30, N * 30, 30)),
    MEDI = sample(c(sample(1:249, N / 2), sample(250:1000, N / 2))),
  )
dataset.combined <- rbind(dataset1, dataset2)

dataset1 %>%
  dplyr::reframe("TAT >250lx" = duration_above_threshold(MEDI, Datetime, threshold = 250))

dataset1 %>%
  dplyr::reframe(duration_above_threshold(MEDI, Datetime, threshold = 250, as.df = TRUE))

# Group by Id to account for different epochs
dataset.combined %>%
  dplyr::group_by(Id) %>%
  dplyr::reframe("TAT >250lx" = duration_above_threshold(MEDI, Datetime, threshold = 250))

Description

This function calculates the total duration of data in each group of a dataset, based on a datetime column and a variable column. It uses the dominant epoch (interval) of each group to calculate the duration.

Usage

durations(
  dataset,
  Variable.colname = Datetime,
  Datetime.colname = Datetime,
  count.NA = FALSE,
  show.missing = FALSE,
  show.interval = FALSE,
  FALSE.as.NA = FALSE
)

Arguments

Value

A tibble with one row per group and a column "duration" containing the duration of each group as a lubridate::duration(). If show.missing = TRUE, a column "missing" is added with the duration of NAs, and a column "total" with the total duration. If show.interval = TRUE, a column "interval" is added with the dominant epoch of each group.

Examples

# Calculate the duration of a dataset
durations(sample.data.environment)

# create artificial gaps in the data
gapped_data <-
sample.data.environment |>
  dplyr::filter(MEDI >= 10) |>
  gap_handler(full.days = TRUE)

#by default, the Datetime column is selected for the `Variable.colname`, 
#basically ignoring NA measurement values
gapped_data |>
 durations(count.NA = TRUE)

# Calculate the duration where MEDI are available
durations(gapped_data, MEDI)

# Calculate the duration, show the duration of NAs separately
durations(gapped_data, MEDI, show.missing = TRUE)

# Calculate the duration, show the dominant epoch
durations(gapped_data, Variable.colname = MEDI, show.interval = TRUE)

# Calculate durations for day and night separately
gapped_data |>
  add_photoperiod(coordinates = c(48.52, 9.06)) |>
  dplyr::group_by(photoperiod.state, .add = TRUE) |>
  durations(Variable.colname = MEDI, show.interval = TRUE, show.missing = TRUE)

Description

This function smoothes the data using an exponential moving average filter with a specified decay half-life.

Usage

exponential_moving_average(
  Light.vector,
  Time.vector,
  decay = "90 min",
  epoch = "dominant.epoch"
)

Arguments

Details

The timeseries is assumed to be regular. Missing values in the light data will be replaced by 0.

Value

A numeric vector containing the smoothed light data. The output has the same length as Light.vector.

References

Price, L. L. A. (2014). On the Role of Exponential Smoothing in Circadian Dosimetry. Photochemistry and Photobiology, 90(5), 1184-1192. doi:10.1111/php.12282

Hartmeyer, S.L., Andersen, M. (2023). Towards a framework for light-dosimetry studies: Quantification metrics. Lighting Research & Technology. doi:10.1177/14771535231170500

See Also

Other metrics: bright_dark_period(), centroidLE(), disparity_index(), dose(), duration_above_threshold(), frequency_crossing_threshold(), interdaily_stability(), intradaily_variability(), midpointCE(), nvRC(), nvRD(), nvRD_cumulative_response(), period_above_threshold(), pulses_above_threshold(), threshold_for_duration(), timing_above_threshold()

Examples

sample.data.environment.EMA = sample.data.environment %>%
  dplyr::filter(Id == "Participant") %>%
  filter_Datetime(length = lubridate::days(2)) %>%
  dplyr::mutate(MEDI.EMA = exponential_moving_average(MEDI, Datetime))

# Plot to compare results
sample.data.environment.EMA %>%
  ggplot2::ggplot(ggplot2::aes(x = Datetime)) +
  ggplot2::geom_line(ggplot2::aes(y = MEDI), colour = "black") +
  ggplot2::geom_line(ggplot2::aes(y = MEDI.EMA), colour = "red")

Description

extract_clusters() searches for and summarizes clusters where data meets a certain condition. Clusters have a specified duration and can be interrupted while still counting as one cluster. The variable can either be a column in the dataset or an expression that gets evaluated in a dplyr::mutate() call.

Cluster start and end times are shifted by half of the epoch each. E.g., a state lasting for 4 measurement points will have a duration of 4 measurement intervals, and a state only occuring once, of one interval. This deviates from simply using the time difference between the first and last occurance, which would be one epoch shorter (e.g., the start and end points for a state lasting a single point is identical, i.e., zero duration)

Groups will not be dropped, meaning that summaries based on the clusters will account for groups without clusters.

For correct cluster identification, there can be no gaps in the data! Gaps can inadvertently be introduced to a gapless dataset through grouping. E.g., when grouping by photoperiod (day/night) within a participant, this introduces gaps between the individual days and nights that together form the group. To avoid this, either group by individual days and nights (e.g., by using number_states() before grouping), which will make sure a cluster cannot extend beyond any grouping. Alternatively, you can set handle.gaps = TRUE (at computational cost).

add_clusters() identifies clusters and adds them back into the dataset through a rolling join. This is a convenience function built on extract_clusters().

Usage

extract_clusters(
  data,
  Variable,
  Datetime.colname = Datetime,
  cluster.duration = "30 mins",
  duration.type = c("min", "max"),
  interruption.duration = 0,
  interruption.type = c("max", "min"),
  cluster.colname = state.count,
  return.only.clusters = TRUE,
  drop.empty.groups = TRUE,
  handle.gaps = FALSE,
  add.label = FALSE
)

add_clusters(
  data,
  Variable,
  Datetime.colname = Datetime,
  cluster.duration = "30 mins",
  duration.type = c("min", "max"),
  interruption.duration = 0,
  interruption.type = c("max", "min"),
  cluster.colname = state,
  handle.gaps = FALSE
)

Arguments

Value

For extract_clusters() a dataframe containing the identified clusters or all time periods, depending on return.only.clusters.

For add_clusters() a dataframe containing the original data with an additional column for cluster identification.

Examples

dataset <-
sample.data.environment |>
dplyr::filter(Id == "Participant") |>
filter_Date(length = "1 day")

# Extract clusters with minimum duration of 1 hour and interruptions of up to 5 minutes
dataset |>
 extract_clusters(
  MEDI > 250,
  cluster.duration = "1 hour",
  interruption.duration = "5 mins"
)

# Add clusters to a dataset where lux values are above 20 for at least 30 minutes
dataset_with_clusters <- 
dataset %>% add_clusters(MEDI > 20)

#peak into the dataset
dataset_with_clusters[4500:4505,]

Description

Finds and extracts gap episodes from a dataset. If no variable is provided, it will look for implicit gaps (gaps in the regular interval), if a variable is provided, it will look for implicit and explicit gaps (NA in the variable)

Usage

extract_gaps(
  dataset,
  Variable.colname = NULL,
  Datetime.colname = Datetime,
  epoch = "dominant.epoch",
  full.days = TRUE,
  include.implicit.gaps = TRUE
)

Arguments

Value

A dataframe containing gap times per grouping variable

See Also

Other regularize: dominant_epoch(), gap_finder(), gap_handler(), gapless_Datetimes(), has_gaps(), has_irregulars()

Examples

#removing some data to create gaps
sample.data.environment |> 
 dplyr::filter(MEDI <= 50000) |> 
 extract_gaps() |> head()

#not searching for implicit gaps
sample.data.environment |> 
  dplyr::filter(MEDI <= 50000) |> 
 extract_gaps(MEDI, include.implicit.gaps = FALSE)

#making implicit gaps explicit changes the summary
sample.data.environment |> 
  dplyr::filter(MEDI <= 50000) |> 
  gap_handler()|> 
  extract_gaps(MEDI, include.implicit.gaps = FALSE) |> head()

Description

This helper function adds metric values to an extract, like from extract_states() or extract_clusters(). E.g., the average value of a variable during a cluster or state instance might be of interest. The metrics must be specified by the user using the ... argument.

Usage

extract_metric(
  extracted_data,
  data,
  identifying.colname = state.count,
  Datetime.colname = Datetime,
  ...
)

Arguments

Details

The original data does not have to have the cluster/state information, but it will be computationally faster if it does.

Value

A dataframe containing the extracted data with added metrics.

Examples

# Extract clusters and add mean MEDI value
sample.data.environment |>
filter_Date(length = "2 days") |> 
extract_clusters(MEDI > 1000) |>
extract_metric(
  sample.data.environment,
  "mean_medi" = mean(MEDI, na.rm = TRUE)
) |>
dplyr::select(Id, state.count, duration, mean_medi)

# Extract states and add mean MEDI value
dataset <-
sample.data.environment |>
filter_Date(length = "2 days") |> 
 add_photoperiod(c(48.5, 9))

dataset |>
  extract_states(photoperiod.state) |>
  extract_metric(dataset, mean_lux = mean(MEDI)) |>
  dplyr::select(state.count, duration, mean_lux)

Description

Extracts a state from a dataset and provides their start and end times, as well as duration and epoch. The state does not have to exist in the dataset, but can be dynamically created. Extracted states can have group-dropping disabled, meaning that summaries based on the extracted states show empty groups as well.

Usage

extract_states(
  data,
  State.colname,
  State.expression = NULL,
  Datetime.colname = Datetime,
  handle.gaps = FALSE,
  epoch = "dominant.epoch",
  drop.empty.groups = TRUE,
  group.by.state = TRUE
)

Arguments

Value

a dataframe with one row per state instance. Each row will consist of the original dataset grouping, the state column. A state.count column, start and end Datetimes, as well as a duration of the state

Examples

#summarizing states "photoperiod"
states <-
sample.data.environment |>
  add_photoperiod(c(48.52, 9.06)) |>
  extract_states(photoperiod.state)
states |> head(2)
states |> tail(2)
states |> summarize_numeric(c("state.count", "epoch"))

Description

Filtering a dataset based on Dates or Datetimes may often be necessary prior to calcuation or visualization. The functions allow for a filtering based on simple strings or Datetime scalars, or by specifying a length. They also support prior dplyr grouping, which is useful, e.g., when you only want to filter the first two days of measurement data for every participant, regardless of the actual date. If you want to filter based on times of the day, look to filter_Time().

Usage

filter_Datetime(
  dataset,
  length = NULL,
  start = NULL,
  end = NULL,
  length_from_start = TRUE,
  full.day = FALSE,
  only_Id = NULL,
  filter.expr = NULL,
  Datetime.colname = Datetime,
  tz = NULL
)

filter_Date(..., start = NULL, end = NULL)

Arguments

Value

a data.frame object identical to dataset but with only the specified Dates/Times.

See Also

Other filter: filter_Time()

Other filter: filter_Time()

Examples

library(lubridate)
library(dplyr)
#baseline
range.unfiltered <- sample.data.environment$Datetime %>% range()
range.unfiltered

#setting the start of a dataset
sample.data.environment %>%
filter_Datetime(start = "2023-08-31 12:00:00") %>%
pull(Datetime) %>%
range()

#setting the end of a dataset
sample.data.environment %>%
filter_Datetime(end = "2023-08-31 12:00:00") %>% pull(Datetime) %>% range()

#setting a period of a dataset
sample.data.environment %>%
filter_Datetime(end = "2023-08-31 12:00:00", length = days(2)) %>%
pull(Datetime) %>% range()

#setting only the period of a dataset
sample.data.environment %>%
filter_Datetime(length = days(2)) %>%
pull(Datetime) %>% range()

#advanced filtering based on grouping (second day of each group)
sample.data.environment %>%
#shift the "Environment" group by one day
mutate(
Datetime = ifelse(Id == "Environment", Datetime + ddays(1), Datetime) %>%
as_datetime()) -> sample
sample %>% summarize(Daterange = paste(min(Datetime), max(Datetime), sep = " - "))
#now we can use the `filter.expr` argument to filter from the second day of each group
sample %>%
filter_Datetime(filter.expr = Datetime > Datetime[1] + days(1)) %>%
summarize(Daterange = paste(min(Datetime), max(Datetime), sep = " - "))

sample.data.environment %>% filter_Date(end = "2023-08-31")

Description

filter_Datetime_multiple() is a wrapper around filter_Datetime() or filter_Date() that allows the cumulative filtering of Datetimes based on varying filter conditions. It is most useful in conjunction with the only_Id argument, e.g., to selectively cut off dates depending on participants (see examples)

Usage

filter_Datetime_multiple(
  dataset,
  arguments,
  filter_function = filter_Datetime,
  ...
)

Arguments

Value

A dataframe with the filtered data

Examples

arguments <- list(
 list(start = "2023-08-31", only_Id = quote(Id == "Participant")),
 list(end = "2023-08-31", only_Id = quote(Id == "Environment")))
 #compare the unfiltered dataset
 sample.data.environment %>% gg_overview(Id.colname = Id)
 #compare the unfiltered dataset
 sample.data.environment %>%
 filter_Datetime_multiple(arguments = arguments, filter_Date) %>%
 gg_overview(Id.colname = Id)

Description

Filter Times in a dataset.

Usage

filter_Time(
  dataset,
  Datetime.colname = Datetime,
  start = NULL,
  end = NULL,
  length = NULL
)

Arguments

Value

a data.frame object identical to dataset but with only the specified Times.

See Also

Other filter: filter_Datetime()

Examples

sample.data.environment %>%
filter_Time(start = "4:00:34", length = "12:00:00") %>%
dplyr::pull(Time) %>% range() %>% hms::as_hms()

Description

Create a concise latitude/longitude label (e.g., $48.5^\circ N, 9.1^\circ E$) from a two element coordinate vector.

Usage

format_coordinates(coordinates, digits = 1)

Arguments

Value

A character scalar with the formatted coordinate string.

Examples

# Coordinates for Tuebingen, Germany
format_coordinates(c(48.5216, 9.0576))

Description

This functions calculates the number of times a given threshold light level is crossed.

Usage

frequency_crossing_threshold(
  Light.vector,
  threshold,
  na.rm = FALSE,
  as.df = FALSE
)

Arguments

Value

Data frame or matrix with pairs of threshold and calculated values.

References

Alvarez, A. A., & Wildsoet, C. F. (2013). Quantifying light exposure patterns in young adult students. Journal of Modern Optics, 60(14), 1200–1208. doi:10.1080/09500340.2013.845700

Hartmeyer, S.L., Andersen, M. (2023). Towards a framework for light-dosimetry studies: Quantification metrics. Lighting Research & Technology. doi:10.1177/14771535231170500

See Also

Other metrics: bright_dark_period(), centroidLE(), disparity_index(), dose(), duration_above_threshold(), exponential_moving_average(), interdaily_stability(), intradaily_variability(), midpointCE(), nvRC(), nvRD(), nvRD_cumulative_response(), period_above_threshold(), pulses_above_threshold(), threshold_for_duration(), timing_above_threshold()

Examples

N = 60
dataset1 <-
  tibble::tibble(
    Id = rep("A", N),
    Datetime = lubridate::as_datetime(0) + lubridate::minutes(1:N),
    MEDI = sample(c(sample(1:249, N / 2), sample(250:1000, N / 2))),
  )

dataset1 %>%
  dplyr::reframe("Frequency crossing 250lx" = frequency_crossing_threshold(MEDI, threshold = 250))

dataset1 %>%
  dplyr::reframe(frequency_crossing_threshold(MEDI, threshold = 250, as.df = TRUE))

Description

A list of tables containing gain and gain-ratios to normalize counts across different sensor gains.

Usage

gain.ratio.tables

Format

gain.ratio.tables A list containing two-column tibbles

TSL2585

gain table for the ambient light sensor TSL2585

Info

A named character vector specifying the version and date a sensor was added

Details

Utility: Some sensors provide raw counts and gain levels as part of their output. In some cases it is desirable to compare counts between sensors, e.g., to gauge daylight outside by comparing UV counts to photopic counts (a high ratio of UV/Pho indicates outside daylight). Or to gauge daylight inside by comparing IR counts to photopic counts (a high ratio of IR/Pho with a low ratio of UV/Pho indicates daylight in the context of LED or fluorescent lighting)

Description

Quickly check for implicit missing Datetime data. Outputs a message with a short summary, and can optionally return the gaps as a tibble. Uses gap_handler() internally.

Usage

gap_finder(
  dataset,
  Datetime.colname = Datetime,
  epoch = "dominant.epoch",
  gap.data = FALSE,
  silent = FALSE,
  full.days = FALSE
)

Arguments

Details

The gap_finder() function is a wrapper around gap_handler() with the behavior argument set to "gaps". The main difference is that gap_finder() returns a message with a short summary of the gaps in the dataset, and that the tibble with the gaps contains a column gap.id that indicates the gap number, which is useful to determine, e.g., the consecutive number of gaps between measurement data.

Value

Prints message with a short summary of the gaps in the dataset. If gap.data = TRUE, returns a tibble of the gaps in the dataset.

See Also

Other regularize: dominant_epoch(), extract_gaps(), gap_handler(), gapless_Datetimes(), has_gaps(), has_irregulars()

Examples

dataset <-
tibble::tibble(Id = c("A", "A", "A", "B", "B", "B"),
              Datetime = lubridate::as_datetime(1) +
                         lubridate::days(c(0:2, 4, 6, 8)) +
                         lubridate::hours(c(0,12,rep(0,4)))) %>%
dplyr::group_by(Id)
dataset

#look for gaps assuming the epoch is the dominant epoch of each group
gap_finder(dataset)

#return the gaps as a tibble
gap_finder(dataset, gap.data = TRUE)

#assuming the epoch is 1 day, we have different gaps, and the datapoint at noon is now `irregular`
gap_finder(dataset, epoch = "1 day")

Description

Datasets from light loggers often have implicit gaps. These gaps are implicit in the sense that consecutive timestamps (Datetimes) might not follow a regular epoch/interval. This function fills these implicit gaps by creating a gapless sequence of Datetimes and joining it to the dataset. The gapless sequence is determined by the minimum and maximum Datetime in the dataset (per group) and an epoch. The epoch can either be guessed from the dataset or specified by the user. A sequence of gapless Datetimes can be created with the gapless_Datetimes() function, whereas the dominant epoch in the data can be checked with the dominant_epoch() function. The behaviour argument specifies how the data is combined. By default, the data is joined with a full join, which means that all rows from the gapless sequence are kept, even if there is no matching row in the dataset.

Usage

gap_handler(
  dataset,
  Datetime.colname = Datetime,
  epoch = "dominant.epoch",
  behavior = c("full_sequence", "regulars", "irregulars", "gaps"),
  full.days = FALSE
)

Arguments

Value

A modified tibble similar to dataset but with handling of implicit gaps, depending on the behavior argument:

• "full_sequence" adds timestamps to the dataset that are missing based on a full sequence of Datetimes (i.e., the gapless sequence). The dataset is this equal (no gaps) or greater in the number of rows than the input. One column is added. is.implicit indicates whether the row was added (TRUE) or not (FALSE). This helps differentiating measurement values from values that might be imputed later on.

• "regulars" keeps only rows from the gapless sequence that have a matching row in the dataset. This can be interpreted as a row-reduced dataset with only regular timestamps according to the epoch. In case of no gaps this tibble has the same number of rows as the input.

• "irregulars" keeps only rows from the dataset that do not follow the regular sequence of Datetimes according to the epoch. In case of no gaps this tibble has 0 rows.

• "gaps" returns a tibble of all implicit gaps in the dataset. In case of no gaps this tibble has 0 rows.

See Also

Other regularize: dominant_epoch(), extract_gaps(), gap_finder(), gapless_Datetimes(), has_gaps(), has_irregulars()

Examples

dataset <-
tibble::tibble(Id = c("A", "A", "A", "B", "B", "B"),
              Datetime = lubridate::as_datetime(1) +
                         lubridate::days(c(0:2, 4, 6, 8)) +
                         lubridate::hours(c(0,12,rep(0,4)))) %>% 
dplyr::group_by(Id)
dataset
#assuming the epoch is 1 day, we can add implicit data to our dataset
dataset %>% gap_handler(epoch = "1 day")

#we can also check whether there are irregular Datetimes in our dataset
dataset %>% gap_handler(epoch = "1 day", behavior = "irregulars")

#to get to the gaps, we can use the "gaps" behavior
dataset %>% gap_handler(epoch = "1 day", behavior = "gaps")
 
#finally, we can also get just the regular Datetimes
dataset %>% gap_handler(epoch = "1 day", behavior = "regulars")

Description

gap_table() creates a gt::gt() with one row per group, summarizing key gap and gap-related information about the dataset. These include the available data, total duration, number of gaps, missing implicit and explicit data, and, optionally, irregular data.

Usage

gap_table(
  dataset,
  Variable.colname = MEDI,
  Variable.label = "melanopic EDI",
  title = "Summary of available and missing data",
  Datetime.colname = Datetime,
  epoch = "dominant.epoch",
  full.days = TRUE,
  include.implicit.gaps = TRUE,
  check.irregular = TRUE,
  get.df = FALSE
)

Arguments

Value

A gt table about data and gaps in the dataset

Examples

sample.data.environment |> dplyr::filter(MEDI <= 50000) |> gap_table()

Description

Create a gapless sequence of Datetimes. The Datetimes are determined by the minimum and maximum Datetime in the dataset and an epoch. The epoch can either be guessed from the dataset or specified by the user.

Usage

gapless_Datetimes(
  dataset,
  Datetime.colname = Datetime,
  epoch = "dominant.epoch",
  full.days = FALSE
)

Arguments

Value

A tibble with a gapless sequence of Datetime as specified by epoch.

See Also

Other regularize: dominant_epoch(), extract_gaps(), gap_finder(), gap_handler(), has_gaps(), has_irregulars()

Examples

dataset <-
  tibble::tibble(Id = c("A", "A", "A", "B", "B", "B"),
                 Datetime = lubridate::as_datetime(1) +
                 lubridate::days(c(0:2, 4, 6, 8))) %>%
                 dplyr::group_by(Id)

  dataset %>% gapless_Datetimes()
  dataset %>% dplyr::ungroup() %>%  gapless_Datetimes()
  dataset %>% gapless_Datetimes(epoch = "1 day")

Description

gg_day() will create a simple ggplot for every data in a dataset. The result can further be manipulated like any ggplot. This will be sensible to refine styling or guides.

Usage

gg_day(
  dataset,
  y.axis = MEDI,
  geom = "point",
  start.date = NULL,
  end.date = NULL,
  x.axis = Datetime,
  aes_col = NULL,
  aes_fill = NULL,
  group = Id,
  scales = c("fixed", "free_x", "free_y", "free"),
  x.axis.breaks = hms::hms(hours = seq(0, 24, by = 3)),
  y.axis.breaks = c(-10^(5:0), 0, 10^(0:5)),
  y.scale = "symlog",
  y.scale.sc = FALSE,
  x.axis.label = "Local time (HH:MM)",
  y.axis.label = "Melanopic EDI (lx)",
  format.day = "%d/%m",
  title = NULL,
  subtitle = NULL,
  interactive = FALSE,
  facetting = TRUE,
  jco_color = TRUE,
  ...
)

Arguments

Details

Besides plotting, the function creates two new variables from the given Datetime:

• Day.data is a factor that is used for facetting with ggplot2::facet_wrap(). Make sure to use this variable, if you change the faceting manually. Also, the function checks, whether this variable already exists. If it does, it will only convert it to a factor and do the faceting on that variable.

• Time is an hms created with hms::as_hms() that is used for the x.axis

The default scaling of the y-axis is a symlog scale, which is a logarithmic scale that only starts scaling after a given threshold (default = 0). This enables values of 0 in the plot, which are common in light logger data, and even enables negative values, which might be sensible for non-light data. See symlog_trans() for details on tweaking this scale. The scale can also be changed to a normal or logarithmic scale - see the y.scale argument for more.

The default scaling of the color and fill scales is discrete, with the ggsci::scale_color_jco() and ggsci::scale_fill_jco() scales. To use a continuous scale, use the jco_color = FALSE setting. Both fill and color aesthetics are set to NULL by default. For most geoms, this is not important, but geoms that automatically use those aesthetics (like geom_bin2d, where fill = stat(count)) are affected by this. Manually adding the required aesthetic (like aes_fill = ggplot2::stat(count) will fix this).

Value

A ggplot object

Examples

#use `col`for separation of different sets
plot <- gg_day(
sample.data.environment,
scales = "fixed",
end.date = "2023-08-31",
y.axis.label = "mEDI (lx)",
aes_col = Id)
plot

#you can easily overwrite the color scale afterwards
plot + ggplot2::scale_color_discrete()

#or change the facetting
plot + ggplot2::facet_wrap(~Day.data + Id)

Description

gg_days() will create a simple ggplot along the timeline. The result can further be manipulated like any ggplot. This will be sensible to refine styling or guides. Through the x.axis.limits arguments, the plot can be much refined to align several groups of differing datetime ranges. It uses the Datetime_limits() function to calculate the limits of the x-axis. Another notable functions that are used are Datetime_breaks() to calculate the breaks of the x-axis.

Usage

gg_days(
  dataset,
  y.axis = MEDI,
  geom = "line",
  x.axis = Datetime,
  aes_col = NULL,
  aes_fill = NULL,
  group = NULL,
  scales = c("free_x", "free_y", "fixed", "free"),
  x.axis.breaks = Datetime_breaks,
  y.axis.breaks = c(-10^(5:0), 0, 10^(0:5)),
  y.scale = "symlog",
  y.scale.sc = FALSE,
  x.axis.label = "Local date/time",
  y.axis.label = "Melanopic EDI (lx)",
  x.axis.limits = Datetime_limits,
  x.axis.format = "%a %D",
  title = NULL,
  subtitle = NULL,
  interactive = FALSE,
  facetting = TRUE,
  jco_color = TRUE,
  ...
)

Arguments

Details

The default scaling of the y-axis is a symlog scale, which is a logarithmic scale that only starts scaling after a given threshold (default = 0). This enables values of 0 in the plot, which are common in light logger data, and even enables negative values, which might be sensible for non-light data. See symlog_trans() for details on tweaking this scale. The scale can also be changed to a normal or logarithmic scale - see the y.scale argument for more.

Value

A ggplot object

Examples

dataset <-
sample.data.environment %>%
aggregate_Datetime(unit = "5 mins")

dataset %>% gg_days()
#restrict the x-axis to 3 days
dataset %>%
gg_days(
x.axis.limits = \(x) Datetime_limits(x, length = lubridate::ddays(3))
)

Description

The function is by default opinionated, and will automatically select the best way to display the double date plot. However, the user can also manually select the type of double date plot to be displayed: repeating each day (default when there is only one day in all of the groups), or displaying consecutive days (default when there are multiple days in the groups).

Usage

gg_doubleplot(
  dataset,
  Datetime.colname = Datetime,
  type = c("auto", "repeat", "next"),
  geom = "ribbon",
  alpha = 0.5,
  col = "grey40",
  fill = "#EFC000FF",
  linewidth = 0.4,
  x.axis.breaks.next = Datetime_breaks,
  x.axis.format.next = "%a %D",
  x.axis.breaks.repeat = ~Datetime_breaks(.x, by = "6 hours", shift =
    lubridate::duration(0, "hours")),
  x.axis.format.repeat = "%H:%M",
  ...
)

Arguments

Details

gg_doubleplot() is a wrapper function for gg_days(), combined with an internal function to duplicate and reorganize dates in a dataset for a double plot view. This means that the same day is displayed multiple times within the plot in order to reveal pattern across days.

Value

a ggplot object

Examples

#take only the Participant data from sample data, and three days
library(dplyr)
library(lubridate)
library(ggplot2)
sample.data <- 
sample.data.environment %>% 
dplyr::filter(Id == "Participant") %>% 
filter_Date(length = ddays(3))

#create a double plot with the default settings
sample.data %>% gg_doubleplot()

#repeat the same day in the plot
sample.data %>% gg_doubleplot(type = "repeat")

#more examples that are not executed for computation time:

#use the function with more than one Id
sample.data.environment %>% 
filter_Date(length = ddays(3)) %>% 
gg_doubleplot(aes_fill = Id, aes_col = Id) +
facet_wrap(~ Date.data, ncol = 1, scales = "free_x", strip.position = "left")

#if data is already grouped by days, type = "repeat" will be automatic
sample.data.environment %>% 
dplyr::group_by(Date = date(Datetime), .add = TRUE) %>% 
filter_Date(length = ddays(3)) %>% 
gg_doubleplot(aes_fill = Id, aes_col = Id) + 
guides(fill = "none", col = "none") + #remove the legend
facet_wrap(~ Date.data, ncol = 1, scales = "free_x", strip.position = "left")

#combining `aggregate_Date()` with `gg_doubleplot()` easily creates a good
#overview of the data
sample.data.environment %>%
aggregate_Date() %>%
gg_doubleplot()

Description

gg_gaps() is built upon gg_days(), gap_finder(), and gg_states() to visualize where gaps and irregular data in a dataset are. The function does not differentiate between ⁠implicit gaps⁠, which are missing timestamps of the regular interval, ⁠explicit gaps⁠, which are NA values. Optionally, the function shows ⁠irregular data⁠, which are datapoints that fall outside the regular interval.

Usage

gg_gaps(
  dataset,
  Variable.colname = MEDI,
  Datetime.colname = Datetime,
  fill.gaps = "red",
  col.irregular = "red",
  alpha = 0.5,
  on.top = FALSE,
  epoch = "dominant.epoch",
  full.days = TRUE,
  show.irregulars = FALSE,
  group.by.days = FALSE,
  include.implicit.gaps = TRUE,
  ...
)

Arguments

Value

a ggplot object with all gaps and optionally irregular data. Groups that do not have any gaps nor irregular data will be removed for clarity. Null if no groups remain

Examples

#calling gg_gaps on a healthy dataset is pointless
sample.data.environment |> gg_gaps()

#creating a gapped and irregular dataset
bad_dataset <-
sample.data.environment |>
  aggregate_Datetime(unit = "5 mins") |>
  dplyr::filter(Id == "Participant") |> 
  filter_Date(length = "2 days") |>
  dplyr::mutate(
   Datetime = dplyr::if_else(
     lubridate::date(Datetime) == max(lubridate::date(Datetime)),
           Datetime, Datetime + 1
     )
   ) |>
dplyr::filter(MEDI <250)
bad_dataset |> has_gaps()
bad_dataset |> has_irregulars()

#by default, gg_gaps() only shows gaps
bad_dataset |> gg_gaps()

#it can also show irregular data
bad_dataset |> gg_gaps(show.irregulars = TRUE)

Description

This function plots a heatmap of binned values across the day over all days in a group. It also allows doubleplot functionality. **gg_heatmap() does not work with the additive functions gg_photoperiod() and gg_states().

Usage

gg_heatmap(
  dataset,
  Variable.colname = MEDI,
  Datetime.colname = Datetime,
  unit = "1 hour",
  doubleplot = c("no", "same", "next"),
  date.title = "Date",
  date.breaks = 1,
  date.labels = "%d/%m",
  time.title = "Local time (HH:MM)",
  time.breaks = hms::hms(hours = seq(0, 48, by = 6)),
  time.labels = "%H:%M",
  fill.title = "Melanopic EDI (lx)",
  fill.scale = "symlog",
  fill.labels = function(x) format(x, scientific = FALSE, big.mark = " "),
  fill.breaks = c(-10^(5:0), 0, 10^(0:5)),
  fill.limits = c(0, 10^5),
  fill.remove = FALSE,
  facetting = TRUE,
  ...
)

Arguments

Details

The function uses ggplot2::scale_fill_viridis_c() for the fill scale. The scale can be substituted by any other scale via the standard + command of ggplot2. It is recommended to set fill.remove = TRUE to reduce warnings.

Value

A ggplot object

Examples

sample.data.environment |> gg_heatmap()

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

#change the unit of aggregation
sample.data.environment |> gg_heatmap(unit = "5 mins")

#change the limits of the fill scale
sample.data.environment |> gg_heatmap(fill.limits = c(0, 10^4))

Description

Plot an overview of dataset intervals with implicit missing data

Usage

gg_overview(
  dataset,
  Datetime.colname = Datetime,
  Id.colname = Id,
  gap.data = NULL,
  ...,
  interactive = FALSE
)

Arguments