信息速览

数据集名称IPD-IMGT/HLA — 免疫遗传学的命名权威

数据类型47,424 个等位基因,346 MB 扁平文本,CC BY-ND 许可,季度更新,免注册直下,JSON API 无鉴权

规模不适用（等位基因参考库，含 78,489 条细胞系记录，无患者级数据）

接入方式IPD-IMGT/HLA（EMBL-EBI / Anthony Nolan Research Institute） url: https://www.ebi.ac.uk/ipd/imgt/hla/

AI 就绪度

IPD-IMGT/HLA — 免疫遗传学的命名权威 AI-Ready Wikipedia

INFOBOX

字段	内容
数据集名称	IPD-IMGT/HLA 数据库
英文全称	Immuno Polymorphism Database — ImMunoGeneTics HLA Database
别名/简称	IPD-IMGT/HLA、IMGT/HLA、HLA 数据库、hla.alleles
疾病分类	不适用（跨疾病的免疫遗传参考库；直接关联移植排斥、乳糜泻、强直性脊柱炎、1 型糖尿病、药物超敏反应等）
SNOMED CT	不适用；提供 ISO OID `2.16.840.1.113883.13.252` 命名空间，可映射到 FHIR 编码系统
数据模态	核酸序列（genomic / coding）、蛋白序列、序列比对、基因特征注释（exon/intron/UTR）、细胞系溯源
AI 任务类型	HLA 分型算法训练与验证、等位基因命名归一化、免疫肽组学参照、群体单倍型频率建模、序列比对与变异注释
样本总数	47,424 个等位基因（3.66.0 版，2026-10-14）；API 实时 47,622（2026-10-22）；78,489 条细胞系记录
数据大小	`hla.dat` 337 MB（zip 43 MB）、`hla_gen.fasta` 136 MB、全部文件约 600 MB
数据格式	扁平文本（EMBL 风格 hla.dat）、FASTA、MSF、XML、PIR、文本比对；API 为 JSON
许可证	CC BY-ND（署名—禁止演绎）；允许商用，禁止分发修改版，须先申请
访问级别	开放（FTP 与 API 均免注册、免凭证、免数据使用协议）
DUO 标签	官方未发布 DUO 标注；等效 NRES（无限制），但 CC BY-ND 附加了「不得改」约束
语言	英文（注释、命名规则、文档）
首发日期	1998（首版 964 个等位基因）
最后更新	2026-10-14（3.66.0，季度更新）
发布机构	Anthony Nolan Research Institute + EMBL-EBI（WHO HLA 系统因子命名委员会官方指定）
官方主页	ebi.ac.uk/ipd/imgt/hla
下载地址	EMBL-EBI FTP、GitHub ANHIG/IMGTHLA
DOI	无数据集级 DOI；引用论文 doi:10.1093/nar/gkaf1218（NAR 2026）
引用次数	数据库级未公布；NAR 2026 论文发表于核酸研究数据库专刊
AI 就绪度评分	⭐⭐⭐⭐（4/5）— 结构规整、API 可用、版本按季发布、注释完整；扣分项：无人口学标签、CC BY-ND 限制衍生、`locus` 过滤参数失效
页面状态	published

§0 E-E-A-T 信任声明与免责声明

医学审核者：千方病案医学编辑部（免疫遗传与移植方向编辑）交叉审核：§2 HLA 生物学背景与临床关联、§7 偏倚与伦理分析。
数据工程审核者：[千方病案医学编辑部交叉审核] 医疗 AI 数据工程师，审核范围：§4 字段字典、§5 切分与泄漏分析、§6 解析 Pipeline 和 8 个坑点。
审核日期：2026-10-22

医疗免责声明：本页面提供的医学信息仅供研究和教育目的，不构成医疗建议、诊断或治疗方案。IPD-IMGT/HLA 是命名参考库，不含任何患者表型或临床结局，不能用于直接诊断或配型决策。任何基于该库训练的算法在进入临床 HLA 分型或移植配型流程前，必须按当地法规完成方法学验证与监管审批（例如 IVDR 下的 CE 认证）。

技术免责声明：本页面的代码示例、解析流程与规模数字基于 2026-10-22 的公开资料与接口实测整理，数据库每季度发布新版，字段与文件布局可能变更，不保证在特定环境下的准确性和适用性。使用者应自行验证代码安全性与解析正确性。千方病案医数集不对因使用本页面信息而导致的任何直接或间接损失承担责任。

数据使用合规：IPD-IMGT/HLA 采用 CC BY-ND，不是常见于 EBI 资源的 CC0 或 CC BY。这意味着：可以复制、分发、展示、商用，但必须完整署名（引用指定三篇论文），不得分发修改后的版本，若需发布衍生序列集必须先向 ipdsubs@anthonynolan.org 申请许可。官方还明确反对镜像站点，要求改用链接。此外，官方免责声明指出部分数据可能受专利保护，无法给出无限制使用许可。

§1 数据集概览

§1.0 📌 30 秒速览

这是什么？ 当一篇论文说"我们发现了新的 HLA 等位基因 A*02:1294"，这个名字不是作者随便起的——它由一个叫 WHO HLA 系统因子命名委员会的专家组审核后授予，而承载全部官方名字与序列的库，就是 IPD-IMGT/HLA。1998 年首版只有 964 个等位基因，2026-10 的 3.66.0 版已有 47,424 个，API 实时口径 47,622 个，分布在 30 余个基因座上。

为什么重要？ HLA 是人类基因组中多态性最高的区域，它决定了器官与造血干细胞移植能否成功、决定了疫苗肽段能否被呈递、也决定了为什么某些药物会在特定人群里引发严重超敏反应（例如 HLA-B*57:01 与阿巴卡韦）。这个领域有一条罕见的全球共识：发表新 HLA 序列之前必须先获得官方命名。这让 IPD-IMGT/HLA 成为免疫遗传学里唯一具有"命名权威"地位的数据库——不是之一，是唯一。

我能用它做什么？ 三类真实用途：① 训练和验证 HLA 分型算法（NGS 时代的核心任务，需要完整的等位基因参照集）；② 构建等位基因名归一化器（临床报告里的 A*01:01 与 A*01:01:01:01 该怎么对？）；③ 免疫肽组学与群体遗传学的参照底座。要注意的是它没有人群频率、没有疾病标签、没有患者数据——那些要去 AFND、dbMHC 或队列研究里找。

§1.1 技术摘要

IPD-IMGT/HLA 最初是国际 ImMunoGeneTics（IMGT）项目的一部分，1998 年由 Anthony Nolan 研究所（前身 ICRF 团队）与 EMBL-EBI 联合上线，首版 964 个等位基因，开发资金来自欧盟 BIOMED1（BIOCT930038）与 BIOTECH2（BIO4CT960037）两项资助。它现在由 Anthony Nolan Research Institute 维护，与 UCL Cancer Institute、Stanford University、EMBL-EBI 合作，技术上运行在 Oracle 数据库之上，对外提供扁平文件、FASTA、MSF、XML、PIR 与 REST API 六种读取通道。

数据模型的核心是"一个等位基因 = 一条记录"，主键是 HLA 编号（如 HLA00001），永不复用——这点与很多数据库不同，一个被删除的等位基因编号不会被回收，所以 accession 可以作为稳定的跨版本连接键。每条记录携带 29 个字段，覆盖核酸与蛋白序列、外显子/内含子/UTR 特征坐标、CIGAR 比对串、INSDC（ENA/GenBank）交叉引用、细胞系溯源、文献引用、多实验室确认状态、G 组/P 组映射、以及完整的命名变更历史（allele_history，长记录可达上百条）。

发布节奏是季度：每年 1 月、4 月、7 月、10 月各一次，版本号形如 3.66.0。每次发布同时提供 version_report.txt，逐条列出 New / Modified / Suffix / Deleted 四类变更——这是做增量同步的关键文件。3.66.0 的变更表共 907 行：新增 773、修改 132、后缀变更 1、删除 1。

规模口径有三套且互不相等，必须分开写：Flat 文件实数 47,424（Allelelist.txt，2026-10-14）与官方增长表一致；API 实时 47,622（2026-10-22，含增量入库与状态过滤差异）；NAR 2026 论文口径 “>43,000”（论文投稿时点）。三者相差不大但绝对不能混用——写"47,424"就该注明是 3.66.0 的 flat 口径，写"47,622"就该注明是 API 快照。

§1.2 战略价值

维度一：唯一的命名权威，构成学术基础设施。 大多数生物数据库做的是"汇集已有的东西"，IPD-IMGT/HLA 做的是"决定东西叫什么"。这个区别看似细微，实际影响巨大：全世界所有 HLA 分型软件、所有移植配型报告、所有 HLA 相关论文，共同使用同一套名字。一个等位基因名一旦被授予，其他论文就不能另起新名。这让它成为一种罕见的规范性数据库（normative database）——它不只记录现实，它定义现实。对做临床文本 NLP 的团队，这意味着任何 HLA 实体的归一化都必须串接这个库，没有替代方案。

维度二：四字段命名体系本身就是一套可比对的数据科学设计。 A*01:01:01:01 的四个字段不是任意分隔，而是逐级放宽的序列等价关系：字段 1 是等位基因组（近似血清学家族），字段 2 决定蛋白序列，字段 3 是同义突变（CDS 内不改变氨基酸），字段 4 是非编码区差异。这让"两个名字是否代表同一蛋白"变成一个字符串前缀判断——A*01:01:01:01 与 A*01:01:01:02 蛋白相同、核苷酸不同；A*01:01:01 与 A*01:01:02 CDS 相同、内含子可能不同。G 组（A*01:01:01G）与 P 组（A*01:01P）就是这套等价关系的两个官方聚合层。这是一个"用命名编码数据语义"的经典案例，任何做实体标识体系设计的团队都值得读一遍。

维度三：为新版提交工具与 ENA 代理铺路。 2026 年数据库做了一次基础设施升级：新的提交工具替换了运行 26 年、累计处理超过 28,000 次提交的旧系统，并提供两条关键能力——自动化校验，以及可选地把序列同时代理提交到 European Nucleotide Archive（ENA）。这意味着一条新序列可以同时出现在 IPD-IMGT/HLA 与 ENA，且归属清晰。对使用者而言，结果是可以用 INSDC 编号（PZ509006 这类）在核酸库与 HLA 库之间双向跳转，这在旧版里是断的。

§1.3 同类资源横向对比

资源	定位	规模	许可	与 IPD-IMGT/HLA 的差异化
IPD-IMGT/HLA（本条目）	WHO 官方命名库	47,424 等位基因 / 30+ 基因座	CC BY-ND	唯一具命名权威；四字段体系；G/P 组；季度版本
IPD-KIR	杀伤细胞免疫球蛋白样受体命名库	同 IPD 家族，规模小得多	CC BY-ND	姊妹库，KIR 基因；同一提交与命名流程
IPD-MHC	非人灵长类等 MHC	多物种	CC BY-ND	同一命名框架扩展到其他物种；人类研究用作比较参照
dbMHC（NCBI）	HLA 群体频率与序列	已停止更新	公有领域	历史上提供人群频率；库本体已归档，不做新命名
AFND（Allele Frequency Net Database）	人群等位基因与单倍型频率	千万级个体频率记录	开放	IPD-IMGT/HLA 缺的频率维度在这里；两者常配对使用
IMGT/HLA GitHub（ANHIG/IMGTHLA）	官方镜像仓库	全部版本	CC BY-ND	同一数据；提供 `Latest` 与 `testing` 分支与版本追溯
ENA / GenBank	核酸原始记录	亿级	开放	上游序列库；2026 起通过 brokering 与 HLA 库互链
Allele Frequencies / 1000 Genomes HLA 分型	群体参考面板	千人级	开放	提供真实人群基因型，可测分型算法在真实数据上的表现

§1.4 版本时间轴

时间	版本	事件与规模
1998	—	IPD-IMGT/HLA 首版发布，964 个等位基因
2000	—	Robinson et al. 在 Tissue Antigens 发表数据库论文（55:280-287），确立引用规范
2013-04	3.12	9,310 个等位基因 / 19,659 component entries
2015-04	3.20	13,190 / 26,003
2017-10	3.30	17,509 / 32,919
2019-04	3.36	22,528 / 41,623
2021-01	3.43	29,417 / 55,268
2023-01	3.51	36,625 / 66,477
2024-04	3.56	39,886 / 71,247；>100 MB 文件改 zip，弃用 Git LFS
2025-04	3.60	42,584 / 76,021
2026-01	3.63	44,876 / 79,871
2026-04	3.64	46,005 / 81,830
2026-07	3.65	46,652 / 82,661
2026-10-14	3.66	47,424 / 83,680；新增 773、修改 132、删除 1
2026-10-22	—	API 实时 `total` = 47,622（本 Wiki 实测）

§1.5 典型应用场景

HLA 分型算法训练与验证：NGS 分型工具（如 OptiType、HLA-VBSeq、arcasHLA 类方法）的参照集就是这份库。算法的核心任务是在几十万个候选等位基因中找出最可能的二倍型，参照库不全就会漏检。
等位基因名归一化：临床报告常混用不同分辨率（A*01:01、A*01:01:01、A*01:01:01:01）。用 allele_history 与四字段语义可以构建归一化器，把任意历史名字映射到当前规范名。
免疫肽组学参照构建：质谱鉴定的 HLA 结合肽需要与具体等位基因的蛋白序列比对，蛋白序列直接来自 hla_prot.fasta。
群体遗传学与单倍型建模：需要 HLA 序列多样性结构（而非频率），这份库提供全部序列与基因座关系；频率维度再接 AFND。
药物基因组学规则引擎：HLA-B*57:01（阿巴卡韦）、HLA-B*15:02（卡马西平）、HLA-B*58:01（别嘌醇）等药物警戒规则需要可解析的等位基因集合，G 组/P 组语义直接决定规则该写多宽。

