PhysioEx, a PyTorch based library for Interpretable physiological signal classifiers
See the code
PhysioEx ( Physiological Signal Explainer ) is a versatile python library tailored for building, training, and explaining deep learning models for physiological signal analysis.
The main purpose of the library is to propose a standard and fast methodology to train and evalutate state-of-the-art deep learning architectures for physiological signal analysis, to shift the attention from the architecture building task to the explainability task.
With PhysioEx you can simulate a state-of-the-art experiment just running the train, test_model and finetune commands; evaluating and saving the trained model; and start focusing on the explainability task!
Beyond training classic architectures from scratch, PhysioEx wraps a family of pretrained foundation encoders behind a uniform interface, so you can extract embeddings, run linear probes, and apply the explainability tools on top of them.
The explainability toolkit (physioex.explain) offers gradient-based attribution
(Saliency, Input×Gradient, Integrated / Expected Gradients and their DFT/STFT
variants), concept and prototype methods, and — since 2.0.1 — Layer-wise
Relevance Propagation for CNN, recurrent and attention/transformer models
(pip install "physioex[explain]"), with built-in conservation diagnostics.
PhysioEx ships two families of models under physioex.models.
Classic sleep-staging architectures (trained from scratch):
TsinalisCNN) — raw time series as input.LSeqSleepNet) — long-sequence time-frequency modelling.Foundation encoders (pretrained backbones exposed through a uniform
(B, L, C, T) -> (B, L, D) encode() interface, for embedding extraction and
linear probing): CBraMod, BENDR, LaBraM, BIOT, SleepFM, TFC, REVE,
S-JEPA, NeuroLM.
All datasets are resolved by name via get_dataset(name); available_datasets() returns:
alzheimers, ccshs, dcsm, hmc, hpap, mass, mesa, mros, parkinsons, shhs, sleepedf, stages, wsc.
These datasets are supported out of the box — PhysioEx reads the raw recordings directly (preprocessing is applied lazily, on the fly).
These datasets can be obtained from the NSRR archive. Once downloaded, point PhysioEx at the dataset root and it will read the recordings directly.
first / second / all).ccshs), 515 children and adolescents with one in-home PSG each (NSRR ccshs-trec): C3/A2 and C4/A1 EEG (128 Hz), LOC/ROC EOG (128 Hz) and chin EMG (256 Hz), stages scored by Rechtschaffen & Kales and merged to N3. Eleven recordings whose hypnogram cannot be reconciled with the NSRR summary table are excluded by default (exclude_subjects=[] keeps them).hpap), a positive-airway-pressure study in NSRR format, with three subsets — lab-full, lab-split and home — selectable via the subset parameter.alzheimers, UZ Leuven), 69 subjects (37 Alzheimer's + 32 healthy controls), one night each with an average-reference EEG montage, differential EOG, chin EMG and ECG at 200 Hz. The subset parameter selects only AD or HC subjects.parkinsons, UZ Leuven), 87 subjects (48 Parkinson's + 40 healthy older adults) with up to 157 recordings (night and nap), bipolar EEG montage, EOG, chin EMG and ECG at 500 Hz.$ conda create -n physioex python==3.11
$ conda activate physioex
$ conda install pip
$ pip install --upgrade pip # On Windows, use `venv\Scripts\activate`
$ git clone https://github.com/guidogagl/physioex.git
$ cd physioex
$ pip install -e .
$ pip install physioex
Note: the github version of the library is kept updated weekly, the PiPy version may be outdated depending on the last commit of the github version. We recommend to use the github version if possible.
Optional extras (heavyweight, feature-specific deps installed lazily):
$ pip install "physioex[foundation]" # transformers, for the REVE encoder
$ pip install "physioex[datasets]" # mne, for the HOMEPAP EDF fallback reader
$ pip install "physioex[tracking]" # tensorboard / wandb logging
$ pip install "physioex[explain]" # zennit, for Layer-wise Relevance Propagation
Note on
torchvision(CPU-only installs). Theexplainextra depends onzennit, which requirestorchvision. If yourtorchcomes from the PyTorch CPU index, installtorchvisionfrom the same index before the extra, otherwise pip pulls a CUDA build from PyPI that fails at import withoperator torchvision::nms does not exist:$ pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu $ pip install "physioex[explain]"
Set PHYSIOEX_DATA to the directory holding your datasets, then use the raw-EDF
data layer, the model zoo, and the training loop:
import os
os.environ["PHYSIOEX_DATA"] = "/path/to/datasets"
from physioex.data.datasets import get_dataset, available_datasets
from physioex.models.tinysleepnet import TinySleepNet
from physioex.train.trainer import Trainer
print(available_datasets()) # -> ['hmc', 'sleepedf', 'dcsm', 'mass', ...]
dataset = get_dataset("hmc")(
channels=["EEG", "EOG", "EMG"],
pipelines="time_domain", # preset preprocessing pipeline
sequence_length=21,
)
model = TinySleepNet(in_chan=3, n_classes=5)
model = Trainer.train(model=model, dataset=dataset, max_epochs=20)
Load a pretrained model or extract foundation-model embeddings:
from physioex.models import load_from_pretrained, extract_embeddings, linear_probe
from physioex.models import CBraModEncoder
model = load_from_pretrained("protosleepnet") # from the HF model zoo
encoder = CBraModEncoder()
ds = encoder.get_dataset("hmc") # matched preprocessing
emb = extract_embeddings(encoder, ds)
scores = linear_probe(emb)
The same dataset spec drives the CLI (train / finetune / test_model) — see
the CLI page in the documentation.
@article{10.1088/1361-6579/adaf73,
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},
}
PhysioEx, a PyTorch based library for Interpretable physiological signal classifiers
See the code
PhysioEx ( Physiological Signal Explainer ) is a versatile python library tailored for building, training, and explaining deep learning models for physiological signal analysis.
The main purpose of the library is to propose a standard and fast methodology to train and evalutate state-of-the-art deep learning architectures for physiological signal analysis, to shift the attention from the architecture building task to the explainability task.
With PhysioEx you can simulate a state-of-the-art experiment just running the train, test_model and finetune commands; evaluating and saving the trained model; and start focusing on the explainability task!
Beyond training classic architectures from scratch, PhysioEx wraps a family of pretrained foundation encoders behind a uniform interface, so you can extract embeddings, run linear probes, and apply the explainability tools on top of them.
The explainability toolkit (physioex.explain) offers gradient-based attribution
(Saliency, Input×Gradient, Integrated / Expected Gradients and their DFT/STFT
variants), concept and prototype methods, and — since 2.0.1 — Layer-wise
Relevance Propagation for CNN, recurrent and attention/transformer models
(pip install "physioex[explain]"), with built-in conservation diagnostics.
PhysioEx ships two families of models under physioex.models.
Classic sleep-staging architectures (trained from scratch):
TsinalisCNN) — raw time series as input.LSeqSleepNet) — long-sequence time-frequency modelling.Foundation encoders (pretrained backbones exposed through a uniform
(B, L, C, T) -> (B, L, D) encode() interface, for embedding extraction and
linear probing): CBraMod, BENDR, LaBraM, BIOT, SleepFM, TFC, REVE,
S-JEPA, NeuroLM.
All datasets are resolved by name via get_dataset(name); available_datasets() returns:
alzheimers, ccshs, dcsm, hmc, hpap, mass, mesa, mros, parkinsons, shhs, sleepedf, stages, wsc.
These datasets are supported out of the box — PhysioEx reads the raw recordings directly (preprocessing is applied lazily, on the fly).
These datasets can be obtained from the NSRR archive. Once downloaded, point PhysioEx at the dataset root and it will read the recordings directly.
first / second / all).ccshs), 515 children and adolescents with one in-home PSG each (NSRR ccshs-trec): C3/A2 and C4/A1 EEG (128 Hz), LOC/ROC EOG (128 Hz) and chin EMG (256 Hz), stages scored by Rechtschaffen & Kales and merged to N3. Eleven recordings whose hypnogram cannot be reconciled with the NSRR summary table are excluded by default (exclude_subjects=[] keeps them).hpap), a positive-airway-pressure study in NSRR format, with three subsets — lab-full, lab-split and home — selectable via the subset parameter.alzheimers, UZ Leuven), 69 subjects (37 Alzheimer's + 32 healthy controls), one night each with an average-reference EEG montage, differential EOG, chin EMG and ECG at 200 Hz. The subset parameter selects only AD or HC subjects.parkinsons, UZ Leuven), 87 subjects (48 Parkinson's + 40 healthy older adults) with up to 157 recordings (night and nap), bipolar EEG montage, EOG, chin EMG and ECG at 500 Hz.$ conda create -n physioex python==3.11
$ conda activate physioex
$ conda install pip
$ pip install --upgrade pip # On Windows, use `venv\Scripts\activate`
$ git clone https://github.com/guidogagl/physioex.git
$ cd physioex
$ pip install -e .
$ pip install physioex
Note: the github version of the library is kept updated weekly, the PiPy version may be outdated depending on the last commit of the github version. We recommend to use the github version if possible.
Optional extras (heavyweight, feature-specific deps installed lazily):
$ pip install "physioex[foundation]" # transformers, for the REVE encoder
$ pip install "physioex[datasets]" # mne, for the HOMEPAP EDF fallback reader
$ pip install "physioex[tracking]" # tensorboard / wandb logging
$ pip install "physioex[explain]" # zennit, for Layer-wise Relevance Propagation
Note on
torchvision(CPU-only installs). Theexplainextra depends onzennit, which requirestorchvision. If yourtorchcomes from the PyTorch CPU index, installtorchvisionfrom the same index before the extra, otherwise pip pulls a CUDA build from PyPI that fails at import withoperator torchvision::nms does not exist:$ pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu $ pip install "physioex[explain]"
Set PHYSIOEX_DATA to the directory holding your datasets, then use the raw-EDF
data layer, the model zoo, and the training loop:
import os
os.environ["PHYSIOEX_DATA"] = "/path/to/datasets"
from physioex.data.datasets import get_dataset, available_datasets
from physioex.models.tinysleepnet import TinySleepNet
from physioex.train.trainer import Trainer
print(available_datasets()) # -> ['hmc', 'sleepedf', 'dcsm', 'mass', ...]
dataset = get_dataset("hmc")(
channels=["EEG", "EOG", "EMG"],
pipelines="time_domain", # preset preprocessing pipeline
sequence_length=21,
)
model = TinySleepNet(in_chan=3, n_classes=5)
model = Trainer.train(model=model, dataset=dataset, max_epochs=20)
Load a pretrained model or extract foundation-model embeddings:
from physioex.models import load_from_pretrained, extract_embeddings, linear_probe
from physioex.models import CBraModEncoder
model = load_from_pretrained("protosleepnet") # from the HF model zoo
encoder = CBraModEncoder()
ds = encoder.get_dataset("hmc") # matched preprocessing
emb = extract_embeddings(encoder, ds)
scores = linear_probe(emb)
The same dataset spec drives the CLI (train / finetune / test_model) — see
the CLI page in the documentation.
@article{10.1088/1361-6579/adaf73,
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},
}