Determine Time of Dimlight Melatonin Onset • dlmoR

`dlmoR`

dlmoR is an R package that implements the hockey-stick method (Danilenko et al., 2014) for estimating dim light melatonin onset (DLMO) — a key circadian phase marker in chronobiology and sleep research.

The hockey-stick algorithm models melatonin rise as a piecewise linear-parabolic curve, with the DLMO time point determined as the inflection point of the piecewise curve that best fits the melatonin profile, in a least-squares sense. This approach provides a more objective and robust estimate of DLMO compared to traditional threshold-based methods, which can be limited by variability in baseline melatonin levels and subjectivity in visual estimation (Benloucif et al., 2008; Kennaway, 2023; Glacet et al., 2023).

A Windows-based executable of this algorithm was previously released (Danilenko & Verevkin, 2020), but its closed-source format limits flexibility. The original software does not allow modification or inspection of the underlying algorithm, lacks an API for integration into analytical workflows, and requires manual operation, making batch processing inefficient.

By bringing this method into the R-programming environment, dlmoR provides an open-source, transparent, and scriptable alternative. It enables reproducible and batchable DLMO estimation, allowing users to efficiently analyze multiple melatonin time-series within high-throughput workflows.

Installation

You can install the latest development version of dlmoR from GitHub with:

# install.packages("pak")
pak::pak("tscnlab/dlmoR")

Quick start guide

This short example shows the basic dlmoR workflow. For a more detailed tutorial covering package functionality and common use cases, see the get started vignette.

# Load the package
library(dlmoR)

# Load sample data (provided with the package)
filename <- system.file("extdata/sample_melatonin_profile.csv", package = "dlmoR")

# Compute DLMO with a threshold of 3 pg/mL
dlmo_result <- calculate_dlmo(file_path = filename, threshold = 3, fine_flag = TRUE)

# View estimated DLMO inflection point (decimal-hours) and melatonin concentration (pg/mL) at this time

# Coarse grid search result
dlmo_result$ip$inflection_point_coarse
#        x     y
10  20.81667 0.1

# Fine grid search result
dlmo_result$ip$inflection_point_fine
#        x     y
36   20.26667 0.1

# View estimated DLMO timestamp for fine search
dlmo_result$dlmo$fine$time
20:16:00

# View estimated melatonin concentration at DLMO time
dlmo_result$dlmo$fine$fit_melatonin
0.1

# View parameters of fit lines 
# Baseline fit type is always linear: slope m, y-intercept b
dlmo_result$dlmo$fine$fit_lines$base
[1] "linear"

dlmo_result$dlmo$fine$fit_lines$base$m
[1] -0.1599731

dlmo_result$dlmo$fine$fit_lines$base$b
[1] 3.342121

# Ascending fit type is either linear or parabolic.
dlmo_result$dlmo$fine$fit_lines$ascending$type
[1] "parabolic"

dlmo_result$dlmo$fine$fit_lines$ascending$a
1.918017 

dlmo_result$dlmo$fine$fit_lines$ascending$b
-72.59794 

dlmo_result$dlmo$fine$fit_lines$ascending$c
683.6161 

# Plot the melatonin profile with DLMO detection
print(dlmo_result$dlmoplotcoarse)
print(dlmo_result$dlmoplotfine)

Dim-Light Melatonin Onset (DLMO) Plot (coarse grid search view)
DLMO Coarse Plot

Dim-Light Melatonin Onset (reduced fine grid search view)
DLMO Fine Plot

Expected Runtime

The runtime of calculate_dlmo() depends on the selected search method and on the computing power of your machine:

Coarse- and fine-grid DLMO search (fine_flag = TRUE, default): ~10 minutes (Windows)/~2 minutes (Mac) per melatonin profile.
Coarse-grid DLMO search only (fine_flag = FALSE): ~1 minute (Windows)/< 1 minute (Mac) per melatonin profile.

For batch processing, runtime scales approximately linearly with the number of profiles analyzed.

Getting Help

For bug reports, usage questions, and feature requests, please open an issue on the GitHub Issues page.

Citing `dlmoR`

If you use dlmoR in your research, please cite the following publication, which describes the package, its implementation, and the evaluation of its performance:

Thalji, S. M., & Spitschan, M. (2026). dlmoR: An Open-Source R Package for the Dim-Light Melatonin Onset (DLMO) Hockey-Stick Method. Journal of Biological Rhythms, 41(3), 301–323.

@article{thalji2026dlmor,
  author  = {Thalji, Salma M. and Spitschan, Manuel},
  title   = {dlmoR: An open-source R package for the dim-light melatonin onset (DLMO) hockey-stick method},
  journal = {Journal of Biological Rhythms},
  year    = {2026},
  doi     = {10.1177/07487304251389994}
}

Data and analysis code availability

All raw data, analysis code, result tables, and figures related to this publication are available in the corresponding publication repository.

dlmoR: Dim-light melatonin onset estimation

dlmoR