§2 HLA 生物学背景与命名体系

§2.1 基因座分布与临床关联映射

IPD-IMGT/HLA 不使用 ICD-11 疾病编码——它记录的是基因而不是疾病。但 HLA 等位基因与一批疾病的关联强度已达到临床可用级别，下表把主要基因座的规模与该基因座关联的代表性疾病并列（ICD-11 编码取章节级或具体条目）：

基因座	等位基因数（3.66.0）	HLA 分类	ICD-11 关联示例	临床场景
B	11,328	I	强直性脊柱炎（FA92.0）、卡马西平超敏（EH62）	移植配型、药物警戒
C	9,580	I	银屑病（EA90）、NK 细胞教育	移植配型、母胎免疫
A	9,457	I	乳糜泻（DA95）、白塞病（4A62）	移植配型、疾病关联
DRB1	4,056	II	类风湿关节炎（FA20）、1 型糖尿病（5A10）、发作性睡病（7A20）	移植配型核心位点、疾病关联最强
DPB1	3,209	II	造血干细胞移植预后	移植配型（次级位点）、DP T 细胞表位匹配
DQB1	3,161	II	乳糜泻（DQ2/DQ8）、1 型糖尿病	移植、疾病易感
DQA1	1,084	II	乳糜泻（与 DQB1 共同构成 DQ2.5/8）	疾病易感
DPA1	980	II	移植预后	移植配型
DRB3 / DRB4 / DRB5	828 / 404 / 302	II	DR 单倍型结构	单倍型判定（DRB3/4/5 是否伴随特定 DRB1）
MICA / MICB	732 / 415	非经典 I 类样	移植排斥、NKG2D 配体	移植、肿瘤免疫
E / F / G	390 / 140 / 207	非经典 I 类	母胎耐受（G）、NK 调控（E）	生殖免疫、移植
TAP1 / TAP2	19 / 106	抗原加工相关	抗原呈递效率	免疫缺陷研究
H / J / K / L / W / T	106 / 34 / 8 / 5 / 13 / 9	假基因或低表达	—	分型时的干扰源（见坑点）

统计口径：基因座计数来自 Allelelist.txt（3.66.0，47,424 条全量解析），不是抽样。总计数与官方增长表的 47,424 完全一致，可作为内部自洽性验证。

§2.1b 与 SNOMED CT / OID 的映射说明

HLA 不是疾病概念，SNOMED CT 中只有"HLA 分型（操作）"与"HLA 抗原（物质/抗体）"两类相关概念，没有逐等位基因编码。工程上的正确映射路径是 ISO OID：

你的需求	正确做法
在 FHIR 里标识一个 HLA 编码系统	使用 OID `2.16.840.1.113883.13.252`（库根），子节点细分到等位基因（`A*01:01:01:01` 的 OID 为 `2.16.840.1.113883.13.252.1.1.1`）
在 SNOMED CT 里找等位基因	找不到。不要硬造映射，用 OID 或直接用等位基因名
映射到疾病	走「等位基因 → 关联疾病」的文献级映射表（如 HLA-B*27 → 强直性脊柱炎），不要指望数据库提供
映射到血清学抗原	用 `dictionary` 字段（含 13th IHWC 等血清学会议指派结果）与 `cwd.version_2`

§2.2 HLA 系统的生物学背景

HLA（Human Leukocyte Antigen，人类白细胞抗原）基因位于 6 号染色体短臂 6p21.3，是人类基因组中多态性最高的区域，官方描述为"hyperpolymorphic"（超多态）。它编码 MHC（主要组织相容性复合体）分子，功能是把细胞内加工的肽段呈递到细胞表面，供 T 细胞识别。这个功能决定了它在三个临床方向上的核心地位。

第一是移植。 供受者的 HLA 差异越大，T 细胞识别"非己"的概率越高，移植物抗宿主病（GVHD）与排斥风险越高。经典位点 HLA-A、-B、-C、-DRB1、-DQB1 是配型的核心，部分方案还看 DPB1。匹配的粒度直接取决于命名分辨率——两个都叫 A*02:01 的等位基因，在字段 3/4 上可能不同，核苷酸序列不一致，这在高分辨分型里是实质性差异。

第二是疾病易感。 最经典的例子是 HLA-B27 与强直性脊柱炎（相对风险可达数十倍），以及 HLA-DQ2/DQ8 与乳糜泻（几乎为必要条件）。此外 DRB1 与类风湿关节炎、DR3/DR4 与 1 型糖尿病、DQB106:02 与发作性睡病都有强关联。

第三是药物超敏。 这一支在近二十年成为药物基因组学的核心：HLA-B57:01 与阿巴卡韦超敏反应、HLA-B15:02 与卡马西平引起的 Stevens-Johnson 综合征、HLA-B*58:01 与别嘌醇重症药疹。这三条都已进入临床指南，成为"用药前先测基因"的标准场景。注意这三条规则写多宽（具体等位基因？P 组？G 组？）完全取决于本库的等价关系定义——这是本库与临床最直接的一条通路。

谱系层面还有一个必须知道的细节：HLA 存在连锁不平衡与单倍型结构。某些等位基因几乎总是一起出现（如 DRB103:01-DQA105:01-DQB1*02:01 构成的 DR3 单倍型），而 DRB3/4/5 的表达取决于 DRB1 的类型。这导致"逐个位点独立建模"在 HLA 上会失效。

§2.3 四字段命名体系：一套用字符串编码的等价关系

这是全篇最重要的一节。A*01:01:01:01 这个名字的每个冒号都有严格语义：

位置	名称	语义	示例	影响
冒号前	基因座	基因名 + `*`	`A`、`DRB1`	决定蛋白类型（I 类 α 链 / II 类 β 链）
字段 1	allele group	等位基因组，近似血清学家族	`A*01`	粗分类，常用于低分辨分型
字段 2	specific allele	决定蛋白氨基酸序列差异	`A*01:01`	临床高分辨分型的最小单位
字段 3	synonymous mutation	CDS 内同义突变（不改变氨基酸）	`A*01:01:01`	影响核酸检测，不影响蛋白
字段 4	non-coding	内含子 / UTR 差异	`A*01:01:01:01`	只影响基因组测序分辨率

后缀字母表达表达水平异常（写在名字末尾）：

后缀	含义	全库计数（47,424 条实测）
`N`	Null，不表达	2,072（4.37%）
`L`	Low，低表达	见 `Allele_status.txt` 逐条记录
`S`	Secreted / soluble，可溶性	同上
`C`	Cytoplasmic，胞质内	同上
`A`	Aberrant，异常表达	同上
`Q`	Questionable，表达存疑	同上

命名分辨率分布（47,424 条实测，按冒号数统计）是本库最值得记住的一张分布：

分辨率	形式	条数	占比
血清学级（0 冒号）	`A*01`	312	0.66%
二字段	`A*01:01`	26,354	55.6%
三字段	`A*01:01:01`	11,297	23.8%
四字段（全分辨率）	`A*01:01:01:01`	9,461	20.0%

这张表的工程含义非常直接：只有 20% 的等位基因有完整四字段名。如果你的分型流程以四字段为目标，参照集的 80% 是不同分辨率的——任何"精确字符串匹配"式的实现都会大面积失配，必须用等级化匹配（见 §6.3）。

G 组与 P 组是官方提供的两个聚合层：

组	定义	示例	典型用途
G 组（G_group）	忽略字段 3/4 的合并组（核苷酸同义）	`A*01:01:01G`	移植配型的标准报告粒度
P 组（P_group）	蛋白序列相同的合并组	`A*01:01P`	抗体与表位研究、免疫肽组学

抽样 300 条详情中，wmda.G_group 存在 166 条（55.3%）、P_group 存在 194 条（64.7%）——并非所有等位基因都有组归属，这是坑点 4 的来源。

§2.4 数据来源人群与提交主体

维度	情况
提交主体	全球 HLA 分型实验室、移植中心、供者登记库、研究团队
覆盖人群	全球，但明显偏向有大型供者登记库的地区
细胞系记录	78,489 条（API `/cell` 实测），用于序列确认与溯源
单条细胞系字段	`cellid`、`primary_name`、`ancestry`（如 European）等
提交量历史	旧提交系统运行 26 年累计 >28,000 次提交（NAR 2026 论文口径）
确认机制	多实验室复核；`confirmation_status` 记录确认实验室数量与真假值

§2.5 为什么"命名"本身就是临床价值

一个思维方式上的转换：大多数人把数据库理解为"存数据的容器"，因此觉得"命名"只是元数据细节。但在 HLA 领域，命名是临床决策的输入。

举一个具体场景。某患者携带 B*57:01，药房系统需要判断是否禁用阿巴卡韦。系统拿到的是实验室报告里的字符串，可能是 B*57:01（二字段）、B*57:01:01（三字段）、或 B*57:01:01:01（四字段），也可能是 G 组写法 B*57:01G。如果规则引擎写的是 name == "HLA-B*57:01:01"，那么三字段与四字段的报告都会漏判——这不是理论风险，是真实发生过的规则失效类型。

正确写法是基于四字段语义的前缀匹配 + G/P 组合并：只要名字以 B*57:01 开头且字段 3/4 的差异是同义的，就应判定为该等位基因组。这要求规则引擎能解析等位基因名而不是做字符串相等——而解析规则的定义权，就在本库。

同理，移植配型报告写 A*02:01G 而不是 A*02:01:01:01，因为 G 组粒度才是临床可操作的分辨率：同一 G 组内的等位基因在移植意义上等价。这个粒度选择不是软件工程决策，是免疫学决策，而这个决策的编码就写在本库的 G 组定义里。

§2.6 质量标准的边界：库保证什么、不保证什么

检查项	库是否执行	说明
序列完整性	⚠️ 部分	大量等位基因只有部分区段（`sequence_status.full` 为 false）
命名唯一性	✅ 是	WHO 命名委员会审核后才分配名字，HLA 编号永不复用
多实验室确认	⚠️ 部分	抽样 300 条中 `confirmed=True` 265 条（88.3%），单实验室确认占 10%
重复序列检测	✅ 是	同一序列不会获得两个名字（历史遗留除外，见 `secondary_names`）
序列正确性	❌ 否	LICENCE 明确"no warranties regarding the correctness of the data"
表型与临床关联	❌ 否	完全不收录
人群频率	❌ 否	完全不收录（去 AFND）
表达水平	⚠️ 部分	通过名字后缀（N/L/S/C/A/Q）间接表达，无定量数据
版本可追溯	✅ 是	`allele_history` 记录每一次改名与所属版本

一句话：这个库保证"这个名字对应这条序列"，不保证"这条序列是对的"，更不保证"这个等位基因有临床意义"。

§3 数据库规格与版本抉择

§3.0 六种获取通道的抉择矩阵

你的需求	推荐通道	体量	理由
只要等位基因列表与名字	`Allelelist.txt`	948 KB	最小、最快、只有两列（HLA 编号 + 名字）
要序列 + 注释 + 全部字段	`hla.dat`（或 `.zip`）	337 MB / 43 MB	完整记录，EMBL 风格扁平文本，BioPython 可解析
只要 FASTA 序列	`hla_gen.fasta` / `hla_nuc.fasta` / `hla_prot.fasta`	136 / 41 / 14 MB	基因组 / CDS / 蛋白三种，比对与建模最快
要程序化按需查询	REST API	按请求	无需下全量；但只能逐条取，无字段投影
要版本追溯与增量	`version_report.txt` + `sversion_history.txt`	41 KB / 8.0 MB	季度增量同步的正确做法
要看历史命名变迁	`Allelelist_history.txt`	28 MB	每次发布的全量快照，可重建任意历史时点
要 git 版本控制	GitHub ANHIG/IMGTHLA	仓库	`Latest` 与 `testing` 双分支；注意 LFS 陷阱（坑点 6）

§3.1 文件清单与体量

文件	大小	内容
`hla.dat`	337 MB	全部等位基因的 EMBL 风格完整记录（序列 + 注释 + 溯源）
`hla.dat.zip`	43 MB	上者的 zip（2024-04 起不再用 Git LFS）
`hla_gen.fasta`	136 MB	基因组序列 FASTA
`hla_nuc.fasta`	41 MB	CDS 序列 FASTA
`hla_prot.fasta`	14 MB	蛋白序列 FASTA
`Allelelist.txt`	948 KB	HLA 编号 ↔ 名字两列对照
`Allelelist_history.txt`	28 MB	历次发布的全量等位基因列表
`Allele_status.txt`	2.0 MB	逐条等位基因的状态与表达标记
`version_report.txt`	41 KB	本版新增/修改/删除明细
`sversion_history.txt`	8.0 MB	序列版本历史
`deleted_alleles.txt`	25 KB	已删除等位基因清单
`Alignments_Rel_3660.zip`	13 MB	全部分子的比对文件（按基因座分文件）
`Manual.md` / `README.md` / `LICENCE.md`	29 / 17 / 4.9 KB	格式说明、仓库说明、许可

§3.2 按基因座的子集规模

分组	基因座	合计等位基因	说明
经典 I 类	A / B / C	30,365（64.0%）	移植配型核心
经典 II 类	DRA / DRB1 / DRB3 / DRB4 / DRB5 / DQA1 / DQB1 / DPA1 / DPB1	14,936（31.5%）	移植与疾病关联核心
非经典 I 类样	E / F / G / MICA / MICB	1,884（4.0%）	生殖免疫、NK 调控、移植
抗原加工	TAP1 / TAP2	125	抗原呈递机制
假基因与低频	H / J / K / L / W / T / DQA2 / DQB2 / DMA / DMB / DOA / DOB	约 400	分型干扰源（坑点 5）

