Skip to content

reports

Report-related models for the API.

These models are used for generating and displaying reports that aggregate analysis events and compute statistics.

NOT_SET_STRATUM_LABEL = 'Not set' module-attribute

Stratum label for studies missing the stratified metadata factor.

Contract, not a display nicety: a stratified report accounts for every study, so studies without the factor form their own stratum under this exact label — the parallel of UNTAGGED_GROUP_LABEL for tag grouping. Ordered last.

AnalysisBiomarkersResponse pydantic-model

Bases: BiomarkerResult

A single analysis's biomarker result plus its presentation table.

Extends BiomarkerResult (so existing consumers of the analysis biomarkers endpoint keep working unchanged) with the server-defined TableModel that renders it — formatted values, curated summary flags, and any configured status tokens.

Fields:

table = None pydantic-field

Server-defined presentation table for the result. None for producers predating the field.

AnnotatedEventStats pydantic-model

Bases: BaseModel

Event statistics with associated analysis metadata.

Fields:

BiomarkerSummaryStats pydantic-model

Bases: BaseSummaryStats

Aggregated biomarker statistics across multiple analyses.

Inherits from BaseSummaryStats — same stats dict pattern as SummaryStats but without event-specific fields.

Fields:

ChannelIdentitySummary pydantic-model

Bases: BaseModel

What the channels behind one vocabulary entry are, across their recordings.

Fields:

canonical_names pydantic-field

Distinct canonical names ('C3-M2', 'E1') the entry's channels carry, in first-seen order; empty when none is known.

corrected = 0 pydantic-field

How many of the entry's channels carry an identity a person set.

lateralities pydantic-field

Distinct sides the entry's channels record, in first-seen order; empty when unknown.

ChannelLocation pydantic-model

Bases: BaseModel

Location of a channel within a recording.

Fields:

channel_index pydantic-field

Index of the channel in the recording

recording_id pydantic-field

Recording identifier

study_id pydantic-field

Study identifier

CreditedAnalysis pydantic-model

Bases: BaseModel

An analysis a report's results came from, with the credit they carry.

Fields:

analysis_config_id pydantic-field

The analysis configuration id.

credit pydantic-field

Who to credit for the analysis's results, and what to cite.

name pydantic-field

The analysis configuration's display name.

ProjectReportChart pydantic-model

Bases: BaseModel

One server-computed chart for a project report stats card.

A chart spans every row sharing one value axis — multiple SummaryStats entries — so it attaches to the report envelope, not to an individual stats entry. The identity fields mirror the card grouping (analysis type + config + parameters) so consumers can place each chart on its card without re-deriving geometry.

Fields:

analysis_config_id pydantic-field

Analysis configuration the card groups by.

analysis_parameters pydantic-field

Analysis parameters the card groups by.

analysis_type = None pydantic-field

Analysis type of the stats card this chart belongs to (None for non-event charts, e.g. future biomarker summaries).

chart pydantic-field

The chart geometry.

event_label = None pydantic-field

Set on by-group comparison charts: the event type this chart compares across study groups. None on single-group charts (rows are the event types).

key pydantic-field

Stable chart identity within the report (safe as a render/caching key).

metric pydantic-field

Metric the value axis plots (a stats dict key, e.g. 'total-duration-ms').

title pydantic-field

Human-readable chart heading.

ProjectReportResponse pydantic-model

Bases: BaseModel

Envelope for project-level report data.

Wraps aggregated event summary statistics with optional biomarker summary statistics computed across all studies in the project.

Fields:

biomarker_summary = None pydantic-field

Aggregated biomarker distribution stats grouped by analysis config (None if not requested)

charts = None pydantic-field

Server-computed chart models for the report's stats cards. None for producers predating the field.

event_stats pydantic-field

Aggregated event summary statistics

longitudinal = None pydantic-field

Set when the report was requested longitudinally: ordered per-metric series with explicit exclusions. The aggregate fields above still describe the whole cohort flat.

origins_sets = None pydantic-field

Shared origins lists, keyed by the origins_ref values carried on event_stats / biomarker_summary entries. On large projects every event family of one analysis configuration shares the same contributing studies, so each distinct list is carried once here instead of repeated per entry. None when all entries carry their origins inline. Use resolve_origins to read an entry's effective origins regardless of representation.

statistics_window = None pydantic-field

Deprecated for project reports: the FIRST study's window, kept for older consumers. A project's windows generally differ per study; use window_summary.

stratification = None pydantic-field

Set when the report was requested with stratify_by: the factor, the resolved bin edges and per-stratum study counts. None on unstratified reports.

tables = None pydantic-field

Server-defined tables: per-config distribution and biomarker-summary tables. None for producers predating the field.

warnings pydantic-field

Warnings about statistics computation

window_summary = None pydantic-field

How the studies' statistics windows were resolved — source counts and the length range. None for producers predating the field.

resolve_origins(entry)

Return the effective origins of a stats entry.

Entries carry their origins inline, or reference a shared list on this envelope via origins_ref. Consumers should always read origins through this method rather than entry.origins directly.

ProjectWindowSummary pydantic-model

Bases: BaseModel

How the statistics windows across a project's studies were resolved.

A project-level report aggregates studies whose windows generally differ — in source and in length — so a single window cannot describe it. This summarises: how many studies resolved their window from each source, and the range of window lengths. A study counts as lights-based when its window came from lights events, including one-ended windows where only lights-off or only lights-on was set.

Fields:

client_set pydantic-field

Studies whose window was pinned by a client override.

full_recording pydantic-field

