Add TransEHR model for clinical EHR time series (CS598 DL4H)

[pintard2]

Summary

• Student: Reshaun Pintard; NetID: pintard2; CS598 Deep Learning for Healthcare
• Contribution type: Option 2: Model
• Paper: Xu et al., "TransEHR: Self-Supervised Transformer for Clinical Time Series Data", PMLR 2023. https://proceedings.mlr.press/v209/xu23a.html

What this PR adds

TransEHR is a transformer encoder designed for longitudinal EHR data. Its key novelty over the existing PyHealth Transformer model is the use of nested_sequence inputs that preserve visit-level temporal structure (patient → visits → codes), rather than a flat list of codes.

Architecture:

1. Clinical codes are embedded and mean-pooled within each visit to produce a single visit vector.
2. Sinusoidal positional encoding is applied over the visit sequence.
3. A standard TransformerEncoder attends over visits (not individual codes).
4. Valid visit representations are mean-pooled to a single patient vector.
5. A linear layer produces the final prediction.

Files

File	Description
pyhealth/models/trans_ehr.py	TransEHR model implementation
tests/test_trans_ehr.py	22 unit tests using synthetic data (no dataset download needed)
examples/mimic4_mortality_trans_ehr.py	Ablation study: num_layers, embedding_dim, num_heads
docs/api/models/pyhealth.models.TransEHR.rst	Sphinx documentation
pyhealth/models/__init__.py	Added TransEHR export
docs/api/models.rst	Added TransEHR to toctree

Tests

All 22 unit tests pass on synthetic data with no real dataset required:

pytest tests/test_trans_ehr.py -v