§3.3 格式族与用途

格式	位置	适用	注意
扁平文本（hla.dat）	根目录	全字段解析	EMBL 风格；BioPython `SeqIO.parse(fmt='imgt')`
FASTA	`fasta/` 与根目录	序列分析	不含比对信息，也丢注释
文本比对	`alignments/`（`X_prot.txt` / `X_nuc.txt` / `X_gen.txt`）	看变异位置	3.32.0 起文件头以 `#` 开头
MSF	`msf/`	GCG 生态工具	老工具链仍用
XML	`xml/hla.xml`、`xml/hla_ambigs.xml`	程序化结构化解析	体量与 hla.dat 同级
PIR	`pir/`	系统发育分析	常用于建树
OID	`oid/`	FHIR / HL7 集成	直接给 OID 映射
TCE	`tce/`	DPB1 T 细胞表位	专用于 DP 表位匹配工具
WMDA	`wmda/`	G 组 / P 组表	移植匹配必需
JSON（API）	`/cgi-bin/ipd/api/allele`	按需查询	无字段投影、无 locus 过滤（坑点 2）

§3.4 存储与下载预算

场景	需要下载	磁盘	说明
只做命名归一化	`Allelelist.txt` + `Allelelist_history.txt`	< 40 MB	最省
做分型算法参照集	`hla_gen.fasta` + `hla_nuc.fasta` + `hla_prot.fasta` + `wmda/`	约 200 MB	解压后
全量分析	全部文件	约 1.2 GB（解压）；`hla.dat` 单文件 337 MB	建议留 3 GB 工作空间
API 逐条取 47,622 条详情	无需磁盘	无	不推荐：按实测速率约 1.8 s/条，需 24 小时以上

§3.5 命名与审核流程

阶段	谁做	做什么	失败后果
测序与组装	提交实验室	用 Sanger 或 NGS 得到完整/部分序列	—
提交	实验室	通过新版提交工具上传，工具自动校验格式与完整性	校验失败则无法提交
编号	IPD 团队	分配 `HLA` 编号（永不复用），入库	—
命名	WHO 命名委员会	审核后授予官方等位基因名	序列可能被归入已有名字（成为 `secondary_names`）
代理提交	提交工具（2026 起可选）	同步提交到 ENA，获得 INSDC 编号	不选则只有 HLA 编号
发布	IPD 团队	季度发布，写 `version_report.txt`	—

§3.6 更新周期与版本号规则

每年四次：1 月、4 月、7 月、10 月（实测日期例：3.65 为 2026-07，3.66 为 2026-10-14）。
版本号 3.xx.0：3 为大版本（历史演进），xx 为季度序，末位用于紧急修订。
Allelelist_history.txt（28 MB）保存每次发布的全量列表，可重建任意历史时点——这是做可复现研究的关键文件。
version_report.txt 只含本版变更，做增量同步应当用它与 lastRelease 做差分，而不是重新解析 337 MB 的 hla.dat。

§3.7 提交界面的「testing 分支」

GitHub 仓库有一个 testing 分支，官方明确说明：

该分支的文件不得用于临床或诊断工作，仅供测试。文件可能包含错误或在后续流程中触发错误。Testing 分支不包含任何未发布信息，没有序列或等位基因名会提前发布。

它的价值在于：格式变更会提前至少 4 周在 testing 分支公开。如果你的解析管线对格式敏感（例如依赖 hla.dat 的某个字段顺序），订阅 testing 分支的 diff 比读发布说明更早发现问题。

§3.8 技术栈

层	组件	说明
数据库	Oracle	官方 About 页明确说明用 Oracle 承载 HLA 序列与复杂查询
前端	EBI 托管网页 + 独立命名站 `hla.alleles.org`	命名规则与统计在后者
API	Flask 风格 REST（`/cgi-bin/ipd/api/`）	根路径返回 `{"build":1,"environment":"production"}`
分发	EMBL-EBI FTP + GitHub `ANHIG/IMGTHLA`	双通道；GitHub 从 3.56.0 起弃用 LFS
交叉引用	INSDC（ENA / GenBank）	通过 `insdc` 字段，2026 起支持 brokering 自动同步
命名体系	ISO OID `2.16.840.1.113883.13.252`	可对接 FHIR 编码系统

§3.9 溯源链：一条序列从提交到命名

实验室测序（Sanger / NGS）
   ↓ 新版提交工具（自动校验：格式、完整性、与已有序列的差异）
IPD 团队分配 HLA 编号（HLA00001 起，永不复用）
   ↓ 转发 WHO HLA 系统因子命名委员会（每年年会 + 月度命名更新）
委员会授予官方等位基因名（如 A*02:1294）
   ↓ 可选：brokering 到 ENA，获得 INSDC 编号（如 PZ509006）
季度发布 → version_report.txt 记录 New / Modified / Deleted
   ↓
同时出现在：FTP 全量文件、GitHub 仓库、REST API、命名站统计页
   ↓
被分型软件、配型系统、论文、临床报告引用

这条链的关键节点在命名委员会：它每年开会一次，日常以月度命名更新（HLA Nomenclature Updates）发布新名字。这解释了为什么 3.66.0 的 773 个新等位基因的 date_assigned 集中在 2026-07 与 2026-08 两个月——它们是季度发布前累积起来的。

§4 记录结构与字段字典

§4.0 四层对象模型与目录形态

IPD-IMGT/HLA 的"表结构"比一般数据集复杂，因为它同时是命名登记册、序列库和比对库。同一份内容有四种形态，理解层级关系是全部工程工作的前提：一条 等位基因（allele） 记录挂着一个或多个 序列（sequence） 版本，序列由若干 特征（feature） 区间组成，特征坐标对应到具体 细胞系（cell） 来源与文献。

FTP 根 /pub/databases/ipd/imgt/hla/
├── hla.dat                           ← 串行主记录（EMBL 风格，一份文件含 47,424 条）
│   └── 每条记录 = 1 个 allele
│       ├── ID   HLA00001; SV 1; standard; DNA; HUM; 350 BP.
│       ├── AC   HLA00001;            ← accession，永不复用
│       ├── DE   Homo sapiens HLA-A*01:01:01:01
│       ├── FT   exon / intron / UTR 区间（坐标 + 产品）
│       ├── SQ   核酸序列
│       ├── //                          ← 记录分隔符
│       ├── CO   (蛋白翻译区块，同一 accession 的 protein view)
│       └── DR   (交叉引用：ENA / GenBank / PDB / PMID)
├── Allelelist.txt                    ← 两列对照表（AlleleID, Allele）
│   └── HLA00001,A*01:01:01:01
├── Allele_status.txt                 ← 第三条轴：表达状态与确认等级
│   └── A*01:01:01:01; A; (N); ...
├── wmda/                             ← 第四条轴：G 组 / P 组映射
│   ├── hla_nom_g.txt                 ← G 组
│   └── hla_nom_p.txt                 ← P 组
├── fasta/                            ← 派生视图
│   ├── hla_gen.fasta  (genomic)
│   ├── hla_nuc.fasta  (coding)
│   └── hla_prot.fasta (protein)
├── alignments/                       ← 派生视图（按基因座分文件）
│   ├── A_prot.txt  A_nuc.txt  A_gen.txt
│   └── ...（每个基因座三份）
├── xml/  msf/  pir/  oid/  tce/      ← 更多派生格式
├── Allelelist_history.txt            ← 全历史对照（28 MB）
├── sversion_history.txt              ← 序列版本历史
├── version_report.txt                ← 本版变更
└── deleted_alleles.txt               ← 已删除清单

四条轴（Allelelist / Allele_status / wmda / hla.dat）必须联表才能得到完整语义。新手最常犯的错是只读 hla.dat——它不含 G 组/P 组，也不含确认等级；或只读 Allelelist.txt——它只有两列，连基因座之外的任何属性都没有。

§4.1 字段字典（allele 记录，29 字段）

下表按 /api/allele/{accession} 的实返结构整理（hla.dat 中的 DR / FT 行是同一批信息的另一种编码）。8 列沿用 DAIMS 风格：字段、类型、说明、示例、AI 用途、观测误差、信息性缺失编码、取值范围。

字段	类型	说明	示例	AI 用途	观测误差	缺失编码	取值范围
`accession`	string	HLA 编号，全库唯一、永不复用	`HLA00001`	稳定主键、跨版本连接	无	必有	`HLA` + 5 位数字，已过 4.7 万
`name`	string	官方等位基因名	`A*01:01:01:01`	标签、实体归一化目标	名字会随命名更新改变	必有	四字段 + 可选后缀
`locus`	string	基因座	`A*`	分组、按座建模	无	必有	30 余种
`class`	string	HLA 分类	`I`	粗粒度分层	非经典座归类不一致	必有	`I` / `II`
`project`	string	所属项目	`IPD-IMGT/HLA`	多库合并时区分来源	恒为同值	必有	单值
`status`	string	记录状态	`Public`	必须过滤	13/300 抽样为 `Deleted`	必有	`Public` / `Deleted`
`oid`	string	ISO 对象标识符	`2.16.840.1.113883.13.252.1.1.1`	FHIR/HL7 映射	只在部分记录上出现	可能缺省	OID 树
`omim`	array	OMIM 关联	`[142800]`	疾病关联跳转	与等位基因级的关联不精确	空数组 `[]`	6 位 MIM 号
`sequence_version`	string	序列版本号	`1`	判断序列是否修订过	与库版本号不同轴	必有	整数串
`sequence_status`	object	序列区间与完整性	`{start:"1", end:"350", full:true, type:"Genomic"}`	筛完整序列	`full` 为字符串化布尔	对象内字段可能缺	四子字段
`sequence`	object	三段序列	`{coding:"...", genomic:"...", protein:"...", codon_start:"1"}`	直接训练	三条序列可能长短不等	段级缺失	核苷酸/氨基酸串
`feature`	object	特征区间	`{coding:[...], genomic:[...], protein:[...]}`	外显子级建模	抽样 exon 1,931 / intron 1,670	空数组 `[]`	坐标区间
`cigars`	object	与参照的比对串	`{coding_cigar:"350M", ...}`	变异定位	语义需对照 Manual.md	可能缺省	CIGAR 语法
`insdc`	array	ENA/GenBank 编号	`["PZ509006"]`	与核酸库互跳	旧记录常为空	空数组 `[]`	INSDC 编号
`allele_history`	array	命名变更史	`[{...}]`	历史名归一化	长记录可达上百条	空数组 `[]`	变更加事件序列
`secondary_names`	string	曾用名/别名	`A*01:01:01:01`	去重关键	多对一映射	空串 `""`	逗号分隔串
`previous_nomenclature`	string	旧命名法名	`A*01010101`	老文献对齐	早期记录才有	空串 `""`	无冒号连写
`confirmation_status`	object	多实验室确认	`{cells:[], confirmed:true, laboratories:5}`	质量权重	22/300 为 `false`	`confirmed` 可为 `null`	布尔 + 计数
`cell_entries`	array	细胞系溯源	`[{cell_id, ...}]`	交叉验证素材	部分记录为空	空数组 `[]`	细胞系 ID 列表
`citations`	array	文献引用	`[{pubmed_id, ...}]`	溯源、可信度	旧记录引用少	空数组 `[]`	PMID 列表
`cwd`	object	常见且充分记录	`{version_3:{"AFA":"C",...}}`	按人群可用性加权	20.3% 为 null	`null`	人群 → 等级字典
`wmda`	object	G 组 / P 组	`{G_group:"A01:01:01G", P_group:"A01:01P", rel_dna_ser:"..."}`	移植匹配层级	55.3% / 64.7% 才有值	`null`	组名或血清学名
`dictionary`	object	术语来源	`{data:..., source:...}`	标准化	多为固定结构	可能缺省	结构体
`date_assigned`	string	命名日期	`2026-07-15`	时间切片	与发布日不同	必有	ISO 日期
`date_modified`	string	记录修改日	`2026-08-01`	增量同步	无	必有	ISO 日期
`first_release`	string	首次出现版本	`3.66.0`	版本切片	无	必有	版本号
`release_version`	string	当前所属版本	`3.66.0`	快照对齐	无	必有	版本号
`release_date`	string	该版本发布日	`2026-10-14`	快照对齐	无	必有	ISO 日期
`release_status`	string	发布状态	`Sequence unchanged`	不可用于筛选	300/300 恒定同值	必有	枚举（实际退化）

字段表里两个"看起来有用其实不可用"的字段值得单独点名：release_status 在 300 条抽样中恒为 Sequence unchanged，任何基于它的筛选都等于不筛；project 恒为 IPD-IMGT/HLA，多库合并时才有区分意义。反过来，status 与 sequence_status.full 是真正高价值的两个筛子，前者排除已撤回记录，后者把 47,424 条压到"可用于分型算法"的子集。

§4.2 字段字典（G 组 / P 组映射表）

wmda/hla_nom_g.txt 与 hla_nom_p.txt 是两份独立的分组表，语义不同但格式相似（分号分隔、# 开头为注释）。

字段	类型	说明	示例	AI 用途	观测误差	缺失编码	取值范围
列 1	string	具体等位基因名	`A*01:01:01:01`	多对一映射的左端	名字随命名更新变化	必有	四字段名
列 2	string	所属 G 组 / P 组名	`A*01:01:01G`	映射的右端	一个等位基因可能有多个历史组	必有	组名
列 3	string	表达/血清学标记	`A1`	血清学家族对齐	部分行为空	空串	血清学名

G 组与 P 组的差别是移植匹配的核心概念：G 组把"CDS 内同义突变"合并（即四字段的前三字段相同），P 组把"蛋白序列相同"的全部合并（跨基因座内的所有同义与同蛋白变体）。做配型时用 G 组是常规做法，做免疫肽组学用 P 组更合适——因为肽段呈递只取决于蛋白序列。这两份表不能互相替代，也不能用四字段前缀硬算，因为官方组名里包含不以简单前缀规则生成的成员（历史命名残留）。

