Skip to contents

Validate a Hypnogram Data Frame

check_hypnogram.Rd

This function checks the structure and validity of a hypnogram dataset. It ensures:

  • The presence of required columns (epoch_col, stage_col).

  • The correct format of epoch_col (numeric, ordered, contiguous).

  • The correct format of stage_col (valid sleep stages, no missing values).

  • If id_col is provided, validation is performed separately for each subject.

Usage

check_hypnogram(
  df,
  epoch_col,
  stage_col,
  id_col = NULL,
  valid_levels = c("N3", "N2", "N1", "R", "W", "A"),
  on_error = "stop"
)

Arguments

df

A data frame containing the hypnogram.

epoch_col

The column name that represents sleep epochs (must be numeric and sequential).

stage_col

The column name representing sleep stages.

id_col

(Optional) A column representing subject IDs for grouped data. If provided, validation runs separately for each subject.

valid_levels

valid stage levels you would like to check against when validating the hypnogram.

on_error

Defines error handling behavior:

  • "stop" (default) will halt execution on errors.

  • "message" will print warnings instead of stopping execution. This behavior allows the user to see errors for all ids when working with a grouped hypnogram.

Value

Returns NULL if validation is successful. Otherwise, it stops or prints an error message.