Skip to content

events

Events data models.

BaseSummaryStats pydantic-model

Bases: BaseModel

Base model for aggregated distribution statistics.

Shared by both event summary stats and biomarker summary stats.

Fields:

analysis_config_id pydantic-field

The ID of the analysis configuration.

analysis_parameters pydantic-field

The analysis parameters used in computation.

origins pydantic-field

Studies/analyses that contributed to these stats. May be empty when origins_ref is set — the referenced shared list on the response envelope is then authoritative (large reports carry each distinct origins list once instead of repeating it per entry).

origins_ref = None pydantic-field

Key into the response envelope's origins_sets when the origins list is shared between entries. None when origins is carried inline.

origins_summary = None pydantic-field

Aggregate provenance. Always derivable from the origins list when one is carried; on very large reports the producer may carry ONLY this summary (origins empty, origins_ref None) to bound the payload — renderers must then read counts, group labels, window sources and research-regime markers from here, and fetch per-study detail from the audit endpoints. None for producers predating the field.

stats pydantic-field

Metric name to distribution statistics.

CreateStudyEventsRequest pydantic-model

Bases: BaseModel

Request body for creating study events.

Fields:

DistributionStats pydantic-model

Bases: BaseModel

Distribution statistics for a single metric across multiple observations.

Fields:

iqr pydantic-field

Interquartile range (p75 - p25)

max pydantic-field

Maximum value

mean pydantic-field

Arithmetic mean

median pydantic-field

Median (50th percentile)

min pydantic-field

Minimum value

p25 pydantic-field

25th percentile

p5 pydantic-field

5th percentile

p75 pydantic-field

75th percentile

p95 pydantic-field

95th percentile

std pydantic-field

Standard deviation

support pydantic-field

Number of observations

support_non_zero pydantic-field

Number of non-zero observations

Event pydantic-model

Bases: BaseModel

Event data type.

start_time_ms: Start time of the event in milliseconds relative to the recording start. end_time_ms: End time of the event in milliseconds relative to the recording start. Must be greater than or equal to start_time. If equal, the event is considered instantaneous. label: Label of the event (e.g., "Sleep stage W"). confidence: Optional confidence in [0, 1] of the event. value: Optional value associated to the event. channels: List of channels where the event was detected. If empty, the event should be considered global.

Fields:

  • start_time_ms (NonNegativeInt)
  • end_time_ms (NonNegativeInt)
  • label (EventLabel)
  • probability (float | None)
  • value (float | None)
  • channels (list[str])

Validators:

probability = None pydantic-field

Optional probability/confidence in [0, 1] of the event

value = None pydantic-field

Optional value associated to the event

validate_time_order() pydantic-validator

Validate that start time is less than end time.

EventListResponse pydantic-model

Bases: PaginatedResponse

A page of an analysis's events.

Fields:

EventStats pydantic-model

Bases: BaseModel

A model for statistics computed over a list of events of similar type.

Fields:

event_type pydantic-field

The type of event for which the statistics were computed.

stats pydantic-field

Dictionary of statistics computed over the events.

EventType pydantic-model

Bases: BaseModel

Model for the type of an event.

Represents an event label with a type, where types are e.g., 'instant-probabilistic' or 'interval-discrete'.

Fields:

channels pydantic-field

List of channels where the event was detected. If empty, the event should be considered global.

instant = False pydantic-field

Whether the event is instantaneous or not.

label pydantic-field

The label of the event, e.g., 'sleep-stage'.

probabilistic = False pydantic-field

Whether the event has an associated 'probability' value in [0, 1] or not.

valued = False pydantic-field

Whether the event has an associated 'value' or not.

infer_from_concrete_event(event) classmethod

Infer the type of the event from a concrete event.

EventsFilter pydantic-model

Bases: SignalWindow

Filter parameters for querying events.

This is a data container for filter criteria. Actual filtering is performed at the database layer for performance. Two independent filters are applied:

  1. Time window filter: Restricts events to a time range. Events outside the window are excluded. Controlled by window_start_time_ms, window_end_time_ms, and window_mode. Most modes only select whole events; CLIP additionally truncates the ones that straddle a boundary.

  2. Label filter: Filters by event labels/types. Controlled by labels and match_mode:

  3. INCLUDE mode: Only events matching the labels are returned.
  4. EXCLUDE mode: Events matching the labels are removed.

Both filters are independent - the time window acts as a "crop" operation, while match_mode only affects label filtering.

Fields:

Validators:

labels = None pydantic-field

