Add model card with citations, dataset links, and evaluation results

README.md

@@ -1,3 +1,140 @@
----
-license: mit
----
+---
+language: en
+license: apache-2.0
+tags:
+  - sleep-staging
+  - eeg
+  - pytorch
+  - physioex
+pretty_name: PhysioEx Pretrained Models
+---
+
+# PhysioEx — Pretrained Sleep Staging Models
+
+Pretrained deep learning models for automatic sleep staging from [PhysioEx](https://github.com/guidogagl/physioex) (Gagliardi et al. 2025).
+
+All models follow the AASM 5-class standard: **W, N1, N2, N3, REM**.
+
+## Available Models
+
+| Model | Architecture | Training Dataset | Channels | Pipeline | Params | Reference |
+|---|---|---|---|---|---|---|
+| `seqsleepnet-phan` | BiLSTM + Attention | Sleep-EDF | EEG | seqsleepnet (STFT) | 659K | Phan et al. 2019 |
+| `tinysleepnet-supratak` | CNN + LSTM | Sleep-EDF | EEG | raw | 83K | Supratak & Guo 2020 |
+| `sleeptransformer-phan` | Transformer | SHHS | EEG | seqsleepnet (STFT) | 2.1M | Phan et al. 2022 |
+| `lseqsleepnet-phan` | Long-sequence BiLSTM | SHHS | EEG | seqsleepnet (STFT) | 1.8M | Phan et al. 2023 |
+| `chambon2018` | Braindecode CNN | MASS SS3 | EEG | raw (128 Hz) | 220K | Chambon et al. 2018 |
+| `tsinalis-2016` | 2-layer CNN | Sleep-EDF | EEG | identity | 145K | Tsinalis et al. 2016 |
+
+*Models are added as training completes. Check back for updates.*
+
+## Usage
+
+```python
+from physioex.models import load_from_pretrained
+
+# Load a pretrained model
+model = load_from_pretrained("seqsleepnet-phan", verbose=True)
+
+# Use for inference or embedding extraction
+from physioex.models import extract_embeddings, load_embeddings
+
+# Extract embeddings on a new dataset
+path = extract_embeddings(model, dataset, model_name="seqsleepnet-phan", ...)
+
+# Or download pre-extracted embeddings from HuggingFace
+path = load_embeddings("seqsleepnet-phan", "hmc", verbose=True)
+```
+
+## Cross-Dataset Evaluation (SeqSleepNet-Phan)
+
+Zero-shot transfer from Sleep-EDF to other datasets (voting evaluation):
+
+| Dataset | ACC | Macro F1 | κ |
+|---|---|---|---|
+| **Sleep-EDF** (train) | 0.8101 | 0.7575 | 0.7421 |
+| DCSM | 0.6649 | 0.5839 | 0.5370 |
+| MESA | 0.6330 | 0.5546 | 0.4921 |
+| MASS | 0.6033 | 0.5422 | 0.4655 |
+| HMC | 0.5851 | 0.5574 | 0.4464 |
+| WSC | 0.4928 | 0.4577 | 0.3255 |
+| Parkinsons | 0.4428 | 0.3902 | 0.2737 |
+| SHHS | 0.3989 | 0.3597 | 0.2434 |
+| Alzheimers | 0.2582 | 0.1449 | 0.0239 |
+
+## Pre-extracted Embeddings
+
+Contextualized per-epoch embeddings are available as separate dataset repos:
+
+| Model | HuggingFace Repo | Datasets |
+|---|---|---|
+| SeqSleepNet-Phan | [`4rooms/seqsleepnet-phan-embeddings`](https://huggingface.co/datasets/4rooms/seqsleepnet-phan-embeddings) | 20 datasets, 12.5K subjects |
+
+## Datasets
+
+| Dataset | Source | URL |
+|---|---|---|
+| Sleep-EDF | PhysioNet | https://physionet.org/content/sleep-edfx/1.0.0/ |
+| HMC | PhysioNet | https://physionet.org/content/hmc-sleep-staging/1.1/ |
+| DCSM | ERDA/KU | https://erda.ku.dk/public/archives/db553715ecbe1f3ac66c1dc569826eef/published-archive.html |
+| SHHS | NSRR | https://sleepdata.org/datasets/shhs |
+| MESA | NSRR | https://sleepdata.org/datasets/mesa |
+| HomePAP | NSRR | https://sleepdata.org/datasets/homepap |
+| STAGES | NSRR | https://sleepdata.org/datasets/stages |
+| MASS | CEAMS | http://ceams-carsm.ca/mass/ |
+| WSC | NSRR | https://sleepdata.org/datasets/wsc |
+| MrOS | NSRR | https://sleepdata.org/datasets/mros |
+
+## Citations
+
+```bibtex
+@article{gagliardi2025physioex,
+    author={Gagliardi, Guido and Alfeo, Luca and Cimino, Mario G C A and Valenza, Gaetano and De Vos, Maarten},
+    title={PhysioEx, a new Python library for explainable sleep staging through deep learning},
+    journal={Physiological Measurement},
+    url={http://iopscience.iop.org/article/10.1088/1361-6579/adaf73},
+    year={2025},
+}
+
+@article{phan2019seqsleepnet,
+    title={SeqSleepNet: End-to-End Hierarchical Recurrent Neural Network for Sequence-to-Sequence Automatic Sleep Staging},
+    author={Phan, Huy and Andreotti, Fernando and Cooray, Navin and Chen, Oliver Y and De Vos, Maarten},
+    journal={IEEE Transactions on Neural Systems and Rehabilitation Engineering},
+    year={2019},
+}
+
+@inproceedings{supratak2020tinysleepnet,
+    title={TinySleepNet: An Efficient Deep Learning Model for Sleep Stage Scoring based on Raw Single-Channel EEG},
+    author={Supratak, Akara and Guo, Yike},
+    booktitle={IEEE EMBC},
+    year={2020},
+}
+
+@article{phan2022sleeptransformer,
+    title={SleepTransformer: Automatic Sleep Staging with Interpretability and Uncertainty Quantification},
+    author={Phan, Huy and Mikkelsen, Kaare and Ch\'en, Oliver Y and Koch, Philipp and Mertins, Alfred and De Vos, Maarten},
+    journal={IEEE Transactions on Biomedical Engineering},
+    year={2022},
+}
+
+@article{phan2023lseqsleepnet,
+    title={L-SeqSleepNet: Whole-cycle Long Sequence Modelling for Automatic Sleep Staging},
+    author={Phan, Huy and Ch\'en, Oliver Y and Koch, Philipp and Lu, Zhongxiang and McLoughlin, Ian and Mertins, Alfred and De Vos, Maarten},
+    journal={IEEE Transactions on Neural Systems and Rehabilitation Engineering},
+    year={2023},
+}
+
+@article{chambon2018deep,
+    title={A deep learning architecture for temporal sleep stage classification using multivariate and multimodal time series},
+    author={Chambon, Stanislas and Galtier, Mathieu and Arnal, Pierrick and Wainrib, Gilles and Gramfort, Alexandre},
+    journal={IEEE Transactions on Neural Systems and Rehabilitation Engineering},
+    year={2018},
+}
+
+@article{tsinalis2016automatic,
+    title={Automatic Sleep Stage Scoring with Single-Channel EEG Using Convolutional Neural Networks},
+    author={Tsinalis, Orestis and Matthews, Paul M and Guo, Yike and Zafeiriou, Stefanos},
+    journal={arXiv:1610.01683},
+    year={2016},
+}
+```