Explain Module#

PhysioEx ships an explainability (XAI) toolkit for sleep-staging and foundation models, organized in three families under physioex.explain. For the full class diagram see the explain-layer architecture 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 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).

See the API Reference for verified signatures across all three families.