yasa.sleep_statistics

yasa.sleep_statistics(hypno, sf_hyp)[source]

Compute standard sleep statistics from an hypnogram.

New in version 0.1.9.

Parameters
hypnoarray_like

Hypnogram, assumed to be already cropped to time in bed (TIB, also referred to as Total Recording Time, i.e. “lights out” to “lights on”).

Note

The default hypnogram format in YASA is a 1D integer vector where:

  • -2 = Unscored

  • -1 = Artefact / Movement

  • 0 = Wake

  • 1 = N1 sleep

  • 2 = N2 sleep

  • 3 = N3 sleep

  • 4 = REM sleep

sf_hypfloat

The sampling frequency of the hypnogram. Should be 1/30 if there is one value per 30-seconds, 1/20 if there is one value per 20-seconds, 1 if there is one value per second, and so on.

Returns
statsdict

Sleep statistics (expressed in minutes)

Notes

All values except SE, SME and percentages of each stage are expressed in minutes. YASA follows the AASM guidelines to calculate these parameters:

  • Time in Bed (TIB): total duration of the hypnogram.

  • Sleep Period Time (SPT): duration from first to last period of sleep.

  • Wake After Sleep Onset (WASO): duration of wake periods within SPT.

  • Total Sleep Time (TST): total duration of N1 + N2 + N3 + REM sleep in SPT.

  • Sleep Efficiency (SE): TST / TIB * 100 (%).

  • Sleep Maintenance Efficiency (SME): TST / SPT * 100 (%).

  • W, N1, N2, N3 and REM: sleep stages duration. NREM = N1 + N2 + N3.

  • % (W, … REM): sleep stages duration expressed in percentages of TST.

  • Latencies: latencies of sleep stages from the beginning of the record.

  • Sleep Onset Latency (SOL): Latency to first epoch of any sleep.

Warning

Since YASA 0.5.0, Artefact and Unscored epochs are now excluded from the calculation of the total sleep time (TST). Previously, YASA calculated TST as SPT - WASO, thus including Art and Uns. TST is now calculated as the sum of all REM and NREM sleep in SPT.

Warning

The definition of REM latency in the AASM scoring manual differs from the REM latency reported here. The former uses the time from first epoch of sleep, while YASA uses the time from the beginning of the recording. The AASM definition of the REM latency can be found with SOL - Lat_REM.

References

  • Iber, C. (2007). The AASM manual for the scoring of sleep and associated events: rules, terminology and technical specifications. American Academy of Sleep Medicine.

  • Silber, M. H., Ancoli-Israel, S., Bonnet, M. H., Chokroverty, S., Grigg-Damberger, M. M., Hirshkowitz, M., Kapen, S., Keenan, S. A., Kryger, M. H., Penzel, T., Pressman, M. R., & Iber, C. (2007). The visual scoring of sleep in adults. Journal of Clinical Sleep Medicine: JCSM: Official Publication of the American Academy of Sleep Medicine, 3(2), 121–131.

Examples

>>> from yasa import sleep_statistics
>>> hypno = [0, 0, 1, 1, 1, 2, 2, 2, 3, 3, 3, 2, 3, 3, 4, 4, 4, 4, 0, 0]
>>> # Assuming that we have one-value per 30-second.
>>> sleep_statistics(hypno, sf_hyp=1/30)
{'TIB': 10.0,
 'SPT': 8.0,
 'WASO': 0.0,
 'TST': 8.0,
 'N1': 1.5,
 'N2': 2.0,
 'N3': 2.5,
 'REM': 2.0,
 'NREM': 6.0,
 'SOL': 1.0,
 'Lat_N1': 1.0,
 'Lat_N2': 2.5,
 'Lat_N3': 4.0,
 'Lat_REM': 7.0,
 '%N1': 18.75,
 '%N2': 25.0,
 '%N3': 31.25,
 '%REM': 25.0,
 '%NREM': 75.0,
 'SE': 80.0,
 'SME': 100.0}