§4.3 规模口径的实际形态：四套数字怎么用

这是本篇最容易出错的地方。同一时刻，"有多少个 HLA 等位基因"有四个官方或半官方答案：

口径	数字	时点	来源	适合什么场景
Flat 文件实数	47,424	2026-10-14（3.66.0）	`Allelelist.txt` 行数 + 官方增长表	可复现实验、写方法学章节
API 实时	47,622	2026-10-22 快照	`/api/allele?limit=1` 的 `meta.total`	说明"当前能用多少"
Component entries	83,680	2026-10-14（3.66.0）	官方增长表	说明序列片段总数（一个等位基因可有多段）
论文口径	“>43,000”	2025 年投稿时点	NAR 2026 摘要	引用论文时照抄，不要换算

四者的关系：47,424 是"名字数"，83,680 是"序列条目数"，后者大于前者是因为同一等位基因可能分别记录了 genomic / coding / protein 三种视图与不同长度的片段。API 的 47,622 比 flat 多 198 条，来自发布后十天内的增量入库与 Deleted 记录的计入策略差异（API 不默认排除 Deleted）。

写法规范（编辑部内部约定）：正文首次出现必须写明口径与时点，例如"47,424 个等位基因（3.66.0，2026-10-14 的 Allelelist.txt 实数）"；表格中若并列两口径，须在表头标注来源列。任何只写"约 4.7 万"而不标注来源的表述，视为不合格。

§4.4 数据层级：基因座 → 等位基因组 → 等位基因 → 序列

层级	粒度	数量关系	AI 建模时的含义
基因座（locus）	一个 HLA 基因	30 余个	分层抽样与分组交叉验证的自然单位
等位基因组（allele group）	字段 1	数百个	血清学家族近似；临床报告常用粒度
等位基因（allele）	一个官方名	47,424 个	样本单位；一个名字 = 一条记录
序列（sequence）	一段核酸/蛋白	83,680 个 component entries	真正的建模输入
特征（feature）	一个 exon/intron	每记录 10 余个	外显子级任务的切分单位

关键的建模含义：样本单位应当选"等位基因"或"基因座 + 等位基因组"，绝不能选"序列条目"。因为同一等位基因的多条序列高度重复（genomic 包含 coding，coding 包含 protein 的翻译），以序列为样本单位会造成严重的重复计数。

§4.5 缺失值的五种形态

HLA 的缺失不是统一的 NaN，而是五种不同语义，混为一体会直接毁掉下游统计：

形态	表现	频率（实测）	真实含义	处理建议
`null`	`"wmda": null`	G 组缺 44.7%、P 组缺 35.3%	尚未被分入任何组	判为"未分组"，不是"无 G 组"
`""` 空串	`"secondary_names": ""`	常见	从未改过名	判为"无别名"，可安全当作"自身"
`[]` 空数组	`"insdc": []`	常见	未代理提交 ENA	判为"无 INSDC 编号"，不等于无序列
`false`	`"confirmed": false`	22/300（7.3%）	未获多实验室确认	不能当缺失删掉，它是真实的质量信号
全零 / 恒值	`release_status` 恒为 `Sequence unchanged`	300/300	字段退化、无信息量	直接弃用该字段

第五种形态最阴险：它不是缺失，是伪造的完整性。一个字段只要有值，df.isna().sum() 就报 0，任何"缺失率体检"都会放它过去；但它的方差为 0，对模型毫无贡献，还会在特征重要性里抢位置。诊断方法很简单：

def audit_degenerate_fields(df, max_unique=1):
    """找出「全表同值」或「缺失率过高」的字段——前者是伪完整，后者是真缺失。"""
    report = []
    for col in df.columns:
        nunique = df[col].nunique(dropna=True)
        na_rate = df[col].isna().mean()
        if nunique <= max_unique:
            report.append((col, "DEGENERATE", nunique, round(na_rate, 4)))
        elif na_rate > 0.30:
            report.append((col, "HIGH_MISSING", nunique, round(na_rate, 4)))
    return sorted(report, key=lambda x: -x[3])

# 在 300 条抽样上的预期输出（示意）：
# [('release_status', 'DEGENERATE', 1, 0.0),
#  ('cwd', 'HIGH_MISSING', 9, 0.2033),
#  ('wmda', 'HIGH_MISSING', 194, 0.3533),
#  ('omim', 'HIGH_MISSING', 2, 0.90)]

§4.6 防御式解析代码

hla.dat 是 EMBL 风格的定宽+定前缀文本，不能用 pandas.read_csv 读（坑点 8）。下面是最小可运行的联表脚本，把四个文件合并成一张宽表：

# build_table.py —— 从 flat 文件构建等位基因宽表（无需 API，无需装 BioPython 也能跑）
import re, csv
from pathlib import Path

ROOT = Path("hla_3660")          # 解压后的目录

def load_allelelist(p):
    """Allelelist.txt：CSV 两列，前 6 行为 # 注释 + 1 行表头。"""
    rows = []
    with open(p, encoding="utf-8") as f:
        for i, line in enumerate(f):
            line = line.rstrip("\n")
            if not line or line.startswith("#"):
                continue
            parts = line.split(",")
            if len(parts) != 2 or parts[0] == "AlleleID":   # 跳过表头
                continue
            rows.append({"accession": parts[0].strip(), "name": parts[1].strip()})
    return rows

def load_groups(p):
    """hla_nom_g.txt / hla_nom_p.txt：分号分隔，前三列有效。"""
    m = {}
    with open(p, encoding="utf-8") as f:
        for line in f:
            if line.startswith("#") or not line.strip():
                continue
            cols = [c.strip() for c in line.split(";")]
            if len(cols) >= 2 and cols[0]:
                m[cols[0]] = cols[1]
    return m

def parse_name(name):
    """把 A*01:01:01:01N 拆成 locus / 四字段 / 后缀 / 命名层级。"""
    m = re.match(r"^([A-Z0-9]+)\*(\d+)((?::\d+)*)([NLSCAQ]?)$", name)
    if not m:
        return None
    locus, f1, rest, suffix = m.groups()
    fields = [f1] + [x for x in rest.split(":") if x]
    return {
        "locus": locus + "*",
        "group": f"{locus}*{f1}",
        "n_fields": len(fields),
        "suffix": suffix or "",
        "is_null": suffix == "N",
    }

alleles = load_allelelist(ROOT / "Allelelist.txt")
g_map = load_groups(ROOT / "wmda" / "hla_nom_g.txt")
p_map = load_groups(ROOT / "wmda" / "hla_nom_p.txt")

out = []
for a in alleles:
    meta = parse_name(a["name"])
    if meta is None:            # 命名异常记录单独留档，不要静默丢弃
        print("UNPARSED", a)
        continue
    out.append({**a, **meta,
                "g_group": g_map.get(a["name"]),
                "p_group": p_map.get(a["name"])})

print(f"解析 {len(out)} / {len(alleles)} 条")
print("四字段占比", round(sum(r['n_fields'] == 4 for r in out) / len(out), 4))
print("Null 占比", round(sum(r['is_null'] for r in out) / len(out), 4))

这段脚本的预期输出与实测一致：四字段占比 0.1995、Null 占比 0.0437。如果跑出来不是这两个数，说明版本不同或解析逻辑漏了某个分支——这两个数可以当作解析正确性的回归测试断言。

§5 检索、抽样与泄漏分析

§5.1 官方有没有划分？

没有，而且不应该有。IPD-IMGT/HLA 是命名参考库，不是评测基准；它不提供 train/valid/test，也不提供"任务标签"。但没有官方划分不等于划分问题简单——这里的泄漏比常规数据集更隐蔽，因为每个样本天生带血缘关系（同一基因座的等位基因互为进化祖先，同一位点的不同等位基因共享整段侧翼序列）。

§5.2 三种可用的抽样策略

策略	做法	适用任务	主要风险
按基因座留一（leave-one-locus-out）	训练用 HLA-A/B/C，测试用 DRB1 等	评估跨基因座泛化	不同基因座的序列长度与外显子数差异极大，指标会大幅下降——这是真实信号而非 bug
按等位基因组切分	同一 `group`（字段 1）整体进同一侧	HLA 分型、命名归一化	最贴近真实需求：临床上没人要求区分同组内成员
按命名层级切分	训练高分辨率（三/四字段），测试低分辨率	分辨率推断任务	低分辨率样本只有 312 + 26,354 条，且集中在常见型
按时间切分	用 3.63 及更早训练，3.66 新增的 773 条测试	模拟"预测未来新等位基因"	最严格，样本量小（773 条），只适合小规模验证
随机切分	—	不推荐	同组同座等位基因跨侧，指标虚高 10-30 个百分点

§5.3 泄漏风险（重点）

HLA 有四类结构泄漏，每一类都能让随机切分得到"看起来很好"的假结果：

第一类：G 组内泄漏（最严重）。 G 组把同义突变的等位基因合并为一组，同组成员的前三字段完全相同，核苷酸序列往往只差 1-3 个碱基。若 A*01:01:01:01 进训练、A*01:01:01:02 进测试，模型只要记住前缀就能"预测"——而这个能力在真实场景（遇到全新等位基因组）里毫无价值。实测中 G 组映射覆盖 55.3% 的样本，说明这类泄漏影响面过半。

第二类：历史名泄漏。 secondary_names 与 allele_history 记录了同一个等位基因的历史名字。一个在 2010 年被重命名的序列，可能在旧文献里以另一个名字出现；若你的数据集混合了新旧文献抽取结果，同一条序列会以两个样本的身份跨侧出现。

第三类：跨版本泄漏。 3.66 的 907 条变更中，132 条是 Modified（序列修订）、1 条 Deleted。若同时纳入 3.65 与 3.66 的数据，同一 accession 会出现两次，且内容几乎相同。

第四类：侧翼序列泄漏（最隐蔽）。 两个不同基因座的位置相邻（如 DRB1 与 DRB3），HLA 区域存在大量重复与重组。用滑动窗口做序列分类任务时，DRB1 的窗口可能包含 DRB3 的片段——这在数据层面看不出来，只能通过序列比对发现。

import re
from collections import defaultdict

def group_key_name(name: str) -> str:
    """把 A*01:01:01:01N 归并成 A*01:01 作为切分键。
    这是「等位基因组 + 字段2」粒度：同键样本必须同侧。
    """
    m = re.match(r"^([A-Z0-9]+)\*(\d+):(\d+)", name)
    return f"{m.group(1)}*{m.group(2)}:{m.group(3)}" if m else name

def assert_no_leak(train, test):
    g_tr = {group_key_name(r["name"]) for r in train}
    g_te = {group_key_name(r["name"]) for r in test}
    overlap = g_tr & g_te
    assert not overlap, f"等位基因组泄漏 {len(overlap)} 个，例：{list(overlap)[:3]}"
    a_tr = {r["accession"] for r in train}
    a_te = {r["accession"] for r in test}
    assert not (a_tr & a_te), f"accession 泄漏 {a_tr & a_te}"
    # 历史名检查：把 secondary_names 展开后不能跨侧
    def alias_set(rows):
        s = set()
        for r in rows:
            for a in str(r.get("secondary_names") or "").split(","):
                if a.strip():
                    s.add(a.strip())
        return s
    assert not (alias_set(train) & alias_set(test)), "历史名泄漏"

§5.4 交叉验证与自检建议

分组键用"基因座 + 字段 1 + 字段 2"，不要用完整的四字段名（那样等于随机切分）。
折数按基因座分层：I 类三座占 64%，若直接 5 折，某一折可能完全不含 DRB1 这类低频座。建议用 StratifiedGroupKFold，分层变量选 locus。
必须报告"跨基因座"与"同基因座"两组指标。二者差距就是模型的真实泛化能力；只报同基因座指标是自欺。
回归断言：任何一次切分后，四字段占比在两个子集内的差异应小于 2 个百分点，否则说明切分破坏了分辨率分布。

§5.5 外部验证建议

验证目标	外部数据源	为什么合适
HLA 分型算法泛化	1000 Genomes 项目的 HLA 分型结果	有真实人群二倍型，可与参照库互证
等位基因名归一化	临床 HLA 报告（不同实验室、不同分辨率）	真实世界的名字混用形态只有临床报告里有
人群频率结构	AFND（Allele Frequency Net Database）	提供 IPD 缺失的频率维度
跨物种命名一致性	IPD-MHC（非人灵长类等）	同一命名框架下的外部对照，可测解析器的鲁棒性
免疫肽组学	IEDB 的 HLA-配体记录	有实验验证的肽段-等位基因对应关系
与核酸库一致性	ENA 的 `insdc` 交叉编号	可验证 2026 年 brokering 后的序列是否逐字节一致

§6 AI 就绪指南

§6.0 云端快速启动

API 免鉴权，最小验证一条命令：

# 应输出 total=47622（2026-10-22 实测）
curl -s "https://www.ebi.ac.uk/cgi-bin/ipd/api/allele?limit=1" \
  | python3 -c "import sys,json;print('total =', json.load(sys.stdin)['meta']['total'])"

若你要的是全量而不是"按需查询"，正确选择是下载 flat 文件而不是遍历 API。理由见 §3.4：API 单条详情约 1.8 秒，全量需 24 小时以上，且并发会被断开（坑点 4）。

§6.1 快速上手：三条通道

# 通道 A：flat 文件（推荐，全量、可复现、有版本号）
BASE="https://ftp.ebi.ac.uk/pub/databases/ipd/imgt/hla"
for f in hla.dat.zip Allelelist.txt Allelelist_history.txt version_report.txt; do
  curl -sSL -O "$BASE/$f"
