bright_dark_period: Brightest or darkest continuous period

In LightLogR: Process Data from Wearable Light Loggers and Optical Radiation Dosimeters

Brightest or darkest continuous period

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

Light.vector	Numeric vector containing the light data.
Time.vector	Vector containing the time data. Can be POSIXct, hms, duration, or difftime.
period	String indicating the type of period to look for. Can be either "brightest"(the default) or "darkest".
timespan	The timespan across which to calculate. Can be either a duration or a duration string, e.g., "1 day" or "10 sec".
epoch	The epoch at which the data was sampled. Can be either a duration or a string. If it is a string, it needs to be either "dominant.epoch" (the default) for a guess based on the data, or a valid duration string, e.g., "1 day" or "10 sec".
loop	Logical. Should the data be looped? If TRUE, a full copy of the data will be concatenated at the end of the data. Makes only sense for 24 h data. Defaults to FALSE.
na.rm	Logical. Should missing values be removed for the calculation? Defaults to FALSE.
as.df	Logical. Should the output be returned as a data frame? Defaults to TRUE.

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. \Sexpr[results=rd]{tools:::Rd_expr_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))

LightLogR documentation built on June 10, 2025, 5:12 p.m.