Skip to content

events

File related data types.

EventLabel

Bases: str, Enum

Labels of sleep events (EDF+ labels) + a small set of additional custom labels.

Custom labels
  • REM: Rapid eye movements
  • SIGNAL_ARTIFACT: Signal-level artifact detected by artifact analysis
  • UNKNOWN: Unknown event
References

See https://www.edfplus.info/specs/edftexts.html

scope property

Return the scope of this event label.

Study-scoped labels (e.g. LIGHTS_OFF, LIGHTS_ON) describe environmental events shared across all recordings in a study. Recording-scoped labels describe signal-level events tied to a specific recording.

by_analysis_type(analysis_type) classmethod

Given an analysis type, return the list of event labels that are relevant to the analysis.

Parameters:

Name Type Description Default
analysis_type AnalysisType

The analysis type.

 required

Returns:

Type Description
list[EventLabel]

The list of relevant event labels.

Examples:

>>> from yousleep_common.types import AnalysisType
>>> EventLabel.by_analysis_type(AnalysisType.STAGING)
[<EventLabel.SLEEP_STAGE_W: 'Sleep stage W'>, ...]

from_string(event) classmethod

Return the EventType based on the string representation.

If the string does not match any EventLabel, returns EventLabel.UNKNOWN.

Parameters:

Name Type Description Default
event str

The event string representation.

 required

Returns:

Type Description
EventLabel

The EventLabel.

Examples:

>>> EventLabel.from_string("Sleep stage W")
<EventLabel.SLEEP_STAGE_W: 'Sleep stage W'>

MatchModes

Bases: Enum

An enum for different filter match modes.

EXCLUDE = 'exclude' class-attribute instance-attribute

Exclude the events that matches the filter.

INCLUDE = 'include' class-attribute instance-attribute

Include the events that matches the filter.

SleepStageGroup

Bases: str, Enum

The five clinical stage groups every scored staging label folds into.

Scientific semantics, defined once: the api-server's biomarker stage sets and hypnogram lanes, and any other consumer, derive from this map instead of re-encoding which raw label means N3 (the R&K "Sleep stage 3/4" folding lives here and nowhere else).

StudyEventOrigin

Bases: str, Enum

Origin of a study-level event.

EDF_ANNOTATION = 'edf_annotation' class-attribute instance-attribute

Parsed from an EDF+ annotation signal.

MANUAL = 'manual' class-attribute instance-attribute

Created via the REST API by a user.

WindowFilterModes

Bases: Enum

An enum for different window filter match modes.

Modes:

  • START: Match events that start after the window start time and before the window end time if provided. Does not enforce events to stop before the window end time. If no end time is provided, the window is considered open-ended (ending at time +infinity).

    For example: | ----------------- window ----------------- | | -- event -- || -- event -- | | -- event -- | | -- event -- | EXCL. INCL. INCL. EXCL.

  • END: Match events that end before the window end time and after the window start time if provided. Does not enforce events to start after the window start time. If no start time is provided, the window is considered open-ended (starting at time 0).

    For example: | ----------------- window ----------------- | | -- event -- || -- event -- | | -- event -- | | -- event -- | INCL. INCL. EXCL. EXCL.

  • CONTAIN: Match events that are fully contained within the [start, end] time window. If either start or end time is not provided, the window is considered open-ended in that direction (0/+infinity)

    For example: | ----------------- window ----------------- | | -- event -- || -- event -- | | -- event -- | | -- event -- | EXCL. INCL. EXCL. EXCL.

  • CLIP: Match events overlapping the window at all, and return them truncated to the window. Unlike the other modes, which only select, this one also modifies the returned times: an event straddling a boundary comes back with the outside part removed, so reported durations sum to at most the window's width. Both start and end times are required.

    For example: | ----------------- window ----------------- | | -- event -- || -- event -- | | -- event -- | | -- event -- | INCL.(cut) INCL. INCL.(cut) EXCL.