biopsykit.io.sleep_analyzer module

Module containing different I/O functions to load data recorded by Withings Sleep Analyzer.

biopsykit.io.sleep_analyzer.WITHINGS_RAW_DATA_SOURCES = {'hr': 'heart_rate', 'respiratory-rate': 'respiration_rate', 'sleep-state': 'sleep_state', 'snoring': 'snoring'}

Mapping of data source names to names of the biosignal (and the exported dataframe column)

biopsykit.io.sleep_analyzer.load_withings_sleep_analyzer_raw_file(file_path, data_source, timezone=None, split_into_nights=True)[source]

Load single Withings Sleep Analyzer raw data file and convert into time-series data.

Parameters

  • file_path (Path or str) – path to file

  • data_source (str) – data source of file specified by file_path. Must be one of [‘heart_rate’, ‘respiration_rate’, ‘sleep_state’, ‘snoring’].

  • timezone (str or datetime.tzinfo, optional) – timezone of recorded data, either as string or as tzinfo object. Default: ‘Europe/Berlin’

  • split_into_nights (bool, optional) – whether to split the dataframe into the different recording nights (and return a dictionary of dataframes) or not. Default: True

Returns

dataframe (or dict of dataframes, if split_into_nights is True) with Sleep Analyzer data

Return type

DataFrame or dict of such

Raises
biopsykit.io.sleep_analyzer.load_withings_sleep_analyzer_raw_folder(folder_path, timezone=None, split_into_nights=True)[source]

Load folder with raw data from a Withings Sleep Analyzer recording session and convert into time-series data.

The function will return a list of dataframes (one dataframe per night, if split_into_nights is True) with continuous time-series data (sampling distance: 1min) of all data sources (heart rate, respiratory rate, sleep state, snoring) combined. The dataframe columns will be:

  • heart_rate: heart rate in beats-per-minute (bpm)

  • respiration_rate: respiration rate in breaths-per-minute (bpm)

  • sleep_state: current sleep state: 0 = awake, 1 = light sleep, 2 = deep sleep, 3 = rem sleep

  • snoring: flag whether snoring was detected: 0 = no snoring, 100 = snoring

The files are all expected to have the following name pattern: raw-sleep-monitor_<datasource>.csv.

Warning

If data is not split into single nights (split_into_nights is False), data in the dataframe will not be resampled.

Parameters

  • folder_path (Path or str) – path to folder with Sleep Analyzer raw data

  • timezone (str or datetime.tzinfo, optional) – timezone of the acquired data, either as string of as tzinfo object. Default: ‘Europe/Berlin’

  • split_into_nights (bool, optional) – whether to split the dataframe into the different recording nights (and return a list of dataframes) or not. Default: True

Returns

dataframe (or list of dataframes, if split_into_nights is True) with Sleep Analyzer data

Return type

DataFrame or list of such

Raises

ValueError – if folder_path is not a directory if no Sleep Analyzer Raw files are in directory specified by folder_path

See also

load_withings_sleep_analyzer_raw_file

load a single Sleep Analyzer file with only one data source

biopsykit.io.sleep_analyzer.load_withings_sleep_analyzer_summary(file_path, timezone=None)[source]

Load Sleep Analyzer summary file.

This function additionally computes several other sleep endpoints from the Sleep Analyzer summary data to be comparable with the output with the format of other sleep analysis algorithms. All time information are reported in minutes. The resulting dataframe has the following columns:

  • total_duration: Total recording time

  • total_time_light_sleep: Total time of light sleep

  • total_time_deep_sleep: Total time of deep sleep

  • total_time_rem_sleep: Total time of REM sleep

  • total_time_awake: Total time of being awake

  • total_sleep_duration: Total sleep duration, i.e., time between Sleep Onset and Wake Onset

  • number_wake_bouts: Total number of wake bouts

  • sleep_onset_latency: Sleep Onset Latency, i.e., time in bed needed to fall asleep

  • getup_onset_latency: Get Up Latency, i.e., time in bed after awakening until getting up

  • sleep_onset: Sleep Onset, i.e., time of falling asleep, in absolute time

  • wake_onset: Wake Onset, i.e., time of awakening, in absolute time

  • wake_after_sleep_onset: Wake After Sleep Onset (WASO), i.e., total time awake after falling asleep

  • count_snoring_episodes: Total number of snoring episodes

  • total_time_snoring: Total time of snoring

  • heart_rate_avg: Average heart rate during recording in bpm

  • heart_rate_min: Minimum heart rate during recording in bpm

  • heart_rate_max: Maximum heart rate during recording in bpm

Parameters

  • file_path (Path or str) – path to file

  • timezone (str or datetime.tzinfo, optional) – timezone of recorded data, either as string or as tzinfo object. Default: ‘Europe/Berlin’

Returns

dataframe with Sleep Analyzer summary data, i.e., sleep endpoints

Return type

SleepEndpointDataFrame

biopsykit.io.sleep module biopsykit.metadata package