haplo-donor-selection

---\nname: haplo-donor-selection\ndescription: "Haploidentical donor selection for hematopoietic cell transplantation (HCT) with advanced automation. Integrates HLA typing extraction (from images/PDFs), precise HLA matching based on user-defined criteria (<6/12 excluded, 12/12 identified as MSD), queries IPD-IMGT/HLA APIs (B-Leader, DPB1 TCE v3, KIR Ligand), applies TCE-Core reclassification (Solomon 2024), calculates 3-year DFS via local Cox model (Fuchs 2022), ranks haplo donors, compares against MSD/MMUD reference outcomes (Mehta 2024), and generates a comprehensive clinical decision report with patient/donor HLA details, KIR analysis (for reference), and PDF export. Optimized for strict adherence to clinical guidelines and automated workflow coordination."\n---\n\n# Haplo Donor Selection Workflow\n\n## Overview\n\nAutomated 13-step master pipeline: HLA report intake → clinical data collection → Automated HLA Match Screening (<6/12 excluded, 12/12 identified as MSD) → API-based immunogenetic analysis (B-Leader, DPB1 TCE, KIR Ligand) → Cox model DFS prediction → haplo donor ranking → comparative outcome analysis (vs MSD/MMUD) → Comprehensive PDF report generation with detailed patient/donor HLA typing and KIR analysis.\n\n## Workflow Steps\n\n### Step 0: Receive HLA Typing Report\nAccept image (JPG/PNG) or PDF. Extract all HLA loci at 4-digit resolution:\nA, B, C, DRB1, DQB1, DPB1 for patient and each donor.\n\n### Step 1: Collect Patient Clinical Info\nAsk sequentially (do NOT assume — ask one at a time):\n\n1. 疾病诊断 — AML / ALL / MDS\n2. 疾病状态 — see references/disease-codes.md\n3. 患者年龄\n4. HCT-CI 评分 — 0 / 1 / 2 / ≥3\n\nCMV: default all positive (patient + donors). Donor ages from typing report.\n\n### Step 2: Extract HLA Typing\nParse each person's alleles from the report image/PDF.\nVerify: 6 loci × 2 alleles = 12 values per person.\n\n### Step 2.5: Data Cross-Validation (MANDATORY)\nUse the report's built-in Matches row to verify extracted data:\n- For each donor × each locus, count shared alleles with patient (0/1/2)\n- Compare against the Matches number shown in the report\n- If mismatch → re-read that locus from the image\n- DPB1 is rightmost column — highest risk of column misalignment\n- This step catches OCR/reading errors before they propagate to wrong rankings\n\n### Step 2.7: Automated HLA Match Screening (NEW)\nAutomated Filtering:\n- Donors with < 6/12 matched alleles are automatically disqualified.\n- Donors with 12/12 matched alleles are identified as MSD (Matched Sibling Donors) and are treated as a separate reference group for comparison, not ranked among haploidentical donors.\n- Only donors with 6-11/12 matched alleles proceed as haploidentical candidates for detailed analysis.\n\n### Step 3: Haplotype Deduction & Donor Screening\nFor sibling donors, deduce parental haplotypes.\n- 1 shared haplotype → ✅ Haploidentical\n- 2 shared → MSD (flag separately)\n- 0 shared → ❌ Exclude with explanation\n\n### Step 4: IPD-IMGT/HLA API Calls\nRun scripts/hla_matching.py --json '{...}'\n\nThree API endpoints (now integrated and called by haplo_master_pipeline.py):\n- B-Leader: https://www.ebi.ac.uk/cgi-bin/ipd/matching/b_leader\n- DPB1 TCE v3: https://www.ebi.ac.uk/cgi-bin/ipd/matching/dpb1_tce_v3\n- KIR Ligand: https://www.ebi.ac.uk/cgi-bin/ipd/matching/kir_ligand\n\nDonor IDs must be ASCII-only in URL params.\n\n### Step 5: TCE-Core Reclassification (Solomon 2024)\nTCE Group 3 splits into core vs non-core. See references/tce-core.md.\n\nKey rule: G3 non-core mismatched with G3 core → C-NPMM → nonpermissive (HR 0.72).\n\n### Step 6: DRB1/DQB1 Match Status\nCompare patient vs donor alleles:\n- DRB1: match / mismatch\n- DQB1: match / mismatch\n- Best combo: mismatch/match (HR 0.80)\n- Worst combo: match/match (HR 1.32)\n\n### Step 7: Cox Model DFS Calculation\nRun scripts/haplo_dfs.py --json '{...}'\n\nModel: Fuchs et al., Blood 2022, Table 3.\nBaseline S₀(3yr) = 0.413. See references/cox-model.md for all coefficients.\n\n### Step 8: Donor Ranking\nSort by 3-year DFS descending.\n- Ranking factors: B-Leader + DRB1/DQB1 + DPB1 TCE-Core + CMV + HCT-CI + age\n- KIR: display only, does NOT affect ranking\n\n### Step 9: MSD/MMUD Comparison Table (Mehta 2024)\nAlways show 5-row comparison table. See references/mehta-comparison.md.\n\n| Group | Source |\n|---|---|\n| ⭐ Optimal Haplo (by B-Leader + DRB1 group) | Mehta TCT 2024 |\n| 🟢 Young MSD+PTCy (under 50y) | Mehta Blood Adv 2024 |\n| 🟡 Old MSD+PTCy (≥50y) | Mehta Blood Adv 2024 |\n| 🔵 MMUD PBM-matched (CNI) | Mehta TCT 2024 |\n| 🟠 MMUD PBM-mismatched (CNI) | Mehta TCT 2024 |\n\n### Step 10: Donor Selection Recommendation\nAuto-generate recommendations for each hypothetical scenario:\n- 🟢 If young MSD available → choose whom?\n- 🟡 If old MSD available → choose whom?\n- 🔵 If MMUD available → choose whom?\n- 💡 Final conclusion\n\nLogic depends on: Haplo group × donor age × patient age.\n\n### Step 11: Generate Final Report\nOutput comprehensive text report (now coordinated by haplo_master_pipeline.py):\n1. Patient clinical info\n2. Patient & All Donor HLA Typing (NEW)\n3. Donor ranking (DFS + KIR display)\n4. MSD/MMUD comparison table\n5. HR comparisons + age effects\n6. GVHD advantage analysis\n7. If-other-donor-type recommendations\n8. Comprehensive conclusion\n9. KIR Ligand Analysis Results & Clinical Significance (NEW, for reference)\n10. References (7 papers)\n\n### Step 12: Export PDF and Save\nGenerate PDF using scripts/report_pdf.py, filename: {patient_name}_DFS.pdf\n\nSave location (now standardized):\n1. Default local path — ~/openclaw/workspace/output/ (always saves local copy)\n2. Google Drive — if gog CLI is configured and user provides a folder path/ID:\n - Use gog drive upload <file> --parent <folder_id>\n - Ask user for Drive folder on first use, remember for subsequent runs\n\n## Scripts\n\n| Script | Purpose |\n|---|---|\n| haplo_master_pipeline.py (NEW) | Orchestrates the entire workflow, including HLA Match Screening and report generation. |\n| scripts/hla_matching.py | B-Leader, DPB1 TCE, KIR Ligand API queries |\n| scripts/haplo_dfs.py | Cox model DFS + comparison + recommendation |\n| scripts/report_pdf.py | Text report → PDF (Chinese font support) |\n\n## References\n\n| File | Content |\n|---|---|\n| references/disease-codes.md | Supported disease/stage codes |\n| references/cox-model.md | Full Cox model coefficients |\n| references/tce-core.md | TCE-Core reclassification rules |\n| references/mehta-comparison.md | Mehta 2024 reference outcome data |\n\n## Dependencies\n\n- Python 3.x with urllib, json, math (stdlib)\n- fpdf2 (for PDF generation, installed in local venv)\n- Chinese font: SimSun (fonts/SimSun.ttf, packaged with skill)\n- Internet access for IPD-IMGT/HLA API calls\n