Skip to contents

Extract Sleep Cycles from a Hypnogram

sleepcycles_from_hypnogram.Rd

This function detects sleep cycles from a hypnogram using one of two algorithms:

  • DUDE (Density-Based Underlying Dynamics of Epochs): Uses sleep stage densities to define sleep cycles.

  • Feinberg (Classic Feinberg & Floyd method): Uses rule-based classification for defining cycles.

Usage

sleepcycles_from_hypnogram(
  df,
  epoch_col,
  stage_col,
  method = "dude",
  options = list(),
  id_col = NULL,
  verbose = TRUE
)

Arguments

df

A data frame containing sleep staging data.

epoch_col

A string specifying the column name for sleep epochs (must be numeric and sequential).

stage_col

A string specifying the column name representing sleep stages.

method

The algorithm used for detecting sleep cycles. Options:

  • "dude" (default) - Uses density-based clustering for defining cycles.

  • "feinberg" - Uses traditional rule-based heuristics for cycle segmentation.

options

A named list containing algorithm-specific parameters. If left empty, default parameters are used.

  • DUDE Algorithm Options:

    • "sleep_levels": Vector of valid sleep stages (default: c("N1", "N2", "N3", "R")).

    • "combos": Defines merged stages (e.g., list("N1_N2_N3" = c("N1", "N2", "N3"))).

    • "NREMP": Named list defining NREM Period (NREMP) detection parameters:

      • "density_col": Column used for NREMP detection (default: "N1_N2_N3").

      • "threshold": Threshold for cycle classification (default: 0.8).

      • "min_gap": Minimum gap between cycles (default: 20 epochs).

      • "min_size": Minimum cycle duration (default: 40 epochs).

    • "REMP": Named list defining REM Period (REMP) detection parameters:

      • "density_col": Column used for REMP detection (default: "R").

      • "threshold": Threshold for cycle classification (default: 0.3).

      • "min_gap": Minimum gap between cycles (default: 15 epochs).

      • "min_size": Minimum cycle duration (default: 10 epochs).

    • "kernel": A Gaussian kernel used for smoothing sleep stage transitions.

  • Feinberg Algorithm Options:

    • "sleepstart": Defines when sleep begins ("N1" or "N2", default: "N1").

    • "treat_as_W": Defines which stage should be treated as wakefulness (default: "A").

    • "rm_incomplete_period": Whether to remove incomplete cycles (default: FALSE).

    • "REMP_length": Minimum REM duration for it to be considered a valid cycle (default: 10 epochs).

    • "sleep_levels": Vector of sleep stages included in cycles (default: c("N1", "N2", "N3", "R")).

id_col

(Optional) A string specifying the column name for subject IDs. If provided, the function processes each subject separately.

verbose

Logical. If TRUE (default), the function prints warnings and messages when issues occur in grouped data.

Value

An object of class "SleepCycle", which is a list containing:

  • epoch: A data frame with per-epoch cycle classifications.

  • summary: A summary of detected cycles with their start and end epochs.

  • info: A list of metadata including the method used, selected options, and sleep stage levels.

Details

It processes both single-subject and multi-subject data. For grouped data (multiple IDs), it applies the selected method separately to each subject.

The function first validates the input hypnogram using check_hypnogram(), ensuring correct format and no missing values. Then, based on the chosen method, it calls either .sleepcycles_from_hypnogram_dude() or .sleepcycles_from_hypnogram_feinberg() to process the data.

If id_col is provided, the function runs the cycle detection independently for each subject and combines the results.

References

Feinberg, I., & Floyd, T. C. (1979). Systematic trends across the night in human sleep cycles. Psychophysiology, 16(3), 283-291.