SleepFMStager — pretrained sleep stager

Mirror of the official SleepFM sleep-staging model, re-hosted for stable loading from Braindecode.

SleepFM is a multimodal polysomnography (PSG) foundation model introduced in:

R. Thapa et al., "A multimodal sleep foundation model for disease prediction," Nature Medicine (2026). https://doi.org/10.1038/s41591-025-04133-4

Files

File	Description
model.safetensors	The complete stager (180 tensors: tokenizer, channel pooling, temporal Transformer and staging head), with the parameter names of braindecode.models.SleepFMStager
config.json	Architecture of the checkpoint, read by from_pretrained()

Upstream ships the stager in two pieces: the encoder (channel-agnostic tokenizer, channel pooling and temporal Transformer) lives in model_base/best.pt and the staging head in model_sleep_staging/best.pth. This file merges both, so a single call returns a model that is pretrained end to end, its five-class output layer included. It holds the whole encoder except its trial-level temporal pooling, which sleep staging does not use. The tensors are those of the upstream artifacts; only the keys were rewritten to the library's parameter names. Loading this file or the two upstream ones gives bit-identical outputs.

The upstream artifacts themselves are kept, byte-for-byte, in braindecode/SleepFM.

Training data

The data that shaped these weights. The ids are the datasets: field of this card, which braindecode reads into model.card_data.datasets when you call from_pretrained (MOABB class names for MOABB datasets, OpenNeuro / NEMAR accessions, Hub ids otherwise). nm/on ids are datasets on NEMAR (on = NEMAR's copy of the OpenNeuro dataset with the same number). Rows marked private: are data the authors did not release; they are not in datasets:.

datasets: id	Dataset	Stage	Modality
SSC	Stanford Sleep Clinic PSG cohort (Stanford Sleep Dataset)	pretraining, fine-tuning	PSG
private:BioSerenity	BioSerenity / SleepMed proprietary PSG collection (18,869 overnight recordings)	pretraining	PSG
MESA	Multi-Ethnic Study of Atherosclerosis (sleep ancillary, NSRR)	pretraining, fine-tuning	PSG
MrOS	Outcomes of Sleep Disorders in Older Men (MrOS Sleep, NSRR)	pretraining, fine-tuning	PSG
SHHS	Sleep Heart Health Study (NSRR)	fine-tuning	PSG

• Encoder weights = braindecode/SleepFM (leave-one-out contrastive pretraining, SHHS held out).
• Sleep-staging head (modality pooling, Transformer, BiLSTM, 5-class FC) trained on frozen encoder embeddings; upstream model_sleep_staging/config.json lists "dataset": "ssc_stanford,mesa,mros,shhs" (train split; SHHS test = 2,000 nights). BioSerenity has no staging labels and is not listed.
• Starts from the weights of braindecode/SleepFM, whose card lists the data those saw.
• Sources: Thapa et al., Nature Medicine 2026, doi:10.1038/s41591-025-04133-4, Results 'Dataset and SleepFM architecture'; https://github.com/zou-group/sleepfm-clinical/blob/main/sleepfm/checkpoints/model_sleep_staging/config.json; same config.json; braindecode SleepFMStager docstring.

Usage

from braindecode.models import SleepFMStager

# Defaults to this repository. The release encodes BAS, RESP, EKG and EMG
# channels as separate modalities; name the modality of each channel.
model = SleepFMStager.from_pretrained(
    n_chans=7,
    n_outputs=5,
    n_times=38400,
    sfreq=128,
    channel_modalities=["BAS"] * 3 + ["RESP"] * 2 + ["EKG", "EMG"],
)
model.eval()

config.json leaves channel_modalities unset (null), because it depends on the montage. Without it every channel is encoded as a single modality and from_pretrained warns.

The output has shape (batch, n_outputs, n_patches): one prediction per 5-second patch, not per 30-second scoring epoch, so six predictions cover one scored epoch. For this checkpoint the five classes are Wake, N1, N2, N3 and REM. Input must be sampled at 128 Hz. Pass n_outputs different from 5 to reinitialise the output layer for another label set.

Revisions

• 8681fba: tokenizer and staging head only (93 tensors). SleepFMStager.from_pretrained reads the encoder's channel pooling and temporal Transformer from braindecode/SleepFM at load time.
• Current revision: the complete stager (180 tensors), bit-identical to the upstream model_base/best.pt + model_sleep_staging/best.pth, re-exported with the fixed port of braindecode PR #1106. config.json now lists every constructor argument; the defaults (n_chans=4, n_times=3840, sfreq=128) are unchanged. Its outputs are bit-identical to those of 8681fba completed from braindecode/SleepFM, and both revisions load with SleepFMStager.from_pretrained (pass revision= to pin one).

License & attribution

• License: Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0).
• Copyright (c) 2025 Rahul Thapa.
• Upstream source: https://github.com/zou-group/sleepfm-clinical

These weights are not covered by Braindecode's BSD-3 license and inherit the upstream noncommercial terms. Re-hosted for reproducibility and stable availability only; attribution and the CC BY-NC 4.0 restriction are preserved.

Cite Braindecode

If you use this braindecode port in scientific work, cite the software on Zenodo, doi:10.5281/zenodo.17699192, and the original model and datasets cited above.

@software{braindecode,
  author = {Aristimunha, Bruno and
            Guetschel, Pierre and
            Wimpff, Martin and
            Gemein, Lukas and
            Rommel, Cedric and
            Banville, Hubert and
            Sliwowski, Maciej and
            Wilson, Daniel and
            Brandt, Simon and
            Gnassounou, Théo and
            Paillard, Joseph and
            {Junqueira Lopes}, Bruna and
            Sedlar, Sara and
            Moreau, Thomas and
            Chevallier, Sylvain and
            Gramfort, Alexandre and
            Schirrmeister, Robin Tibor},
  title = {Braindecode: toolbox for decoding raw electrophysiological brain data
           with deep learning models},
  url = {https://github.com/braindecode/braindecode},
  doi = {10.5281/zenodo.17699192},
  publisher = {Zenodo},
  license = {BSD-3-Clause},
}