Feature/multiview contrastive

[ddori]

Pull Request: MultiViewContrastive Model

Contributor: Juhwan Song (juhwans3@illinois.edu)
Type of contribution: Model
Original paper: Oh & Bui (2025), "Multi-View Contrastive Learning for Robust Domain Adaptation in Medical Time Series Analysis", CHIL 2025 Best Paper

---

High-level description

This PR adds the MultiViewContrastive model to PyHealth, implementing the multi-view contrastive learning framework from Oh & Bui (2025). The model constructs three views of a raw time-series signal (temporal, derivative, frequency), encodes each with an independent backbone, fuses them via hierarchical attention, and classifies the fused representation.

This fills a gap in PyHealth's model collection: while ContraWR and SparcNet exist for biosignal classification, neither supports cross-domain transfer learning on medical time series.

Key features:

• Three configurable encoder backbones: Transformer, 1D-CNN, GRU
• Three fusion strategies: hierarchical attention, concatenation, mean pooling
• Seven view configurations (T/D/F/TD/TF/DF/ALL)
• Contrastive pre-training helper (encode_views()) for domain adaptation
• Comprehensive ablation study comparing encoders and fusion strategies

File guide

File	Description
pyhealth/models/multiview_contrastive.py	Core model implementation (MultiViewContrastive, inherits BaseModel)
pyhealth/models/__init__.py	Updated to export MultiViewContrastive
tests/core/test_multiview_contrastive.py	20+ unit tests with synthetic data (all < 1s)
examples/sleepEEG_epilepsy_multiview_contrastive.py	Full ablation study: SleepEEG→Epilepsy domain adaptation
docs/api/models/pyhealth.models.MultiViewContrastive.rst	API documentation
docs/api/models.rst	Updated index to include MultiViewContrastive

Testing

All tests use small synthetic tensors (4 samples, 1 channel, 178 timesteps) and complete in milliseconds. Coverage includes:

• Model initialization with all encoder/view/fusion configurations
• Forward pass shapes for 14 configuration combinations
• Gradient flow for all 3 encoder types
• Embedding output and encode_views() helper
• Static view computation (temporal, derivative, frequency)

Ablation study

The example script runs two ablation studies on SleepEEG→Epilepsy:

1. Encoder backbone: Transformer vs. 1D-CNN vs. GRU (same fusion)
2. Fusion strategy: Attention vs. Concatenation vs. Mean Pooling (same encoder)