Skip to content

biomarkers

Biomarker computation models.

Standard sleep biomarkers (13 metrics), QC metrics, and result envelope. Used by the report pipeline and single-analysis biomarker endpoints.

BiomarkerParameters pydantic-model

Bases: BaseModel

Parameters for biomarker computation.

TIB window is not included here — it comes from StatisticsWindow, resolved from study events or client override in the report use case.

Fields:

epoch_duration_sec = 30 pydantic-field

Epoch duration in seconds

soremp_threshold_min = 15.0 pydantic-field

Maximum minutes from sleep onset to the first REM epoch for the night to count a SOREMP

BiomarkerResult pydantic-model

Bases: BaseModel

Complete biomarker computation result for a single analysis.

Fields:

biomarkers pydantic-field

13 standard sleep biomarkers

metadata pydantic-field

Computation metadata (epoch count, computation time, etc.)

qc pydantic-field

Quality metrics

Biomarkers pydantic-model

Bases: BaseModel

13 standard sleep biomarkers.

TST, TIB, SE, SOL and WASO, plus REM latency, SOREMPs, the stage percentages and the sleep fragmentation index. The definitions follow the AASM scoring manual except where a description says otherwise. Each description is the metric's definition as the platform computes it, gotchas included, and is served as its help text. A metric that is undefined for a night (no sleep, no REM) is empty (None), never 0.

Sleep means an epoch scored N1, N2, N3 or REM (R&K stages 1-4 map onto them). "Sleep stage ?" (unscored), the generic "Sleep stage N" and movement time are no stage: they count toward time in bed and nothing else.

Fields:

fragmentation_index = None pydantic-field

Sleep fragmentation index: awakenings (sleep followed by wake) plus shifts to a lighter sleep stage (N3 to N2 or N1, N2 to N1, REM to N1), per hour of total sleep time. Counted between consecutive scored epochs; unscored epochs are skipped. It depends on the epoch length: shorter epochs resolve brief changes that 30-second scoring averages away, so compare it only between analyses with the same epoch length. Empty when no sleep is scored.

rem_latency_min = None pydantic-field

REM latency: minutes from sleep onset to the first REM epoch, wake in between included. Some software measures it from lights off or the start of the recording instead, which adds the sleep onset latency. Empty when no REM is scored.

sleep_efficiency_pct pydantic-field

Sleep efficiency: total sleep time as a percentage of time in bed (TST / TIB x 100). Without lights markers TIB is the whole recording, so efficiency reads lower than a lights-off-to-on figure.

sleep_onset_latency_min pydantic-field

Sleep onset latency: minutes from the start of the statistics window to the first epoch scored N1, N2, N3 or REM. When no sleep is scored it equals time in bed: the night counts as never falling asleep, and enters group means at that value.

soremps_count pydantic-field

Sleep-onset REM period: 1 when the first REM epoch begins within the SOREMP threshold (15 minutes by default) of sleep onset, otherwise 0. A per-night indicator for a nocturnal recording, not an MSLT's count across naps; summed over nights it is the number of nights with a SOREMP.

stage_percentages pydantic-field

Stage percentages

tib_min pydantic-field

Time in bed: the length of the statistics window in minutes, lights off to lights on when the study records them, otherwise the whole recording (the AASM's total recording time). Without lights markers it includes time before lights off and after lights on, which lowers sleep efficiency and lengthens sleep onset latency.

tst_min pydantic-field

Total sleep time: minutes scored N1, N2, N3 or REM inside the statistics window. Unscored epochs, the generic 'Sleep stage N' and movement time count toward no stage.

waso_min = None pydantic-field

Wake after sleep onset: minutes of wake between the first and the last epoch scored as sleep. Wake after the final awakening is not included; the AASM definition (TRT - sleep latency - TST) also counts wake until lights on, so it reads higher when the morning wake period is long. Empty when no sleep is scored.

QCMetrics pydantic-model

Bases: BaseModel

Quality metrics for a sleep analysis.

Confidence-dependent fields are None when events lack probability (non-probabilistic analysis configs).

Fields:

artifact_epochs pydantic-field

Number of artifact-flagged epochs

artifact_pct pydantic-field

Percentage of epochs flagged as artifact

confidence_mean = None pydantic-field

Mean confidence across all epochs

confidence_min = None pydantic-field

Minimum confidence across all epochs

confidence_p5 = None pydantic-field

5th percentile confidence

entropy = None pydantic-field

Staging entropy — true Shannon entropy from full 5-class softmax when available, argmax-based proxy otherwise

recording_completeness_pct pydantic-field

Percentage of recording length covered by events

total_epochs pydantic-field

Total number of epochs

transition_confidence = None pydantic-field

Mean confidence at epochs where the sleep stage changes

valid_epochs pydantic-field

Number of non-artifact epochs

StagePercentages pydantic-model

Bases: BaseModel

Stage percentages of total sleep time (N1–N3, REM) and time in bed (Wake).

Each description is the metric's definition as the platform computes it, served as its help text; the sleep stages are empty (None) when no sleep is scored, since a share of zero sleep is undefined rather than 0%.

Fields:

n1_pct = None pydantic-field

N1 time as a percentage of total sleep time (TST). Empty when no sleep is scored.

n2_pct = None pydantic-field

N2 time as a percentage of total sleep time (TST). Empty when no sleep is scored.

n3_pct = None pydantic-field

N3 time as a percentage of total sleep time (TST); Rechtschaffen & Kales stages 3 and 4 both count as N3. Empty when no sleep is scored.

rem_pct = None pydantic-field

REM time as a percentage of total sleep time (TST). Empty when no sleep is scored.

wake_pct pydantic-field

Wake time as a percentage of time in bed (TIB), not of TST as for the sleep stages. Epochs scored as no stage (unscored, movement time) count toward TIB only, so wake and the sleep stages' share of TIB need not add up to 100%.