Studies that fell back to the full recording.

lights_based pydantic-field

Studies whose window came from lights events (including one-ended lights windows).

max_length_ms = None pydantic-field

Longest resolved window, in ms. None when no study has a window.

min_length_ms = None pydantic-field

Shortest resolved window, in ms. None when no study has a window.

windowless pydantic-field

Studies with no resolvable window at all.

ReportAnalysisInfo pydantic-model

Bases: BaseModel

Analysis metadata for reports.

Fields:

analysis_config_id pydantic-field

Analysis config identifier

analysis_config_name pydantic-field

Analysis config name

analysis_config_version = None pydantic-field

Version of the analysis configuration that produced the results — provenance for the report audit appendix. None for producers predating the field.

analysis_id pydantic-field

Short analysis identifier

analysis_types pydantic-field

Types of analysis

channels = None pydantic-field

Channel names the analysis ran on — provenance for reports. None for producers predating the field.

completed_at = None pydantic-field

When the analysis completed — provenance for the report audit appendix. None for producers predating the field.

parameters pydantic-field

Analysis parameters

research_parameters = None pydantic-field

Parameters (by API name) whose value lay outside the analysis's validated regime, marking this analysis's outputs as exploratory. Empty when every parameter was within the regime. None when not derived (producers predating the field, or a configuration change made the submitted values unresolvable).

status pydantic-field

Analysis status

ReportAnnotatedEvents pydantic-model

Bases: BaseModel

Events with associated analysis metadata for reports.

Fields:

recording_length_ms = None pydantic-field

Length of the source recording in milliseconds, used for coverage % computation

ReportSection pydantic-model

Bases: BaseModel

One section of a report, in the order the report shows it.

The report's composition is served with its content: the live page renders these sections and every export is built from the same list, so the two show the same sections, in the same order, with the same defaults. A section points at its content (a table in tables, a figure by its key and source) rather than repeating it.

Fields:

default_visible = True pydantic-field

Whether the section shows when the reader has not chosen. A per-analysis section a comparison already covers starts hidden.

figure = None pydantic-field

For a 'figure' section: the key of its figure in the collection figure_source names.

figure_source = None pydantic-field

Where the figure is: 'hypnogram' (hypnograms, keyed by analysis id), 'chart' (charts), 'longitudinal' (longitudinal.charts) or 'subject' (longitudinal.subject_view.charts).

key pydantic-field

Stable section identity, in the section-key vocabulary; what a layout entry names.

kind pydantic-field

'text' (a sentence or two), 'heading' (groups the sections that name it as parent), 'table' or 'figure'.

parent = None pydantic-field

The key of the 'heading' section this one is grouped under; null at the top level.

table = None pydantic-field

For a 'table' section: the key of its table in the response's tables.

text = None pydantic-field

The prose of a 'text' section, or the line under a heading's title; formatted.

title = '' pydantic-field

The section's heading text.

ReportStratification pydantic-model

Bases: BaseModel

The stratification a report was computed with.

Present on stratified reports only. Echoes the factor, the resolved bin edges and the per-stratum study counts, so consumers can caption the grouping instead of inferring it from labels.

Fields:

edges = None pydantic-field

Resolved bin edges for numeric factors. Bins are half-open intervals [a, b): a value equal to an edge belongs to the bin above it. None for categorical factors (sex).

factor pydantic-field

The subject-metadata factor the report is stratified by.

strata pydantic-field

Every stratum in display order — edge order for numeric factors, enum order for sex — with the 'Not set' stratum last when present. Strata with zero studies are included.

unit = None pydantic-field

Unit the edges are expressed in (e.g. 'years'); None for categorical factors.

StatisticsWindow pydantic-model

Bases: BaseModel

The time window used for TIB-based statistics computation.

Resolved from study events (lights off/on), client override, or full recording. The source field tells the frontend how the window was determined.

Fields:

end_time_ms pydantic-field

Window end in ms from recording/study reference

source pydantic-field

How this window was determined

start_time_ms pydantic-field

Window start in ms from recording/study reference

StratumCount pydantic-model

Bases: BaseModel

Cohort count for one stratum of a stratified report.

Fields:

label pydantic-field

The stratum's group label, exactly as it appears on the report's stats entries and chart rows.

study_count pydantic-field

How many of the cohort fall in this stratum: distinct subjects when any study in scope carries a subject key, else studies — the same unit the report's demographics table counts.

StudyReportResponse pydantic-model

Bases: BaseModel

Envelope for study-level report data.

Wraps event statistics with optional biomarkers and the statistics window used for TIB-based metric computation.

Fields:

biomarkers = None pydantic-field

Per-analysis biomarker results (None if not requested)

event_stats pydantic-field

Per-analysis event statistics

hypnograms = None pydantic-field

Server-computed hypnogram chart models keyed by analysis_id. None for producers predating the field.

statistics_window = None pydantic-field

The time window used for statistics (None if no window available)

tables = None pydantic-field

Server-defined tables: biomarker and event-metrics tables with formatting and semantic status computed once. None for producers predating the field.

warnings pydantic-field

Warnings about statistics computation

UniqueChannel pydantic-model

Bases: BaseModel

A unique channel with its locations across recordings.

Fields:

channel_name pydantic-field

Name of the channel

identity = None pydantic-field

What these channels are, as stored on their rows (canonical name, side, and whether a person corrected any). None from a server that predates channel identity.

records pydantic-field

Locations where this channel appears

type pydantic-field

Type of the channel

unit pydantic-field

Physical unit of the channel