pulses_above_threshold: Pulses above threshold

In steffenhartmeyer/lightdosimetry: Functions for quantifying personal light exposure data

Pulses above threshold

Description

This function clusters the light data into continuous clusters (pulses) of light above/below a given threshold. Clustering may be fine-tuned by setting the minimum length of the clusters and by allowing brief interruptions to be included in a single cluster, with a specified maximum length of interruption episodes and proportion of total amount of interruptions to light above threshold.

Usage

pulses_above_threshold(
  lightVar,
  timeVar,
  threshold,
  min_length = 0,
  max_interrupt = 0,
  prop_interrupt = 0,
  unit_pulse_length = "mins",
  return_indices = FALSE,
  loop = FALSE,
  as_df = TRUE,
  wide = TRUE
)

Arguments

lightVar	Numeric vector containing the light data. Missing values are replaced by 0.
timeVar	Vector containing the time data. Can be POSIXct or numeric. Must be regularly spaced.
threshold	Single numeric value or vector specifying threshold intensities. The sign indicates above/below (see threshold).
min_length	Minimum length of each cluster. Can be numeric or string in the format "[numeric] [unit]", with possible units ("seconds","minutes", "hours","days"). Units can be abbreviated, see parse_timeunit_tosecs. Defaults to 0.
max_interrupt	Maximum length of each episode of interruptions. Can be numeric or string in the format "[numeric] [unit]", with possible units ("seconds","minutes","hours","days"). Units can be abbreviated, see parse_timeunit_tosecs. Defaults to 0.
prop_interrupt	Single numeric value between [0, 1] specifying the maximum proportion of the total number of interruptions to light above threshold. Defaults to 0.
unit_pulse_length	Character. Time unit of pulse length metric. Possible values are ("seconds", "minutes", "hours", "days"), which can be abbreviated. Defaults to "minutes".
return_indices	Logical. Should the cluster indices be returned? Defaults to FALSE.
loop	Logical. Should the data be looped? Defaults to FALSE.
as_df	Logical. Should the output be returned as a data frame? Defaults to TRUE.
wide	Logical. Should the output be returned in wide format? Defaults to TRUE.

Value

Data frame or matrix with pairs of threshold and calculated values. If 'wide' is TRUE then variable names will be concatenated with the threshold. If 'return_indices' is TRUE then a list with the data frame and a list of cluster indices will be returned.

References

Wilson, J., Reid, K. J., Braun, R. I., Abbott, S. M., & Zee, P. C. (2018). Habitual light exposure relative to circadian timing in delayed sleep-wake phase disorder. Sleep, 41(11). https://doi.org/10.1093/sleep/zsy166

steffenhartmeyer/lightdosimetry documentation built on Jan. 29, 2024, 12:48 p.m.