Skip to content

Sleep

You obtain sleep information when it is detected. One night of sleep is a sleep session. A small nap during the day it is also a sleep session. All sleep sessions have the same structure.

Sleep Session Structure

Each sleep session is comprised by:

  • Start and end timestamps
  • A list of sleep stages, where each stage includes the following:
    • Start and end timestamps of that sleep stage.
    • Stage value (REM, Deep Sleep, Light Sleep, Awake, Unknown) when the sleep is automatically detected;
    • Stage value (Awake, Unknown) when the sleep is manually logged by the user;

Note

  • For detected sleep: Unknown stages usually occur when the signal quality is too poor (e.g., noisy PPG preventing Interbeat Interval (IBI) extraction) or missing sensor data.
  • For manually logged sleep: Awake stages correspond to manually logged awakenings.

Context of Sleep data

From sleep sessions, you can calculate:

  • Percentage of time in each sleep stage
  • Sleep efficiency
  • Sleep latency
  • Number of awakenings
  • Ratio of time in the deep relaxation zone
  • Time taken to reach the deep relaxation zone

Heart Rate Variability (HRV) can also be derived by:

  • Extracting IBIs within the sleep session
  • Calculating HRV using those IBIs

Some of these metrics will be added to the API soon (ie IBI, night HRV, etc.), some of them will come later (ie sleep efficiency, sleep latency).

Heart Rate Variability calculations

Although HRV can be computed at different times, we recommend calculating it during sleep as it’s most accurate/reliable.

We will provide a daily sleep measure of HRV. Once the IBIs are available in the API, you can also calculate HRV at other times, though we strongly recommend choosing periods of low motion within a consistent context to ensure accuracy, reliability, and interpretability.

For that, we advise:

  • Using a sliding window analysis approach.
  • The simplest method is to calculate the Root Mean Square of Successive Differences (RMSSD) on the IBIs within each window.
  • However, there are other methods, such as the LF/HF ratio. Though, please note that different measures of HRV provide different physiological information and have different applications.

Note

We can provide code for these calculations if needed.