Haplo Donor Selection

SKILL.md

---
name: haplo-donor-selection
description: HLA 配型分析，从 OCR 提取的样本数据中选择最佳供者（患者优先匹配）。支持多家族成员比较，输出排名和匹配分数。
version: 3.0.0
allowed-tools:
  - exec
  - read
  - write
  - edit
---

# Haplo Donor Selection Skill — v3.0

端到端单倍体供者选择：从 HLA 报告图片 → OCR → 临床信息 → EBI API → DFS Cox 模型 → 中文 PDF 报告。

## Capabilities (v3.0)

- ✅ **端到端流水线**：从图片输入到 PDF 报告全自动
- ✅ **高精度 OCR**：PaddleOCR + 表格行分组算法（meta-centric）
- ✅ **EBI API 集成**：B-Leader, DPB1 TCE (v3.0), KIR Ligand
- ✅ **DFS Cox 模型**：Fuchs 2021 预计算生存表查表法（通用，适用于任何患者）
- ✅ **循证比较**：Mehta et al. 2024（vs MSD / vs MMUD）
- ✅ **中文 PDF 报告**：Noto Sans CJK SC 字体嵌入
- ✅ **交互式询问**：诊断、疾病状态、HCT-CI
- ✅ **置信区间**：DFS 预测包含 95% CI

## Quick Start (花卷使用)

```bash
# 从 HLA 报告图片生成最终 PDF
python3 scripts/run_v2.py path/to/hla_report.jpg --output report.pdf

# 示例（徐春花报告）
python3 scripts/run_v2.py media/inbound/xu_report.jpg -o XuChunHua_HLA_Report.pdf
```

## Full Pipeline

### Step 1: OCR（local-ocr 集成）
- 使用 PaddleOCR 识别表格
- meta-centric 行分组算法合并上下等位基因
- 输出 JSON 结构（samples[]）

### Step 2: 询问患者临床信息（必须）
**在进入 DFS 分析之前，必须向查询者确认以下信息：**

> 请提供以下患者信息以进入 DFS 分析：
> 1. **诊断**？（AML / ALL / MDS）
> 2. **疾病状态**？（CR1 / CR2+ / 复发/难治）
> 3. **HCT-CI 评分**？（0 / 1 / 2 / ≥3）

CMV 血清学默认为患者+/供者+（参考组，β=0），不再询问。

这些信息直接影响 Cox 模型中的 HR 计算，不可假设默认值。
等待查询者填入后方可继续。

### Step 3: 供者筛选
- 排除 12/12 全相合供者（不进入分析流程，在报告中单独列出）
- 排除 < 6/12 低匹配供者
- 保留 6/12–11/12 的部分相合供者

### Step 4: EBI IPD-IMGT/HLA API 查询
- 等位基因统一为 2-field 格式（如 `13:01`）
- 查询 B-Leader 匹配状态
- 查询 HLA-DPB1 TCE v3.0（core/non-core）
- 查询 KIR Ligand（GvH/HvG）

### Step 5: DFS Cox 模型预测（v3.0 升级）
使用 Fuchs et al. 2021 预计算生存表（haplodonorselector 查表法）：
- 数据来源：`skills/ebi-hla-match/data/ib1902_drdq_3yr.csv`（含 DQB1）或 `ib1902_dr_3yr.csv`（仅 DRB1）
- **7 个协变量编码**：
  1. `match_b` — B-Leader 匹配状态（0=Matched, 1=Mismatched）
  2. `drdq2` — DRB1/DQB1 匹配类型（0=both match, 1=DR match/DQ mismatch, 2=DR mismatch/DQ match, 3=both mismatch）；匹配定义为两个等位基因完全一致
  3. `tcegpd` — DPB1 TCE 分组（2=Permissive/Matched, 3=Non-permissive, 4=Missing）
  4. `hctcigp` — HCT-CI 评分（0/1/2/3+）
  5. `drcmvpr` — CMV 血清学（0=pos/pos, 1=pos/neg, 2=neg/pos, 3=neg/neg）
  6. `ragecat` — 患者年龄分类（1=<18, 2=18-29, 3=30-39, 4=40-49, 5=50-59, 6=≥60）
  7. `disstage` — 诊断+疾病状态编码（AML CR1=1, AML CR2+=2, AML Advanced=4; ALL CR1=10, ALL CR2=20, ALL CR3+=30; MDS Early=100, MDS Advanced=200）
