Skip to content

event_blocks

Block representation of analysis events.

A block describes N consecutive equal-duration slots beginning at an exact origin, with the per-slot attributes carried as parallel arrays. A full night of sleep staging — tens of thousands of events on a regular grid — is a single block, while events that share no grid are blocks of one slot each. Any valid list of :class:~yousleep_common.models.events.Event can therefore be represented exactly, whatever its shape.

This is the one output format analysis containers write, and the compact form in which large event sets travel to clients.

EventBlock pydantic-model

Bases: BaseModel

N consecutive equal-duration event slots beginning at an exact origin.

Slot i spans [origin_ms + i * period_ms, origin_ms + (i + 1) * period_ms). A period_ms of 0 marks instantaneous events, where every slot collapses onto origin_ms.

Fields:

Validators:

channels pydantic-field

List of channels the block's events were detected on, shared by every slot. If empty, the events should be considered global.

end_ms property

Return the end of the final slot.

labels pydantic-field

One label per slot. Labels may vary from slot to slot.

origin_ms pydantic-field

Start time of the first slot in milliseconds relative to the recording start.

period_ms pydantic-field

Duration of every slot in milliseconds. 0 marks instantaneous events.

probability = None pydantic-field

Optional probability/confidence in [0, 1] per slot. None when no slot in the block carries a probability; individual entries may still be None.

slot_count property

Return the number of slots.

value = None pydantic-field

Optional value per slot. None when no slot in the block carries a value; individual entries may still be None.

validate_parallel_arrays() pydantic-validator

Validate that the optional per-slot arrays match the slot count.

EventBlocksDocument pydantic-model

Bases: BaseModel

The events output document an analysis container writes.

A versioned envelope around a list of blocks. Block order is meaningful and must be preserved: it is the canonical order the encoding produces, and consumers rely on it being stable.

Fields:

blocks pydantic-field

The event blocks, in canonical order.

device = None pydantic-field

Optional provenance recorded by the producing analysis: software and model identity, versions, an input content hash, and any further descriptive fields the producer chooses. Opaque to the platform — carried with the document, never interpreted.

event_count property

Return the total number of events across all blocks.

format_version = 1 pydantic-field

Version of the events document format.

EventsOutputLimits pydantic-model

Bases: BaseModel

Bounds on an events document read from an analysis container.

The document is written by the container, so its size is chosen by whoever built the image. Every reader applies these bounds before the content is decoded or expanded: a small gzip payload can decompress to gigabytes, and a small block document can describe millions of events. The defaults leave ample room for a full night scored every second with every class's probability, which is well under a million events.

Config:

  • extra: forbid
  • frozen: True

Fields:

max_decompressed_bytes = 128 * 1024 * 1024 pydantic-field

Largest document accepted after gzip decompression.

max_events = 2000000 pydantic-field

Most events a document may describe across its blocks.

max_file_bytes = 64 * 1024 * 1024 pydantic-field

Largest document accepted as stored, compressed or not.