done
mkdir -p wmda && curl -sSL -o wmda/hla_nom_g.txt "$BASE/wmda/hla_nom_g.txt" \
                        -o wmda/hla_nom_p.txt "$BASE/wmda/hla_nom_p.txt"
unzip -o hla.dat.zip

# 通道 B：GitHub 镜像（要 git 历史时用；注意 LFS 陷阱，见坑点 6）
git clone --depth 1 https://github.com/ANHIG/IMGTHLA.git

# 通道 C：API（只需少量记录时用）
curl -s "https://www.ebi.ac.uk/cgi-bin/ipd/api/allele/HLA00001" | python3 -m json.tool | head -40

下载后先做三件事，不要急着建模：

wc -l Allelelist.txt                    # 减去注释与表头，应得 47,424
head -8 Allelelist.txt                  # 确认前 6 行注释 + 1 行表头
ls -la hla.dat                          # 应约 337 MB；若是 130 字节则是 LFS 指针

§6.2 数据获取：分页游标的正确用法

API 的分页不是页码制，而是不透明游标：meta.next 返回的是 ?limit=100&next=gASV... 这样的相对串，不是完整 URL，也不是页码。

# paginate.py —— 正确的游标翻页（含重试与退避）
import json, time, urllib.request, urllib.error

BASE = "https://www.ebi.ac.uk/cgi-bin/ipd/api/allele"

def fetch(url, retries=5, backoff=3.0):
    for i in range(retries):
        try:
            with urllib.request.urlopen(url, timeout=60) as r:
                return json.loads(r.read())
        except (urllib.error.URLError, TimeoutError, ConnectionError) as e:
            if i == retries - 1:
                raise
            time.sleep(backoff * (2 ** i))     # 指数退避：3s → 6s → 12s ...
    raise RuntimeError("unreachable")

def iter_alleles(page_size=100, max_pages=None):
    url = f"{BASE}?limit={page_size}"
    page = 0
    while url:
        data = fetch(url)
        for rec in data.get("data", []):
            yield rec
        page += 1
        nxt = (data.get("meta") or {}).get("next")
        if not nxt or (max_pages and page >= max_pages):
            break
        url = BASE + nxt          # ← 关键：拼绝对 URL，直接传 nxt 会抛 unknown url type
        time.sleep(0.2)           # 温和节流，避免被断开

# 用法：先只跑 3 页验证，再放开
for i, rec in enumerate(iter_alleles(max_pages=3)):
    if i < 3:
        print(rec["accession"], rec["name"], rec.get("status"))

⚠️ 注意 BASE + nxt 的拼接：BASE 是 https://www.ebi.ac.uk/cgi-bin/ipd/api/allele（不含 ?），而 nxt 以 ? 开头，正好拼成合法 URL。若你用的 BASE 末尾带了 ?，就会得到 ??limit=...。

§6.3 预处理全流程

# preprocess.py —— flat 文件 → 建模用 DataFrame（含质量过滤与归一化）
import re
import pandas as pd
from pathlib import Path

ROOT = Path("hla_3660")
NAME_RE = re.compile(r"^([A-Z0-9]+)\*(\d+)((?::\d+)*)([NLSCAQ]?)$")

def parse_rows(path):
    rows = []
    with open(path, encoding="utf-8") as f:
        for line in f:
            if not line.strip() or line.startswith("#"):
                continue
            parts = line.rstrip("\n").split(",")
            if len(parts) != 2 or parts[0] == "AlleleID":
                continue
            rows.append(parts)
    return rows

def to_frame(rows):
    recs = []
    for acc, name in rows:
        m = NAME_RE.match(name)
        if not m:
            recs.append({"accession": acc, "name": name, "parse_ok": False})
            continue
        locus, f1, rest, sfx = m.groups()
        n_fields = 1 + len([x for x in rest.split(":") if x])
        recs.append({
            "accession": acc, "name": name, "parse_ok": True,
            "locus": locus, "group": f"{locus}*{f1}",
            "n_fields": n_fields, "suffix": sfx or "none",
            "is_null": sfx == "N",
        })
    df = pd.DataFrame(recs)
    # 分辨率等级：0 冒号→血清型级，3 冒号→完整四字段
    df["resolution"] = df["n_fields"] - 1
    return df

df = to_frame(parse_rows(ROOT / "Allelelist.txt"))
assert len(df) == 47_424, f"行数异常: {len(df)}"          # 回归断言 1
assert abs((df.n_fields == 4).mean() - 0.1995) < 5e-4      # 回归断言 2
assert abs(df.is_null.mean() - 0.0437) < 5e-4              # 回归断言 3

# 分级：按基因座规模三档，供分层抽样使用
size = df.groupby("locus").size()
df["locus_tier"] = df["locus"].map(
    lambda x: "large" if size[x] >= 3000 else ("medium" if size[x] >= 300 else "small"))
print(df.groupby("locus_tier").agg(n=("name", "size"),
                                   full_res=("n_fields", lambda s: (s == 4).mean())))

这三个断言是刻意写成"会失败"的形式：任何一次重跑若版本变了，len(df) == 47_424 立刻报错，逼迫你显式更新版本号与文中数字，而不是让新旧数字悄悄混在一起。

§6.4 PyTorch DataLoader 完整实现

一个真实可跑的任务：给定 HLA 核酸序列片段，预测其所属基因座（30 类分类）。这个任务的价值不在精度，而在验证"一个解析器能否把四种格式的数据统一成张量"。

# hla_dataset.py —— 序列 → 基因座分类的最小可运行实现
import re, random
from pathlib import Path
import torch
from torch.utils.data import Dataset, DataLoader
from torch.nn.utils.rnn import pad_sequence

# k-mer 编码：(4^3)=64 维 one-hot 展平，比字符级 tokenizer 更稳
K = 3
BASE_IDX = {"A": 0, "C": 1, "G": 2, "T": 3}

def read_fasta(path):
    """极简 FASTA 解析；header 形如 '>HLA:HLA00001 A*01:01:01:01 350 bp'。"""
    name, buf = None, []
    with open(path, encoding="utf-8") as f:
        for line in f:
            line = line.rstrip("\n")
            if line.startswith(">"):
                if name:
                    yield name, "".join(buf)
                # 名字取第二个 token：'>HLA:HLA00001 A*01:01:01:01 ...' → 'A*01:01:01:01'
                toks = line[1:].split()
                name = toks[1] if len(toks) > 1 else toks[0]
                buf = []
            else:
                buf.append(line)
    if name:
        yield name, "".join(buf)

def kmer_encode(seq, k=K, max_len=600):
    """把序列编码成 (max_len-k+1, 4^k) 的 0/1 矩阵；未知碱基归入均匀分布。"""
    seq = re.sub(r"[^ACGT]", "N", seq.upper())[:max_len]
    idx = [BASE_IDX.get(c) for c in seq]
    dim = 4 ** k
    out = torch.zeros(max(len(idx) - k + 1, 1), dim)
    for i in range(len(idx) - k + 1):
        code, ok = 0, True
        for j in range(k):
            c = idx[i + j]
            if c is None:
                ok = False
                break
            code = code * 4 + c
        if ok:
            out[i, code] = 1.0
        else:
            out[i, :] = 1.0 / dim          # N 用均匀分布，避免伪造信号
    return out

class HLALocusDataset(Dataset):
    def __init__(self, fasta_path, locus_vocab, exclude_null=True):
        self.items = []
        for name, seq in read_fasta(fasta_path):
            m = re.match(r"^([A-Z0-9]+)\*", name)
            if not m:
                continue
            if exclude_null and name.endswith("N"):
                continue                    # 坑点 5 的同族问题：Null 等位基因无表达
            loc = m.group(1)
            if loc not in locus_vocab:
                continue
            self.items.append((kmer_encode(seq), locus_vocab[loc]))

    def __len__(self):
        return len(self.items)

    def __getitem__(self, i):
        return self.items[i]

def collate(batch):
    xs, ys = zip(*batch)
    xs = pad_sequence(xs, batch_first=True)          # (B, L, 64)
    return xs, torch.tensor(ys, dtype=torch.long)

# ── 按基因座分组切分：同座全部进同一侧，杜绝 §5.3 的组内泄漏 ──
def split_by_locus(records, test_ratio=0.2, seed=42):
    """records: [{"locus": "A", "name": "A*01:01", "seq": "ACGT..."}, ...]
    返回 (train_records, test_records)，同一 locus 只会出现在一侧。
    """
    rng = random.Random(seed)
    loci = sorted({r["locus"] for r in records})
    rng.shuffle(loci)
    n_test = max(1, int(len(loci) * test_ratio))
    test_loci = set(loci[:n_test])
    train = [r for r in records if r["locus"] not in test_loci]
    test = [r for r in records if r["locus"] in test_loci]
    assert not ({r["locus"] for r in train} & {r["locus"] for r in test}), "基因座跨侧泄漏"
    return train, test

# 使用示例
# vocab = {l: i for i, l in enumerate(sorted({...}))}
# ds = HLALocusDataset("hla_3660/hla_nuc.fasta", vocab)
# loader = DataLoader(ds, batch_size=32, shuffle=True, collate_fn=collate, num_workers=2)

这份代码里两处设计是刻意的：k-mer one-hot 而不是 tokenizer——HLA 序列只有 ACGT 四字母，词表 64 维足够，用 30 万词表的 BPE 只会拖慢训练；按基因座切分而不是随机切分——这是 §5.3 的直接落地。

§6.5 八个坑点

坑点 1：CC BY-ND 不是常规开放许可，禁改禁镜像

问题：多数 EBI 托管资源（ENA、UniProt、Ensembl）是 CC0 或 CC BY，团队按习惯认为"EBI 的东西随便用"。IPD-IMGT/HLA 是 CC BY-ND——署名 + 禁止演绎。
症状：把 HLA 序列与其他来源合并成"统一格式的衍生数据集"并对外发布，属于分发修改版，超出许可范围。更常见的隐性违规是镜像：官方明确反对建镜像站，要求改用链接。
解决：
1. 简单做法：只做内部使用 + 论文里引用，不对外分发衍生集。内部使用不受 ND 约束。
2. 进阶做法：若必须发布衍生集，先向 ipdsubs@anthonynolan.org 申请书面许可，并在数据卡里写明许可来源与申请编号。同时对"衍生"做保守解释——重新编码、重排字段、按基因座拆分都算。
3. SOTA 做法：把"许可校验"做成流水线的硬闸门：CI 里检查产出物是否包含逐字复制自 hla.dat 的序列块，若包含则要求许可凭证文件存在，否则阻断发布。
参考：LICENCE.md（4.9 KB，全文很短，值得逐字读一遍）

坑点 2：`&locus=` 过滤参数被静默忽略

问题：直觉认为 /api/allele?locus=B 会返回 HLA-B 座。实际不是。
症状：传 locus=B 后返回的 meta.total 仍是 47,622，首条记录仍是 A* 开头，不报错、不警告。你的脚本会以为"拿到了 B 座的 4.7 万条"，然后下游统计全错。
解决：
1. 简单做法：不要依赖服务端过滤。全量拉取后在本地按 locus 字段切片——反正 flat 文件才 948 KB。
2. 进阶做法：写一个"参数生效性自检"：请求时带过滤参数，比较返回的 total 与不带参数时的 total，若相同则判定该参数被忽略并记录告警。
3. SOTA 做法：为第三方 API 建"契约测试"（contract test），把每个声称支持的查询参数各测一遍，将"实际生效 / 静默忽略 / 报错"三种结果固化成测试用例；API 升级时自动发现行为变化。
参考：2026-10-22 实测，locus / release / gfe / project / dictionary 五个端点全部 404，仅 allele 与 cell 可用

坑点 3：`meta.next` 是相对游标，不是页码

问题：把 meta.next 当作"下一页页码"或"完整 URL"直接请求。
症状：urllib 抛 ValueError: unknown url type: '?limit=100&next=gASV...'；或某框架把它拼成 .../allele/?limit=... 得到空结果。
解决：
1. 简单做法：url = BASE + nxt，其中 BASE 必须不含结尾 ?。
2. 进阶做法：用 urllib.parse.urljoin 而非字符串拼接，并断言结果以 BASE 开头。
3. SOTA 做法：把游标当作不透明令牌——不解析、不构造、不缓存超过一次使用；同时为长任务实现"断点续爬"，把最后一次成功游标落盘，中断后从该游标恢复。
参考：§6.2 的 iter_alleles() 实现

坑点 4：并发请求被 `RemoteDisconnected` 断开

问题：想用 8 线程加速抓取 300 条详情。
症状：http.client.RemoteDisconnected: Remote end closed connection without response。服务端无文档化限流，但对并发敏感；串行 300 条约 9 分钟（≈1.8 s/条）。
解决：
1. 简单做法：串行 + time.sleep(0.2)，接受慢。全量详情本来就不该走 API（§3.4）。
2. 进阶做法：限并发到 2-3，加指数退避重试（3s → 6s → 12s），失败记录落盘以便续跑。
3. SOTA 做法：根本不用 API 做全量。下载 hla.dat.zip（43 MB）解压后本地解析，43 MB 的下载远快于 4.7 万次 HTTP 请求，且得到的是全字段而非 API 的子集。
参考：本次实测 8 线程首次请求即失败，改串行后稳定

坑点 5：`Deleted` 等位基因仍在 API 结果里

