Skip to contents

Calculate Dim-Light Melatonin Onset (DLMO)

Source: R/calculate_dlmo.R
calculate_dlmo.Rd

This function calculates the DLMO time point based on input melatonin concentration data with an associated time series. The user can provide data directly as a data frame or specify a .csv file to load the data.

Usage

calculate_dlmo(
  data = NULL,
  file_path = NULL,
  threshold = 2.3,
  interval_limit = lubridate::hours(2),
  fine_flag = TRUE
)

Arguments

data

A data frame with columns datetime (POSIXct) and melatonin (numeric). If NULL, use the file_path parameter to load data.

file_path

A string specifying the path to a CSV file containing the data. The file must have two columns: datetime (POSIXct) and melatonin (numeric).

threshold

The numeric melatonin threshold for defining DLMO (default: 2.3 pg/mL).

interval_limit

Numeric or lubridate duration. Indicates the time window within which repeated melatonin threshold crossings are treated as part of the same rise event. When multiple candidate rises occur within this window, the later crossing is taken to represent the melatonin rise. Single-point excursions above threshold that immediately return below threshold are treated as blips and ignored automatically. Excursions with more than one consecutive above-threshold point are treated as candidate rises; if a later rise should be preferred, set interval_limit large enough to include both candidate rise starts. The interval is measured between the start times of candidate rises, not from when the earlier excursion falls back below threshold. For example, if an early candidate rise starts at 12:00 and a later sustained rise starts at 22:00, the relevant interval is 10 hours. If provided as a numeric value, it represents the window in hours (e.g., interval_limit = 2 for 2 hours, or interval_limit = 0.5 for 30 minutes). Alternatively, users can specify a lubridate duration object (e.g., lubridate::hours(2) for 2 hours, lubridate::minutes(30) for 30 minutes). Default is 2 hours.

fine_flag

Logical. If TRUE, performs an additional fine-grid search to refine the DLMO point after the initial coarse search (default: TRUE).

Value

A list containing the following elements:

  • prof: A tibble containing the segmented melatonin profile.

    • datetime (POSIXct): Timestamps of melatonin measurements.

    • melatonin (numeric): Melatonin concentration values.

    • time (hms): Time of day.

    • slope (numeric): Rate of change in melatonin concentration.

    • base (binary, 0/1): Indicates baseline segment.

    • ascending (binary, 0/1): Indicates ascending segment.

    • intermediate (binary, 0/1): if present, indicates intermediate segment.

  • prl: List containing parallelogram rule fit paramters.

    • pll_datetime_0 (POSIXct): Estimated lower bound of melatonin rise.

    • pll_datetime_1 (POSIXct): Estimated upper bound of melatonin rise.

    • pll_slope (numeric): Slope of melatonin rise.

    • corners (list): Coordinates of parallelogram corners:

      • ll, lr, ur, ul (numeric vectors): (x, y) for each corner.

    • flag (logical): Whether parallelogram rule was violated or not.

  • roi: List defining the Region of Interest (ROI).

    • x_start (POSIXct): Start time of the ROI window.

    • x_end (POSIXct): End time of the ROI window.

    • y_min (numeric): Minimum melatonin value in the ROI.

    • y_max (numeric): Maximum melatonin value in the ROI.

  • threshold: Numeric. The melatonin threshold used for the DLMO calculation.

  • interval_limit: lubridate duration. The interval-limit setting used for repeated threshold-crossing selection.

  • ip: List containing estimated DLMO inflection point.

    • inflection_point (tibble):

      • x (numeric): Estimated DLMO time index in units of decimal-hours.

      • y (numeric): Melatonin concentration at DLMO.

    • base_params (numeric): Parameter for linear-fit of base segment of profile.

    • ascending_params (list): Parameters for the linear or parabolic fit of melatonin rise:

      • a, b, c (numeric): Fitted parameters.

  • dlmo_time: Estimated DLMO time-stamp in units of hh:mm:ss

  • dlmoplotcoarse: ggplot object visualizing melatonin profile (coarse view).

  • dlmoplotfine: ggplot object visualizing melatonin profile (fine view).

Details

Understanding the Outputs:

  • The prof tibble contains labeled data for different melatonin profile phases.

  • The prl list provides the parallelogram rule fit used to trim the melatonin rise segment of the profile to ensure only strong rises are fit when determining DLMO.

  • The roi specifies the bounds of the search window used for DLMO determination.

  • The threshold value records the melatonin concentration threshold used for the calculation.

  • The interval_limit value records the repeated-crossing time window used for ascending-segment selection, stored as a lubridate duration.

  • The ip list contains the DLMO inflection point, the fit parameters for the base and ascending regions, as well as the grid of residuals from fitting the melatonin profile at each point of the ROI.

  • The dlmo_time variable contains the DLMO timestamp in units of hh:mm:ss (equivalent to ip$inflection_point$x in decimal-hours)

  • The plots (dlmoplotcoarse and dlmoplotfine) visualize the results of the coarse and fine grid DLMO search, respectively.

Examples

# Load the sample melatonin profile data included in the package
filename <- system.file("extdata/sample_melatonin_profile.csv", package = "dlmoR")

# Calculate the DLMO using the sample data and a threshold of 5
sample_dlmo <- calculate_dlmo(file_path = filename, threshold = 5)
#> Loading data from file: /private/var/folders/jc/0t013ckx36db6z5ztm52h3vw0000gn/T/RtmpQ4mYk1/temp_libpath84c1b87c1ea/dlmoR/extdata/sample_melatonin_profile.csv
#> Creating 'time' column from 'datetime'.
#> Warning: Warning: Descents across threshold found in base segment at the following timestamps:
#> 2024-04-17 08:18:57
#> Warning: Warning: Large slope differences found in base segment at the following timestamps:
#> 2024-04-17 08:18:57, 2024-04-17 09:04:33