Installation#
ProtoSleepNet requires Python ≥ 3.10. The model, data loaders,
preprocessing, dataset splits, seeds and metrics come from
physioex == 2.0.2, which is installed
as a dependency.
conda env create -f environment.yml && conda activate protosleepnet # optional
pip install -e . # installs the `protosleepnet` package + physioex==2.0.2
pip install -e ".[events]" # + YASA/pyedflib, only for the detected-events analysis
After pip install -e . every script runs as a module from the repo root —
one convention throughout:
python -m protosleepnet.train --help
python -m protosleepnet.figure_reconstruction.spectral_signature --help
Pretrained weights#
Weights are on the HuggingFace Hub and load through physioex. Names follow the
physioex convention <model>-<primary-author>. The paper’s models live in
4rooms/sleep-prototypes:
from physioex.models import load_from_pretrained
# PST — SleepTransformer backbone (trained on SHHS, L=21)
model = load_from_pretrained("protosleeptransformer-gagliardi", repo_id="4rooms/sleep-prototypes")
# PSN — SeqSleepNet backbone (trained on MASS, L=20)
# load_from_pretrained("protosleepnet-gagliardi", repo_id="4rooms/sleep-prototypes")
# input (batch, L, 3, 29, 129) STFT log-power (EEG/EOG/EMG)
# output (batch, L, 5) AASM logits (W, N1, N2, N3, REM)
The 3-channel baselines and ablation variants are published alongside them:
{seqsleepnet,sleeptransformer}-gagliardi[-dropout|-mixer]. The Phan originals
{seqsleepnet,sleeptransformer}-phan are in 4rooms/physioex.
bash reproduce.sh runs a smoke path (load weights → forward pass → regenerate
one figure).
Documentation dependencies#
Building this documentation needs only a light, import-free set of tools
(no torch / physioex) — the module reference is parsed statically by
sphinx-autoapi, so the docs environment installs the doc tools alone (not the
package):
pip install -r docs/requirements.txt
sphinx-build -b html -W --keep-going docs docs/_build/html
Configuration (environment variables)#
Scripts read paths from the environment so no absolute paths are baked in:
Variable |
Meaning |
Default |
|---|---|---|
|
physioex dataset root (preprocessed datasets; raw MASS SS2 EDFs for the detected-events analysis) |
— |
|
root for predictions, embeddings and reconstruction outputs |
|
|
checkpoints / training statistics |
|
|
per-prototype reconstruction records (Fig 3–4, Tab 1–2 sources) |
|
|
root of the analysis modules ( |
|
|
raw KPD recordings (lights-off markers; clinical probing only) |
— |
Cluster launchers additionally source examples/slurm/env.sh (copy from
examples/slurm/env.sh.example).