Overview#

ProtoSleepNet is a prototype-based, interpretable sleep-staging model. It wraps a standard staging backbone (SeqSleepNet or SleepTransformer) with a Prototype Sub-Stage (PSS) module that quantizes each 30-second epoch’s contextualized embedding onto a small, learned codebook of \(M=12\) prototypes. A sleep stage is then decided by which prototypes an epoch resembles — so reading the prototypes is reading the decision.

This is the companion documentation to the paper “Prototype-based interpretable sleep staging with physiologically meaningful sub-stage pattern discovery” (under review at npj Digital Medicine; version 1 preprint), and to the interactive explainability demo.

▶ Try it live

Explore the prototype atlas, click any epoch to see the evidence for its stage, and open the prototype cards: https://protosleepnet-demo.pages.dev. The Live demo page embeds it directly.

ProtoSleepNet interactive demo

How the model reasons#

        flowchart LR
    A[Raw PSG<br/>EEG · EOG · EMG] --> B[STFT log-power<br/>3 × 29 × 129]
    B --> C[Per-channel encoder<br/>+ modality embeddings]
    C --> D[Channel dropout →<br/>Transformer mixer]
    D --> E[Epoch embedding<br/>128-d]
    E -->|argmin L2| F[Prototype codebook<br/>M = 12]
    F --> G[Stage logits<br/>W · N1 · N2 · N3 · REM]
    E -.hypnogram.-> H[Prototype-gram<br/>full-night ribbon]

Each epoch is embedded into a 128-dimensional space, matched to its nearest prototype (squared-L2), and staged from the prototypes it activates. Because the codebook is small and each prototype is stage-specialized, the model is faithful by construction: there is no post-hoc surrogate between the explanation and the prediction.

The claims this documentation demonstrates#

The demo and the How to interpret ProtoSleepNet guide are organized around the paper’s explainability claims that a single public cohort can substantiate:

Claim

Where you see it

A

Faithful by construction — the model reasons only through similarity to the 12 prototypes.

The atlas + the nearest-prototype (L2) panel.

B

Every decision is traceable — each epoch is staged via its nearest prototype, with Integrated-Gradients evidence.

Epoch detail + per-epoch IG + hypnogram position.

C

Monosemantic prototypes — each of the 12 is a pure, stage-specialized pattern.

Prototype cards (purity / monosemanticity).

D

Clinically meaningful microstructure — signatures follow AASM physiology.

Rules, band/channel relevance, spectral envelope, and the How to interpret ProtoSleepNet audit.

G

Prototype-gram — the full-night prototype sequence is a new representation between raw PSG and the hypnogram.

The prototype-gram ribbon under each recording.

Claims E (no accuracy cost vs. the black-box backbone) and F (cross-dataset transfer and disease biomarkers) require multiple cohorts and are covered in the paper — the demo does not fabricate single-cohort visuals for them.

What is in this repository#

This repo is the experiment pipeline that produced every figure and table in the paper. The model, data loaders, preprocessing, dataset splits, seeds and metrics all live in physioex v2.0.0.