physioex 2.0.0__tar.gz → 2.0.2__tar.gz

{physioex-2.0.0 → physioex-2.0.2}/.github/workflows/test.yml

@@ -27,12 +27,13 @@ jobs:
           # torchaudio must come from the same CPU index as torch, otherwise the
           # transitively-installed (braindecode) torchaudio has a mismatched ABI
           # and fails to load its compiled _torchaudio.so.
-          pip install torch torchaudio --index-url https://download.pytorch.org/whl/cpu
+          pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
 
-      - name: Install package (editable) with dev + legacy extras
+      - name: Install package (editable) with dev + legacy + explain extras
         # Editable so coverage's source=["physioex"] measures the executed tree
         # (a non-editable install runs the site-packages copy -> 0% reported).
-        run: pip install -e .[dev,legacy]
+        # 'explain' pulls in zennit so the LRP tests run instead of skipping.
+        run: pip install -e .[dev,legacy,explain]
 
       - name: Run test suite with coverage gate
         env:

physioex-2.0.2/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+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`)
+
+A conservation-based attribution family (Bach et al. 2015) covering the whole
+model zoo. Install with the new optional extra `pip install "physioex[explain]"`
+(Zennit only; no LXT dependency).
+
+- **Two entry points**, both seeding the target neuron with its logit so that
+  `Σ R ≈ f_c(x)`, both returning a per-sample `ConservationReport` with
+  `return_report=True`:
+  - `LRP` — Zennit composites for feed-forward / CNN models (Tsinalis,
+    Chambon2018): ε on dense, γ on convolutions, **w²** on the first layer
+    (unbounded EEG, not the pixel z-box), BatchNorm canonized; αβ / flat / z-box
+    configurable via `physioex_composite`.
+  - `ModelLRP` — whole-model LRP for recurrent, attention and transformer
+    architectures (TinySleepNet, SeqSleepNet, L-SeqSleepNet, SleepTransformer,
+    CoReSleep, ProtoSleepNet): **Arras signal-take** rule for LSTM/GRU at cell
+    level (`LRPLSTM`/`LRPGRU`, drop-in subclasses with a bit-identical forward,
+    `gate_rule="signal_take" | "uniform"`), **CP-LRP** for attention (value
+    path, exact conservation; Ali et al. 2022), identity rule for
+    LayerNorm/activations, proportional rule for residual sums, ε for linear
+    leaves and PhysioEx's learnable filterbank, CP-LRP adapters for the softmax
+    poolings (`AttentionPooling`, `AttentionLayer`, `ChannelMixer`).
+- `prepare_model_for_lrp` rewrites a deep copy of the model; plain `+` residuals
+  written in a model's own `forward` are redirected to the proportional rule at
+  runtime (`patch_residuals`); `audit_lrp_coverage` / `strict=True` report any
+  parametric leaf left on plain autograd; `register_lrp_adapter` adds custom
+  blocks. Signed, dtype-safe stabiliser `z + ε·sign z` everywhere (fp16-safe).
+- Docs: entry-point/rule matrix, how to read conservation and choose ε (ε must be
+  scaled to the activations: measured on the pretrained SeqSleepNet, 1e-6 inflates
+  relevance 2–3×, 1e-2 conserves), unsupported cases, and a literature note on
+  LRP vs path-based attribution (Deep Taylor, Integrated Gradients,
+  DeepLIFT/DeepSHAP). `physioex.explain.lrp` is in the API reference.
+- Example: `examples/explain/lrp_seqsleepnet_n3.py` explains the N3 logit of the
+  pretrained `seqsleepnet-phan` on MASS training sequences with Saliency,
+  Input×Gradient, Integrated Gradients and LRP under different rule assignments.
+- Tests: 91 new tests (`tests/explain/lrp/`), including forward-equivalence to
+  the fused modules, exact conservation on bias-free blocks and models, and all
+  six real architectures end-to-end with full rule coverage.
+
+### Known limitations
+
+CP-LRP assigns zero relevance to the attention query/key path by design (full
+AttnLRP is not implemented); bias relevance is absorbed (LRP-ε convention);
+attention masks, `batch_first=False` transformers, explicit RNN initial states
+and `proj_size` raise; ProtoSleepNet's VQ path runs under `no_grad`. Foundation
+encoders and frequency-domain (DFT/STFT) LRP are planned follow-ups.
+
+## 2.0.0 — 2026-07-15
+
+Ground-up release: raw-EDF lazy data layer with 12 dataset loaders, 9 pretrained
+foundation encoders behind a uniform `encode()` interface, hand-written `Trainer`,
+pytest suite and Sphinx documentation. Full notes in the
+[v2.0.0 GitHub Release](https://github.com/guidogagl/physioex/releases/tag/v2.0.0).

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: physioex
-Version: 2.0.0
+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
@@ -42,6 +42,8 @@ Requires-Dist: sphinx-copybutton==0.5.2; extra == 'docs'
 Requires-Dist: sphinx-design==0.6.1; extra == 'docs'
 Requires-Dist: sphinx==8.1.3; extra == 'docs'
 Requires-Dist: sphinxcontrib-mermaid==1.0.0; extra == 'docs'
+Provides-Extra: explain
+Requires-Dist: zennit>=0.5.1; extra == 'explain'
 Provides-Extra: foundation
 Requires-Dist: transformers>=4.40.0; extra == 'foundation'
 Provides-Extra: gpu-monitor
@@ -62,7 +64,7 @@ Description-Content-Type: text/markdown
 # PhysioEx
 
 ![Python Version](https://img.shields.io/badge/python-3.11%2B-blue)
-![PyPI Version](https://badge.fury.io/py/physioex.svg)
+[![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. 
 
@@ -74,6 +76,12 @@ 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.
+
 ## Supported deep learning architectures
 
 PhysioEx ships two families of models under `physioex.models`.
@@ -164,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.0 → 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://badge.fury.io/py/physioex.svg)
+[![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. 
 
@@ -17,6 +17,12 @@ 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.
+
 ## Supported deep learning architectures
 
 PhysioEx ships two families of models under `physioex.models`.
@@ -107,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.0 → physioex-2.0.2}/docs/api/index.md

@@ -128,7 +128,7 @@ Metrics, statistics and progress helpers are documented at module level:
 ## `physioex.explain`
 
 Post-hoc attribution, the foundational Conceptual Spectral Decomposition (CSD),
-and prototype discovery.
+prototype discovery, and Layer-wise Relevance Propagation (`explain` extra).
 
 ```{eval-rst}
 .. autosummary::
