Reproducing the paper

Every paper asset maps to an entry-point module run as python -m protosleepnet.<module>. Pass --help for options; full experiment settings (M value, seeds, datasets) are documented per script and mirrored in the protosleepnet.

Note

Raw recordings are not redistributed here — obtain them from their sources and preprocess with physioex (this repo ships none of its own preprocessing). Large artifacts (predictions, embeddings, reconstruction arrays, checkpoints) live in a backup root wired in via the git-ignored json/ and reconstructions_bulk/ symlinks; only small figure-source JSON is committed under data/.

Figure / table → experiment → command

Paper asset	Experiment	Command
Fig 2a; Supp §1	In-domain + OOD staging, per-class, confusion, stats	python -m protosleepnet.train · python -m protosleepnet.test_pretrained
Fig 2b; Supp §3,§8	M-sweep, residual/VQ robustness, VQ methods, randomization	python -m protosleepnet.posthoc_prototypes.learn_prototypes_vq · python -m protosleepnet.plot.residual · python -m protosleepnet.plot.vq
Supp §2	Ablation (4 component variants) + occlusion robustness	python -m protosleepnet.ablation.train_ablation --variant {baseline,dropout,mixer,protosleepnet} (SleepTransformer) / ...train_ablation_seqsleepnet ... (SeqSleepNet) · python -m protosleepnet.plot.occlusion
Fig 4; Supp §5,§6	Prototype reconstruction (data/model/hybrid) + cross-dataset	python -m protosleepnet.proto_reconstruction.data_driven (.model_driven, .hybrid) · python -m protosleepnet.figure_reconstruction.compute_cross_dataset_metrics
Fig 3; Tab 1,2; Supp §4,§6	Codebook summaries, band-ablation rules, coherence, local IG	python -m protosleepnet.figure_reconstruction.{rule_learning,spectral_signature,relevance_signature,compute_local_explanations,combinatorial_ablation}
Supp §9	Seed stability	python -m protosleepnet.seed_stability_pipeline
Fig 5; Supp §7	Clinical probing (AD/PD), frozen-model LOSO	python -m protosleepnet.clinical_probing.staging.extract_embeddings · python -m protosleepnet.probing.{parkinsons,alzheimers}.diagnosis_probe · python -m protosleepnet.clinical_probing.{parkinsons,alzheimers}.analyze_features

Manuscript figure/table assembly (LaTeX-coupled emitters) is kept out of this repo, with the paper sources.

Repository layout

src/protosleepnet/            # installable package (run as python -m protosleepnet.<mod>)
  train.py  test_*.py  extract_*.py  seed_*.py   # staging training/eval + seed-stability
  build_protosleepnet.py                          # shared model factory
  ablation/  baselines/                           # ablation & residual/mixer/dropout variants
  posthoc_prototypes/  proto_reconstruction/      # VQ codebook learning + reconstruction
  figure_reconstruction/                          # prototype cards / rules / spectral & relevance signatures
  probing/  clinical_probing/                      # clinical probing (AD/PD) compute + analysis
  ood_disease/                                     # OOD disease evaluation / transport
  plot/                                            # portable figure scripts (from predictions)
  demo/                                            # the interactive-demo precompute pipeline
examples/slurm/    # cluster launchers; copy env.sh.example -> env.sh
notebooks/         # global_explain.ipynb, local_explain.ipynb
data/              # small committed figure-source JSON only
tests/             # smoke tests (import graph + optional pretrained forward pass)

Smoke test

bash reproduce.sh      # load weights → forward pass → regenerate one figure

pip install -e . pytest
pytest                 # import-graph smoke test (no network)
pytest --runslow       # also pull weights from HuggingFace and run a forward pass

The interactive demo

The protosleepnet.demo subpackage builds the static bundle behind the Live demo: subject selection, subsetting/anonymization, the PaCMAP atlas, per-epoch IG, and the clinical-plausibility audit. It ships only anonymized derived artifacts — never the source signals. See its module reference in the protosleepnet.