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. Modules under clinical_probing/ run in the order listed.

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) are not in git; only small figure-source JSON is committed under data/ (data/reconstructions/M12/, the per-prototype records behind Fig 3–4 and Tab 1–2, and data/probing_staging_summary/, the staging tables of Supplementary Note 1). Paths are read from the environment: see Installation.

Figure / table → experiment → command#

Paper asset

Experiment

Command

Fig 2a; Supp Note 1

In-domain + OOD staging, per-class, confusion, stats

python -m protosleepnet.train · python -m protosleepnet.test_pretrained · python -m protosleepnet.extract_embeddings

Supp Note 2

Component ablation (4 variants) + occlusion robustness

python -m protosleepnet.ablation.train_ablation --variant {baseline,dropout,mixer,protosleepnet} (SleepTransformer) / ...train_ablation_seqsleepnet (SeqSleepNet) · python -m protosleepnet.test_occlusion · python -m protosleepnet.plot.occlusion · python -m protosleepnet.plot.occlusion_ablation

Fig 2b; Supp Note 3

M-sweep, VQ methods, residual baselines

python -m protosleepnet.learn_prototypes_vq · python -m protosleepnet.test_prototypes · python -m protosleepnet.posthoc_prototypes.{extract_epoch_embeddings,learn_prototypes_vq_kmeans,test_posthoc_prototypes,test_vq_paired,probe_posthoc_prototypes} · python -m protosleepnet.baselines.{train_*_residual,extract_residual_embeddings,learn_residual_prototypes_vq,test_residual_prototypes} · python -m protosleepnet.plot.{vq,residual,residual_ablation}

Supp Note 3 (§5)

Continuous-vs-quantized disagreement; paired per-subject κ

python -m protosleepnet.posthoc_prototypes.quantization_disagreement · python -m protosleepnet.posthoc_prototypes.non_inferiority

Fig 4; Supp Notes 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 Notes 4, 6

Codebook summaries, band-ablation rules, coherence checklist, local IG

python -m protosleepnet.figure_reconstruction.{rule_learning,spectral_signature,relevance_signature,combinatorial_ablation,compute_local_explanations}

Tab 2; Supp Note 6 (§5)

Checklist threshold sweeps + joint margins; stage-permutation control

python -m protosleepnet.figure_reconstruction.threshold_sweep · python -m protosleepnet.figure_reconstruction.stage_permutation

Supp Note 6 (§10)

Automatically detected spindles / slow waves vs band relevance (MASS SS2; needs pip install -e ".[events]")

python -m protosleepnet.figure_reconstruction.detect_events · python -m protosleepnet.figure_reconstruction.events_relevance

Supp Note 8

Prototype randomization

python -m protosleepnet.test_prototype_randomization

Supp Note 9

Seed stability (training seeds, reconstruction, MMD)

python -m protosleepnet.seed_stability_pipeline · python -m protosleepnet.convert_and_predict_seeds · python -m protosleepnet.seed_recon_all_m · python -m protosleepnet.seed_mmd_analysis · python -m protosleepnet.seed_stability_summary

Supp Note 9 (§4)

Coarse-to-fine codebook refinement across adjacent M

python -m protosleepnet.posthoc_prototypes.codebook_refinement

Fig 5; Tab 3; Supp Note 7

Clinical probing (ASD, KPD): frozen embeddings → training atlas → per-subject records → 20 features → 34-descriptor comparator → nested LOSO → DeLong inference → deficit structure

python -m protosleepnet.clinical_probing.staging.extract_embeddings · python -m protosleepnet.clinical_probing.atlas · python -m protosleepnet.clinical_probing.subject_stats · python -m protosleepnet.clinical_probing.build_features · python -m protosleepnet.clinical_probing.hypnogram_comparator · python -m protosleepnet.clinical_probing.nested_loso · python -m protosleepnet.clinical_probing.inference · python -m protosleepnet.clinical_probing.structure

Live demo

Subject selection, anonymized subset, PaCMAP atlas, per-epoch IG, prototype cards

python -m protosleepnet.demo.{select_subjects,precompute,precompute_indomain,build_cards,subset_bundle,evaluate_explanations}

CPU-only analyses have ready-made launchers under examples/slurm/analysis/. 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_pretrained.py  extract_embeddings.py   # staging training / evaluation
  learn_prototypes_vq.py  test_prototypes.py            # VQ codebook learning + quantized inference
  test_occlusion.py  test_prototype_randomization.py    # occlusion robustness, prototype randomization
  seed_*.py  convert_and_predict_seeds.py              # seed-stability pipeline
  build_protosleepnet.py                                # shared model factory
  ablation/  baselines/                                 # component ablation; residual / mixer / dropout variants
  posthoc_prototypes/                                   # k-means codebooks, quantization disagreement, codebook refinement
  proto_reconstruction/                                 # data-driven / model-driven / hybrid reconstruction
  figure_reconstruction/                                # rules, spectral & relevance signatures, local IG,
                                                        #   threshold sweeps, stage permutation, detected events
  clinical_probing/                                     # atlas, per-subject records, 20 features, nested LOSO,
                                                        #   hypnogram comparator, DeLong inference, deficit structure
  plot/                                                 # portable figure scripts (from predictions)
  demo/                                                 # interactive-demo precompute pipeline + static app
examples/slurm/    # cluster launchers; copy env.sh.example -> env.sh (analysis/ = CPU-only analyses)
data/              # small committed figure-source JSON only
scripts/           # HuggingFace upload of the released weights + model cards
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.