haplo-donor-selection

---nname: haplo-donor-selectionndescription: "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---nn# Haplo Donor Selection Workflownn## OverviewnnAutomated 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.nn## Workflow Stepsnn### Step 0: Receive HLA Typing ReportnAccept image (JPG/PNG) or PDF. Extract all HLA loci at 4-digit resolution:nA, B, C, DRB1, DQB1, DPB1 for patient and each donor.nn### Step 1: Collect Patient Clinical InfonAsk sequentially (do NOT assume — ask one at a time):nn1. 疾病诊断 — AML / ALL / MDSn2. 疾病状态 — see references/disease-codes.mdn3. 患者年龄n4. HCT-CI 评分 — 0 / 1 / 2 / ≥3nnCMV: default all positive (patient + donors). Donor ages from typing report.nn### Step 2: Extract HLA TypingnParse each person's alleles from the report image/PDF.nVerify: 6 loci × 2 alleles = 12 values per person.nn### 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 reportn- If mismatch → re-read that locus from the imagen- DPB1 is rightmost column — highest risk of column misalignmentn- This step catches OCR/reading errors before they propagate to wrong rankingsnn### 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.nn### Step 3: Haplotype Deduction & Donor ScreeningnFor sibling donors, deduce parental haplotypes.n- 1 shared haplotype → ✅ Haploidenticaln- 2 shared → MSD (flag separately)n- 0 shared → ❌ Exclude with explanationnn### Step 4: IPD-IMGT/HLA API CallsnRun scripts/hla_matching.py --json '{...}'nnThree API endpoints (now integrated and called by haplo_master_pipeline.py):n- B-Leader: https://www.ebi.ac.uk/cgi-bin/ipd/matching/b_leadern- DPB1 TCE v3: https://www.ebi.ac.uk/cgi-bin/ipd/matching/dpb1_tce_v3n- KIR Ligand: https://www.ebi.ac.uk/cgi-bin/ipd/matching/kir_ligandnnDonor IDs must be ASCII-only in URL params.nn### Step 5: TCE-Core Reclassification (Solomon 2024)nTCE Group 3 splits into core vs non-core. See references/tce-core.md.nnKey rule: G3 non-core mismatched with G3 core → C-NPMM → nonpermissive (HR 0.72).nn### Step 6: DRB1/DQB1 Match StatusnCompare patient vs donor alleles:n- DRB1: match / mismatchn- DQB1: match / mismatchn- Best combo: mismatch/match (HR 0.80)n- Worst combo: match/match (HR 1.32)nn### Step 7: Cox Model DFS CalculationnRun scripts/haplo_dfs.py --json '{...}'nnModel: Fuchs et al., Blood 2022, Table 3.nBaseline S₀(3yr) = 0.413. See references/cox-model.md for all coefficients.nn### Step 8: Donor RankingnSort by 3-year DFS descending.n- Ranking factors: B-Leader + DRB1/DQB1 + DPB1 TCE-Core + CMV + HCT-CI + agen- KIR: display only, does NOT affect rankingnn### Step 9: MSD/MMUD Comparison Table (Mehta 2024)nAlways show 5-row comparison table. See references/mehta-comparison.md.nn| 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 |nn### Step 10: Donor Selection RecommendationnAuto-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 conclusionnnLogic depends on: Haplo group × donor age × patient age.nn### Step 11: Generate Final ReportnOutput comprehensive text report (now coordinated by haplo_master_pipeline.py):n1. Patient clinical infon2. Patient & All Donor HLA Typing (NEW)n3. Donor ranking (DFS + KIR display)n4. MSD/MMUD comparison tablen5. HR comparisons + age effectsn6. GVHD advantage analysisn7. If-other-donor-type recommendationsn8. Comprehensive conclusionn9. KIR Ligand Analysis Results & Clinical Significance (NEW, for reference)n10. References (7 papers)nn### Step 12: Export PDF and SavenGenerate PDF using scripts/report_pdf.py, filename: {patient_name}_DFS.pdfnnSave 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 runsnn## Scriptsnn| 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) |nn## Referencesnn| 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 |nn## Dependenciesnn- 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 callsn