@@ -136,4 +136,5 @@ and prototype discovery.
 
    physioex.explain.foundational
    physioex.explain.prototypes.posthoc
+   physioex.explain.lrp
 ```

physioex-2.0.2/docs/pages/explain/explain.md

@@ -0,0 +1,158 @@
+# Explain Module
+
+PhysioEx ships an explainability (XAI) toolkit for sleep-staging and
+foundation models, organized under `physioex.explain`: three core families
+(post-hoc gradients, foundational/concept, prototypes) plus an optional
+**Layer-wise Relevance Propagation** family (`explain` extra). For
+the full class diagram see the
+[explain-layer architecture](../architecture/library/explain.md) page.
+
+## Post-hoc attribution — `physioex.explain.posthoc`
+
+Gradient-based attribution over a trained classifier, plus frequency- and
+time-frequency-domain variants:
+
+- **Time-domain**: `Saliency`, `InputXGradient`, `IntegratedGradients`,
+  `ExpectedGradients` (`physioex/explain/posthoc/gradients.py`). Each is a
+  `torch.nn.Module` built around a scalar-valued target function `f` (wrap a
+  classifier into one with `Funct` / `SeqFunct` from
+  `physioex/explain/posthoc/functionizer.py`); attribution is produced by
+  calling the attributor on the input.
+- **Spectral**: `SpectralGradients` (`spectralgradients.py`) — path-integral
+  attribution across frequency bands.
+- **Frequency-resolved**: DFT- and STFT-domain attributors, exported from
+  `vidft.py` and `vistdft.py`, wrap the same gradient methods around
+  differentiable (I)DFT/(I)STFT layers.
+- **Faithfulness metrics** under `posthoc/metrics/` quantify attribution quality
+  (complexity, localization, infidelity, and time-frequency measures).
+
+Refer to the [API Reference](../../api/index.md) for the exact constructor and
+call signatures of each attributor before use.
+
+## Foundational explainability — `physioex.explain.foundational`
+
+Concept-level analysis of foundation-model embeddings:
+
+- **Conceptual Spectral Decomposition** — `ConceptualSpectralDecomposition`
+  (`csd.py`) decomposes embeddings over interpretable spectral concepts and
+  returns a `CSDResult` (a list of `ConceptAttribution`).
+- **Specificity strategies** — a pluggable `SpecificityStrategy`
+  (`CohenDSpecificity`, `MarginSpecificity`, `SoftmaxSpecificity`,
+  `TopKSpecificity`, `NoFilter`) selects the concepts most specific to a class.
+- **Sleep bands** (`sleep_bands.py`), **multi-channel spectral gradients**
+  (`multichannel_sg.py`), and reporting helpers (`report.py`).
+
+## Prototypes — `physioex.explain.prototypes`
+
+Prototype/concept discovery and reconstruction:
+
+- **Local relevance**: `PrototypeRelevance`, `get_prototypes` (`local.py`).
+- **NMF** prototype discovery (`posthoc/nmf.py`:
+  `discover_prototypes_nmf`).
+- **Vector-quantized** codebooks: `VQBottleneck` and the codebook helpers in
+  `posthoc/vq.py` (`learn_codebook_kmeans`, `quantize_embeddings`,
+  `train_codebook`).
+- **Reconstruction** of learned concepts (`reconstruct.py`).
+
+## Layer-wise Relevance Propagation — `physioex.explain.lrp`
+
+Conservation-based attribution (Bach et al. 2015): relevance is redistributed
+backward through the network, conserving the total (`Σ R ≈ f(x)`). This family
+is **optional** — install the extra:
+
+```bash
+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:
+
+| Model family | Entry point | Rules |
+|---|---|---|
+| Feed-forward / CNN (Tsinalis, Chambon2018) | `LRP` (Zennit) | ε dense · γ conv · **w²** first layer (unbounded EEG, *not* the pixel z-box) · BatchNorm canonized · αβ/flat/z-box configurable via `physioex_composite` |
+| Recurrent (TinySleepNet, SeqSleepNet, L-SeqSleepNet, ProtoSleepNet-seq) | `ModelLRP` | **Arras signal-take** LSTM/GRU (`LRPLSTM`/`LRPGRU`, cell-level, forward identical to the fused module) · ε on the learnable filterbank / linears · CP-LRP on the attention poolings |
+| Attention / transformer (SleepTransformer, CoReSleep, ProtoSleepNet-tf) | `ModelLRP` | **CP-LRP** attention (value path; Ali et al. 2022) · identity rule on LayerNorm/GELU · proportional rule on residuals · ε on projections/FFN |
+
+```python
+from physioex.explain.lrp import LRP, ModelLRP
+
+relevance = LRP(cnn_model, out_index=2)(x)                       # Zennit path
+relevance, report = ModelLRP(seq_model, in_index=10, out_index=2)(x, return_report=True)
+print(report)   # Σ R / f per sample — 1.0 = exact conservation
+relevance = ModelLRP(coresleep, output_key="combined")(x)      # dict outputs
+```
+
+**How `ModelLRP` works.** The trained model is deep-copied and rewritten
+(`prepare_model_for_lrp`): fused `nn.LSTM`/`nn.GRU` become `LRPLSTM`/`LRPGRU`
+(subclasses, so `isinstance` checks and the `(output, states)` interface keep
+working), `nn.TransformerEncoder`/`MultiheadAttention` become their CP-LRP
+versions, PhysioEx's softmax poolings (`AttentionPooling`, `AttentionLayer`,
+`ChannelMixer`) and the `LearnableFilterbank` get dedicated adapters, remaining
+`Linear`/`Conv` leaves get ε-LRP, BatchNorm is folded into the preceding layer,
+and norms/activations use the identity rule. Plain `+` residuals written in a
+model's own `forward` are redirected at runtime to the proportional rule
+(`patch_residuals=True`) — a plain add would give both branches the full
+relevance and over-count. Register your own blocks with
+`register_lrp_adapter(cls, factory)`; `audit_lrp_coverage(model)` (also
+`ModelLRP(...).uncovered`, and `strict=True`) lists parametric leaves left on
+plain autograd, which would propagate *gradient* instead of relevance.
+
+**Reading the numbers.** Conservation is exact (up to ε) for bias-free
+networks; **biases absorb relevance** (LRP-ε convention), so on real models
+`Σ R / f` is below 1 — `ConservationReport.absorbed` shows how much. CP-LRP
+treats the attention matrix as constant: features acting only through *where
+to attend* (query/key path) receive zero relevance by design; full AttnLRP
+(Achtibat et al. 2024) is non-conserving and not implemented. All stabilisers
+are signed (`z + ε·sign z`), as in Arras et al. Not supported (raise): attention
+masks, `batch_first=False` transformers, explicit RNN initial states, `proj_size`;
+ProtoSleepNet's VQ path (`quantize=True`) runs under `no_grad`, so no relevance can
+flow through it — `ModelLRP` explains the default `quantize=False` forward.
+
+**Choosing ε.** The stabiliser must be scaled to the activations: on the
+pretrained SeqSleepNet (dB-scale spectrograms, 4-layer BiLSTM/BiGRU) ε = 1e-6
+inflates total relevance 2–3× through near-zero state sums, ε = 1e-2 conserves
+(`ΣR/f ≈ 0.96`) and ε = 1e-1 over-absorbs. Sweep ε and read the
+`ConservationReport`; `examples/explain/lrp_seqsleepnet_n3.py` does this on a
+real model and compares the LRP rule assignments with Saliency, Input×Gradient
+and Integrated Gradients.
+
+**Related methods — LRP vs path-based attribution.** LRP is *not* path-based:
+by Deep Taylor Decomposition (Montavon et al. 2017) every rule is a first-order
+Taylor expansion of each neuron at a closed-form *root point* (ε/LRP-0 → root at
+0, hence LRP-0 = Gradient×Input; z⁺ → along the positive contributions; z^B →
+on the input box), applied layer by layer in one backward pass — the baseline
+is implicit in the rule. Integrated Gradients (Sundararajan et al. 2017)
+instead integrates the gradient along the straight path from an explicit
+baseline x′ to x; both satisfy completeness (Σ R = f(x) − f(x′)) by different
+routes. The propagation-family counterpart of a *baseline* method is
+**DeepLIFT** (Shrikumar et al. 2017): finite-difference multipliers
+Δy/Δx w.r.t. a reference, i.e. Integrated Gradients applied layer-wise in a
+single backward pass; Ancona et al. (2018) prove ε-LRP ≡ DeepLIFT-Rescale with a
+zero baseline (ReLU nets without bias, ε → 0) and cast both as
+modified-gradient × input, and **DeepSHAP** (Lundberg & Lee 2017) adds an
+expectation over baselines — the analogue of `ExpectedGradients`. Averaging LRP
+relevance along the x′→x path ("integrated LRP", e.g. Zennit's
+`IntegratedGradients` attributor combined with a composite) is a supported
+construct: it reduces exactly to IG for LRP-0 but carries no completeness
+guarantee for ε/γ/CP rules and should be read as an ensemble. On LSTMs, Arras
+et al. (2019) found gate-rule LRP the best-performing method, with DeepLIFT
+close and IG/gradients behind.
+
+- **Composites** (`lrp/composites.py`): `physioex_composite` (ε/γ/w²),
+  `epsilon_composite` (pure-ε reference). **Canonizers** (`lrp/canonizers.py`):
+  `default_canonizers` (BatchNorm merge).
+- **Blocks**: `lrp/recurrent.py`, `lrp/transformer.py`, `lrp/pooling.py`;
+  shared primitives in `lrp/_functional.py`; diagnostics in `lrp/diagnostics.py`.
+- **Backends**: [Zennit](https://github.com/chr5tphr/zennit) for the composites
+  and BatchNorm canonization; the recurrent, attention and pooling rules are
+  implemented in PhysioEx (`_functional.py`, `_rules.py`) following Arras et al.,
+  Ali et al. (CP-LRP) and the LXT conventions — no LXT dependency.
+
+See the [API Reference](../../api/index.md) for verified signatures across all
+families.

physioex-2.0.2/examples/explain/lrp_seqsleepnet_n3.py

@@ -0,0 +1,187 @@
+"""LRP vs post-hoc explanations of the pretrained single-channel SeqSleepNet.
+
+Explains the N3 logit of the pretrained ``seqsleepnet-phan`` (MASS, EEG 1 ch) on
+training-set sequences whose central epoch is N3, side by side with Saliency,
+Input×Gradient and Integrated Gradients, and shows how the LRP **rule
+assignment** changes the attribution (gate rule, filterbank input rule,
+attention handling, stabiliser ε), always reporting the conservation ratio
+``ΣR / f``.  CPU is enough (a few minutes; the physioex cache makes re-runs
+instant).
+
+Requirements: ``pip install "physioex[explain]"``, the MASS EDFs under
+``$PHYSIOEX_DATA/MASS/Original/SS0{1..5}`` and a writable ``PHYSIOEX_CACHE_DIR``.
+Set ``SEQSLEEPNET_DIR`` to a folder holding ``config.json`` + ``model.pt`` to run
+offline (otherwise the weights are pulled from the HF hub).
+
+Usage::
+
+    python examples/explain/lrp_seqsleepnet_n3.py --out ./n3_out [--n 8] [--eps 1e-2]
+"""
+
+import argparse
+import importlib
+import json
+import os
+import time
+import warnings
+
+import numpy as np
+import torch
+import torch.nn as nn
+
+from physioex.explain.lrp import LRPGRU, LRPLSTM, ModelLRP
+from physioex.explain.lrp import model as lrpmodel
+from physioex.explain.lrp.pooling import _PoolAdapter
+from physioex.explain.posthoc import InputXGradient, IntegratedGradients, Saliency
+from physioex.explain.posthoc.functionizer import SeqFunct
+
+CLASSES = ["W", "N1", "N2", "N3", "REM"]
+FBQ = "physioex.models.seqsleepnet.LearnableFilterbank"
+ATQ = "physioex.models.seqsleepnet.AttentionLayer"
+
+
+def load_model(model_dir):
+    """Pretrained SeqSleepNet from a local folder (config.json + model.pt) or the hub."""
+    if model_dir:
+        cfg = json.load(open(os.path.join(model_dir, "config.json")))
+        mod, cls = cfg["model_class"].split(":")
+        model = getattr(importlib.import_module(mod), cls)(**cfg["model_kwargs"])
+        state = torch.load(os.path.join(model_dir, "model.pt"), map_location="cpu", weights_only=True)
+        model.load_state_dict(state)
+        return model.eval(), cfg
+    from huggingface_hub import hf_hub_download
+    from physioex.models import load_from_pretrained
+
+    cfg = json.load(open(hf_hub_download("4rooms/physioex", "seqsleepnet-phan/config.json")))
+    return load_from_pretrained("seqsleepnet-phan", device="cpu").eval(), cfg
+
+
+def n3_training_sequences(cfg, n, target_idx, log):
+    """``n`` training-split sequences (fold 0, all cohorts) whose target epoch is N3."""
+    from physioex.data.datasets import get_dataset
+    from physioex.data.multi import MultiDataset
+
+    MASS = get_dataset("mass")
+    L = cfg["training"]["sequence_length"]
+    cohorts = []
+    for c in cfg["training"]["dataset_cohorts"]:
+        cohorts.append(MASS(cohort=c, channels=cfg["training"]["channels"],
+                            pipelines=cfg["training"]["pipeline_preset"], sequence_length=L))
+        log(f"cohort {c} indexed ({len(cohorts[-1])} sequences)")
+    ds = MultiDataset(cohorts)
+    train_idx = np.array(ds.split(fold=cfg["training"]["fold"])[0])
+    order = np.random.default_rng(0).permutation(len(train_idx))
+    xs, ys = [], []
+    for k in order:
+        item = ds[int(train_idx[k])]
+        if int(item["labels"][target_idx]) != CLASSES.index("N3"):
+            continue
+        xs.append(item["signals"][item["channel_order"][0]].unsqueeze(1).float())  # (L, 1, T, F)
+        ys.append(item["labels"].clone())
+        if len(xs) == n:
+            break
+    return torch.stack(xs), torch.stack(ys)
+
+
+# --- alternative input-layer rules for the filterbank (demo of a *wrong* choice) ---
+
+
+class _FBLinearRule(torch.autograd.Function):
+    @staticmethod
+    def forward(ctx, x, Wfb, mode):
+        ctx.save_for_backward(Wfb)
+        ctx.mode = mode
+        return torch.matmul(x, Wfb)
+
+    @staticmethod
+    def backward(ctx, R):
+        (Wfb,) = ctx.saved_tensors
+        if ctx.mode == "w2":  # squared weights, independent of the input value
+            W2 = Wfb ** 2
+            W2 = W2 / (W2.sum(dim=-2, keepdim=True) + 1e-12)
+            return torch.matmul(R, W2.transpose(-1, -2)), None, None
+        F = Wfb.shape[-2]  # flat: uniform over the frequency bins
+        return R.sum(-1, keepdim=True).expand(*R.shape[:-1], F) / F, None, None
+
+
+class FilterbankAltRule(_PoolAdapter):
+    def __init__(self, orig, mode):
+        super().__init__(orig)
+        self.mode = mode
+
+    def forward(self, x):
+        with torch.no_grad():
+            Wfb = torch.mul(torch.sigmoid(self.orig.W), self.orig.S)
+        return _FBLinearRule.apply(x, Wfb, self.mode)
+
+
+def run_lrp(model, x, target_idx, epsilon, gate_rule="signal_take", fb_mode=None, attn_naive=False):
+    saved = dict(lrpmodel._BUILTIN_BY_QUALNAME)
+    try:
+        if fb_mode:
+            lrpmodel._BUILTIN_BY_QUALNAME[FBQ] = lambda m, e, _mode=fb_mode: FilterbankAltRule(m, _mode)
+        if attn_naive:
+            lrpmodel._BUILTIN_BY_QUALNAME.pop(ATQ, None)
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            explainer = ModelLRP(model, in_index=target_idx, out_index=CLASSES.index("N3"), epsilon=epsilon)
+        for m in explainer.model.modules():
+            if isinstance(m, (LRPLSTM, LRPGRU)):
+                m.gate_rule = gate_rule
+        rel, report = explainer(x, return_report=True)
+        return rel.detach(), report.ratio.tolist(), explainer.uncovered
+    finally:
+        lrpmodel._BUILTIN_BY_QUALNAME.clear()
+        lrpmodel._BUILTIN_BY_QUALNAME.update(saved)
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--out", default="n3_out")
+    ap.add_argument("--n", type=int, default=8)
+    ap.add_argument("--eps", type=float, default=1e-2)
+    ap.add_argument("--model-dir", default=os.environ.get("SEQSLEEPNET_DIR"))
+    args = ap.parse_args()
+    os.makedirs(args.out, exist_ok=True)
+    torch.set_num_threads(4)
+    t0 = time.time()
+    log = lambda *a: print(f"[{time.time() - t0:6.0f}s]", *a, flush=True)  # noqa: E731
+
+    model, cfg = load_model(args.model_dir)
+    L = cfg["training"]["sequence_length"]
+    mid, n3 = L // 2, CLASSES.index("N3")
+    x, y = n3_training_sequences(cfg, args.n, mid, log)
+    with torch.no_grad():
+        logits = model(x)
+    log("x", tuple(x.shape), "N3 logits", [round(v, 2) for v in logits[:, mid, n3].tolist()])
+
+    f = SeqFunct(model, in_index=mid, out_index=n3)
+    results = {
+        "Saliency": Saliency(f)(x).detach(),
+        "Input x Gradient": InputXGradient(f)(x).detach(),
+        "Integrated Gradients (32 steps)": IntegratedGradients(f, steps=32)(x).detach(),
+    }
+    conserv = {}
+    variants = {
+        "LRP recommended": {},
+        "LRP gate uniform": {"gate_rule": "uniform"},
+        "LRP filterbank w2": {"fb_mode": "w2"},
+        "LRP filterbank flat": {"fb_mode": "flat"},
+        "LRP attention not ruled": {"attn_naive": True},
+    }
+    for eps in (1e-6, 1e-4, 1e-3, 1e-2, 1e-1):
+        variants[f"LRP eps={eps:g}"] = {"epsilon": eps}
+    for name, kw in variants.items():
+        rel, ratio, uncovered = run_lrp(model, x, mid, kw.pop("epsilon", args.eps), **kw)
+        results[name], conserv[name] = rel, ratio
+        log(f"{name}: sumR/f={[round(v, 3) for v in ratio]} uncovered={uncovered}")
+
+    freqs = np.arange(x.shape[-1]) * cfg["model_kwargs"]["fs"] / cfg["model_kwargs"]["nfft"]
+    torch.save({"x": x, "labels": y, "logits": logits, "results": results, "conservation": conserv,
+                "freqs": freqs, "target_index": mid}, os.path.join(args.out, "attributions.pt"))
+    json.dump({k: v for k, v in conserv.items()}, open(os.path.join(args.out, "conservation.json"), "w"), indent=1)
+    log("saved", args.out)
+
+
+if __name__ == "__main__":
+    main()

physioex-2.0.2/physioex/__init__.py

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

physioex-2.0.2/physioex/explain/__init__.py

@@ -0,0 +1,34 @@
+"""PhysioEx explainability subsystem.
+
+Sub-packages:
+    - ``posthoc``      — gradient-based attribution (Saliency, InputXGradient,
+      Integrated / Expected Gradients, and their DFT/STFT spectral variants).
+    - ``foundational`` — spectral-concept methods (CSD, specificity, ...).
+    - ``prototypes``   — prototype / concept discovery and reconstruction.
+    - ``lrp``          — Layer-wise Relevance Propagation (needs the ``explain``
+      extra: ``pip install "physioex[explain]"``).
+
+The LRP entry points are re-exported lazily so that ``import physioex.explain``
+does not pull in the optional ``zennit`` dependency.
+"""
+
+_LAZY = {
+    "LRP": "physioex.explain.lrp.attributor",
+    "ModelLRP": "physioex.explain.lrp.model",
+    "prepare_model_for_lrp": "physioex.explain.lrp.model",
+}
+
+__all__ = sorted(_LAZY)
+
+
+def __getattr__(name):
+    # PEP 562 lazy attribute — only import the LRP stack on first access.
+    if name in _LAZY:
+        import importlib
+
+        return getattr(importlib.import_module(_LAZY[name]), name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    return sorted(set(globals()) | set(_LAZY))