问题：以为 API 只返回有效记录。
症状：300 条抽样中有 13 条 status=Deleted（占 4.3%），且这些记录的 confirmation_status.confirmed 为 null。若不过滤，你会把已撤回的等位基因当成有效训练样本——它们往往正是"命名有误"或"与已有序列重复"的案例。
解决：
1. 简单做法：if rec["status"] != "Public": continue。
2. 进阶做法：不要丢弃，而是单独存为"负例池"。已删除记录的典型成因值得用于训练"命名质量判别器"；同时在数据卡里报告删除率。
3. SOTA 做法：把 deleted_alleles.txt（25 KB）纳入版本对照，每次升级时对比"本版新删除"与"本版恢复"，把撤回当作一个有时间维度的信号，而不是静态过滤条件。
参考：deleted_alleles.txt

坑点 6：Git LFS 指针陷阱——130 字节的"hla.dat"

问题：克隆 GitHub 仓库的历史 tag 以复现旧版本。
症状：hla.dat 只有 130 字节，内容是 version https://git-lfs.github.com/spec/v1 开头的指针文本。解析脚本读到 0 条记录却不报错（因为文本里确实没有 // 分隔符，循环直接结束）。3.55.0 及更早版本的 tag 都有这个问题。
解决：
1. 简单做法：git lfs install 后再 git lfs pull；或者干脆用 FTP 的 hla.dat.zip（2024-04 起 >100 MB 文件已改为普通 zip，不再用 LFS）。
2. 进阶做法：在加载器里加文件头校验——若文件小于 1 MB 或首行包含 git-lfs.github.com，直接抛异常。
3. SOTA 做法：所有外部数据入口统一走"尺寸 + 魔数 + 行数"三重断言，断言值写入配置并随版本号变更；把断言失败当作发布阻断条件，而不是日志警告。
参考：README.md 中关于 3.56.0 改用 zip 的说明

坑点 7：四字段全分辨率只占 20%，精确字符串匹配大面积失配

问题：假设等位基因名都是四字段形式，直接 df["name"] == "A*01:01:01:01" 做匹配。
症状：47,424 条中只有 9,461 条（20.0%） 是四字段；1 冒号形（A*01:01）多达 26,354 条（55.6%），0 冒号形 312 条。临床报告常写 A*02:01，而库里主记录是 A*02:01:01:01——精确匹配命中率为 0。
解决：
1. 简单做法：统一按前缀匹配，name.startswith(query)。
2. 进阶做法：建"分辨率感知"的索引：把库里每个名字按 0/1/2/3 冒号四种形态各生成一个键，形成 4 份字典。查询时按查询串的冒号数选对应字典，O(1) 命中，且能拿到"该低分辨率名对应多少个高分辨率成员"。
3. SOTA 做法：实现双向归一化 API——向上（把高分辨率折叠到请求的分辨率，返回候选集与每个候选的人群证据 cwd）、向下（把低分辨率展开为全部可能的高分辨率成员，附带 G 组/P 组语义）。这是移植配型系统里真正需要的形态。
参考：§2.3 的分辨率分布表；官方命名规则见 hla.alleles.org

坑点 8：`hla.dat` 是 EMBL 风格扁平文本，`read_csv` 必然失败

问题：把 hla.dat 当表格文件读。
症状：pandas.read_csv 报 ParserError，或"成功"读出一列几千行的乱码；Bio.SeqIO.parse(fmt="fasta") 也会失败（格式不匹配）。
解决：
1. 简单做法：用 Bio.SeqIO.parse("hla.dat", "imgt")，BioPython 内置了 IMGT/HLA 解析器。
2. 进阶做法：自己按两字母前缀解析（ID / AC / DE / FT / SQ / //），FT 行是定宽 21 列的子格式（key 占 2-21 列，location 与 qualifier 各有固定列），必须按列切而不能按空格切。
3. SOTA 做法：优先用派生格式——只要序列就用 fasta/，只要名字对照就用 Allelelist.txt，只要组映射就用 wmda/。hla.dat 是唯一含全部字段的格式，但你通常不需要全部字段。把"最小必要文件"写进流程文档，能省掉 337 MB 的解析开销与大部分格式坑。
参考：Manual.md（29 KB，FT 行格式在第 3 节）

§6.6 数据增强：安全与危险

序列数据的增强比表格数据危险得多，因为任何改变碱基的做法都在伪造生物学事实。

增强方式	判定	说明
反向互补（reverse complement）	✅ 安全	但只适用于双链无方向性任务；基因座分类可以用，外显子边界任务不能用
大小写统一 + 去空白	✅ 安全	`hla.dat` 中小写表示重复区（低复杂度），统一成大写会丢信息，应另存一个 `is_repeat` 掩码
截断到固定长度	✅ 安全	常见做法；注意别截掉 exon 2/3（I 类抗原结合槽所在）
滑动窗口切片 + 标签继承	✅ 安全	提升样本量；但窗口跨侧切分时必须按原等位基因分组，否则造成 §5.3 第一类泄漏
随机掩码（BERT 风格 15% N）	⚠️ 谨慎	可提升鲁棒性；HLA 高度多态，掩掉关键多态位点会破坏标签，建议只掩非多态位点
同义密码子替换	❌ 危险	形式上是"同义"，但 HLA 的稀有密码子影响翻译效率，已被证明与表达水平相关
随机点突变造"新等位基因"	❌ 危险	生成的等位基因不存在，任何"泛化到新等位基因"的结论都是自证
序列混洗（shuffle）作为负样本	⚠️ 谨慎	只适合"是否为人 HLA"这类粗任务；混洗后仍保留碱基组成，对基因座分类是无效负样本
用 G 组扩充样本（把同组成员视为独立样本）	❌ 危险	这正是要把它们整体切分的原因（§5.3），拿来扩充等于主动引入泄漏

§6.7 模型推荐

任务	推荐方案	理由
基因座分类（30 类）	CNN（k-mer one-hot 输入）+ 全局池化	序列短（数百 bp）、标签少，CNN 已足够；Transformer 在此规模上收益不明显
分辨率推断（低分辨率 → 高分辨率候选）	检索式：精确索引 + 排序	本质是查表问题，用模型生成会编造不存在的等位基因名
等位基因名归一化	规则引擎 + 字典（§6.3）	规范明确，规则覆盖率接近 100%；模型只用于兜底异常串
分型算法（读长 → 二倍型）	比对优先（minimap2/BWA）+ EM 定量	主流工具（OptiType、arcasHLA 类）都走这条路线，深度学习不是首选
序列质量判别（是否完整/是否可信）	梯度提升树 + 元数据特征	`sequence_status`、`confirmation_status`、`cwd` 都是强特征，规则可解释
免疫肽结合预测	专用模型（NetMHCpan 系）	需要训练数据（IEDB 的亲和力测定），IPD 只提供等位基因序列

一条明确的反建议：不要试图用 LLM 生成 HLA 等位基因名或序列。命名受 WHO 委员会严格约束，任何生成的名字都是虚构的，会污染下游数据库。

§6.8 硬件需求

场景	最低配置	推荐配置	说明
下载 + 解压全部文件	2 核 / 4 GB / 5 GB 磁盘	4 核 / 8 GB / 20 GB	解压后约 1.2 GB，留 3 倍余量
解析 hla.dat（337 MB）	4 核 / 8 GB / 10 GB	8 核 / 16 GB / 50 GB	BioPython 逐条解析约数分钟；全量对象化到内存约 3-6 GB
基因座分类训练	单卡 8 GB 显存 / 32 GB 内存	单卡 24 GB 显存 / 64 GB 内存	k-mer 张量比原始序列占内存，按 (L, 64) 估算
全量 API 抓取	—	不推荐	串行需 24 小时以上；改用 flat 文件
比对建索引（alignments/）	4 核 / 16 GB	16 核 / 64 GB	13 MB 压缩包解压后按基因座分文件，单座比对可上万条序列

§6.9 评估指标代码

# eval_metrics.py —— 序列分类的全套指标 + 分组自检
import numpy as np
from sklearn.metrics import (f1_score, precision_recall_fscore_support,
                             top_k_accuracy_score, confusion_matrix)

def report(y_true, y_pred, y_prob=None, groups=None, k=3):
    p, r, f, _ = precision_recall_fscore_support(y_true, y_pred, average="macro", zero_division=0)
    out = {
        "macro_f1": round(f1_score(y_true, y_pred, average="macro", zero_division=0), 4),
        "micro_f1": round(f1_score(y_true, y_pred, average="micro", zero_division=0), 4),
        "macro_precision": round(p, 4),
        "macro_recall": round(r, 4),
        "n": int(len(y_true)),
    }
    if y_prob is not None:
        out[f"top{k}_acc"] = round(float(top_k_accuracy_score(
            y_true, y_prob, k=k, labels=list(range(y_prob.shape[1])))), 4)
    if groups is not None:
        # 按基因座报告：跨座泛化能力才是真本事（§5.4）
        per = {}
        for g in sorted(set(groups)):
            m = np.asarray(groups) == g
            if m.sum() >= 5:
                per[g] = round(f1_score(np.asarray(y_true)[m], np.asarray(y_pred)[m],
                                        average="macro", zero_division=0), 3)
        out["per_locus_f1"] = dict(sorted(per.items(), key=lambda x: x[1])[:5])
        out["worst_locus_f1"] = min(per.values()) if per else None
    out["confusion"] = confusion_matrix(y_true, y_pred).tolist()
    return out

def bootstrap_ci(y_true, y_pred, metric_fn, n_boot=1000, alpha=0.05, seed=42):
    """自助法 CI——小样本的 HLA 子集评估必做，单点数字不可信。"""
    rng = np.random.default_rng(seed)
    yt, yp = np.asarray(y_true), np.asarray(y_pred)
    vals = []
    for _ in range(n_boot):
        idx = rng.integers(0, len(yt), len(yt))
        try:
            vals.append(metric_fn(yt[idx], yp[idx]))
        except ValueError:
            continue
    lo, hi = np.percentile(vals, [100 * alpha / 2, 100 * (1 - alpha / 2)])
    return round(float(lo), 4), round(float(hi), 4)

per_locus_f1 与 worst_locus_f1 是这段代码的重点：HLA 的 30 个基因座规模差三个数量级（B 座 11,328 条 vs T 座 9 条），只看宏平均会被大类主导，必须看最差基因座。"最差座 F1 = 0.1"这种结果才是真实状况，而它恰恰是最该报告的数字。

§6.10 MLOps 笔记

环节	关键动作	IPD-IMGT/HLA 特有注意
数据版本	记录 `release_version`（如 3.66.0）与 `release_date`	季度发布，模型上线超过 3 个月就该考虑重训；版本号必须写进模型卡
快照一致性	flat 文件与 API 混用会得到两套数字	一篇论文/一个模型只能用一个口径，且在方法学里写明
溯源	每个训练样本保留 `accession`	accession 永不复用，是最可靠的溯源键
许可记录	模型卡里写明 CC BY-ND 与"是否分发衍生数据"	模型权重通常不构成"对原数据的演绎"，但训练集快照的再分发构成，需申请
监控	监控新发布版本的 `Deleted` 数与 `Modified` 数	删除率突然升高说明命名规则可能调整，模型标签会漂移
增量更新	用 `version_report.txt` 做差分，不要全量重下	907 行 vs 337 MB，差三个数量级
失败重跑	用 `Allelelist_history.txt` 重建历史时点	28 MB 存了每次发布的全量，是唯一的时点重建材料

§7 质量评估与局限性

§7.1 已知偏倚

偏倚类型	描述	严重程度	缓解
发现偏倚（最核心）	只有被提交的序列才进入库；提交动力来自临床需求与发表需求，而非人口代表性	高	把"库内条数"当作"发现强度"而非"真实多样性"；写论文时显式声明
基因座偏倚	B/C/A 三座占 64.0%，其余 30 余座共 36%	高	按基因座分层报告；低频座单独说明样本量
分辨率偏倚	四字段全分辨率仅 20.0%，1 冒号形占 55.6%	高	明确任务需要哪种分辨率；不要假设全库都高分辨率
人群代表偏倚	提交集中在欧洲、东亚、北美的大注册库	中	用 `cwd` 字段的人群标记做加权；无标记者不可假定为"全球代表"
确认等级偏倚	单实验室确认占 10%，未确认占 7.3%	中	用 `confirmation_status.laboratories` 做质量权重
时间偏倚	老记录引用少、组映射缺失多、命名法更旧	中	时间切分验证时注意老数据特征分布不同
表达偏倚	Null 等位基因 4.37%，但分布极不均匀（某些座显著更高）	低-中	按座统计 Null 率；不要把"库内 Null 率"当疾病人群频率

§7.2 元数据质量实证

300 条详情抽样的实测结果（2026-10-22，API 前 300 条，全为 HLA class I）：

指标	结果	解读
`status`	Public 287 / Deleted 13	4.3% 已撤回，必须过滤（坑点 5）
`confirmation_status.confirmed`	True 265 / False 22 / None 13	None 恰好对应 Deleted 记录，语义自洽
确认实验室数	1 家 30（10.0%）/ 2 家 31 / 3 家 43 / 4 家 41 / 5 家 49 / 6 家 29 / 7 家 34 / 8 家 14	单实验室是最大单一群体之一，多实验室确认并非普遍
`wmda.G_group` 有值	166/300（55.3%）	近一半记录未分组
`wmda.P_group` 有值	194/300（64.7%）	P 组覆盖高于 G 组
`cwd.version_3` 为 null	61/300（20.3%）	五分之一记录无"常见且充分记录"人群数据
`release_status`	300/300 = `Sequence unchanged`	字段退化，无信息量（§4.5 第五形态）
特征类型计数	exon 1,931 / intron 1,670 / 3’UTR 251 / 5’UTR 250	每条记录平均 6.4 个 exon、5.6 个 intron

这份抽样有一个必须声明的局限：API 默认按 accession 升序返回，前 300 条全部是 class I，且是 1998-2000 年最早入库的一批。它们不能代表全库——尤其不能代表 2020 年后 NGS 时代入库的记录（那些更可能是"部分序列"而非"全基因序列"）。引用这些比例时必须写明抽样范围。

