wonambi.attr.annotations module

Module to keep track of the user-made annotations and sleep scoring.

class wonambi.attr.annotations.Annotations(xml_file, rater_name=None)

Bases: object

Class to return nicely formatted information from xml.

Parameters:

xml_file (path to xml file) – Annotation xml file

add_bookmark(name, time, chan='')

Add a new bookmark

Parameters:

• name (str) – name of the bookmark

• time ((float, float)) – float with start and end time in s

Raises:

IndexError – When there is no selected rater

add_event(name, time, chan='')

Add event to annotations file. :param name: Event type name. :type name: str :param time: Start and end times of event, in seconds from recording start. :type time: tuple/list of float :param chan: Channel or channels associated with event. :type chan: str or list of str, optional

Raises:

IndexError – When there is no rater / epochs at all

add_event_type(name)

Raises:

IndexError – When there is no selected rater

add_events(event_list, name=None, chan=None, parent=None)

Add series of events. Faster than calling add_event in a loop. :param event_list: each dict is an event with ‘start’ and ‘end’ times :type event_list: list of dict :param name: save events to this event type. :type name: str, optional :param chan: save events to this or these channel(s). If None, channel will be

read from the event list dict under ‘chan’

add_rater(rater_name, epoch_length=30)

clear_cycles()

Remove all cycle markers in current rater.

create_epochs(epoch_length=30, first_second=None)

Create epochs in annotation file. :param epoch_length: duration in seconds of each epoch :type epoch_length: int :param first_second: Time, in seconds from record start, at which the epochs begin :type first_second: int, optional

property current_rater

property dataset

property epoch_length

property epochs

Get epochs as generator

Returns:

list of dict – each epoch is defined by start_time and end_time (in s in reference to the start of the recordings) and a string of the sleep stage, and a string of the signal quality. If you specify stages_of_interest, only epochs belonging to those stages will be included (can be an empty list).

Raises:

IndexError – When there is no rater / epochs at all

property event_types

raises IndexError: When there is no selected rater

export(file_to_export, xformat='csv')

Export epochwise annotations to csv file.

Parameters:

file_to_export (path to file) – file to write to

export_events(filename, evt_type=None, chan=None, stage=None, cycle=None)

Export events to CSV

Parameters:

• filename (str) – path of export file

• evt_type (list of str, optional) – event types to export

• chan (tuple of str, optional) – list of channels of interests

• stage (tuple of str, optional) – list of stages of interest

• cycle (list of int, optional) – list of cycles of interest, numbered starting at 1

export_sleep_stats(filename, lights_off, lights_on)

Create CSV with sleep statistics.

Parameters:

• filename (str) – Filename for csv export

• lights_off (float) – Initial time when sleeper turns off the light (or their phone) to go to sleep, in seconds from recording start

• lights_on (float) – Final time when sleeper rises from bed after sleep, in seconds from recording start

Returns:

float or None – If there are no epochs scored as sleep, returns None. Otherwise, returns the sleep onset latency, for testing purposes.

Note

Total dark time and sleep efficiency does NOT subtract epochs marked as Undefined or Unknown.

property first_second

get_bookmarks(time=None, chan=None)

Raises:

IndexError – When there is no selected rater

get_cycles()

Return the cycle start and end times.

Returns:

list of tuple of float – start and end times for each cycle, in seconds from recording start and the cycle index starting at 1

get_epoch_start(window_start)

Get the position (seconds) of the nearest epoch.

Parameters:

window_start (float) – Position of the current window (seconds)

Returns:

float – Position (seconds) of the nearest epoch.

get_epochs(time=None, stage=None, qual=None, chan=None, name=None)

Get list of events in the file.

Parameters:

• time (tuple of two float, optional) – start and end time of the period of interest

• stage (tuple of str, optional) – list of stages of interest

• qual (str, optional) – epoch signal qualifier (Good or Poor)

• chan (None) – placeholder, to maintain format similar to get_events

• name (None) – placeholder, to maintain format similar to get_events

Returns:

list of dict – where each dict has ‘start’ (start time), ‘end’ (end time), ‘stage’, ‘qual’ (signal quality)

get_events(name=None, time=None, chan=None, stage=None, qual=None, cycle=None)

Get list of events in the file.

Parameters:

• name (str, optional) – name of the event of interest

• time (tuple of two float, optional) – start and end time of the period of interest

• chan (tuple of str, optional) – list of channels of interests

• stage (tuple of str, optional) – list of stages of interest

• qual (str, optional) – epoch signal qualifier (Good or Poor)

• cycle (list of int, optional) – list of cycles of interest, numbered starting at 1

Returns:

list of dict – where each dict has ‘name’ (name of the event), ‘start’ (start time), ‘end’ (end time), ‘chan’ (channels of interest, can be empty), ‘stage’, ‘quality’ (signal quality), ‘cycle’ (sleep period)

Raises:

IndexError – When there is no rater / epochs at all

get_rater(rater_name)

get_stage_for_epoch(epoch_start, window_length=None, attr='stage')

Return stage for one specific epoch.

Parameters:

• id_epoch (str) – index of the epoch

• attr (str, optional) – ‘stage’ or ‘quality’