Filter events by labels. If set, only events with labels in this list are considered for inclusion/exclusion based on match_mode. If None, label filtering is disabled.

match_mode = MatchModes.INCLUDE pydantic-field

Controls how label filtering works. INCLUDE: only include events matching the labels list. EXCLUDE: exclude events matching the labels list. Note: This only affects label filtering, not window filtering.

window_mode = WindowFilterModes.START pydantic-field

Controls how the time window filter matches events. START: match events starting within the window. END: match events ending within the window. CONTAIN: match events fully contained in the window. CLIP: match events overlapping the window and truncate them to it, so returned durations sum to at most the window's width. Events outside the window are always excluded regardless of match_mode.

validate_window_mode() pydantic-validator

Validate that required window times are provided for the selected window mode.

OriginsSummary pydantic-model

Bases: BaseModel

Aggregate provenance for a stats entry.

Carried when the full per-study origins list is too large for the wire. Everything renderers derive from the origins list is available here in aggregate form: the contributing-study count, the entry's group label, the statistics-window source distribution, and the research-regime parameters. Per-study detail is not lost — it remains available through the report's audit table and the audit CSV endpoint, which stream from the server rather than riding the payload.

Fields:

group = None pydantic-field

The entry's group label (a study tag, a stratum label or a longitudinal bucket). None presents as the untagged group, matching StatsOrigin.group semantics.

research_parameters = None pydantic-field

Union of the contributing analyses' research-regime parameters (see StatsOrigin.research_parameters). Empty when every contribution was validated; None when not derived.

study_count pydantic-field

Number of distinct studies contributing to the entry.

window_sources pydantic-field

Statistics-window source name to contributing-study count (WindowSource values as keys).

StatsOrigin pydantic-model

Bases: BaseModel

Represents ID information on the origin of stats.

Fields:

analysis_id pydantic-field

The ID of the analysis from which the stat was computed.

first_recording_date = None pydantic-field

The date of the first recording in the study that was analysed to give rise to the stat(s). None when no recording in the study carries a usable start date — the EDF header had none, or marked it unknown — so a report shows no date rather than a substitute.

group = None pydantic-field

Optional group label string that assigns the stat to a group. Can be a study tag (for by-group reports) or a datetime string (for longitudinal reports). None presents as the 'Untagged' group (UNTAGGED_GROUP_LABEL) in chart rows and legends.

research_parameters = None pydantic-field

Parameters (by API name) of the producing analysis whose submitted values lay outside the analysis configuration's validated regime, marking this origin's contribution as exploratory. Empty when every parameter was within the regime. None when not derived (producers predating the field).

study_creation_date pydantic-field

The creation date of the study that was analysed to give rise to the stat(s).

study_name pydantic-field

The study that was analysed to give rise to the stat(s)

window_source = None pydantic-field

Which statistics-window source this study's stats were computed over: lights events when available, a client-provided window, or the full recording. None for producers predating the field.

StudyEvent pydantic-model

Bases: BaseModel

A study-level event (e.g. lights off/on).

Study events are definitionally certain — no probability or value fields. Times are milliseconds relative to the earliest recording start in the study.

Fields:

  • id (UUID)
  • study_id (UUID)
  • start_time_ms (NonNegativeInt)
  • end_time_ms (NonNegativeInt)
  • label (EventLabel)
  • origin (StudyEventOrigin)

Validators:

validate_time_order() pydantic-validator

Validate that start time is less than or equal to end time.

StudyEventInput pydantic-model

Bases: BaseModel

Input for creating or upserting a study event.

Supports two input formats: - Relative: provide start_time_ms and end_time_ms directly. - Absolute: provide a datetime timestamp (converted to relative ms on ingestion; aware datetimes resolve as instants, naive datetimes are read in the recording's wall-clock frame — see timestamp).

Fields:

  • start_time_ms (NonNegativeInt | None)
  • end_time_ms (NonNegativeInt | None)
  • timestamp (datetime | None)
  • label (EventLabel)

Validators:

timestamp = None pydantic-field

Absolute event time, converted to relative ms against the study's earliest recording start. Timezone-aware datetimes are resolved as instants; naive datetimes are interpreted in the recording's own wall-clock frame (recording starts carry a nominal UTC offset).

validate_input_format() pydantic-validator

Validate that exactly one input format is used.

SummaryStats pydantic-model

Bases: BaseSummaryStats

Summary statistics computed across a list of comparable events.

Extends BaseSummaryStats with event-specific fields (analysis type, event type).

Fields:

analysis_type pydantic-field

The type of analysis.

event_type pydantic-field

The type of event the summary statistics are computed over.