§7.3 泛化性风险

风险	场景	后果	对策
跨人群泛化	用欧洲为主的库训练的分型算法用于非洲人群	漏检率高（非洲人群 HLA 多样性最高，库内覆盖最少）	用 1000 Genomes 非洲样本做外部测试
跨基因座泛化	用 A/B/C 训练的模型用于 DRB1	序列长度与外显子结构差异导致精度骤降	按座独立训练或显式加入座特征
跨分辨率泛化	训练用四字段，部署时输入 `A*02:01`	输入分布偏移，需前缀归一化	部署前做输入分辨率普查
跨版本泛化	模型训练于 3.63，部署于 3.66	773 个新等位基因未见过	每季度增量微调或至少回归测试
跨命名法泛化	处理 2010 年前的文献名（`A*01010101`）	旧命名法无冒号	用 `previous_nomenclature` 建映射表
跨物种泛化	移植到 IPD-MHC（非人灵长类）	命名框架相同但内容不同	解析器可复用，模型需重训

§7.4 伦理与治理

HLA 数据本身不涉及个人隐私——它记录的是等位基因，不是某个人的基因型。但有三条治理红线：

HLA 型别具有人群推断能力。某些等位基因频率在人群间差异极大，理论上可结合其他信息做祖先推断。虽然 IPD-IMGT/HLA 不含个体数据，但把你的输出（等位基因名）与其他数据关联可能产生群体归因，需在伦理审查中说明。
移植配型场景的算法责任。任何声称可辅助配型的模型都必须按医疗器械监管（中国 NMPA、欧盟 IVDR）注册，参照库本身不能替代临床验证。
禁止用库内容训练"生成新 HLA 序列"的模型。CC BY-ND 禁止演绎；且生成不存在的序列在医学上没有正当用途，只有滥用空间。

治理层面值得注意的是：这个库由 Anthony Nolan Research Institute（慈善机构）+ EMBL-EBI（政府间组织）+ WHO 命名委员会（专业共同体） 三方共治，没有单一商业实体可以单方面改变规则。这是它 28 年保持稳定的制度原因，也是它难以快速转向新需求（如 API 现代化）的制度成本。

§7.5 公平性

维度	现状	影响
人群覆盖	提交集中在有大注册库的地区（欧洲、东亚、北美）	少数民族与低资源地区的等位基因发现滞后，直接导致这些人群移植配型更难找到全合供者
命名语言	全英文，命名规则文档也仅英文	非英语地区的临床实验室理解成本更高
工具可得性	API 与文件免费，但解析需要编程能力	小实验室常依赖商业软件，间接推高成本
确认资源	多实验室确认需要细胞系共享与测序成本	资源少的实验室提交的记录更可能单实验室确认

公平性在这里有一个具体而沉重的现实后果：库的覆盖结构直接映射到临床上"谁能找到配型"。这不是抽象的算法公平问题，而是移植机会的分配问题。任何用这个库做配型相关研究的团队，都应在论文里报告所选等位基因的人群来源结构。

§7.6 数据漂移

漂移类型	表现	监测方法
规模漂移	每季度 +400 至 +800 个等位基因	记录每次 `Allelelist.txt` 行数，画增长曲线
结构漂移	新入库记录更可能是部分序列（NGS 短读）	统计 `sequence_status.full` 为 true 的比例随时间变化
命名漂移	名字会因合并、拆分、重命名而变	对比 `Allelelist_history.txt` 两个版本的名字集合差
格式漂移	2024-04 弃用 LFS 改 zip；`FT` 行格式曾调整	订阅 `testing` 分支 diff（§3.7）
字段漂移	字段实际退化（`release_status`）或新增	每次升级跑 `audit_degenerate_fields`（§4.5）
元数据漂移	`cwd` 缺失率可能随人群更新而变化	季度统计缺失率，超过 25% 触发复核

漂移监测的最小实现：把每个版本的六个统计量（总条数、四字段占比、Null 占比、cwd 缺失率、G 组覆盖率、Deleted 数）存成一行 CSV，季度更新。这张表比任何单篇文档都更能说明库的真实状态。

§7.7 DAIMS 24 项评估

#	检查项	状态	说明
1	宽格式	⚠️	扁平文件是长记录制，派生 FASTA 是序列制，XML 才有完整结构化；无单一"宽表"视图
2	唯一标识	✅	`accession`（HLA 编号）永不复用，是教科书级的稳定主键；另有 ISO OID 命名空间
3	特殊字符	✅	名字受控字符集（A-Z、0-9、`*`、`:`），无空格与编码问题；`FT` 行定宽可控
4	重复行	✅	命名机制本身保证唯一：同一序列不能有两个名字，重复会被合并进 `secondary_names`
5	缺失编码	⚠️	缺失形态不统一（`null` / `""` / `[]` / `false` 四种语义），无显式缺失码表（§4.5）
6	标签标识	✅	标签就是官方等位基因名，定义权威且带完整层级语义；`status` 明确区分有效/撤回
7	罕见类分组	✅	基因座、等位基因组、G 组、P 组四层分组齐备，罕见类可被显式识别
8	偏倚评估	❌	官方不提供偏倚评估；本条目 §7.1 为编辑部实测补充
9	数据字典	✅	`Manual.md` + API 字段 + 命名规则文档三件套，字段含义明确到可比对
10	信息性缺失解释	❌	不区分缺失成因（未分组 / 未确认 / 未代理提交），需使用者自行推断
11	设备记录	⚠️	`cell_entries` 与 `citations` 可间接溯源到实验室，但无测序平台/仪器的结构化字段
12	共线性	❌	不做任何变量相关性或序列冗余度检查
13	编码映射	✅	ENA/GenBank（`insdc`）、OMIM、PubMed、ISO OID、血清学名五套映射齐备
14	时间戳处理	⚠️	五个日期字段（`date_assigned`/`date_modified`/`first_release`/`release_date`）标准，但无时区声明
15	划分建议	❌	不提供 train/test 划分（§5.1），也不应提供
16	泄漏讨论	⚠️	官方文档提示"同组等位基因高度相似"，但未系统化描述泄漏类型；本条目 §5.3 补足四类
17	标签分布	✅	基因座分布、分辨率分布、Null 率均可从 flat 文件全量统计，且官方发布增长表
18	测量偏倚	⚠️	`confirmation_status` 提供了确认等级，但不做测量一致性分析
19	外部验证建议	❌	无（官方不需要；使用者需自建，见 §5.5）
20	版本记录	✅	季度版本 + `version_report.txt` + `Allelelist_history.txt` + `sversion_history.txt`，可重建任意历史时点
21	预处理脚本	❌	官方提供格式说明但不提供参考实现；BioPython 的 `imgt` 解析器是社区产物
22	合规要求	✅	`LICENCE.md` 明确 CC BY-ND、明确强制引用清单、明确禁止镜像、明确专利免责；合规链条完整
23	多模态对齐	⚠️	同一等位基因的核酸/蛋白/特征/细胞系通过 `accession` 天然对齐，但跨库（ENA/PDB）对齐不成体系
24	去标识化	✅	不含患者级数据；细胞系以公开细胞名标识，无供者身份

DAIMS 评分：✅ 10 项 × 1.0 = 10.0；⚠️ 8 项 × 0.5 = 4.0；❌ 6 项 × 0 = 0；合计 14.0 / 24。

评分解读：14.0/24 在"参考型数据库"里属于中上，显著高于通用存储库（Dryad 11.0），低于精心设计的临床队列数据集（MIMIC-IV 类通常 20+）。分数结构很典型：✅ 集中在标识、标签语义、分组、字典、版本、合规这六个"登记册型强项"；❌ 集中在偏倚评估、共线性、划分建议、外部验证、预处理脚本这五个"建模型职责"。

这个分布说明一件事：IPD-IMGT/HLA 把自己定位为命名与序列的权威登记册，而不是建模就绪的数据集。它的 47,424 条记录之所以可信，正因为每一件"建模该做的事"（划分、泄漏控制、偏倚评估）都留给了使用者——如果它替你做，反而会因为不了解你的任务而做错。

对你意味着什么：

唯一标识与版本记录是它最值钱的两项。做可复现研究时，accession + release_version 的组合足以精确定位任何一条记录的任何时点状态。
标签语义高度可靠，标签分布必须自己算。名字的定义权威无可质疑，但"哪些名字占多数"这种统计它只给年度增长表，细分维度要自己跑。
不要把 CC BY-ND 当小事。这是 24 项里唯一可能让你项目停摆的合规项。
14.0/24 的短板全部是"你的活"。想把这份库用于建模，§5 的泄漏控制与 §6 的解析管线必须自己搭，且必须写进方法学。

§7.8 外部验证矩阵

口径/来源	数字	与本文主口径的关系	关键发现
`Allelelist.txt` 实数（3.66.0，2026-10-14）	47,424	本文主口径	与官方增长表完全一致，可作为可复现基线
API `meta.total`（2026-10-22）	47,622	+198（+0.42%）	差异来自发布后增量入库与 API 计入 `Deleted`；两口径并存合理，不可混用
官方增长表 3.66 component entries	83,680	序列条目数，非名字数	一个等位基因可对应多条序列视图（genomic/coding/protein）
官方增长表 3.65 / 3.64 / 3.63	46,652 / 46,005 / 44,876	季度增速 +772 / +647 / +1,129	增速不均匀，与提交活跃度相关，不能线性外推
NAR 2026 论文摘要	“>43,000”（47 个基因）	论文投稿时点口径	论文用保守表述；引用论文时照抄，不要换算成 47,424
1998 首版	964	28 年增长约 49 倍	年均复合增长率约 14.7%，可用来校验任何"历史数字"的合理性
本次 300 条抽样（class I 前段）	`locus` 分布与全库一致（A/B/C 占绝对多数）	抽样校验通过	确认 API 返回顺序为 accession 升序，抽样偏早期但座结构正确
`version_report.txt` 3.66	907 行 = New 773 + Modified 132 + Suffix 1 + Deleted 1	与 47,424 − 46,652 = 772 的差异	772 是净增（773 新 − 1 删除），与变更表自洽

说明：IPD-IMGT/HLA 是命名登记册而非基准数据集，不存在"某模型在此库上达到 X 准确率"这类外部验证。上表做的是规模口径与变更账目的交叉核对——这属于数据治理层面的验证，不是模型性能验证。任何把这类核对写成"性能提升"的表述都是口径滥用。

§8 生态与影响

§8.1 在数据生态中的位置

                    上游（原始序列）
        ┌──────────────┬──────────────┐
        │  ENA（欧洲）  │ GenBank（美国）│  ← 2026 起 brokering 自动同步
        └──────┬───────┴──────┬───────┘
               ↓              ↓
        ┌──────────────────────────┐
        │  IPD-IMGT/HLA（命名）      │  ← 本条目
        │  47,424 等位基因 / 30+ 座  │
        └───┬────────┬────────┬────┘
            ↓        ↓        ↓
    ┌───────────┐ ┌──────┐ ┌────────────┐
    │ 分型软件   │ │配型  │ │ 研究参照   │
    │ OptiType  │ │系统  │ │ 免疫肽组学 │
    │ arcasHLA  │ │WMDA  │ │ 群体遗传学 │
    └───────────┘ └──────┘ └────────────┘
            ↓        ↓        ↓
        ┌──────────────────────────┐
        │  下游互补资源              │
        │  AFND（频率）IEDB（肽）    │
        │  IPD-MHC（跨物种）        │
        └──────────────────────────┘

它处在"上游核酸库"与"下游应用"之间的规范性中间层：上游记录"某实验室测了什么序列"，它记录"这条序列叫什么名字"。这个位置使它无法被上游替代（ENA 不做命名），也无法被下游替代（分型软件依赖命名，不定义命名）。

§8.2 选型建议

你的需求	该用什么	不该用什么
拿到全部 HLA 等位基因序列	flat 文件 `hla_gen.fasta` / `hla_nuc.fasta`	❌ 遍历 API（24 小时以上）
做 HLA 分型算法参照集	`fasta/` + `wmda/` + `Allelelist.txt`	❌ 只用 `hla.dat`（337 MB 解析慢）
做等位基因名归一化	`Allelelist.txt` + `Allelelist_history.txt`	❌ 用 API 逐条取（慢且含 Deleted）
移植配型相关研究	`wmda/hla_nom_g.txt` + `wmda/hla_nom_p.txt`	❌ 自己按前缀算 G 组（历史残留不服从规则）
人群频率分析	AFND + 本库的 `cwd`	❌ 把本库条数当频率
免疫肽组学	`hla_prot.fasta` + IEDB	❌ 只用本库（缺实验测定的结合数据）
单条记录详查	`/api/allele/{accession}`	❌ 下载 337 MB 只为看一条
复现旧版本分析	`Allelelist_history.txt` + GitHub tag（配 git-lfs）	❌ 用裸 GitHub tag（坑点 6）

§8.3 使用协议与评测方法

虽然没有官方评测，但这个领域已经形成了事实上的评测惯例。要让你的结果可被同行比较，建议按以下四条报告：

参照库快照：写明 release_version + release_date + 数据来源（flat / API）。三缺一即不可复现。
等位基因集：写明是全部 47,424 还是某一子集（如"四字段全分辨率 + status=Public + I 类三座"，约多少条）。
测试集来源：1000 Genomes、GIAB、某个注册库的真实分型数据，还是合成数据。合成数据必须说明生成方式。
指标定义：HLA 分型领域的标准指标是"二倍型准确率"（两等位基因都对）、“单等位基因准确率"与"错配数”。只报"序列相似度"没有可比性。

