physioex 2.0.1__tar.gz → 2.0.2__tar.gz

{physioex-2.0.1 → physioex-2.0.2}/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to PhysioEx are documented here. Versions follow the
 `physioex.__version__` string (read dynamically by the build) and the `v*` git tags
 that publish to PyPI.
 
+## 2.0.2 — 2026-10-10
+
+### Fixed — accuracy-weighted modality dropout (`physioex.models.protosleepnet`)
+
+`ZeroEmbeddingDropout` now samples the channels to occlude with probability
+proportional to their accuracy, `p_c = a_c / sum_j a_j`, so the channels the
+model relies on most are dropped most often. This is the rule the released
+ProtoSleepNet and ProtoSleepTransformer models were trained with; a later
+refactoring had inverted the sampling weights to `1 - a_c`. When no accuracy
+estimate is available yet the sampling is uniform. Unit tests in
+`tests/test_modality_dropout.py`.
+
 ## 2.0.1 — 2026-09-13
 
 ### Added — Layer-wise Relevance Propagation (`physioex.explain.lrp`)

{physioex-2.0.1 → physioex-2.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: physioex
-Version: 2.0.1
+Version: 2.0.2
 Summary: A python package for explainable sleep staging via deep learning
 Project-URL: Homepage, https://github.com/guidogagl/physioex
 Project-URL: Documentation, https://guidogagl.github.io/physioex
@@ -64,7 +64,7 @@ Description-Content-Type: text/markdown
 # PhysioEx
 
 ![Python Version](https://img.shields.io/badge/python-3.11%2B-blue)
-[![PyPI Version](https://img.shields.io/pypi/v/physioex)](https://pypi.org/project/physioex/)
+[![PyPI Version](https://img.shields.io/pypi/v/physioex?cacheSeconds=3600)](https://pypi.org/project/physioex/)
 
 **PhysioEx ( Physiological Signal Explainer )** is a versatile python library tailored for building, training, and explaining deep learning models for physiological signal analysis. 
 
@@ -172,8 +172,20 @@ Note: the github version of the library is kept updated weekly, the PiPy version
 $ 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).** The `explain` extra depends on
+> `zennit`, which requires `torchvision`. If your `torch` comes from the PyTorch
+> CPU index, install `torchvision` from the **same** index *before* the extra,
+> otherwise pip pulls a CUDA build from PyPI that fails at import with
+> `operator torchvision::nms does not exist`:
+>
+> ```bash
+> $ pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
+> $ pip install "physioex[explain]"
+> ```
+
 ## Quickstart
 
 Set `PHYSIOEX_DATA` to the directory holding your datasets, then use the raw-EDF

{physioex-2.0.1 → physioex-2.0.2}/README.md

@@ -5,7 +5,7 @@
 # PhysioEx
 
 ![Python Version](https://img.shields.io/badge/python-3.11%2B-blue)
-[![PyPI Version](https://img.shields.io/pypi/v/physioex)](https://pypi.org/project/physioex/)
+[![PyPI Version](https://img.shields.io/pypi/v/physioex?cacheSeconds=3600)](https://pypi.org/project/physioex/)
 
 **PhysioEx ( Physiological Signal Explainer )** is a versatile python library tailored for building, training, and explaining deep learning models for physiological signal analysis. 
 
@@ -113,8 +113,20 @@ Note: the github version of the library is kept updated weekly, the PiPy version
 $ 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).** The `explain` extra depends on
+> `zennit`, which requires `torchvision`. If your `torch` comes from the PyTorch
+> CPU index, install `torchvision` from the **same** index *before* the extra,
+> otherwise pip pulls a CUDA build from PyPI that fails at import with
+> `operator torchvision::nms does not exist`:
+>
+> ```bash
+> $ pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
+> $ pip install "physioex[explain]"
+> ```
+
 ## Quickstart
 
 Set `PHYSIOEX_DATA` to the directory holding your datasets, then use the raw-EDF

{physioex-2.0.1 → physioex-2.0.2}/docs/pages/explain/explain.md

@@ -64,6 +64,12 @@ is **optional** — install the extra:
 pip install "physioex[explain]"
 ```
 
+The extra pulls in `zennit`, and therefore `torchvision`. On a CPU-only `torch`
+from the PyTorch index, install `torch torchvision` from that same index *first*
+(`pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu`),
+or pip will fetch a mismatched CUDA `torchvision` from PyPI that fails at import
+(`operator torchvision::nms does not exist`).
+
 Two entry points, both seeding the target neuron with its **logit value** so
 that `Σ R ≈ f_c(x)` and returning relevance shaped like the input:
 

physioex-2.0.2/physioex/__init__.py

@@ -0,0 +1 @@
+__version__ = "2.0.2"

{physioex-2.0.1 → physioex-2.0.2}/physioex/models/protosleepnet.py

@@ -52,9 +52,17 @@ from physioex.train.metrics import accuracy_score
 
 
 class ZeroEmbeddingDropout(nn.Module):
-    """Drop channels by replacing embeddings with the encoder's zero-input
-    embedding. Drop probability is accuracy-weighted: low-accuracy channels
-    are dropped more often.
+    """Accuracy-weighted modality dropout.
+
+    Replaces the embeddings of selected channels with the encoder's
+    zero-input embedding. The drop probability of channel ``c`` is
+    proportional to its accuracy, ``p_c = a_c / sum_j a_j``, so the
+    channels the model relies on most are occluded most often and the
+    model must learn to stage from the secondary modalities.
+
+    For each sample, with probability ``p_apply`` a number ``n`` of
+    channels drawn uniformly in ``{1, ..., C-1}`` is sampled without
+    replacement according to ``{p_c}`` and replaced.
 
     Only active during training.
 
@@ -84,11 +92,13 @@ class ZeroEmbeddingDropout(nn.Module):
         else:
             acc = torch.tensor(channel_acc, device=device, dtype=torch.float32)
 
-        proba = 1.0 - acc
+        proba = acc.clamp(min=0.0)
         proba_sum = proba.sum()
         if proba_sum <= 0:
-            return x
-        proba = proba / proba_sum
+            # No accuracy estimate yet: fall back to uniform sampling.
+            proba = torch.full((nchan,), 1.0 / nchan, device=device)
+        else:
+            proba = proba / proba_sum
 
         apply_mask = torch.rand(batch, device=device) < self.p_apply
         n_to_drop = torch.randint(1, nchan, (batch,), device=device)

physioex-2.0.2/tests/test_modality_dropout.py

@@ -0,0 +1,62 @@
+"""Accuracy-weighted modality dropout of ProtoSleepNet.
+
+The drop probability of a channel must be proportional to its accuracy,
+``p_c = a_c / sum_j a_j``: the most accurate channel is the one occluded
+most often.
+"""
+from __future__ import annotations
+
+import pytest
+
+torch = pytest.importorskip("torch")
+
+from physioex.models.protosleepnet import ZeroEmbeddingDropout  # noqa: E402
+
+pytestmark = pytest.mark.unit
+
+
+def _drop_counts(acc, n_samples=4000, seed=0):
+    torch.manual_seed(seed)
+    nchan = len(acc)
+    drop = ZeroEmbeddingDropout(p_apply=1.0).train()
+    x = torch.ones(n_samples, nchan, 4)
+    zero_emb = torch.zeros(1, 4)
+    out = drop(x, zero_emb, torch.tensor(acc))
+    dropped = (out == 0).all(dim=-1)  # (n_samples, nchan)
+    return dropped.float().sum(dim=0)
+
+
+def test_high_accuracy_channel_is_dropped_most():
+    counts = _drop_counts([0.9, 0.3, 0.1])
+    assert counts[0] > counts[1] > counts[2]
+
+
+def test_drop_frequency_follows_accuracy_ratio():
+    # With two channels, exactly one is dropped per sample (n in {1}), so
+    # the empirical drop frequency equals p_c = a_c / sum_j a_j.
+    counts = _drop_counts([0.8, 0.2], n_samples=20000)
+    freq = counts / counts.sum()
+    assert abs(freq[0].item() - 0.8) < 0.02
+    assert abs(freq[1].item() - 0.2) < 0.02
+
+
+def test_never_drops_all_channels():
+    torch.manual_seed(0)
+    drop = ZeroEmbeddingDropout(p_apply=1.0).train()
+    x = torch.ones(512, 3, 4)
+    out = drop(x, torch.zeros(1, 4), torch.tensor([0.5, 0.3, 0.2]))
+    kept = (out != 0).any(dim=-1).sum(dim=1)
+    assert (kept >= 1).all()
+
+
+def test_uniform_fallback_without_accuracy_estimates():
+    counts = _drop_counts([0.0, 0.0, 0.0], n_samples=6000)
+    freq = counts / counts.sum()
+    assert (freq - 1.0 / 3).abs().max().item() < 0.03
+
+
+def test_identity_in_eval_mode():
+    drop = ZeroEmbeddingDropout(p_apply=1.0).eval()
+    x = torch.randn(8, 3, 4)
+    out = drop(x, torch.zeros(1, 4), torch.tensor([0.9, 0.1, 0.1]))
+    assert torch.equal(out, x)

physioex-2.0.1/physioex/__init__.py

@@ -1 +0,0 @@
-__version__ = "2.0.1"