Skip to contents

Mean/first/last timing above/below threshold.

Source: R/metric_timing_above_threshold.R
timing_above_threshold.Rd

This function calculates the mean, first, and last timepoint (MLiT, FLiT, LLiT) where light levels are above or below a given threshold intensity within the given time interval.

Usage

timing_above_threshold(
  Light.vector,
  Time.vector,
  comparison = c("above", "below"),
  threshold,
  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.

comparison

String specifying whether the time above or below threshold should be calculated. Can be either "above" (the default) or "below". If two values are provided for threshold, this argument will be ignored.

threshold

Single numeric value or two numeric values specifying the threshold light level(s) to compare with. If a vector with two values is provided, the timing corresponding to light levels between the two thresholds will be calculated.

na.rm

Logical. Should missing values be removed for the calculation? Defaults to FALSE.

as.df

Logical. Should a data frame be returned? If TRUE, a data frame with three columns (MLiT, FLiT, LLiT) and the threshold (e.g., MLiT_{threshold}) will be returned. Defaults to FALSE.

Value

List or dataframe with the three values: mean, first, and last timing above threshold. 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 and numeric.

References

Reid, K. J., Santostasi, G., Baron, K. G., Wilson, J., Kang, J., & Zee, P. C. (2014). Timing and Intensity of Light Correlate with Body Weight in Adults. PLOS ONE, 9(4), e92251. doi:10.1371/journal.pone.0092251

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(), frequency_crossing_threshold(), interdaily_stability(), intradaily_variability(), midpointCE(), nvRC(), nvRD(), nvRD_cumulative_response(), period_above_threshold(), pulses_above_threshold(), threshold_for_duration()

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

# Above threshold
dataset1 %>%
  dplyr::reframe(timing_above_threshold(MEDI, Datetime, "above", 250, as.df = TRUE))
#> # A tibble: 1 × 3
#>   mean_timing_above_250 first_timing_above_250 last_timing_above_250
#>   <dttm>                <dttm>                 <dttm>               
#> 1 1970-01-01 12:00:00   1970-01-01 06:00:00    1970-01-01 18:00:00  

# Below threshold
dataset1 %>%
  dplyr::reframe(timing_above_threshold(MEDI, Datetime, "below", 10, as.df = TRUE))
#> # A tibble: 1 × 3
#>   mean_timing_below_10 first_timing_below_10 last_timing_below_10
#>   <dttm>               <dttm>                <dttm>              
#> 1 1970-01-01 10:54:33  1970-01-01 00:00:00   1970-01-01 23:00:00 

# Input = HMS -> Output = HMS
dataset1 %>%
  dplyr::reframe(timing_above_threshold(MEDI, hms::as_hms(Datetime), "above", 250, as.df = TRUE))
#> # A tibble: 1 × 3
#>   mean_timing_above_250 first_timing_above_250 last_timing_above_250
#>   <time>                <time>                 <time>               
#> 1 12:00                 06:00                  18:00