Add comprehensive README with architecture docs

README.md

@@ -0,0 +1,167 @@
+# SleepStageNet - 基于心率/HRV/呼吸/体动的睡眠分期模型
+
+## 🎯 概述
+
+SleepStageNet 是一个基于深度学习的睡眠分期模型，使用 **4个非EEG特征** 进行自动睡眠分期：
+
+| 特征 | 说明 | 生理意义 |
+|------|------|---------|
+| **HRV (RMSSD)** | 心率变异性 | 反映自主神经状态（副交感活性） |
+| **心率 (HR)** | 每分钟心跳次数 | 反映整体心血管水平 |
+| **呼吸频率 (RR)** | 每分钟呼吸次数 | 反映呼吸调节状态 |
+| **体动 (Movement)** | 身体活动量 | 反映肢体运动/觉醒 |
+
+**输出**：每30秒epoch的睡眠分期 → Wake / N1 / N2 / N3 / REM
+
+## 📐 架构设计
+
+综合了以下SOTA论文的最佳设计：
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                     SleepStageNet                            │
+├──────────────────────────────────────────────────────────────┤
+│                                                              │
+│  输入: (batch, T, 4)  ← T个30秒epoch, 每个有4个特征         │
+│                                                              │
+│  ┌──────────────────────────────────────────────────┐       │
+│  │ 1. Feature Projection (参考SleepPPG-Net)         │       │
+│  │    MLP: 4 → d_model*2 → d_model                  │       │
+│  └──────────────────┬───────────────────────────────┘       │
+│                     │                                        │
+│  ┌──────────────────┴───────────────────────────────┐       │
+│  │ 2. Cross-Feature Attention (参考wav2sleep)        │       │
+│  │    每个特征独立投影 + CLS Token + Transformer      │       │
+│  │    学习 HRV↔HR↔RR↔Movement 的交互关系            │       │
+│  └──────────────────┬───────────────────────────────┘       │
+│                     │ (门控融合)                              │
+│  ┌──────────────────┴───────────────────────────────┐       │
+│  │ 3. Positional Encoding                            │       │
+│  │    正弦位置编码 (时间位置对睡眠结构很重要)         │       │
+│  └──────────────────┬───────────────────────────────┘       │
+│                     │                                        │
+│  ┌──────────────────┴───────────────────────────────┐       │
+│  │ 4. Dilated Temporal CNN (参考wav2sleep)            │       │
+│  │    2 blocks × [d=1,2,4,8,16,32], k=7              │       │
+│  │    感受野 ≈ 6小时 → 捕获完整睡眠周期               │       │
+│  └──────────────────┬───────────────────────────────┘       │
+│                     │                                        │
+│  ┌──────────────────┴───────────────────────────────┐       │
+│  │ 5. Classification Head                            │       │
+│  │    Linear(d_model → d_model/2 → n_classes)        │       │
+│  └──────────────────────────────────────────────────┘       │
+│                                                              │
+│  输出: (batch, T, n_classes)  ← 每个epoch的分类logits       │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### 关键创新
+
+1. **双路径门控融合**：简单MLP投影 + 跨特征Transformer注意力的门控融合，兼顾效率和表达能力
+2. **随机特征遮蔽** (参考wav2sleep)：训练时以30%概率随机mask特征，提高传感器缺失时的鲁棒性
+3. **膨胀时序CNN** (参考wav2sleep)：感受野覆盖≈6小时，能捕获完整的90-120分钟睡眠周期
+4. **Per-patient Z-score标准化** (参考SleepPPG-Net)：消除个体基线差异，这是最关键的预处理步骤
+
+## 📊 模型配置
+
+| 配置 | d_model | 参数量 | Epoch Mixer | Sequence Mixer | 适用场景 |
+|------|---------|--------|-------------|----------------|---------|
+| small | 64 | ~195K | 1层 Transformer | 1 block, d=[1,2,4,8,16] | 快速实验 |
+| **base** | 128 | **~2M** | 2层 Transformer | 2 blocks, d=[1,2,4,8,16,32] | **推荐** |
+| large | 256 | ~13.7M | 3层 Transformer | 3 blocks, d=[1,2,4,8,16,32,64] | 最佳性能 |
+
+## 🔬 参考文献
+
+| 论文 | 贡献 | 年份 |
+|------|------|------|
+| [wav2sleep](https://arxiv.org/abs/2411.04644) | Epoch Mixer + Sequence Mixer + 随机模态遮蔽 | 2024 |
+| [Cross-Modal Transformer](https://arxiv.org/abs/2208.06991) | 跨模态注意力 + 加权交叉熵 [1,2,1,2,2] | 2022 |
+| [SleepPPG-Net](https://arxiv.org/abs/2202.05735) | Per-patient Z-score + BiLSTM FE基线 | 2022 |
+| [Mamba-sleep](https://arxiv.org/abs/2412.15947) | 轻量Mamba序列建模 + 逆频率加权 | 2024 |
+
+## 🚀 快速使用
+
+### 安装依赖
+
+```bash
+pip install torch numpy
+```
+
+### 推理示例
+
+```python
+import numpy as np
+import torch
+from sleep_staging_model import create_model
+
+# 创建模型
+model = create_model('base', n_features=4, n_classes=4)
+
+# 准备输入数据: T个30秒epoch的特征
+T = 1200  # 10小时 = 1200个epoch
+features = np.stack([
+    hrv_rmssd,          # HRV (RMSSD) 序列
+    heart_rate,          # 心率序列
+    respiratory_rate,    # 呼吸频率序列
+    body_movement,       # 体动序列
+], axis=-1)  # shape: (T, 4)
+
+# Z-score标准化 (关键步骤!)
+features = (features - features.mean(axis=0)) / (features.std(axis=0) + 1e-8)
+features = np.clip(features, -5, 5)
+
+# 推理
+x = torch.tensor(features, dtype=torch.float32).unsqueeze(0)  # (1, T, 4)
+model.eval()
+with torch.no_grad():
+    logits = model(x)  # (1, T, n_classes)
+    predictions = torch.argmax(logits, dim=-1)  # (1, T)
+
+# 标签: 0=Wake, 1=N1, 2=N2, 3=N3, 4=REM
+stage_names = {0: 'Wake', 1: 'N1', 2: 'N2', 3: 'N3', 4: 'REM'}
+```
+
+### 训练
+
+```bash
+python train_sleep_staging.py --model base --batch_size 16 --lr 1e-3 --max_epochs 100
+```
+
+## 📋 训练配置 (来自文献最佳实践)
+
+| 超参数 | 值 | 来源 |
+|--------|------|------|
+| Optimizer | AdamW | wav2sleep |
+| Learning Rate | 1e-3 | wav2sleep |
+| Weight Decay | 1e-2 | wav2sleep |
+| Batch Size | 16 (整夜) | wav2sleep |
+| LR Schedule | OneCycleLR (10% warmup + cosine) | 改进自wav2sleep |
+| Loss | Weighted Focal Loss (γ=2) | Cross-Modal Transformer + Focal |
+| Class Weights | 逆频率加权 | Mamba-sleep |
+| Early Stopping | patience=10 | wav2sleep (5) |
+| Gradient Clip | max_norm=1.0 | 标准实践 |
+| Augmentation | 随机翻转(p=0.5) + 噪声(p=0.3) | wav2sleep |
+| Feature Mask | p=0.3 | wav2sleep |
+
+## 📊 数据集
+
+训练数据: [`abmallick/heart-breath-sleep-stage-dataset`](https://huggingface.co/datasets/abmallick/heart-breath-sleep-stage-dataset)
+
+- 30秒epoch粒度
+- 包含心率、呼吸频率、HRV指标
+- 485+夜睡眠记录
+- 4类标注: Wake, N1, N2, N3
+
+## 期望性能 (基于文献)
+
+| 指标 | 4类 (无REM) | 5类 (含REM) |
+|------|------------|------------|
+| Cohen's κ | 0.55-0.65 | 0.50-0.60 |
+| Accuracy | 70-80% | 65-75% |
+| F1 (macro) | 0.50-0.65 | 0.45-0.60 |
+
+> 注: 非EEG特征的睡眠分期性能通常低于EEG-based方法(κ≈0.75+)，这是该领域的固有限制。
+
+## License
+
+MIT