平台	链接	与本库的关系
官方主页	https://www.ebi.ac.uk/ipd/imgt/hla/	入口、文档、提交
FTP	https://ftp.ebi.ac.uk/pub/databases/ipd/imgt/hla/	全量文件
GitHub 镜像	https://github.com/ANHIG/IMGTHLA	版本追溯、testing 分支
命名与统计站	https://hla.alleles.org	命名规则、季度增长表
AFND	http://www.allelefrequencies.net	人群频率（本库缺的维度）
IEDB	https://www.iedb.org	免疫肽与表位（本库缺的实验数据）
IPD-KIR	https://www.ebi.ac.uk/ipd/kir/	姊妹库，KIR 基因
IPD-MHC	https://www.ebi.ac.uk/ipd/mhc/	跨物种 MHC
dbMHC（归档）	https://www.ncbi.nlm.nih.gov/gv/mhc/	历史频率资源，已停更
ENA	https://www.ebi.ac.uk/ena/	上游核酸库，通过 `insdc` 互跳

§8.5 关键文献与官方材料

文献	用途	链接
Barker et al., NAR 2026;54(D1):D1152-D1158	现行必引（新版提交工具）	doi:10.1093/nar/gkaf1218
Robinson et al., HLA 2024;103(6):e15549	必引（命名体系与库介绍）	doi:10.1111/tan.15549
Robinson et al., Tissue Antigens 2000;55:280-287	必引（首版论文）	doi:10.1034/j.1399-0039.2000.550314.x
Marsh et al., 命名规则系列（hla.alleles.org）	四字段命名语义	https://hla.alleles.org/nomenclature/naming.html
Robinson et al., IPD 系列综述	理解 IPD 家族设计	https://www.ebi.ac.uk/ipd/
Manual.md	文件格式权威说明（`FT` 行等）	https://ftp.ebi.ac.uk/pub/databases/ipd/imgt/hla/Manual.md

§8.6 社区与治理活跃度

维度	现状	评估
发布节奏	严格季度（1/4/7/10 月），28 年未断	✅ 极高
版本可追溯	每版全量列表 + 变更表 + 序列版本史	✅ 极高
文档完备度	有 Manual、README、LICENCE、API、命名规则站	✅ 高（API 文档偏薄）
接口现代化	2026 换新提交工具；REST API 字段少、无过滤	⚠️ 中（API 明显落后于 flat 文件能力）
社区反馈渠道	GitHub issue 可用，但响应不固定	⚠️ 中
治理结构	Anthony Nolan + EMBL-EBI + WHO 委员会三方	✅ 稳定，但决策慢
许可友好度	CC BY-ND（禁改禁镜像）	⚠️ 在 EBI 家族里偏严

§8.7 生态资源快照

类别	数量/状态
基因座	30 余个（含假基因与低频座）
等位基因	47,424（3.66.0 flat 口径）
序列条目	83,680 component entries
细胞系记录	78,489（`/api/cell` 的 `total`）
文件格式	10 类（dat / fasta / alignments / msf / xml / pir / oid / tce / wmda / JSON）
历史版本	自 1998 起的全部版本可在 GitHub 与 FTP 获取（带 LFS 注意事项）
引用论文	3 篇强制引用 + 多篇命名规则文献

§9 相关资源与引用

§9.1 官方资源

资源	链接	用途
数据库主页	https://www.ebi.ac.uk/ipd/imgt/hla/	总入口
About 页	https://www.ebi.ac.uk/ipd/imgt/hla/about/	历史、资助、技术栈
版本发布说明	https://www.ebi.ac.uk/ipd/imgt/hla/release/v366/	3.66.0 变更摘要
提交入口	https://www.ebi.ac.uk/ipd/imgt/hla/submit/	2026 新版提交工具
引用页	https://www.ebi.ac.uk/ipd/imgt/hla/about/citations/	强制引用清单
FTP 根	https://ftp.ebi.ac.uk/pub/databases/ipd/imgt/hla/	全量文件
LICENCE.md	https://ftp.ebi.ac.uk/pub/databases/ipd/imgt/hla/LICENCE.md	许可原文（必读）
Manual.md	https://ftp.ebi.ac.uk/pub/databases/ipd/imgt/hla/Manual.md	格式权威说明
GitHub	https://github.com/ANHIG/IMGTHLA	版本追溯、`testing` 分支
命名与统计	https://hla.alleles.org/pages/genes/statistics	季度增长表
命名规则	https://hla.alleles.org/nomenclature/naming.html	四字段与后缀定义

§9.2 引用格式

数据库级引用（官方要求三篇同引）：

@article{barker2026ipd,
  title   = {The IPD-IMGT/HLA database: recent developments in sequence submission},
  author  = {Barker, Dominic J and Natarajan, Richard H L and Cooper, Michael A and
             Hopper, Sebastian J F and Yates, Andrew D and Parham, Peter and
             Marsh, Steven G E and Robinson, James},
  journal = {Nucleic Acids Research},
  volume  = {54}, number = {D1}, pages = {D1152--D1158}, year = {2026},
  doi     = {10.1093/nar/gkaf1218}
}

@article{robinson2024ipd,
  title   = {IPD-IMGT/HLA Database},
  author  = {Robinson, James and Barker, Dominic J and Georgiou, Xenia and
             Cooper, Michael A and Flicek, Paul and Marsh, Steven G E},
  journal = {HLA},
  volume  = {103}, number = {6}, pages = {e15549}, year = {2024},
  doi     = {10.1111/tan.15549}
}

@article{robinson2000imgt,
  title   = {The IMGT/HLA database},
  author  = {Robinson, James and Malik, A and Parham, Peter and
             Bodmer, Julia G and Marsh, Steven G E},
  journal = {Tissue Antigens},
  volume  = {55}, number = {3}, pages = {280--287}, year = {2000},
  doi     = {10.1034/j.1399-0039.2000.550314.x}
}

快照级引用（可复现研究必须写版本）：

@misc{ipd_imght_hla_3660,
  title        = {IPD-IMGT/HLA Database, release 3.66.0},
  author       = {{Anthony Nolan Research Institute and EMBL-EBI}},
  year         = {2026},
  howpublished = {EMBL-EBI FTP},
  note         = {Release date 2026-10-14; 47,424 alleles; accessed 2026-10-22;
                  licensed CC BY-ND},
  url          = {https://ftp.ebi.ac.uk/pub/databases/ipd/imgt/hla/}
}

§9.3 引用指南

三篇必引。CC BY-ND 的署名义务在 LICENCE.md 里明确列出了这三篇；只引最新一篇不满足要求。
写版本号与发布日期。IPD-IMGT/HLA 每季度变，不写版本的分析无法复现。推荐格式：IPD-IMGT/HLA 3.66.0 (2026-10-14)。
写规模口径。若你在方法学里写了"47,424 个等位基因"，说明来源是 3.66.0 的 Allelelist.txt；若写 47,622，说明是 API 快照。二选一并保持一致。
不要引 NAR 摘要里的 “>43,000” 当"当前规模"。那是投稿时点数字，引用时照抄原文，不要改写成 47,424。
写访问日期。API 快照尤其需要，因为它不落在任何版本号上。
商业使用请考虑资助。官方在 LICENCE 里明确请求商业使用者考虑资助数据库运营。

§9.4 常见误用速查

误用	后果	正确做法
用 `&locus=` 过滤拉数据	拿到全库当单座，统计全错（坑点 2）	全量下载后本地切片
直接请求 `meta.next`	`unknown url type` 报错（坑点 3）	`BASE + next` 拼绝对 URL
8 线程抓 300 条详情	`RemoteDisconnected`（坑点 4）	串行 + 退避，或改用 flat 文件
不过滤 `status=Deleted`	4.3% 已撤回记录混入训练（坑点 5）	显式筛 `Public`
裸克隆旧 GitHub tag	得到 130 字节 LFS 指针，读到 0 条不报错（坑点 6）	`git lfs pull` 或直接用 FTP zip
精确匹配四字段名	命中率 0，因为 80% 记录不是四字段（坑点 7）	前缀匹配 + 分辨率索引
`pd.read_csv("hla.dat")`	`ParserError`（坑点 8）	`SeqIO.parse(fmt="imgt")` 或派生格式
把库当频率表	结论完全错误	频率去 AFND
随机切分训练/测试	同 G 组等位基因跨侧，指标虚高（§5.3）	按基因座 + 等位基因组切分
分发"标准化后的 HLA 数据集"	违反 CC BY-ND 禁止演绎	先申请许可（坑点 1）
把 NAR 摘要 “>43,000” 当当前规模	规模低报 10%	用 3.66.0 的 47,424
认为 API 与 flat 文件数字一致	差 198 条，无法解释	明确单一口径并写明来源

§10 AI 使用声明卡

10.1 AI 模型列表

用途	模型/工具	说明
事实检索与交叉核对	联网检索工具	定位官方发布说明、命名规则文档、NAR 论文、增长表
接口实测	本机 HTTP 客户端（curl / urllib）	直连 `/cgi-bin/ipd/api/`，47,622 与 78,489 两个 total 由实测取得
全量文件统计	Python 3.11 脚本	`Allelelist.txt` 47,424 行全量统计 locus 分布、命名层级、Null 率
变更明细统计	Python 3.11 脚本	`version_report.txt` 907 行分类计数
稿件撰写与结构化	大语言模型辅助	在编辑部规范下生成初稿，逐节人工修订

10.2 AI 参与范围

AI 参与：资料检索、章节结构、代码示例编写与调试、表格生成、语言润色。
人工完成：四套规模口径的取舍与并列方式、8 个坑点的实证核对与筛选（只保留有实测或一手文档依据的）、DAIMS 24 项逐项定性、偏倚与伦理判断、全部数字的最终核对。
AI 未参与：任何原始数据的采集与加工；本条目不包含任何由模型生成的"HLA 等位基因名"或"序列"。

10.3 输入来源列表

EMBL-EBI. IPD-IMGT/HLA Database 主页. https://www.ebi.ac.uk/ipd/imgt/hla/
EMBL-EBI. About the IPD-IMGT/HLA Database. https://www.ebi.ac.uk/ipd/imgt/hla/about/
EMBL-EBI. Release 3.66.0 说明. https://www.ebi.ac.uk/ipd/imgt/hla/release/v366/
EMBL-EBI. LICENCE.md. https://ftp.ebi.ac.uk/pub/databases/ipd/imgt/hla/LICENCE.md
EMBL-EBI. Manual.md. https://ftp.ebi.ac.uk/pub/databases/ipd/imgt/hla/Manual.md
EMBL-EBI. README.md（3.56.0 起改用 zip 的说明）. https://ftp.ebi.ac.uk/pub/databases/ipd/imgt/hla/README.md
HLA Informatics Group. Nomenclature for factors of the HLA system. https://hla.alleles.org/nomenclature/naming.html
HLA Informatics Group. HLA allele numbers statistics. https://hla.alleles.org/pages/genes/statistics
Barker DJ, et al. The IPD-IMGT/HLA database: recent developments in sequence submission. Nucleic Acids Research 2026;54(D1):D1152-D1158. doi:10.1093/nar/gkaf1218
Robinson J, et al. IPD-IMGT/HLA Database. HLA 2024;103(6):e15549. doi:10.1111/tan.15549
Robinson J, et al. The IMGT/HLA database. Tissue Antigens 2000;55(3):280-287. doi:10.1034/j.1399-0039.2000.550314.x
EMBL-EBI. IPD-IMGT/HLA FTP 目录. https://ftp.ebi.ac.uk/pub/databases/ipd/imgt/hla/
ANHIG. IMGTHLA GitHub 仓库. https://github.com/ANHIG/IMGTHLA
EMBL-EBI. 新版序列提交工具. https://www.ebi.ac.uk/ipd/imgt/hla/submit/
本 Wiki 实测（2026-10-22）：/api/allele?limit=1 → meta.total 47,622；/api/cell → 78,489；300 条详情串行抓取（约 9 分钟）；Allelelist.txt（3.66.0）全量 47,424 行解析；version_report.txt 907 行分类统计

10.4 人工校验表

内容模块	审核者	审核方式	审核状态
§1 概览与四套规模口径	千方病案医学编辑部	对照 flat 文件实数、API 实测、官方增长表、NAR 论文逐条核对	✅ 已验证
§2 HLA 生物学与命名体系	千方病案医学编辑部（免疫遗传方向）	对照 WHO 命名规则文档	✅ 已验证
§3 规格、文件清单与版本机制	千方病案医学编辑部	对照 FTP 目录实况与 release 说明	✅ 已验证
§4 字段字典与解析代码	千方病案医学编辑部	逐字段对照 API 实返；解析代码实际运行，四字段 0.1995 / Null 0.0437 复算一致	✅ 已验证
§5 泄漏分析与切分建议	千方病案医学编辑部	方法论复核	✅ 已验证
§6 代码与 8 个坑点	千方病案医学编辑部	坑点逐条对应一手文档或本次实测	✅ 已验证
§7 DAIMS 24 项与偏倚	千方病案医学编辑部	逐项定性复核 + 300 条抽样复算	✅ 已验证
§8 生态与选型	千方病案医学编辑部	对照各平台官方页面	✅ 已验证
§9 引用格式与许可	千方病案医学编辑部	BibTeX 语法核对；许可条款对照 LICENCE.md 原文	✅ 已验证

10.5 AI 生成章节标注

全文由 AI 辅助起草后经人工逐节修订，无单独保留未经人工编辑的 AI 生成段落。§6 代码在 Python 3.11 环境实际执行；§4.1 字段表由 API 实返结构整理；§2.3 分辨率分布、§3.2 基因座分布、§4.3 规模口径、§7.2 抽样质量均由脚本对全量或抽样数据计算。

10.6 最后人工审核日期

2026-10-22

页面状态：published（全部内容已完成审核并发布）