Midpoint of cumulative light exposure.

This function calculates the timing corresponding to half of the cumulative light exposure within the given time series.

Usage

midpointCE(Light.vector, Time.vector, 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.

na.rm

Logical. Should missing values be removed for the calculation? If TRUE, missing values will be replaced by zero. Defaults to FALSE.

as.df

Logical. Should the output be returned as a data frame? If TRUE, a data frame with a single column named midpointCE will be returned. Defaults to FALSE.

Value

Single column data frame or vector.

References

Shochat, T., Santhi, N., Herer, P., Flavell, S. A., Skeldon, A. C., & Dijk, D.-J. (2019). Sleep Timing in Late Autumn and Late Spring Associates With Light Exposure Rather Than Sun Time in College Students. Frontiers in Neuroscience, 13. doi:10.3389/fnins.2019.00882

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(), 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 = c(rep(1, 6), rep(250, 13), rep(1, 5))
  )
dataset1 %>%
  dplyr::reframe(
    "Midpoint of cmulative exposure" = midpointCE(MEDI, Datetime)
  )
#> # A tibble: 1 × 1
#>   `Midpoint of cmulative exposure`
#>   <dttm>                          
#> 1 1970-01-01 11:00:00             

# 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(
    "Midpoint of cmulative exposure" = midpointCE(MEDI, Time)
  )
#> # A tibble: 1 × 1
#>   `Midpoint of cmulative exposure`
#>   <time>                          
#> 1 11:00                           

# 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(
    "Midpoint of cmulative exposure" = midpointCE(MEDI, Hour)
  )
#> # A tibble: 1 × 1
#>   `Midpoint of cmulative exposure`
#>   <Duration>                      
#> 1 39600s (~11 hours)