- 输出：1年/2年/3年 DFS 概率 + 95% 置信区间
- `intxrel` 单位为**月**（0–36 对应 3 年）
- 优先使用 DRDQ 表（更精确），无 DQB1 时回退到 DR-only 表
- 若查表无匹配行则使用简化估算（fallback）

**v2.0 → v3.0 变更**：
- ❌ 旧版：硬编码 if/else（仅适配特定患者名）
- ✅ 新版：通用查表法，适用于任何 AML/ALL/MDS 患者

### Step 6: 循证供者选择原则（Mehta 2024）
- **vs MSD**：年轻 Haplo (<35) B-leader M 可能优于年老 MSD (≥50)；与年轻 MSD 总体相当
- **vs MMUD**：B-leader M / DRB1 MM 的 Haplo 优于任何 MMUD（OS HR 0.72 vs PBM-matched）
- 这些原则用于相对推荐，不直接对比不同研究的 DFS 数值

### Step 7: PDF 报告生成
- 模板风格：参考 TianHong_DFS_final_v9_Comprehensive.pdf
- 字体：Noto Sans CJK SC（简体中文）
- 包含：患者信息、供者排名、DFS 表格、比较分析、结论、参考文献

## Input Format (Intermediate JSON)

OCR 脚本（`hla_ocr.py`）输出：

```json
{
  "samples": [
    {
      "id": "8316-0",
      "name": "徐春花",
      "relation": "患者",
      "gender": "女",
      "age": 41,
      "type": "HLA",
      "alleles": {
        "HLA-A": "02:01/11:01",
        "HLA-B": "13:01/40:02",
        "HLA-C": "03:04/03:04",
        "HLA-DRB1": "09:01/15:01",
        "HLA-DQB1": "03:03/06:02",
        "HLA-DPB1": "05:01/13:01:01G"
      }
    },
    ...
  ]
}
```

## Output Format (PDF)

- **Page 1**: 患者信息 + HLA 分型
- **Page 2**: 供者排名（DFS 降序）+ EBI API 结果
- **Page 3**: vs MSD/MMUD 比较 + 推荐 + KIR

## Dependencies

```bash
pip install fpdf2 pymupdf pandas
# PaddleOCR（虚拟环境 /opt/paddle_venv）
# EBI API 访问（Internet）
# 生存表数据：skills/ebi-hla-match/data/ib1902_*.csv
```

## File Structure

```
skills/haplo-donor-selection/
├── SKILL.md                 # 本文件
├── scripts/
│   ├── run_v2.py           # 主流水线（v3.0 入口）
│   ├── hla_ocr.py          # PaddleOCR 解析（local-ocr 集成）
│   ├── full_analysis.py    # EBI API + Cox 查表法 DFS（v3.0 核心）
│   └── analyze.py          # v1 旧版，供保留
└── fonts/
    └── NotoSansCJK-SC-Regular.otf  # 中文 PDF 字体

# 外部依赖数据（来自 ebi-hla-match 技能）：
skills/ebi-hla-match/data/
├── ib1902_dr_3yr.csv       # DR-only 生存表 (~9MB)
└── ib1902_drdq_3yr.csv     # DRDQ 生存表 (~18MB)
```

## Notes

- 本技能 v3.0 使用 Fuchs 2021 预计算生存表（查表法），取代 v2.0 的硬编码规则
- DFS 预测现适用于任何 AML/ALL/MDS 患者，无需按患者名硬编码
- DRB1/DQB1 匹配定义为**完全匹配**（两个等位基因都必须一致），而非"至少有一个共享"
- 生存表 `intxrel` 单位为月（非年），查询时直接传入 12/24/36
- OCR 结果建议保留供复查
- 临床信息一旦错误会导致 DFS 预测偏差
- 最终报告仅供研究参考，临床决策需多学科审核

## References

1. Fuchs EJ et al. Blood. 2022;139(10):1452-1468.
2. Mehta RS et al. Blood Adv. 2024;8(20):5306-5314. (vs MSD)
3. Mehta RS et al. Transplant Cell Ther. 2024;30:909.e1-e11. (vs MMUD)
4. Solomon S et al. TCT. 2024;30:608.e1-e10. (TCE-Core)
5. Nikoloudis O et al. Cytotherapy. 2025;27:457-464. (C1 方向)