Returns:

stage (str) – description of the stage.

import_events(filename, source='wonambi', rec_start=None, chan_dict=None, chan_grp_name='eeg', parent=None)

Import events from Wonambi CSV event export and write to annot.

Parameters:

• filename (str) – path to file

• source (str) – source program: ‘wonambi’ or ‘remlogic’

• rec_start (datetime) – Date and time (year, month, day, hour, minute, second) of recording start. Year is ignored (New Year’s Eve celebratory recordings unsupported.) Only required for remlogic.

• chan_dict (dict) – for prana. keys are channels as they appear in the prana input file, and values are channels as they appear in the Wonambi GUI (with reference and channel group).

• chan_grp_name (str) – for prana. name of the channel group in which to store events.

• parent (QWidget) – for GUI progress bar

import_staging(filename, source, rater_name, rec_start, staging_start=None, epoch_length=None, poor=['Artefact'], as_qual=False)

Import staging from an external staging text file.

Parameters:

• filename (str) – Staging file name.

• source (str) – Name of program where staging was made. One of ‘domino’, ‘alice’, ‘compumedics’, ‘sandman’, ‘remlogic’, ‘phillips’, ‘grael’, ‘egi’

• rater_name (str) – Rater name for imported staging.

• rec_start (datetime) – Date and time (year, month, day, hour, minute, second) of recording start. Year is ignored (New Year’s Eve celebratory recordings unsupported.)

• staging_start (datetime (default: None)) – Date and time of staging start. For use when not provided in staging file.

• epoch_length (int) – duration in s of a scoring epoch

• poor (list of str) – epochs with stage names in this list will be marked as Poor quality

• as_qual (bool) – if True, the staging only be used to mark quality, as per poor

property last_second

latency_to_consolidated(lights_off, duration=5, stage=['NREM2', 'NREM3'])

Find latency to the first period of uninterrupted ‘stage’.

Parameters:

• lights_off (float) – lights off time, in seconds form recording start

• duration (float) – duration of uninterrupted period, in minutes

• stage (list of str) – target stage(s)

Returns:

float – latency to the start of the consolidated period, in minutes

load()

Load xml from file.

property raters

remove_bookmark(name=None, time=None, chan=None)

if you call it without arguments, it removes ALL the bookmarks.

remove_cycle_mrkr(epoch_start)

Remove cycle marker at epoch_start.

Parameters:

epoch_start (int) – start time of epoch, in seconds

remove_event(name=None, time=None, chan=None)

get events inside window.

remove_event_type(name)

Remove event type based on name.

remove_rater(rater_name)

rename_event_type(name, new_name)

Rename event type.

rename_rater(name, new_name)

Rename event type.

save()

Save xml to file.

set_cycle_mrkr(epoch_start, end=False)

Mark epoch start as cycle start or end.

Parameters:

• epoch_start (int) – start time of the epoch, in seconds

• end (bool) – If True, marked as cycle end; otherwise, marks cycle start

set_stage_for_epoch(epoch_start, name, attr='stage', save=True)

Change the stage for one specific epoch.

Parameters:

• epoch_start (int) – start time of the epoch, in seconds

• name (str) – description of the stage or qualifier.

• attr (str, optional) – either ‘stage’ or ‘quality’

• save (bool) – whether to save every time one epoch is scored

Raises:

• KeyError – When the epoch_start is not in the list of epochs.

• IndexError – When there is no rater / epochs at all

Notes

In the GUI, you want to save as often as possible, even if it slows down the program, but it’s the safer option. But if you’re converting a dataset, you want to save at the end. Do not forget to save!

slp_frag(time=None)

Obtain sleep fragmentation parameter, ie number of stage shifts to a lighter stage.

property start_time

switch(time=None)

Obtain switch parameter, ie number of times the stage shifts.

time_in_stage(name, attr='stage')

Return time (in seconds) in the selected stage.

Parameters:

• name (str) – one of the sleep stages, or qualifiers

• attr (str, optional) – either ‘stage’ or ‘quality’

Returns:

int – time spent in one stage/qualifier, in seconds.

to_bids(tsv_file=None, json_file=None)

wonambi.attr.annotations.create_annotation(xml_file, from_fasst, lights_off=False, legacy_meth=False)

Create annotations by importing from FASST sleep scoring file.

Parameters:

• xml_file (path to xml file) – annotation file that will be created

• from_fasst (path to FASST file) – .mat file containing the scores

• lights_off (bool) – set to True if scoring begins at lights off

• legacy_meth (bool) – old functionality; will stage epochs starting at epoch_start = 0.

Returns:

instance of Annotations

Todo

Merge create_annotation and create_empty_annotations

wonambi.attr.annotations.create_empty_annotations(xml_file, dataset)

Create an empty annotation file.

Notes

Dates are made time-zone unaware.

wonambi.attr.annotations.parse_iso_datetime(date)

wonambi.attr.annotations.update_annotation_version(xml_file)

Update the fields that have changed over different versions.

Parameters:

xml_file (path to file) – xml file with the sleep scoring

Notes

new in version 4: use ‘marker_name’ instead of simply ‘name’ etc

new in version 5: use ‘bookmark’ instead of ‘marker’