Define the ascending segment of a melatonin profile

This function identifies and labels the ascending segment of a melatonin profile, where melatonin concentrations rise above a specified threshold and satisfy specific time interval and slope conditions. It also incorporates additional rules to refine the identification of ascending points.

Usage

define_ascending_segment(
  profile_data,
  threshold = 2.3,
  interval_limit = lubridate::hours(2)
)

Arguments

profile_data

A tibble containing melatonin profile data with the following columns:

• datetime: A POSIXct column representing timestamps for each measurement.

• melatonin: A numeric column representing melatonin concentrations.

• base: A binary column (1 for base segments, 0 otherwise) indicating low melatonin baseline segments.

• slope: A numeric column representing the rate of change in melatonin concentrations between consecutive points.

threshold

Numeric. The melatonin concentration threshold to define the ascending segment (default = 2.3 pg/mL).

interval_limit

Numeric or lubridate duration. Specifies the time window within which repeated threshold crossings are treated as the same rise event. When multiple candidate rises occur within this window, the later crossing is used. Single-point excursions above threshold that immediately return below threshold are ignored automatically; excursions with more than one consecutive above-threshold point are treated as candidate rises. The interval is measured between candidate rise start times, not from when the earlier excursion falls back below threshold. If numeric, interval_limit is interpreted as hours (default = 2 hours).

Value

A tibble with the following columns:

• datetime: The original timestamps.

• melatonin: The input melatonin concentrations.

• base: The input base column (1 for base segments, 0 otherwise).

• slope: The calculated slope of the profile.

• ascending: A binary indicator (1 for points in the ascending segment, 0 otherwise).