Add clinical tsf transformer peterbh2

[peterbh2]

Contributor Information

Name: [Peter Huang]

NetID/Email: [peterbh2] / [peterbh2@illinois.edu]

Type: Model Contribution (Multi-Task Clinical Transformer)

This implementation adapts the Transformer architecture for dual-task clinical forecasting and classification. Link: https://arxiv.org/abs/2408.03816

This PR introduces the ClinicalTSFTransformer, a specialized model for clinical time-series data. Unlike standard transformers, this model is designed for Multi-Task Learning (MTL). Key implementation details include:Feature Projection: Includes a linear embedding layer that projects raw clinical features (e.g., 131 eICU variables) to a hidden dimension ($d_{model}=128$). This ensures the embed_dim is divisible by the number of attention heads (nhead=8), resolving standard Transformer architectural constraints.Dual-Head Architecture: * Forecasting Head: Reconstructs the input time-series to predict future physiological states (optimized via MSE loss).Classification Head: Uses the final hidden state of the sequence for clinical event prediction, such as Sepsis (optimized via BCE loss).Temporal Awareness: Incorporates learnable positional encodings to capture the sequential order and temporal trends of ICU data.Sparsity Handling: The forward pass is structured to allow for integration with clinical data masks, common in irregularly sampled datasets like eICU.

File guide:
pyhealth/models/clinical_tsf_transformer.py: Contains the core model architecture and multi-task loss logic.

pyhealth/models/init.py: Added the model to the package namespace for standard library access.

tests/core/test_clinical_tsf_transformer.py: Unit tests verifying input/output shapes and multi-task loss calculation.

docs/api/models/pyhealth.models.ClinicalTSFTransformer.rst: Documentation stub for Sphinx API rendering.

examples/clinical_tsf_example.ipynb: A demonstration notebook showing how to initialize and train the model on eICU data.

pyhealth/datasets/eicu_new.py: (If included) Custom dataset loader logic for the TSF task.