Name: VDJdb: a curated database of T-cell receptor sequences with known antigen specificity
Creator: Institute of Bioorganic Chemistry, Russian Academy of Sciences

信息速览

数据集名称VDJdb — TCR 抗原特异性策展库 AI-Ready Wikipedia

数据类型约 30 MB TSV,13 万+ 条记录,CC BY-NC 4.0,免费开放下载

规模不适用（分子序列级策展库，非患者队列）

接入方式Institute of Bioorganic Chemistry, Russian Academy of Sciences / Pirogov Russian National Research Medical University url: https://vdjdb.cdr3.net/

AI 就绪度

VDJdb — T 细胞受体抗原特异性策展库 AI-Ready Wikipedia

INFOBOX


数据集名称	VDJdb
英文全称	VDJdb: a curated database of T-cell receptor sequences with known antigen specificity
别名/简称	VDJdb、vdjdb-db、VDJ Database
疾病分类	感染性疾病与肿瘤免疫全谱（ICD-11：1D9Z 病毒性疾病 / 2A0Z 恶性肿瘤 / 4A2Z 免疫缺陷等多系统关联）
SNOMED CT	30366006 T-lymphocyte (cell) / 86063006 T cell receptor (substance) / 111975006 Structure of major histocompatibility complex (body structure) / 36751004 Major histocompatibility complex (substance)
数据模态	氨基酸序列（CDR3 α/β 链）、分子相互作用（TCR-肽-MHC）、结构化元数据
AI 任务类型	TCR 特异性预测、表位分类、表征学习、免疫组库注释、跨反应性建模、分子结构预测
样本总数	13 万+ 条单链记录（2025 秋季版人源参考表为 132,204 条）；39,042 条人 TCR 覆盖 30 个抗原物种、750 个表位
数据大小	约 30 MB（vdjdb.slim.txt TSV）；仓库归档约 2.5 MB（Python 装配版）
数据格式	TSV（vdjdb.slim.txt / vdjdb.txt / vdjdb_full.txt 及对应 .meta.txt）、CSV 导出、XLS 模板
许可证	CC BY-NC 4.0（署名-非商业性使用）；代码仓库另附 LICENSE.txt，部分元数据记录标注 CC-BY-SA 4.0
访问级别	开放（网页浏览与批量下载均免费，无需注册；提交新记录需 GitHub 账号）
DUO 标签	GRU（通用研究）/ NPUNCU（非商业非营利）/ PUB（须公开发表）
语言	英文（数据库字段与文档）；无中文界面
首发日期	2017 年（数据库建库）；首篇论文 2018 年 1 月发表于 Nucleic Acids Research
最后更新	2025-09-26（Autumn release 2025）
发布机构	俄罗斯科学院生物有机化学研究所（IBCh RAS）、Pirogov 俄罗斯国立研究医科大学，多国合作
官方主页	https://vdjdb.cdr3.net/
下载地址	https://github.com/antigenomics/vdjdb-db/releases
DOI	10.1093/nar/gkx760（首发论文）；10.1038/s41592-022-01578-0（2022 更新论文）
引用次数	1,000+（Europe PMC 口径：首发论文 453 次 + 2020 更新论文 333 次 + 2022 Nature Methods 论文 167 次，截至 2026-05）
AI 就绪度评分	⭐⭐⭐⭐（4/5）— 官方提供稳定 TSV 下载与置信度评分标签，但无官方 train/test 划分、无预处理脚本，需自行实现负样本构造与相似度去泄漏
页面状态	published

§0 E-E-A-T 与审核声明

§0.1 内容审核主体

医学审核者：[千方病案医学编辑部]交叉审核：§2 医学背景（T 细胞免疫学、TCR 结构与抗原识别、MHC 限制性）、§7 偏倚分析（表位覆盖偏斜、HLA 等位基因偏倚）。

数据工程审核者：[千方病案医学编辑部交叉审核] 医疗 AI 数据工程师，审核范围：§4 DAIMS 数据字典、§5 数据划分策略、§6 预处理 Pipeline 和坑点。

审核日期：2026-09-05

§0.2 版本与事实核查声明

本页面描述的规模数字、版本历史、置信度评分规则均取自 VDJdb 官方仓库 README、官方站点（vdjdb.cdr3.net / vdjdb.com）、GitHub Releases 页面及同行评审论文（Nucleic Acids Research 2018/2020、Nature Methods 2022）。凡属动态数据（记录条数、引用次数、release 版本）均标注检索日期，读者引用前应以官方最新发布为准。所有基准性能数字均标注原始论文出处，不进行跨论文的数值排名比较。

§0.3 免责声明

医疗免责声明：本页面提供的医学信息仅供研究和教育目的，不构成医疗建议、诊断或治疗方案。数据集的医学描述基于公开发表的文献，未经逐一临床验证。任何基于该数据集训练的 AI 模型在应用于临床决策前，必须经过独立的临床验证和监管审批。

技术免责声明：本页面的代码示例、预处理建议和基准性能数据基于公开资料整理，不保证在特定环境下的准确性和适用性。使用者应自行验证代码安全性和数据预处理流程的正确性。千方病案医数集不对因使用本页面信息而导致的任何直接或间接损失承担责任。

数据使用合规：使用本页面描述的数据集前，请务必阅读并遵守数据集原始许可协议。VDJdb 采用 CC BY-NC 4.0 许可，禁止未经授权的商业性使用；使用其人源 TCR 序列开展研究时，应同时遵守原始贡献文献的数据使用条款，并注意 TCR 序列与 HLA 基因型组合可能构成的准可识别性风险。DUO 标签仅供参考，具体使用限制以数据集官方协议为准。

§1 数据集概览

§1.0 30 秒速览

这是什么？ VDJdb 是一本「T 细胞受体认人手册」的索引。人体免疫系统里的 T 细胞靠表面的 T 细胞受体（TCR）去识别入侵者，而 TCR 的识别能力几乎完全由它最关键的三个环区之一——CDR3 区的氨基酸序列决定。VDJdb 做的事就是：把全世界已发表文献里「哪条 TCR 序列认哪个抗原片段」的实验结论一条条抠出来，人工核对后存成一张表。截至 2025 年秋季版，这张表里光是人源的单链记录就有 13 万多条，覆盖 750 个不同的抗原片段。

为什么重要？ 测序技术现在可以一次读出一个人血液里上百万条 TCR 序列，但读出序列不等于知道它们认什么——绝大多数 TCR 的抗原特异性是未知的。VDJdb 是连接「序列」与「功能」的少数几座桥梁之一，而且是唯一为每条记录标注了 0 到 3 级置信度评分的桥。对训练 TCR 特异性预测模型的研究者来说，它是事实上的标准训练集与评测集；对做肿瘤新抗原、免疫组库分析的团队来说，它是把一堆陌生序列翻译成「这群 T 细胞在打什么」的第一站。

我能用它做什么？ 三个最典型的用法：一是把批量测序得到的 TCR 序列上传到 VDJdb 网页端，做整份免疫组库的批量注释，看样本里富集了哪些已知抗原特异性的克隆；二是把 vdjdb.slim.txt 下载下来，训练或评测一个 TCR-表位预测模型；三是按表位检索，挑出候选 TCR 序列送去做湿实验验证。需要注意它是一份「线索清单」而非「金标准答案册」——其中相当一部分记录的抗原特异性在独立复测中未能重现，因此置信度评分和后续验证缺一不可。

§1.1 摘要

VDJdb 由俄罗斯科学院生物有机化学研究所（IBCh RAS）与 Pirogov 俄罗斯国立研究医科大学主导，联合 Eindhoven 理工大学、Cardiff 大学、墨尔本大学、新南威尔士大学 Kirby 研究所、St. Jude 儿童研究医院等机构共同建设，通讯作者为 Mikhail Shugay 与 Dmitriy M. Chudakov。数据库于 2017 年建立，首篇论文（Shugay et al., Nucleic Acids Research 2018）报告了基于 2017 年 2 月数据库快照的 5,491 条 TCR 序列记录、132 个表位与 105 篇来源文献；2020 年的更新论文（Bagaev et al., NAR 2020）报告数据库扩容逾 5 倍，并引入批量 AIRR-seq 注释与 TCR motif 汇编；2022 年的论文（Goncharov et al., Nature Methods）则聚焦新冠疫情期新增的 SARS-CoV-2 特异性 TCR 汇编。

在方法学上，VDJdb 的核心贡献不是数据收集本身，而是一套可审计的策展流水线。所有记录经由 GitHub 仓库管理：每篇来源文献对应一个以 PubMed ID 命名的 issue，提交内容以 pull request 形式进入，持续集成（TravisCI）在每次合并与每次正式发布前执行表格式检查、CDR3 序列规范化修复（补全或切除胚系残基、比对 IMGT 胚系数据库解析 V/J 段）以及置信度评分赋值。这套流程把「文献里五花八门的 TCR 报告方式」转换成「可与免疫组库测序数据直接比对的标准序列」，是 VDJdb 区别于普通文献汇编的关键。

数据集最终产出的核心文件是 vdjdb.slim.txt：每条唯一的 CDR3-抗原配对一行，MHC、V/J 段、参考文献等字段以逗号分隔的多值形式折叠在其中，可直接用 pandas 读取，是绝大多数下游研究的实际入口。数据库官网另提供 Browse、Annotation、Motif、Structure、About 五大功能分区，其中 Annotation 分区支持上传 AIRR-seq 样本做整份组库的批量查询与样本级抗原特异性汇总。

§1.2 战略价值

价值维度一：填补「序列-功能」之间的标注鸿沟。 高通量免疫组库测序与单细胞技术的普及，使得从单个样本中获取数百万条 TCR 序列变得廉价，但为这些序列标注抗原特异性仍然依赖昂贵的湿实验。VDJdb 通过聚合已发表的特异性测定结果，把分散在数百篇论文里的标注集中到一处，并把不同实验室、不同测序技术、不同验证强度产生的证据统一到一套标准序列表示上。对于任何以 TCR 序列为输入、以抗原特异性为输出的监督学习任务，这种集中化标注是不可替代的基础设施。研究者不必重复进行文献挖掘，可以直接在 VDJdb 之上构建模型、设计对照、开展评测。

价值维度二：把「证据强度」显式编码进数据。 与多数只提供「阳性二元标签」的数据库不同，VDJdb 对每条记录赋 0-3 级置信度评分，评分依据包括 TCR 序列的鉴定方式（Sanger / 扩增子 / 单细胞）、克隆频率、初始 TCR:pMHC 鉴定方式（分选或培养）以及是否经过直接结合验证（如含 PDB 结构）。这一设计的战略意义在于：它把「这条记录有多可信」从隐性知识变成了可编程的字段。研究者可以据此做阈值筛选（只用 score ≥ 2 的高可信子集训练）、做标签噪声鲁棒性研究（对比不同 score 层的模型表现）、或在评估时按证据等级分层报告。论文数据显示评分与独立复现概率确实正相关：score 0 的记录中 89% 只在单一样本单篇研究中出现过，而 score 2/3 中分别有 32% 与 30% 见于多个独立研究。

§1.3 同类数据集横向对比

数据集	收录规模	模态	标注方式	差异化特征
VDJdb	13 万+ 单链记录；750 个表位（人源 2025 秋）	TCR 序列 + 表位 + MHC	文献人工策展 + V/J 胚系校正 + 0-3 级置信度评分	唯一提供分级置信度评分；以表位为中心、淡化疾病背景；Git-based 可审计策展流程
IEDB	百万级表位记录，其中 TCR 关联子集约 2,000 条	表位（肽）+ TCR 子集	人工策展	以抗原肽表位为核心，TCR 关联是近年新增子集；表位覆盖广度远超 VDJdb
McPAS-TCR	约 3 万条	TCR 序列 + 病理关联	人工策展	以病理/疾病背景为组织逻辑（如肿瘤、自身免疫），而 VDJdb 淡化疾病背景
TCRdb 2.0	约 7 亿条 TCR 序列	原始 TCR 序列	自动化整合	规模最大的 TCR 序列库，但基本不含抗原特异性标签，属于「景观型」资源
IMGT	胚系基因数据库	胚系 V/D/J 基因序列	专家维护	仅存胚系序列信息，不含配对抗原；是 V/J 段注释的参考标准
TRAIT	近 800 万条实验验证交互	TCR-抗原交互 + 结构 + 亲和力	整合策展	强调单细胞组学来源与结构/亲和力注释，规模远超 VDJdb 但策展深度差异较大

对比要点：VDJdb 在「规模」维度上并不占优，它的护城河在于「每条记录都有可解释的证据分级」以及「序列表示已被规范化到可与 RepSeq 数据直接比对」。在训练 TCR 特异性预测模型时，VDJdb 通常作为高置信度核心集，而 McPAS-TCR、IEDB 与 TCRdb 分别提供疾病背景补充、表位广度补充与负样本/背景分布参考。

§1.4 版本时间轴

版本 / 事件	日期	关键内容
数据库建立	2017	GitHub 仓库启动，首版数据汇编完成
首发论文	2018-01	Shugay et al., Nucleic Acids Res. 46(D1):D419–D427，DOI 10.1093/nar/gkx760；报告 5,491 条记录、132 个表位
NAR 2020 更新	2020-01	Bagaev et al., Nucleic Acids Res. 48(D1):D1057–D1062；数据库扩容逾 5 倍，新增批量 AIRR-seq 注释与 TCR motif 汇编
基础设施更新	2022-03-10	优化数据库装配流程，生成更完整的汇总统计，链接新的 motif 推断脚本
新增研究内容	2022-03-30	纳入肿瘤相关抗原、SARS-CoV-2/HCoV-HKU1 交叉反应、HIV 序列等；引入 Docker 构建
Nature Methods 论文	2022-09	Goncharov et al., Nat. Methods 19(9):1017–1019；新冠疫情期 SARS-CoV-2 特异性 TCR 汇编
2023 夏季版	2023-06-01	Celebrate the summer 2023 release
2024 夏季版	2024-05-23	Summertime-summertime 2024 release
2024 夏季版修复	2024-06-13	Hotfix#1 for 2024 summer release
首个 Python 装配版	2024-11-27	First Python Version Release，装配脚本由 Groovy 迁移至 Python
Spring challenge release	2025-02-21	pyvdjdb-2025-02-21；新装配脚本、新增多个数据集、修复旧数据集错误
Hot summer release’25	2025-07-31	新增数据集、修复缺陷、更新汇总统计
Autumn release 2025	2025-09-26	当前最新版；新增数据并修复部分记录

§1.5 典型应用场景

TCR 特异性预测模型的训练与评测：TCRGP、TCRdist、NetTCR、ERGO-II、TCRex、Cross-TCR-interpreter 等主流方法均在 VDJdb 或其子集上训练/评测，是该领域事实上的标准基准来源。
免疫组库（RepSeq）批量注释：把肿瘤浸润淋巴细胞（TIL）、外周血或组织样本的 TCR 测序结果上传至 VDJdb Annotation 分区，输出样本中已知抗原特异性克隆的富集情况与样本级汇总图表。
肿瘤新抗原与 TIL 分析：以已知病毒表位特异性 TCR 为参照，辅助筛选肿瘤浸润 T 细胞中的候选新抗原反应性克隆；研究显示 TCRβ 链组库信息可用于改进新抗原预测与优先级排序。
疫苗与感染免疫研究：新冠疫情期新增的 SARS-CoV-2 特异性 TCR 汇编被广泛用于评估疫苗接种与自然感染后的 T 细胞应答。
结构生物学与分子建模：官网 Structure 分区提供 AI 预测的 TCR-pMHC 复合物结构与互补决定区接触图，可用于结合界面分析与突变影响评估。

§2 医学背景

§2.1 疾病与免疫学分类映射

VDJdb 本身不是疾病数据集，而是分子相互作用数据集，其记录跨越多类疾病背景。下表给出主要关联疾病类别的 ICD-11 与 SNOMED CT 映射，用于理解数据的临床语境。

标签	ICD-11 编码与中文名	SNOMED CT 编码	术语
病毒感染（CMV/EBV/流感）	1D9Z 病毒性疾病，未特指	34014006	Viral disease
人类免疫缺陷病毒感染	1C62 HIV 病	86406008	Human immunodeficiency virus infection
COVID-19	RA01 COVID-19	840539006	Disease caused by SARS-CoV-2
恶性肿瘤	2A0Z 恶性肿瘤，未特指	363346000	Malignant neoplastic disease
自身免疫与免疫失调	4A4Z 免疫系统疾病，未特指	414029004	Disorder of immune system
T 细胞免疫缺陷	4A20 原发性免疫缺陷	234532001	Immunodeficiency disorder
移植排斥相关免疫	NE84 移植器官排斥	30682006	Transplant rejection

§2.1b SNOMED CT 解剖与分子实体映射

标签	SNOMED CT 编码	术语	在 VDJdb 中的含义
T 淋巴细胞	30366006	T-lymphocyte (cell)	携带 TCR 的细胞实体
T 细胞受体	86063006	T cell receptor (substance)	数据库记录的核心分子
主要组织相容性复合体	111975006	Structure of major histocompatibility complex	呈递抗原肽的分子
肽-MHC 复合物	36751004	Major histocompatibility complex (substance)	被 TCR 识别的配体
CDR3 区	无独立 SNOMED 编码	—	决定特异性的高变区，数据库中以氨基酸字符串表示

§2.2 医学背景简介

T 细胞是适应性免疫系统的核心效应与调节细胞。它通过细胞表面的 T 细胞受体（TCR）识别由主要组织相容性复合体（MHC，在人类中称为 HLA）分子呈递的抗原肽。TCR 是 α 链与 β 链（少数为 γ 链与 δ 链）组成的异二聚体，由 V(D)J 基因重排产生，其中每条链的可变区包含 CDR1、CDR2、CDR3 三个互补决定区。CDR3 由 V 段末端、D 段（仅 β 链）、J 段以及随机插入的核苷酸共同编码，序列高度可变，是决定抗原识别特异性的主要结构基础。理论上人体 TCR 组库的多样性可达 10¹⁵ 量级，而任何个体外周血中实际存在的克隆型数量也在 10⁶–10⁸ 量级。

MHC 分子分为两类：MHC-I 类呈递内源性抗原肽（通常 8-11 个氨基酸），被 CD8⁺ 细胞毒性 T 细胞识别，主要针对病毒感染细胞与肿瘤细胞；MHC-II 类呈递外源性抗原肽（通常 13-25 个氨基酸），被 CD4⁺ 辅助 T 细胞识别。TCR-pMHC 识别具有交叉反应性（polyspecificity），即同一条 TCR 可识别多个结构相似的肽-MHC 复合物，这既是免疫系统覆盖海量病原体的机制，也是造成注释歧义与假阳性的生物学根源。

在流行病学层面，TCR 组库分析的价值已被广泛验证。研究显示特定克隆型可调节 HLA-B27 对 HIV-1 感染的保护效应，以及 Mamu-A01 对 SIV 感染的保护效应，提示通过叠加抗原驱动组库中的体细胞重排信息，可以细化基因型与疾病结局之间的关联分析。这类研究构成了 VDJdb 的主要应用动机。

§2.3 临床任务定义

任务类别	具体任务	VDJdb 的角色	临床成熟度
筛查	供者 T 细胞免疫状态评估（如移植前 CMV/EBV 特异性 T 细胞监测）	提供已知抗原特异性 TCR 参照，用于组库注释	研究中
诊断	感染性疾病的 T 细胞免疫应答判读	辅助判定样本中是否存在病原特异性克隆扩增	研究/探索
分级	肿瘤浸润 T 细胞的抗原特异性谱刻画	提供新抗原反应性候选克隆筛选线索	研究中
预后	免疫治疗后克隆动态与疗效关联分析	提供基线特异性标签用于纵向追踪	研究中
治疗设计	TCR-T 细胞疗法与疫苗靶点筛选	提供候选 TCR 序列与表位配对线索	早期转化
基础研究	TCR 特异性预测算法开发	事实上的标准训练与评测数据源	成熟（科研）

§2.4 数据贡献人群特征

维度	取值范围	说明
物种	Homo sapiens、Mus musculus、Macaca mulatta	人源占绝对主体
供者来源	外周血、组织浸润 T 细胞、克隆化 T 细胞系、移植后样本	由原始文献决定，元数据中记录 meta.tissue
时间跨度	原始文献发表年份跨度约 1990 年代至 2020 年代	记录以参考文献 ID 关联原研究
年龄/性别	不统一记录	由原始文献决定，数据库层未标准化
族裔	以欧洲裔人群为主	HLA 等位基因分布偏斜是其直接反映
就医类型	不适用（分子层面数据，多数来自实验研究而非临床就诊）	—

§2.5 临床价值

VDJdb 的临床价值目前主要通过「赋能算法」间接实现。第一，它为 TCR-T 与肿瘤浸润淋巴细胞疗法中的靶点筛选提供候选序列起点，使研究者可以从已报道的抗原特异性 TCR 出发设计改造候选，而非从零开始筛选。第二，它为移植后免疫监测提供参照：通过注释患者外周血组库，可判断是否存在针对 CMV、EBV 等机会性病原的克隆扩增。第三，它为疫苗免疫原性评估提供 T 细胞层面的读出参照，弥补抗体滴度无法反映细胞免疫的缺口。第四，它通过结构分区提供 AI 预测的 TCR-pMHC 复合物结构，为亲和力成熟与脱靶风险评估提供结构线索。

需要强调的是，VDJdb 中约半数记录的功能反应性在独立复测中未被重现，其收录标准是「文献已报道」而非「独立验证通过」。因此任何以 VDJdb 记录为起点的临床前开发，都必须经过独立的湿实验验证，不可直接进入临床路径。

§2.6 金标准定义

维度	VDJdb 的处理方式	性质评价
划分方式	官方不提供 train/test 划分	需研究者自行设计（见 §5）
标注方式	文献人工策展 + CDR3 自动规范化修复 + V/J 胚系比对	混合式：人工判定来源 + 自动化序列校正
标注者	论文作者与社区贡献者，经数据库维护团队审核	具备领域专业背景，但无统一的标注者资质认证
标注一致性	通过 GitHub pull request 评审 + CI 校验保证格式一致性；生物学一致性由来源文献担保	格式一致性高，生物学一致性受来源实验质量制约
证据分级	每条记录赋 0-3 级置信度评分（vdjdb.score）	该数据集最核心的质量控制机制
阴性标注	仓库含 chunks_negative 目录，但公开负样本数量远少于正样本	显著短板，需用户自行构造负样本

§3 数据集规格

§3.0 版本抉择矩阵

VDJdb 以 GitHub Release 形式持续更新，不同下游用途适配不同版本策略。

你的需求	推荐版本	大小	理由
复现旧论文基准	论文发表时的对应 release（如 2024-05-23 或更早）	约 20-30 MB	数据库持续新增记录，用最新版会引入训练时不存在的数据，破坏可比性
训练 TCR 特异性预测模型	最新 Autumn release 2025，但仅用 score ≥ 2 子集	约 30 MB 中约 15%-25% 的记录	高置信度子集标签噪声显著更低，适合作为正样本来源
免疫组库批量注释	最新 release 的 vdjdb.slim.txt	约 30 MB	注释任务追求召回率，全量使用并保留 score 字段供使用者自行过滤
需要完整方法学元数据	vdjdb_full.txt + 对应 .meta.txt	大于 slim 版	full 版保留 α/β 分列、method.* 全部字段与 CDR3 修复记录
仅需快速原型验证	网页端按物种/链型筛选后导出 TSV	1-10 MB	避免下载全库，直接拿到过滤后的可用表
需要 motif 级别的分析	release 中附带的 motif_pwms.txt + cluster_members.txt	小于 5 MB	提供抗原特异性 TCR motif 的位置权重矩阵与代表序列

选择要点：注释任务用全量，建模任务用高置信度子集，复现实验用固定版本。三条原则不可混用。

§3.1 模态详情

模态	字段/载体	说明
氨基酸序列	cdr3.alpha、cdr3.beta	CDR3 区氨基酸串，规范形式以 C 起始、以 F 或 W 结尾；缺失胚系残基的记录在装配阶段被修复
基因片段	v.alpha、j.alpha、v.beta、j.beta（slim 版中折叠为 v.segm、j.segm）	按 IMGT 命名法标准化的 V/J 段标识，用于解析全长 CDR 信息
链型	gene（TRA / TRB）	单链记录视角下的链标识；同一 complex.id 的 TRA 与 TRB 记录构成配对
抗原表位	antigen.epitope、antigen.gene、antigen.species	肽序列、来源蛋白基因与抗原宿主物种
MHC 限制性	mhc.a、mhc.b、mhc.class	MHC 等位基因与类别（MHCI / MHCII）
方法学元数据	method.identification、method.frequency、method.singlecell、method.sequencing、method.verification	用于置信度评分计算的原始方法学描述
溯源元数据	reference.id、meta.study.id、meta.subject.id、meta.clone.id、meta.tissue、meta.cell.subset	指向原始文献与实验上下文
结构数据	meta.structure.id（PDB ID）	存在结构证据的记录在评分中获得直接验证加分；官网 Structure 分区另提供 AI 预测结构

§3.2 子集规模分布

子集	规模	数据来源时点	说明
总计（首发快照）	5,491 条 TCR 序列记录 / 413 条配对 / 132 个表位 / 105 篇文献	2017-02-02 数据库快照	首篇 NAR 论文 Table 1 报告值
人 MHC-I，TRB	3,001 条（99 条配对）	同上	数量最大的单一子集
人 MHC-I，TRA	481 条（310 条配对）	同上	配对比例最高
人 MHC-II，TRB	451 条（14 条配对）	同上	MHC-II 数据稀缺
人 MHC-II，TRA	138 条（17 条配对）	同上	规模最小的人源子集之一
猕猴 MHC-I，TRB	1,313 条（3 条配对）	同上	非人灵长类主力子集
小鼠全部	33 条（MHC-I 与 MHC-II 合计）	同上	显著偏少
人源参考表（转述）	39,042 条 TCR，30 个抗原物种，750 个表位	2025 秋季版	第三方工具 TIRTLtools 转述口径，已剔除自身抗原
人源完整加载表	132,204 条（单链行）	2025 版 release	omicverse 教程加载口径
10x Genomics 配对数据集	覆盖 40 个表位	2019 年纳入	纳入时是单批表位覆盖最广的高通量数据集

⚠️ 上述三组「人源」数字口径不同：39,042 是剔除了自身抗原并做过聚类去冗余的转述值；132,204 是 vdjdb.slim.txt 的单链行数（同一 CDR3-抗原对经折叠后仍可能因 α/β 链不同而分列）；首发论文的 5,491 条则是 2017 年快照。引用时必须说明口径与版本，不可直接相加或互相替换。

§3.3 文件格式

文件	内容	适用场景
vdjdb_full.txt	α/β 分列的原始版，保留全部 method 与 meta 信息，附 CDR3 修复 JSON 记录	深度元数据分析、策展审计
vdjdb.txt	折叠版，每行一条 α 或 β 单链记录，complex.id 标识配对关系（0 表示无配对信息）	VDJdb-standalone / VDJdb-server 注释
vdjdb.meta.txt	vdjdb.txt 的元数据说明	配合 vdjdb.txt 使用
vdjdb.slim.txt	每 CDR3:antigen 唯一记录一行，mhc.、.segm、complex.id、reference.id 以逗号拼接为多值	端用户探索、pandas 直接读取
vdjdb.slim.meta.txt	vdjdb.slim.txt 的元数据说明	配合 slim 版使用
motif_pwms.txt	抗原特异性 TCR motif 的位置权重矩阵	motif 扫描、可解释性分析
cluster_members.txt	构成各 motif 的代表性 TCR 序列集	motif 溯源
chunks/ 目录	按 PMID 命名的单篇文献原始提交片段（如 PMID_10756006.txt）	社区投稿与审计
LICENSE.txt	许可证全文（约 18.6 kB）	合规审查

格式要点：slim 版是折叠型宽表，同一 CDR3-抗原对若来自多个 MHC 等位基因或多次独立提交，对应字段会是逗号分隔的多值字符串。直接按单值处理会导致匹配失败或统计重复，必须先展开（见 §6.5 坑点 4）。

§3.4 存储大小

对象	大小	说明
vdjdb.slim.txt（TSV）	约 30 MB	全库下载的主要体积来源
GitHub Release 归档（Python 装配版）	约 2.5 MB（压缩包）	含装配脚本与 chunks，非完整数据库
单个 chunks 文件示例	10xgenomics-2019-07-09.txt 约 7.0 MB；PDB_Database.txt 约 52.9 kB	单篇来源文献的提交片段
解压后工作内存建议	≥ 2 GB	pandas 加载 13 万行宽表并做字符串展开时的经验值

§3.5 标注方式

VDJdb 的标注链条由四层构成，属于「人工策展 + 自动化规范化 + 规则化评分」的混合模式。

第一层：文献筛选与人工提取。 策展团队检索报告 TCR 特异性测定结果的已发表研究，从中提取 TCR 序列、表位、MHC 限制性、实验方法学描述与供者元数据。提取结果按模板写成 submission chunk（TSV），以 PubMed ID 命名后通过 pull request 提交。

第二层：CDR3 序列规范化（自动）。 文献中报告的 CDR3 常见两类问题：缺少 V 或 J 段信息、CDR3 序列不完整（缺保守残基）或过长（如把 J 段 FGXG motif 中的保守 F 残基包含在内）。装配脚本执行三项操作：补全或切除多余胚系残基、比对胚系数据库解析 V/J 段、标记无法修复或与作者报告的 V/J 段不符的记录。修复结果以 JSON 形式写入 cdr3fix.alpha / cdr3fix.beta 字段，包含 fixNeeded、good、cdr3、cdr3_old、jFixType、jId、jCanonical、jStart、vFixType、vId、vCanonical、vEnd 等键。修复类型枚举为 NoFixNeeded、FixAdd、FixReplace、FixTrim、FailedReplace（错配过多）、FailedBadSegment（胚系条目异常）、FailedNoAlignment（完全无法比对）。

第三层：置信度评分（规则化）。 见 §3.5b。

第四层：发布前 CI 校验。 每次投稿与每次正式发布前，BuildDatabase 例程执行表格式检查、CDR3 序列检查与修复、置信度评分赋值。近期基础设施进一步引入了面向 Claude Code 与 GitHub Copilot 的策展 skills（/extract、/format、/harmonize、/proofread、/vdjdb-publish），用于辅助从原文提取记录、标准化 IMGT 基因名与 MHC 等位基因格式、统一物种名与方法学词表、执行 ChunkQC 校验。

§3.5b 置信度评分体系

vdjdb.score 是 VDJdb 最具辨识度的设计。评分由三部分构成，最终分取「序列识别分」与「鉴定分 + 验证分之和」中的较小值。

评分来源	考察内容	分值规则
① TCR 序列识别置信	method.sequencing 与 method.singlecell	Sanger 测序：2+ 细胞测序（依 method.frequency）得 2 分，否则 1 分；扩增子测序：频率 > 0.01 得 2 分，否则 0 分；单细胞测序：得 3 分
② 初始 TCR:pMHC 鉴定	method.identification 与 method.frequency	分选法（sort-based）：频率 > 0.1；培养法（culture-based）：频率 > 0.5；测序前限制性稀释/培养时频率含义模糊，需核查是否 > 0.5
③ 特异性验证	method.verification	直接法（如含 PDB ID，meta.structure.id 非空）得 3 分；靶细胞刺激法得 2 分；染色法得 1 分
特殊规则	—	若已做验证，则假定 TCR 序列已知，评分来源①直接置 3 分
聚合规则	—	最终分 = min(①, ② + ③)；指向同一 unique complex 的多条独立提交/重复记录取最大分

vdjdb.score	含义	判定要点
0	低置信度 / 无信息	缺少测序或特异性验证的关键环节
1	中等置信度	无验证，或 TCR 序列可信度偏低
2	高置信度	有部分特异性验证，且序列可信度良好
3	极高置信度	有充分验证或含结构数据

评分的经验效度（仅统计人 TCRβ 记录）：

vdjdb.score	仅单样本单研究	见于多样本	见于多研究	样本总量
0	1,709（89%）	166（9%）	43（2%）	1,918
1	751（77%）	163（17%）	56（6%）	970
2	211（61%）	27（8%）	110（32%）	348
3	87（63%）	9（7%）	42（30%）	138

该表说明评分与「在多个独立研究中被复现」的概率正相关：score 0 记录几乎全部为孤例，而 score 2/3 中约三分之一的记录出现在多个研究中。因此以 score ≥ 2 作为筛选阈值，是在样本量与标签可靠性之间较为稳妥的折中点。

§3.6 标注者资质与一致性

维度	情况
标注主体	数据库维护团队 + 社区贡献者（多为原始论文作者或同领域研究者）
专业背景	免疫学、免疫信息学、计算生物学；通讯作者为免疫组库领域知名学者
审核机制	GitHub pull request 评审 + CI 自动化校验（格式、CDR3 规范性、V/J 合法性）
一致性保证	格式层面通过自动化强约束；生物学层面依赖来源文献的实验可靠性，数据库不做独立复测
已知局限	大规模独立功能复测显示约半数记录的反应性未能重现；数据库亦承认含错误注释序列

§3.7 采集周期

数据库自 2017 年建立以来持续滚动更新，公开 release 节奏约为每年 1-3 次。可查证的近期 release 包括 2023-06-01、2024-05-23、2024-06-13（hotfix）、2024-11-27、2025-02-18（预发布）、2025-02-21、2025-07-31、2025-09-26。数据内容的时间跨度对应原始文献发表年份，覆盖约 1990 年代至 2020 年代。仓库累计提交次数超过 1,300 次，公开 release 累计 36 个。

§3.8 地域覆盖

数据贡献来自全球多国实验室，主要策展机构分布在俄罗斯（IBCh RAS、Pirogov 医科大学、国家血液学研究中心、莫斯科国立大学）、荷兰（Eindhoven 理工大学）、英国（Cardiff 大学）、澳大利亚（墨尔本大学、Kirby 研究所）、美国（St. Jude 儿童研究医院）。供者人群的族裔构成受原始研究制约，以欧洲裔人群为主，直接导致 HLA 等位基因覆盖偏斜。FAIRsharing 记录标注的开发国别为 Czech Republic、Russia、European Union。

§3.9 设备与技术平台

平台/技术	在数据中的角色
流式细胞术 + pMHC 多聚体染色分选	最主要的抗原特异性 T 细胞鉴定手段，是多数记录的来源方法
单细胞 TCR 测序（10x Genomics）	提供配对的 α-β 链记录，显著提升配对记录比例
Sanger 测序	传统克隆测序方式，见于早期文献与克隆化 T 细胞系
扩增子测序（amplicon-seq）	高通量克隆分型，需依赖克隆频率判定可信度
RepSeq 免疫组库测序（IMGT/HighV-QUEST、MiXCR、ImmunoSEQ 等流程）	用户侧的主要下游数据形式，也是注释功能的输入
体外功能读出（靶细胞刺激、细胞因子分泌）	特异性验证手段，决定评分来源③的分值
X 射线晶体学 / 冷冻电镜（PDB）	结构证据来源，使记录获得评分来源③的 3 分

§3.10 深度溯源链

VDJdb 的溯源链条相对清晰，是其可审计性的核心：

原始文献 (PubMed ID)
   ↓  人工提取 + 模板化
submission chunk (chunks/PMID_XXXXXXX.txt)
   ↓  GitHub pull request + CI 校验
BuildDatabase 装配 (Groovy 或 Python)
   ↓  CDR3 规范化 (cdr3fix.*) + V/J 胚系比对 + 置信度评分
database/ 产出 (vdjdb_full.txt / vdjdb.txt / vdjdb.slim.txt)
   ↓  GitHub Release 打包
vdjdb.slim.txt (端用户下载入口)
   ↓  字段 reference.id / meta.study.id
回到原始文献与实验

溯源要点：字段 reference.id 指向原始文献（PubMed ID），meta.study.id 标识具体研究，meta.subject.id 与 meta.clone.id 标识供者与克隆（为研究内部伪匿名标识）。任何一条 VDJdb 记录都可以被追溯到具体出版物与具体实验，这是它能作为科研参照的关键；但链条末端依赖原始文献的实验质量，数据库本身不做二次验证。

§4 数据结构

§4.0 目录树

VDJdb 并不以压缩包目录形式分发，而是以 Git 仓库 + Release 附件形式组织。下图为仓库与 Release 产物的结构预览。

vdjdb-db/                              # GitHub 仓库根目录
├── README.md                          # 数据库规范、评分规则、投稿指南
├── LICENSE.txt                        # 许可证全文（约 18.6 kB）
├── CONTRIBUTING                       # 投稿须知
├── Dockerfile / Dockerfile_2          # 数据库构建容器
├── chunks/                            # 按来源文献组织的提交片段（核心数据源）
│   ├── 10xgenomics-2019-07-09.txt     # 约 7.0 MB，配对链数据集
│   ├── PDB_Database.txt               # 约 52.9 kB，结构证据来源
│   ├── PMID_10756006.txt
│   ├── PMID_10925283.txt
│   ├── ...
│   └── Mice_TCRs_specific_to_B16_melanoma_neoantigens_(Shagina_et_al_2024).txt
├── chunks_negative/                   # 阴性/非结合记录片段（数量远少于正样本）
├── chunks_unformatted/                # 待格式化的原始导入片段
├── chunks_with_unconventional_aa/     # 含非常规氨基酸的片段
├── proofreading/                      # 校对词典（基因别名、物种别名）
│   ├── gene_aliases.tsv
│   └── species_aliases.tsv
├── patches/                           # 跨 chunk 的字段协调补丁
├── processing/                        # 数据加工中间产物
├── py_src/                            # Python 版装配脚本
├── src/                               # Groovy 版装配脚本（BuildDatabase.groovy）
├── skills/                            # AI 辅助策展指令集（extract/format/harmonize/proofread/publish）
├── summary/                           # 汇总统计的 R Markdown 模板
├── withheld/                          # 暂缓公开的记录
└── database/                          # 装配产物（执行 BuildDatabase 后生成）
    ├── vdjdb_full.txt                 # 原始版，α/β 分列 + method/meta 全字段
    ├── vdjdb_full.meta.txt
    ├── vdjdb.txt                      # 折叠单链版（供 standalone 注释器使用）
    ├── vdjdb.meta.txt
    ├── vdjdb.slim.txt                 # ★ 端用户入口：每 CDR3:antigen 一行
    ├── vdjdb.slim.meta.txt
    ├── motif_pwms.txt                 # 抗原特异性 motif 位置权重矩阵
    └── cluster_members.txt            # motif 代表序列集

# Release 下载入口（稳定 URL）
# https://github.com/antigenomics/vdjdb-db/releases/latest/download/vdjdb.slim.txt

§4.1 DAIMS 字段字典（vdjdb.slim.txt 核心列）

字段名	类型	说明	示例值	AI 用途	观测误差	信息性缺失编码	取值范围
cdr3	string	CDR3 区氨基酸序列（规范形式以 C 起始、F/W 结尾）	CASSLSRGGNQPQYF	模型主输入特征	文献报告不规范；已由 cdr3fix 校正，但修复失败记录仍存偏差	空值表示未提供	约 5-25 个氨基酸，20 种标准氨基酸
v.segm	string（可多值）	V 基因片段（IMGT 命名）	TRBV7-9*01	与 CDR3 拼接构成输入；约束搜索空间	部分记录由 CDR3 反推，准确率非 100%	空值表示无法解析	IMGT TRAV/TRBV 家族全集
j.segm	string（可多值）	J 基因片段（IMGT 命名）	TRBJ1-5*01	同上	同上	空值表示无法解析	IMGT TRAJ/TRBJ 家族全集
gene	string	链型标识	TRB / TRA	区分训练任务；配对判定依据	无（数据库内部一致）	—	TRA、TRB
species	string	TCR 来源物种	HomoSapiens	跨物种迁移评估；筛选子集	无	—	HomoSapiens、MusMusculus、MacacaMulatta
mhc.a	string（可多值）	MHC α 链等位基因	HLA-A*02:01	条件化建模（MHC 限制性作为输入）	部分记录仅到基因位点级别，缺等位基因变异信息	空值/多值拼接	HLA 等位基因命名法；MHCI 含 B2M
mhc.b	string（可多值）	MHC β 链（如 B2M）或 MHC-II β 链	B2M	同上	同上	空值	—
mhc.class	string（可多值）	MHC 类别	MHCI / MHCII	任务分域；MHC-II 数据稀缺需谨慎	分类错误少见但存在	空值	MHCI、MHCII
antigen.epitope	string	抗原肽序列	GILGFVFTL	分类标签（预测目标）	部分肽序列来源蛋白未定	空值	肽序列，通常 8-11（I 类）或 13-25（II 类）个氨基酸
antigen.gene	string	抗原来源蛋白/基因	IE1、M、pp65	蛋白质层级任务标签	命名历史上不统一，含别名	空值或占位描述（如 Unnamed protein product）	自由文本（经 patches 协调）
antigen.species	string	抗原宿主物种	CMV、InfluenzaA、SARS-CoV-2	分层评估；病原组泛化分析	命名不统一，含别名	空值	病毒/细菌/自身物种名
reference.id	string（可多值）	来源文献 PubMed ID	28977646	溯源与按研究分组交叉验证	无	空值	PubMed ID
vdjdb.score	integer	0-3 级置信度评分	2	正样本筛选阈值；标签噪声分层分析	规则化评分，反映证据强度而非生物学真值	无（必有值）	0、1、2、3
method.*	string（仅 full 版展开）	测序/鉴定/验证方式	singlecell；sort-based；staining-based	消融实验；纳入 method 作为特征	依赖文献描述完整度	空值	见 §3.5b 枚举
meta.study.id / meta.subject.id / meta.clone.id	string	研究/供者/克隆标识（研究内部伪匿名）	s1 / subj3 / cl7	构造按供者分组的交叉验证（防泄漏必需）	不同研究粒度不一致	空值	自由文本

§4.2 标签分布

VDJdb 的「标签」是抗原表位，其分布呈极端长尾：

表位	关联交互数	来源病原
GILGFVFTL	420	流感 A 型 M1 蛋白
GLCTLVAML	285	EBV BMLF1
SSYRRPVGI	275	病原相关
NLVPMVATV	230	CMV pp65
SSLENFRAYV	190	病原相关
ASNENMETM	150	流感 A 型（小鼠模型常用）
LLWNGPMAV	120	黄热病/病原相关
HGIRNASFI	115	病原相关

统计维度	数值	来源时点
唯一表位数	132	2017-02 快照
唯一表位数	212	2020 更新论文
唯一表位数	750（人源，剔除自身抗原）	2025 秋
抗原物种数	30	2025 秋

分布特征解读：头部少数几个病毒表位（GILGFVFTL、NLVPMVATV、GLCTLVAML）占据了相当大的记录比例，而长尾表位往往只有个位数记录。这种分布直接决定了三件事：一是分层评估（per-epitope AUROC）比总体评估更有意义；二是长尾表位的模型性能通常显著低于头部表位；三是任何「全库随机划分」的评测都会让模型偏向头部表位，掩盖真实的泛化能力。

§4.3 关键统计

统计项	数值
首发快照记录总数	5,491 条
首发快照已知 α-β 配对记录	413 条
配对记录占比（首发快照）	约 7.5%
首发快照来源文献数	105 篇
人源单链记录（2025 版加载口径）	132,204 条
人源去冗余 TCR 数（2025 秋）	39,042 条
高分记录占比（score ≥ 2，仅人 TCRβ 统计口径）	486 / 3,374 ≈ 14.4%
仓库累计提交次数	1,322 次
公开 release 数	36 个

§4.4 数据层级

VDJdb 的数据组织不遵循临床数据集的「患者→就诊→检查」层级，而是分子互作的四层结构：

研究 (reference.id / meta.study.id)          ← 一篇发表文献
   └── 供者 (meta.subject.id)                ← 原始研究中的个体（研究内部伪匿名）
         └── 克隆 (meta.clone.id)            ← 一个 T 细胞克隆型
               └── 复合物 (complex.id)       ← 一次 TCR:肽:MHC 互作
                     ├── α 链记录 (gene = TRA, cdr3.alpha + v.alpha + j.alpha)
                     └── β 链记录 (gene = TRB, cdr3.beta + v.beta + j.beta)

关键点：complex.id 是配对关系的枢纽。vdjdb.txt（单链折叠版）中每行一条 α 或 β 记录，来自同一 α-β 对的记录共享同一个 complex.id；当 complex.id 为 0 时表示该记录没有配对信息。vdjdb.slim.txt 则把同一 CDR3-抗原对的记录进一步折叠，把 complex.id 也变成逗号分隔的多值列表。构造配对数据集时必须先按 complex.id 做透视（pivot），而非简单按行拼接。

§4.5 缺失值与信息性缺失

缺失情形	表示	信息性含义	处理建议
cdr3 字段为空	空字符串	该记录仅提供了另一条链的序列	按链型分别处理；配对建模时剔除
v.segm / j.segm 为空	空字符串	无法从 CDR3 比对解析出 V/J 段（可能是非常规序列或胚系条目异常）	若模型依赖 V/J，剔除该行；或改用仅 CDR3 的模型
mhc.a / mhc.b 为空	空字符串	原始文献未报告 MHC 限制性	条件化 MHC 的模型需将此类记录排除或归入 unknown 类
mhc.a 仅到基因位点	如 “HLA-A” 而非 “HLA-A*02:01”	文献报告粒度不足	视为「等位基因级信息缺失」，不可当作精确等位基因使用
antigen.gene 为空或泛化	如 “Unnamed protein product”	抗原来源蛋白未明确	若任务需要蛋白层级标签，剔除该行
complex.id = 0	整数值 0	该记录无配对链信息	配对任务剔除；单链任务保留
method.* 字段为空	空字符串	原始文献未描述对应方法学细节	影响置信度评分推导的可复现性，但不影响序列使用
meta.subject.id 为空	空字符串	无法追溯供者	构造按供者分组划分时该记录无法参与，只能丢弃

§5 划分与使用建议

§5.1 官方划分

VDJdb 不提供任何官方 train / validation / test 划分。 数据库以完整的互作记录表形式发布，不附带任务定义、数据切分脚本或评测协议。这一点与 MIMIC-III、MIMIC-IV 等带有明确任务基准的数据集形成鲜明对比，也是 VDJdb 被标注为「AI 就绪度 4/5」而非 5/5 的直接原因。研究者使用 VDJdb 时必须自行完成两件事：定义任务（正样本来自哪里、负样本如何构造）与设计划分（如何避免泄漏）。

这一设计有其合理性：TCR 特异性预测的任务定义多样（单表位二分类、多表位多分类、配对链联合预测、表位未见零样本预测），单一官方划分无法覆盖；但代价是不同论文的评测结果往往建立在不同的数据切分之上，导致跨论文数值不可直接比较（见 §8.1 的说明）。

§5.2 社区惯例划分

尽管无官方划分，社区已形成若干相对稳定的惯例，主要围绕「按什么单位分组」这一问题：

划分策略	分组单位	适用场景	代表工作
留一受试者交叉验证（LOSO）	meta.subject.id	同一供者内部外推；最贴近真实临床场景	TCRGP（Jokinen et al., 2021）
留一研究交叉验证（Leave-one-study-out）	reference.id	跨实验室、跨实验批次泛化	若干 benchmark 研究
留一表位交叉验证（Leave-one-epitope-out）	antigen.epitope	零样本表位泛化；难度最高	TCRdist、部分深度模型
唯一 TCR 留一交叉验证	CDR3 + V 基因组合	去除重复克隆后的严格泛化评估	TCRGP 补充实验
随机划分	无分组	仅用于快速原型；不可用于报告性能	教学与调试

其中 LOSO 是最被推荐的默认策略，因为 TCR 序列在同一个体内高度相关——同一个人可能对同一表位产生多个高度相似的克隆，若把这些克隆同时放入训练与测试集，模型只需记住序列模式即可获得虚高性能。

§5.3 泄漏风险（重点）

TCR 特异性预测的泄漏风险远高于常规表格数据，原因有四，每一条都足以单独毁掉评测结论。

泄漏源一：同一受试者的相似克隆跨集。 一个供者体内针对某表位的 T 细胞克隆往往形成序列高度相似的家族（相差 1-2 个氨基酸）。随机划分会把这些近亲分散到训练与测试集，模型学到的是「这个家族的共有 motif」，而测试集里的成员恰好也带着同样的 motif。结果是 AUROC 虚高到 0.95 以上，但在真正未见过的供者上崩塌到 0.7 左右。缓解：严格按 meta.subject.id 分组切分，并用 TCRdist / 编辑距离确认两组间无高度相似序列。

泄漏源二：同一文献的多条记录跨集。 单篇文献可能贡献同一表位的数百条记录（如 10x Genomics 配对数据集单批覆盖 40 个表位、数千条记录）。若这些记录分散到训练与测试集，测试集实质上与训练集同源。缓解：按 reference.id 或 meta.study.id 分组切分。

泄漏源三：重复 CDR3 记录。 vdjdb.slim.txt 中同一 CDR3-抗原对在折叠后仍可能因来源不同而出现多行（不同 complex.id、不同 MHC 等位基因）。若不去重，同一条序列会同时出现在训练与测试集。缓解：按 (cdr3, gene, antigen.epitope) 三元组去重后再划分。

泄漏源四：与模型预训练数据的重叠。 大量已发表的 TCR 预测模型（NetTCR、ERGO-II、PanPep 等）在训练时使用了 VDJdb 或 10x Genomics 数据集。当你想用 VDJdb 评估这些模型的「泛化能力」时，实际上在评估它们的记忆能力。例如 NetTCR-2.1 的外部评测就把 10x Genomics 数据用于训练、VDJdb 用于测试，并额外做了相似度过滤以去除与训练集高相似的测试序列，相似度过滤可带来约 5% 的平均 AUC 变化，这正说明重叠程度对结果影响之大。缓解：评估前显式声明候选模型是否可能见过该数据；对测试集做基于 TCRdist 的相似度过滤（剔除与训练集任意阳性序列距离低于阈值的测试样本）。

§5.4 交叉验证建议

建议项	具体做法	理由
默认策略	按 meta.subject.id 做 GroupKFold（k=5）	去除个体内克隆相似性带来的虚高
报告口径	同时报告 per-epitope AUROC 与按阳性样本数加权的平均 AUROC	长尾表位上的均值会被少数头部表位掩盖
表位筛选	每个表位阳性样本数 ≥ 20 才纳入评估	过小样本的表位 AUROC 方差极大
负样本构造	使用「交换 TCR」（swapped TCR）或来自同一组库的非阳性克隆	随机氨基酸串作为负样本过于简单，会夸大性能
阈值敏感性	报告 score ≥ 1 / ≥ 2 / 全量三种条件下的性能	直接展示标签噪声对结论的影响
泄漏自检	划分后计算训练集与测试集的 TCRdist 分布，确认两者可比但不同源	量化而非声称「已避免泄漏」

§5.5 外部验证建议

VDJdb 上的性能数字只有在独立外部数据上复现才有意义。推荐的外部验证路径：

交叉来源验证：以 VDJdb 为训练集、以 McPAS-TCR 为测试集，或以 McPAS-TCR 为训练集、以 VDJdb 为测试集，观察跨数据库迁移的性能衰减。
原始实验数据的重新划分：使用 10x Genomics 公开的配对 TCR-pMHC 数据集，按供者划分后独立评估。
湿实验验证：对模型预测的 TCR-表位对进行 TCR 工程化报告细胞系（如 Jurkat 76 + NFAT 报告系统）激活实验，这是唯一能确证预测真实性的方式。已有的独立功能复测显示，VDJdb 中声明的反应性仅约一半能被重现，因此湿实验验证不能省略。
结构一致性检查：若有 AI 预测或实验解析的 TCR-pMHC 结构，检查预测的结合界面是否与结构证据相容，作为独立的支持性证据。

§6 AI 就绪指南

§6.0 云端快速启动

VDJdb 体积小（约 30 MB），无需专门的云端存储或数据集挂载，任何具备 Python 环境的机器都能在数秒内完成下载与加载。推荐直接用 Google Colab 或本地 Jupyter 起步：

# 无需任何申请与认证；VDJdb 采用 CC BY-NC 4.0 许可，禁止商业使用
# 全部数据约 30 MB，下载通常 < 30 秒
import urllib.request
url = "https://github.com/antigenomics/vdjdb-db/releases/latest/download/vdjdb.slim.txt"
urllib.request.urlretrieve(url, "vdjdb.slim.txt")

import pandas as pd
df = pd.read_csv("vdjdb.slim.txt", sep="\t", low_memory=False)
print(df.shape)          # 约 (132204, 20) 量级，随 release 变动
print(df.columns.tolist())

§6.1 快速上手

以下代码块假定如下目录结构（data_root 为本示例中的当前工作目录）：

<data_root>/                       # 项目根目录
├── vdjdb.slim.txt                 # ★ 主表（TSV，约 30 MB）
├── vdjdb.txt                      # 可选：单链折叠版（含 complex.id 配对信息）
├── vdjdb_full.txt                 # 可选：原始版（含 method.* 与 cdr3fix.* 字段）
└── work/                          # 中间产物目录（脚本自动创建）
    ├── vdjdb_clean.parquet        # 清洗与展开后的主表
    ├── split_ids.json             # 按供者分组的划分索引
    └── negatives.parquet          # 构造的负样本

data_root 与文件名的拼接关系为 os.path.join(data_root, "vdjdb.slim.txt")。最小可用子集：若只想跑通流程，可只保留 gene == "TRB"、species == "HomoSapiens"、vdjdb.score >= 2 且 antigen.epitope 非空的行，此时数据量降至数千行级别，可在笔记本上秒级完成训练。

import os
import pandas as pd

data_root = "."                                   # 按实际路径修改
slim_path = os.path.join(data_root, "vdjdb.slim.txt")

# 1) 读取主表（TSV，低内存模式解析）
df = pd.read_csv(slim_path, sep="\t", low_memory=False)
print(f"原始行数: {len(df):,}")

# 2) 最小可用子集：人源 TRB 链 + 高置信度 + 有明确表位
sub = df.query(
    "gene == 'TRB' and species == 'HomoSapiens' "
    "and vdjdb.score >= 2 and antigen.epitope.notna()"
).copy()
print(f"最小可用子集行数: {len(sub):,}")
print(sub["antigen.epitope"].value_counts().head(10))

§6.2 数据获取

获取方式	地址	体积	是否需要申请	适用场景
官方 Release 稳定直链（推荐）	https://github.com/antigenomics/vdjdb-db/releases/latest/download/vdjdb.slim.txt	约 30 MB	否	程序化获取，最稳定
网页端交互检索后导出	https://vdjdb.cdr3.net/search	1-50 MB	否	按物种/链型/MHC/病原筛选后导出 CSV、XLS 或 TSV
REST API	https://vdjdb.cdr3.net/api/database/meta （文档见 vdjdb-web.readthedocs.io）	按需	否	集成进分析流水线
仓库克隆后本地装配	https://github.com/antigenomics/vdjdb-db	全仓库	GitHub 账号（如需投稿）	需要自定义装配参数或审计 chunks
Zenodo 归档版本	https://zenodo.org/records/598037 等	约 2.5 MB（脚本与 chunks）	否	引用特定历史版本、获取 DOI

本地装配（仅当需要自定义时）：历史版本需 JDK 8 + Groovy，在 src/ 目录执行 groovy -cp . BuildDatabase.groovy（加 --no2fix 可跳过 CDR3 修复步骤，不建议）。2024 年 11 月起提供 Python 版装配脚本（py_src/），依赖负担显著降低。

# 方式一：直接下载最新 slim 表（推荐，无依赖）
import urllib.request
URL = "https://github.com/antigenomics/vdjdb-db/releases/latest/download/vdjdb.slim.txt"
urllib.request.urlretrieve(URL, "vdjdb.slim.txt")

# 方式二：通过 REST API 查询数据库元信息（用于版本核对）
import json, urllib.request
with urllib.request.urlopen("https://vdjdb.cdr3.net/api/database/meta") as r:
    meta = json.load(r)
print(json.dumps({k: meta[k] for k in list(meta)[:8]}, indent=2, ensure_ascii=False))

§6.3 预处理全流程

预处理分为四个阶段：格式转换 → 清洗与展开 → 标准化 → 训练集构造。每一步都针对 VDJdb 的真实数据特征设计。

import ast
import os
import numpy as np
import pandas as pd

data_root = "."
os.makedirs(os.path.join(data_root, "work"), exist_ok=True)

df = pd.read_csv(os.path.join(data_root, "vdjdb.slim.txt"), sep="\t", low_memory=False)

# ---------- 阶段 1：格式转换 ----------
# slim 版是折叠宽表：同一 CDR3:antigen 对的 *.segm / mhc.* / reference.id 等
# 列可能是逗号分隔的多值字符串。统一解析为首个值 + 集合计数。
MULTIVALUE_COLS = ["v.segm", "j.segm", "mhc.a", "mhc.b", "mhc.class",
                   "complex.id", "reference.id"]

def expand_multi(val):
    """把可能的多值字符串规范为 list[str]。"""
    if pd.isna(val) or val == "":
        return []
    return [s.strip() for s in str(val).split(",") if s.strip()]

for c in MULTIVALUE_COLS:
    if c in df.columns:
        df[c + "_list"] = df[c].map(expand_multi)
        df[c + "_n"] = df[c + "_list"].map(len)
        df[c] = df[c + "_list"].map(lambda xs: xs[0] if xs else "")   # 取首个值便于快速筛选

# ---------- 阶段 2：清洗 ----------
# 2.1 丢弃 CDR3 缺失的行
df = df[df["cdr3"].notna() & (df["cdr3"].astype(str).str.len() > 0)].copy()

# 2.2 规范 CDR3：仅保留标准 20 种氨基酸，去除非常规字符记录
VALID_AA = set("ACDEFGHIKLMNPQRSTVWY")
def is_canonical_cdr3(s):
    s = str(s).upper()
    if not (s.startswith("C") and s.endswith(("F", "W"))):
        return False
    return set(s) <= VALID_AA and 5 <= len(s) <= 25
mask_ok = df["cdr3"].map(is_canonical_cdr3)
print(f"非规范 CDR3 行数（将被剔除）: {(~mask_ok).sum():,}")
df = df[mask_ok].copy()
df["cdr3"] = df["cdr3"].str.upper()

# 2.3 去重：按 (cdr3, gene, antigen.epitope) 三元组，避免同一序列跨集
before = len(df)
df = df.drop_duplicates(subset=["cdr3", "gene", "antigen.epitope"], keep="first")
print(f"去重移除行数: {before - len(df):,}")

# ---------- 阶段 3：标准化 ----------
# 3.1 MHC 等位基因规范：补齐缺失的 "HLA-" 前缀与 "*" 分隔符
def norm_mhc(x):
    x = str(x).strip()
    if x in ("", "nan", "None"):
        return "UNKNOWN"
    x = x.replace("HLA", "HLA-").replace("HLA--", "HLA-")
    # 兼容 HLA-A02:01 / HLA-A02:01 等写法，尽量补星号
    if "*" not in x and ":" in x:
        head, tail = x.split(":", 1)
        parts = head.rsplit("-", 1)
        x = f"{parts[0]}-{parts[1]}*{tail}" if len(parts) == 2 and not parts[1].startswith("*") else x
    return x
df["mhc_a_norm"] = df["mhc.a"].map(norm_mhc)
df["mhc_b_norm"] = df["mhc.b"].map(norm_mhc)

# 3.2 病原物种名规范化：统一大小写与常见别名
SPECIES_MAP = {
    "cmv": "CMV", "ebv": "EBV", "influenzaa": "InfluenzaA",
    "hiv-1": "HIV-1", "hiv1": "HIV-1", "sars-cov-2": "SARS-CoV-2",
    "yellow fever virus": "YFV", "denv": "DENV",
}
df["antigen_species_norm"] = (
    df["antigen.species"].astype(str).str.strip()
    .map(lambda s: SPECIES_MAP.get(s.lower(), s.upper() if len(s) <= 6 else s))
)

# 3.3 表位肽标准化（大写、去空白）
df["epitope_norm"] = df["antigen.epitope"].astype(str).str.strip().str.upper()

# ---------- 阶段 4：训练集构造 ----------
# 4.1 只保留足够阳性样本的表位（长尾表位的评估方差不可接受）
MIN_POS = 20
cnt = df["epitope_norm"].value_counts()
keep_epitopes = cnt[cnt >= MIN_POS].index
df_ml = df[df["epitope_norm"].isin(keep_epitopes)].copy()
print(f"保留表位数: {len(keep_epitopes)}；建模行数: {len(df_ml):,}")
print(df_ml["vdjdb.score"].value_counts().sort_index())

# 4.2 落盘中间产物
out = os.path.join(data_root, "work", "vdjdb_clean.parquet")
df_ml.to_parquet(out, index=False)
print(f"已写出: {out}")

§6.4 PyTorch DataLoader

以下代码实现一个可直接运行的 TCR 特异性预测 Dataset，包含 CDR3 词表构建、按供者分组的防泄漏切分，以及完整 DataLoader 实例化。

import os
import json
import numpy as np
import pandas as pd
import torch
from torch.utils.data import Dataset, DataLoader
from sklearn.model_selection import GroupShuffleSplit

data_root = "."
df = pd.read_parquet(os.path.join(data_root, "work", "vdjdb_clean.parquet"))

# ---------- 1) 任务定义：二分类（是否为某表位）+ 词表 ----------
TARGET_EPITOPE = "GILGFVFTL"        # 示例：流感 M1 表位，阳性样本充足
AA_VOCAB = list("ACDEFGHIKLMNPQRSTVWY")   # 20 种标准氨基酸
PAD, UNK = 0, 21
aa2idx = {a: i + 1 for i, a in enumerate(AA_VOCAB)}
MAX_LEN = 25

def encode_cdr3(seq: str) -> torch.Tensor:
    ids = [aa2idx.get(c, UNK) for c in str(seq).upper()][:MAX_LEN]
    ids += [PAD] * (MAX_LEN - len(ids))
    return torch.tensor(ids, dtype=torch.long)

# ---------- 2) 正负样本与分组键 ----------
pos = df[df["epitope_norm"] == TARGET_EPITOPE].copy()
pos["label"] = 1

# 负样本策略：同库内其它表位的 TCR（比随机氨基酸串更接近真实难度）
neg_pool = df[df["epitope_norm"] != TARGET_EPITOPE]
neg = neg_pool.sample(n=min(len(pos) * 3, len(neg_pool)), random_state=42).copy()
neg["label"] = 0

data = pd.concat([pos, neg], ignore_index=True)
data["group"] = data.get("meta.subject.id", pd.Series(["NA"] * len(data))).fillna("NA").astype(str)

# ---------- 3) 按供者分组切分，杜绝个体内克隆泄漏 ----------
groups = data["group"].values
gss = GroupShuffleSplit(n_splits=1, test_size=0.2, random_state=42)
tr_idx, te_idx = next(gss.split(data, groups=groups))
assert not (set(groups[tr_idx]) & set(groups[te_idx])), "分组切分失败：存在跨集供者"
train_df, test_df = data.iloc[tr_idx].reset_index(drop=True), data.iloc[te_idx].reset_index(drop=True)
print(f"训练集 {len(train_df):,} 行 / 测试集 {len(test_df):,} 行")

# ---------- 4) Dataset ----------
class TCRDataset(Dataset):
    def __init__(self, frame: pd.DataFrame):
        self.seqs = frame["cdr3"].astype(str).tolist()
        self.labels = frame["label"].astype(float).tolist()
        self.scores = frame["vdjdb.score"].astype(int).tolist()

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

    def __getitem__(self, i):
        return {
            "input_ids": encode_cdr3(self.seqs[i]),
            "label": torch.tensor(self.labels[i], dtype=torch.float32),
            "vdjdb_score": torch.tensor(self.scores[i], dtype=torch.long),
        }

# ---------- 5) DataLoader ----------
BATCH = 128
train_loader = DataLoader(TCRDataset(train_df), batch_size=BATCH, shuffle=True,
                          num_workers=0, drop_last=False)
test_loader = DataLoader(TCRDataset(test_df), batch_size=BATCH, shuffle=False,
                         num_workers=0)

# ---------- 6) 极简模型与单轮训练（验证流程可跑通） ----------
class TinyTCRNet(torch.nn.Module):
    def __init__(self, emb=32, hidden=64, n_class=1):
        super().__init__()
        self.emb = torch.nn.Embedding(22 + 1, emb, padding_idx=PAD)
        self.net = torch.nn.Sequential(
            torch.nn.Conv1d(emb, hidden, kernel_size=3, padding=1),
            torch.nn.ReLU(),
            torch.nn.AdaptiveMaxPool1d(1),
            torch.nn.Flatten(),
            torch.nn.Linear(hidden, n_class),
        )

    def forward(self, x):
        return self.net(self.emb(x).transpose(1, 2)).squeeze(-1)

device = "cuda" if torch.cuda.is_available() else "cpu"
model = TinyTCRNet().to(device)
opt = torch.optim.Adam(model.parameters(), lr=1e-3)
loss_fn = torch.nn.BCEWithLogitsLoss()

model.train()
for batch in train_loader:
    opt.zero_grad()
    logits = model(batch["input_ids"].to(device))
    loss = loss_fn(logits, batch["label"].to(device))
    loss.backward()
    opt.step()
print(f"单轮训练完成，最后一批 loss={loss.item():.4f}")

# 落盘切分索引，供复现
os.makedirs(os.path.join(data_root, "work"), exist_ok=True)
with open(os.path.join(data_root, "work", "split_ids.json"), "w", encoding="utf-8") as f:
    json.dump({"target_epitope": TARGET_EPITOPE,
               "train_len": len(train_df), "test_len": len(test_df)}, f)

§6.5 坑点

⚠️ 坑点 1：把 score 0/1 记录当作真阳性标签入训（分类：标签理解）

问题：VDJdb 的收录标准是「文献已报道」，而非「独立验证通过」。score 0 表示缺少测序或特异性验证的关键环节，score 1 表示无验证或序列可信度偏低。大规模独立功能复测显示，VDJdb 中声明的 TCR–pMHC 反应性仅约 50% 在重新实验中得到确认。直接把全库（尤其低分记录）作为正样本训练，等于给模型喂入约半数的噪声标签，模型会学到大量伪关联。
症状：训练集内部验证 AUROC 轻松达到 0.95+，但换到独立数据集或湿实验验证时性能大幅滑坡；模型对高频错误表位的预测置信度异常高；按 score 分层评估时 score 0 组的性能与 score 2 组差异巨大。
解决：

简单方法：只保留 vdjdb.score >= 2 的记录作为正样本。经验上高分组约占人 TCRβ 记录总量的 14%（486/3,374），样本量虽降但标签更干净。

进阶方法：把 score 作为样本权重或辅助标签引入模型（如按 score 分层采样、或用 score 做不确定性加权的损失函数），并强制按 score 分层报告性能：for s in [0,1,2,3]: evaluate(model, test[test.score==s])。

SOTA 方法：使用噪声鲁棒学习框架（如 co-teaching、标签平滑、置信学习 cleanlab）显式建模标签噪声；更彻底的方案是构建自有验证集——参照 TCRvdb 的做法对候选记录做独立功能复测，把「复现成功」作为硬标签。
参考：https://ar5iv.labs.arxiv.org/html/2601.17138 ；VDJdb 评分规则 https://github.com/antigenomics/vdjdb-db

⚠️ 坑点 2：只用 CDR3 精确匹配做表位注释，忽略交叉反应性（分类：评估误用）

问题：TCR 识别的本质是多特异性的，同一条 β 链 CDR3 常被交叉登记到多个不同表位。若仅按 CDR3 字符串做精确匹配查库，一条序列可能命中多条记录，返回的是「记录排序中的第一条」而非生物学上的正确答案。实测数据显示，单用 CDR3 精确匹配的表位一致率仅 41%（996 次调用），加入 V 基因约束后一致率升至 100%，但可用调用数从 996 骤降到 4。
症状：注释结果看似覆盖率高（85% 的查询序列命中），但其中过半表位判断与金标准不符；同一批数据换一个 release 版本，注释结果排名大变。
解决：

简单方法：注释结果至少加两条约束——CDR3 精确匹配 + V 基因一致（match_v=True），接受覆盖率下降换取准确率。

进阶方法：使用序列相似度而非精确匹配（TCRdist 半径内的模糊匹配），并输出所有候选表位及其置信度，而非单一答案；同时要求候选记录 vdjdb.score >= 2。

SOTA 方法：把数据库注释当作「假设生成器」，用不依赖数据库的独立证据交叉验证——如基于序列收敛性（convergence）的克隆分组、motif 分析（release 附带的 motif_pwms.txt），以及结构层面的结合界面相容性检查。
参考：https://omicverse.github.io/omicverse-pages/Tutorials-airr/t_airr_04_tcr.html

⚠️ 坑点 3：随机划分导致个体内克隆泄漏，性能虚高（分类：数据泄漏）

问题：同一供者体内针对同一表位的 T 细胞克隆会形成序列高度相似的家族（常仅相差 1-2 个氨基酸）。随机划分把这些近亲分散到训练与测试集后，模型只需记忆家族 motif 即可命中测试样本，测出的是记忆能力而非泛化能力。VDJdb 的 meta.subject.id 字段使这种泄漏完全可检测、可避免，但默认的 train_test_split 不会用到它。
症状：随机划分 AUROC 0.95+，改用留一受试者（LOSO）划分后掉到 0.7-0.85；训练集与测试集的 TCRdist 分布几乎重合；换个随机种子结果波动剧烈。
解决：

简单方法：改用 GroupShuffleSplit(groups=df["meta.subject.id"]) 或 GroupKFold，确保同一供者的所有记录只出现在一侧。

进阶方法：划分后再做一次相似度体检——计算测试集每条阳性序列到训练集最近阳性序列的 TCRdist / 归一化编辑距离，剔除距离低于阈值的测试样本（相似度过滤）；这样做可使性能数字下降但更诚实。

SOTA 方法：同时报告多种划分口径下的结果（LOSO、留一研究、留一表位），并明确标注哪一种是「真实部署场景对应」的估计——临床场景下面对的是全新个体、全新表位，因此留一表位划分最严苛也最接近真实。
参考：https://pmc.ncbi.nlm.nih.gov/articles/PMC8023491/table/pcbi.1008814.t002/ ；https://www.biorxiv.org/content/10.1101/2023.02.01.526310.full

⚠️ 坑点 4：把 vdjdb.slim.txt 的多值列当单值处理（分类：预处理陷阱）

问题：slim 版的设计目标是「每个 CDR3:antigen 对占一行」，为此把 mhc.a、mhc.b、mhc.class、v.segm、j.segm、complex.id、reference.id 等列折叠成逗号分隔的多值字符串。用 pandas 读取后再 .str.split(",").str[0] 取首值，会静默丢失同一序列的其它 MHC 等位基因与多条来源文献；不做展开直接 value_counts() 统计 MHC 分布，则会把「HLA-A02:01,HLA-B07:02」当做一个独立类别。
症状：MHC 等位基因分布统计出现大量含逗号的「幽灵类别」；按 reference.id 分组做留一研究交叉验证时，分组数远少于实际文献数；同一条 CDR3 在过滤后剩余记录数比预期少。
解决：

简单方法：读取后立即对多值列做 explode——df = df.assign(mhc_a=df["mhc.a"].str.split(",")).explode("mhc_a")，把宽表还原为长表再统计。

进阶方法：按任务区分处理策略——若任务是「CDR3 → 表位」，多值 MHC 只需保留一个代表值或转为多标签编码；若任务是「CDR3 + MHC → 是否结合」，则必须 explode 到 MHC 粒度，并注意 explode 会造成同一序列在训练集内重复出现（需按新粒度重新去重）。

SOTA 方法：需要完整方法学字段（method.、cdr3fix.）时改用 vdjdb_full.txt 而非 slim 版——full 版按 α/β 分列展开，不折叠多值列，代价是体积更大且需自行按 complex.id 做链配对。
参考：https://urls.greenkeeper.io/antigenomics/vdjdb-db ；https://rdrr.io/cran/immunarch/f/vignettes/web_only_v0/v11_db.Rmd

⚠️ 坑点 5：直接用最新 release 复现旧论文基准（分类：评估误用）

问题：VDJdb 每年发布多个 release，每次都会新增记录并修复旧记录。用 2025 秋季版去「复现」一篇 2021 年论文报告的 AUROC，实际上测试集已经包含了训练时不存在的新数据，且部分旧记录的序列或表位标注可能已被修正，结论不可比较。VDJdb 也不提供 release 与论文的对应表，需要自行推断。
症状：无法复现已发表数值，差异方向不一致（有时更高有时更低）；同一份代码在不同时间运行得到不同结果；审稿人质疑数据版本。
解决：

简单方法：在论文/报告中显式记录所用 release tag（如 pyvdjdb-2025-02-21 或 Autumn release 2025）与下载日期，并使用固定 URL 而非 latest 别名。

进阶方法：使用 Zenodo 归档版本获取永久 DOI 与不可变快照（如 https://zenodo.org/records/598037 ），在方法学部分引用 DOI 而非 GitHub 链接。

SOTA 方法：把数据版本纳入实验管理——用 DVC 或 Git LFS 管理数据快照，在 CI 中固化 vdjdb.slim.txt 的 SHA256 校验值，使结果差异可归因于代码而非数据漂移。
参考：https://www.github.com/antigenomics/vdjdb-db/releases ；https://zenodo.org/records/598037

⚠️ 坑点 6：忽略表位与 HLA 的极端长尾分布，报告误导性的平均性能（分类：偏倚陷阱）

问题：VDJdb 的表位分布极度不均衡——GILGFVFTL、GLCTLVAML、NLVPMVATV 等少数病毒表位占据大量记录，而多数表位仅有数十条甚至个位数记录；MHC 层面同样偏斜，HLA-A 与 HLA-B 的少数等位基因占主导，MHC-II 与小鼠数据稀缺。用简单算术平均报告 per-epitope AUROC 时，一个只有 8 条阳性样本的表位会与 420 条样本的表位等权，方差极大且结论不稳。
症状：换一个随机种子，平均 AUROC 波动超过 0.05；模型在头部表位上 0.95+、在长尾表位上接近随机；声称「在 VDJdb 上达到 0.9 AUROC」但无法说明在哪些表位上失败。
解决：

简单方法：设定表位纳入门槛（如阳性样本 ≥ 20 条），同时报告按阳性样本数加权的平均 AUROC 与简单平均 AUROC 两个数字。

进阶方法：按表位、按 MHC 类别（MHCI vs MHCII）、按病原物种、按 score 分层报告性能矩阵，显式暴露失败面；把「长尾表位性能」作为独立的报告项而非淹没在均值中。

SOTA 方法：采用留一表位（leave-one-epitope-out）协议评估零样本泛化能力，这是唯一能反映「模型能否处理数据库中未见过的新抗原」的评测方式；并配合 motif 层面的可解释性分析，确认模型学到的模式是否具备生物学合理性而非数据偏斜产物。
参考：https://www.frontiersin.org/journals/bioinformatics/articles/10.3389/fbinf.2023.1274599 ；https://www.ovid.com/00124336-202608000-00035

⚠️ 坑点 7：用随机氨基酸串构造负样本，夸大模型性能（分类：评估误用）

问题：TCR 特异性预测需要负样本，但 VDJdb 的公开负样本极少（仓库虽有 chunks_negative 目录，数量远不及正样本）。用随机氨基酸串或打乱的 CDR3 作为负样本，会使正负两类在氨基酸组成与序列统计上截然可分，模型只需学会「像 TCR 的序列 vs 不像 TCR 的序列」这一低难度判别，而非真正的特异性识别。
症状：AUROC 接近 1.0，平均精度（APS）也异常高；把负样本换成真实组库中的非阳性克隆后性能大幅下降；模型在真实组库注释任务中假阳性率极高。
解决：

简单方法：使用同库内其它表位的 TCR 作为负样本（即「交换 TCR」策略），保证负样本在氨基酸组成与 V/J 使用上与正样本同分布。

进阶方法：从同一供者的实际免疫组库中采样未注释克隆作为阴性对照，或采用「表位标签置换」（label permutation）构造难度更高的负例；同时报告 ROC AUC 与 APS，APS 对不平衡与难度更敏感。

SOTA 方法：把负样本构造当作可调超参数做敏感性分析，报告多组正负比（1:1 / 1:3 / 1:10）下的性能曲线；参照 ITRAP、ICON 等数据过滤框架的设计思路，用真实数据驱动的判据（而非人为规则）决定哪些记录可作为可靠阴性。
参考：https://www.biorxiv.org/content/10.1101/2023.02.01.526310.full

⚠️ 坑点 8：忽略物种与链型混合导致的数据规模幻觉（分类：偏倚陷阱）

问题：直接 len(df) 得到的十几万条记录会给人「数据很充足」的错觉，但这一总数混合了人、小鼠、猕猴三个物种，TRA 与 TRB 两种链型，以及大量无配对信息的单链记录。实际用于人源 TRB 单表位建模的数据可能只有数千条。更棘手的是，TRA 链的记录在 vdjdb.slim.txt 中可能与对应的 TRB 记录共享 complex.id，按行统计会造成重复计数。
症状：以为有 13 万条独立样本，实际按 (cdr3, gene, epitope) 去重后只剩几万条；训练集里混入 MacacaMulatta 记录导致性能异常；配对链模型的样本量比预期少一个数量级（首发快照中配对记录仅占约 7.5%）。
解决：

简单方法：建模前显式统计并打印子集规模——df.groupby(["species","gene","mhc.class"]).size()，确认目标子集的真实行数后再设计实验。

进阶方法：明确任务口径并锁死——单链任务固定 gene == "TRB" 且 species == "HomoSapiens"；配对任务先按 complex.id 透视出 (cdr3.alpha, cdr3.beta) 对，并接受样本量大幅下降的现实；跨物种任务则单独设一组，不与人类结果混合报告。

SOTA 方法：建库时把物种、链型、MHC 类别作为显式的分层轴，按轴分层采样与分层评估；对小样本轴（如 MHC-II、小鼠）改用迁移学习或元学习框架，并明确声明其结论强度低于人 MHC-I 轴。
参考：https://pmc.ncbi.nlm.nih.gov/articles/PMC5753233/table/tbl1/ ；https://nicholasclark.github.io/TIRTLtools/reference/vdj_db.html

§6.6 数据增强策略

增强操作	安全性	说明
按供者分层过采样少数表位	✅ 安全	只在训练集内部操作，不跨越划分边界，可缓解表位长尾
同义替换 V/J 基因命名到 IMGT 标准	✅ 安全	属于标准化而非增强，消除别名造成的伪类别
序列截断到 CDR3 核心区（去保守首尾）	✅ 安全	去除与表位识别无关的保守 C/F/W 残基，减少模型依赖胚系特征
引入 V 基因作为附加输入通道	✅ 安全	增加真实可用信息，不是标签泄漏
对 CDR3 做随机点突变生成新正样本	❌ 危险	突变后的序列大概率不再结合原表位，制造假阳性标签
反转或打乱 CDR3 序列	❌ 危险	生成的序列不具备生物学意义，只适合作为明显负样本
跨表位合并正样本以扩充数据	❌ 危险	混合了不同标签语义，模型将无法学习表位特异性
对测试集做与训练集相同的过采样	❌ 危险	破坏评测的无偏性，属于隐蔽的数据泄漏

§6.7 模型推荐

模型	类型	适用场景	关键特点
TCRGP	高斯过程 + 序列核	小样本、需不确定性估计	可利用全部 CDRβ 区，LOSO 下均值 AUROC 达 0.863（全 CDR 配置）
TCRdist	距离度量 + 最近邻	基线对照、相似度分析	无需训练，可解释性强，均值 AUROC 0.743
NetTCR-2.0 / 2.1	卷积神经网络	配对 α-β 链预测	同时使用 CDR3α 与 CDR3β，APS 0.7262
ERGO-II	自编码器 + LSTM	单链 / 配对链	可引入 V/J 基因与 MHC 类型作为附加特征
Cross-TCR-interpreter	深度神经网络	表位分类	ROC AUC 0.9445 / APS 0.7600（VDJdb-without10x 基准）
PanPep	元学习	少样本新表位	ROC AUC 0.9009，面向未知表位快速适配
蛋白质语言模型微调（ESM 系列等）	预训练 + 微调	需大规模表征迁移	以 CDR3 为序列输入迁移学习，适合数据稀缺表位

§6.8 硬件需求

任务规模	最低配置	推荐配置	说明
数据加载与探索（13 万行 TSV）	8 GB 内存 / CPU	16 GB 内存 / SSD	展开多值列时内存峰值约 2-3 GB
单表位二分类（数千样本）	CPU（4 核）	单张消费级 GPU（8 GB 显存）	模型参数量小，CPU 亦可在数分钟内完成
全表位多分类（数万样本）	单张 GPU（8 GB）	单张 GPU（16 GB 以上）	类别数多时输出层与批次显存占用上升
蛋白质语言模型微调	单张 GPU（16 GB）	A100 40 GB 或同级	序列长度短但模型参数量大
结构预测（官网 Structure 分区数据的下游使用）	GPU（16 GB）	A100 80 GB	属独立的结构预测任务，非 VDJdb 本身需求

§6.9 评估指标

import numpy as np
import torch
from sklearn.metrics import roc_auc_score, average_precision_score, f1_score

@torch.no_grad()
def collect_preds(model, loader, device="cpu"):
    model.eval()
    ys, ps, scores = [], [], []
    for batch in loader:
        logits = model(batch["input_ids"].to(device))
        ps.append(torch.sigmoid(logits).cpu().numpy())
        ys.append(batch["label"].numpy())
        scores.append(batch["vdjdb_score"].numpy())
    return (np.concatenate(ys), np.concatenate(ps), np.concatenate(scores))

def evaluate(y, p, s, thresholds=(0.5,)):
    """同时报告 ROC AUC、平均精度与固定阈值下的 F1。"""
    out = {
        "roc_auc": roc_auc_score(y, p),
        "avg_precision": average_precision_score(y, p),   # 不平衡与难度更敏感
        "n": int(len(y)),
        "pos_rate": float(y.mean()),
    }
    for t in thresholds:
        out[f"f1@{t}"] = f1_score(y, (p >= t).astype(int), zero_division=0)
    return out

# 按 vdjdb.score 分层评估：直接暴露标签噪声对性能的影响
y, p, s = collect_preds(model, test_loader)
overall = evaluate(y, p, s)
print("总体:", {k: round(v, 4) if isinstance(v, float) else v for k, v in overall.items()})

for lvl in [0, 1, 2, 3]:
    m = (s == lvl)
    if m.sum() >= 10:
        sub = evaluate(y[m], p[m], s[m])
        print(f"vdjdb.score={lvl} (n={sub['n']}): "
              f"AUC={sub['roc_auc']:.4f}  AP={sub['avg_precision']:.4f}")

指标选择要点：必须同时报告 ROC AUC 与平均精度（APS）。在正负比悬殊时 ROC AUC 会显得乐观，而 APS 更能反映模型在真实不平衡场景下的可用性。此外，任何在 VDJdb 上报告的性能数字都应附带三项元信息：所用 release 版本、score 筛选阈值、划分策略（LOSO / 留一研究 / 留一表位）。

§6.10 MLOps 笔记

实践项	建议
数据版本固定	在配置中写死 release tag 与文件 SHA256，禁用 `latest` 别名用于正式实验
数据快照	用 DVC 或对象存储保存所用版本的 vdjdb.slim.txt，避免上游更新导致结果不可复现
标签质量监控	每次数据更新后重新统计 score 分布与表位长尾情况，记录变化趋势
泄漏回归测试	在 CI 中加入断言：训练集与测试集的 meta.subject.id 交集必须为空；TCRdist 相似度检查作为告警项
负样本可复现	负样本采样必须固定随机种子并落盘，避免每次运行得到不同的评测集
分层报告固化	把按 score、按 MHC 类别、按表位规模的性能分层输出作为标准评测脚本的一部分
模型卡片	明确记录模型是否在训练中见过 10x Genomics 数据集或 VDJdb 本身，避免下游误判泛化能力

§7 质量评估与局限性

§7.1 已知偏倚

偏倚类型	描述	严重程度	缓解方式
表位覆盖偏倚	头部少数病毒表位（GILGFVFTL、GLCTLVAML、NLVPMVATV 等）占据大量记录，长尾表位普遍只有个位数记录；2020 年时全库仅 212 个唯一表位	高	分层评估；对长尾表位单独报告；使用留一表位协议检验零样本泛化
病原类型偏倚	病毒表位占绝对主导，肿瘤相关抗原、自身抗原、细菌抗原与移植抗原稀少	高	引入外部数据源（肿瘤新抗原预测需结合 TCGA 等队列）；对肿瘤相关任务明确声明数据局限
HLA 等位基因偏倚	覆盖集中于 HLA-A 与 HLA-B 的少数常见等位基因（HLA-A*02:01 主导），MHC-II 与非常见等位基因数据稀缺；部分记录 MHC 信息仅到基因位点级别	高	按等位基因分层评估；条件化 MHC 的模型需对未知等位基因做特殊处理；跨人群应用前评估 HLA 频次差异
物种偏倚	人源记录占绝对主体，小鼠记录极少（2017 快照仅 33 条），猕猴记录次之	中	明确限定人源任务；跨物种迁移需谨慎并单独验证
链型偏倚	大量研究仅报告 TCRβ 链，配对 α-β 记录为少数（2017 快照配对记录约占 7.5%）	中	单链任务为主流；配对任务需用 10x Genomics 等专项数据集补充
方法学偏倚	多数记录来自 pMHC 多聚体染色分选，单一方法可能系统性偏向高亲和力、高频率克隆	中	引入 method.* 作为协变量做分层分析；结合功能性验证数据
发表偏倚	阳性结果优先发表，阴性/不结合数据几乎不发表；仓库虽设 chunks_negative 目录但负样本极少	高	自行构造同分布负样本；使用表位标签置换策略
族裔偏倚	供者人群以欧洲裔为主（受原始研究制约），直接影响 HLA 覆盖分布	中	跨人群应用前必须验证；明确声明该局限

§7.2 标注质量

VDJdb 的标注质量呈现「格式质量高、生物学质量参差」的双重特征。

格式与结构质量（高）：所有记录均经自动化 CI 校验，V/J 段比对 IMGT 胚系数据库，CDR3 序列在可能时被规范化为标准形式（以 C 起始、F/W 结尾），修复过程以结构化 JSON 记录在 cdr3fix.* 字段中，可审计、可回溯。字段取值受词表约束（物种名、方法学枚举、MHC 命名），命名历史不一致问题通过 patches 与 proofreading 词典持续协调。

生物学质量（参差）：数据库的收录标准是「文献已报道」，维护团队不对原始实验做独立复测。大规模独立功能复测结果显示，VDJdb 中声明的 TCR–pMHC 反应性仅约 50% 在重新实验中确认，研究者据此另行发布了经验证的子集（TCRvdb）。数据库亦公开承认含错误注释序列，并指出这些错误会给下游分析（如互信息计算）引入噪声。

质量分级机制（关键优势）：vdjdb.score 是应对上述问题的核心设计。评分基于测序方式、克隆频率、鉴定方式与验证手段四个可查证维度，与独立复现概率呈正相关（见 §3.5b 表）。研究者可以据此选择质量-数量的取舍点，而不是被动接受全库。

§7.3 泛化性评估

应用场景	失效风险	证据
新表位预测（数据库中无该表位）	高：模型在留一表位协议下性能显著下降，无法外推到结构上不相似的新抗原	TCRGP/TCRdist 在 VDJdb 上的 LOSO 评估均值 AUROC 0.806-0.863，但该口径允许同一表位的其它个体样本入训；留一表位条件下更差
新个体预测（数据库中无该供者）	中：LOSO 协议下的性能可作为该场景的诚实估计	TCRGP LOSO 均值 AUROC 0.806（仅 CDR3β）/ 0.863（全 CDRβ）
跨实验室/跨批次迁移	中高：不同研究的实验流程、测序平台与多聚体试剂差异会引入批次效应	研究明确指出 VDJdb 存在测序平台异质性与批次效应，互信息估计受有限样本效应与填充伪影影响
跨 MHC 类别迁移（I 类 → II 类）	极高：MHC-II 表位数据量不足以支撑同类分析，且结合构象与肽长度分布差异大	相关研究明确指出 VDJdb 的表位特异性数据仅足以在 CD8 T 细胞（MHC-I）上检验假设，MHC-II 数据不足
跨物种迁移（人 → 小鼠）	极高：小鼠记录极少，MHC（H-2）与人类 HLA 差异大	2017 快照中小鼠全部记录仅 33 条
从数据库注释迁移到临床判读	极高：约半数记录不可复现，且数据库不做独立验证	独立功能复测仅约 50% 反应性得证；数据库自述含错误注释序列
单 CDR3 精确匹配注释	高：交叉反应导致多表位命中，一致率仅 41%	omicverse 实测：996 次调用中仅 41% 与 dextramer 金标准一致

§7.4 伦理考量

VDJdb 存储的是 TCR CDR3 氨基酸序列与实验元数据，不包含原始测序读长、姓名或其他直接标识符。供者标识（meta.subject.id）为原始研究内部的伪匿名编号。因此，从传统生物医学伦理角度看，直接的个人可识别风险较低。

但仍有三点需要关注。第一，TCR 序列与 HLA 基因型的组合具有准可识别性：HLA 等位基因本身是高度多态的遗传标记，与罕见疾病背景、特定表位反应性组合后，可能在小范围内指向特定个体，尤其对罕见病或罕见 HLA 类型的供者。第二，原始研究的知情同意范围不同：VDJdb 聚合的数据来自数百篇独立研究，各研究的伦理审批与知情同意范围不尽相同，使用者应遵守原始文献的数据使用条款，而不只是 VDJdb 的整体许可。第三，治疗转化的伦理边界：基于 VDJdb 记录设计的 TCR-T 疗法候选，必须经过完整的临床前验证与监管审查，不可因「数据库已收录」而省略验证环节。

§7.5 公平性

公平性维度	现状	潜在影响
族裔覆盖	供者以欧洲裔为主，HLA 覆盖偏斜至欧洲人群常见等位基因	在欧洲裔人群上训练的模型迁移到东亚、非洲人群时性能可能下降，因 HLA 等位基因频次分布差异大
HLA 等位基因覆盖	少数常见等位基因占主导，非常见等位基因记录稀少	携带罕见 HLA 等位基因的人群可能被系统性漏检或误判
疾病谱覆盖	以常见病毒感染为主，肿瘤、自身免疫、罕见病抗原稀少	肿瘤免疫与自身免疫领域的应用成熟度显著低于抗感染方向
数据可及性	完全免费开放下载，无地域限制或费用门槛	公平性良好；主要门槛是技术能力而非获取成本

§7.6 数据漂移

漂移类型	表现	缓解
版本漂移	每年 1-3 次 release，每次新增记录并修正旧记录，同一查询在不同时间返回不同结果	固定 release tag；记录 SHA256；使用 Zenodo 归档快照
构成漂移	新增记录的表位、病原、物种构成随研究热点变化（如疫情期间 SARS-CoV-2 记录激增）	监控 score 与表位分布变化；评测集应随版本重新统计
术语漂移	基因名、物种名、MHC 命名随 IMGT 与命名规范更新而变化	依赖 release 附带的 patches 与证明词典；自行做标准化映射
标签定义漂移	评分规则本身可能随维护团队判断而调整	在方法学中记录所用评分规则版本；不跨版本直接比较 score 分布

§7.7 DAIMS 24 项评估

#	检查项	状态	说明
1	宽格式	✅	vdjdb.slim.txt 为扁平宽表，可直接被 pandas / R 读取；多值列以逗号折叠并附 .meta.txt 说明
2	唯一标识	✅	complex.id 标识 TCR:肽:MHC 复合物；reference.id 标识来源文献；meta.subject.id / meta.clone.id 标识供者与克隆；vdjdb.slim.txt 中同一 CDR3:antigen 对唯一
3	特殊字符	⚠️	部分 chunks 文件名含括号与空格（如小鼠黑色素瘤新抗原文件名）；antigen.gene 等自由文本字段历史上命名不统一，需依赖 patches 协调
4	重复行	⚠️	slim 版按 CDR3:antigen 对折叠，但同一序列可因 MHC 等位基因、来源文献不同而保留多条记录；不做三元组去重会导致训练/测试集重叠
5	缺失编码	✅	无信息字段留空而非使用占位符（仓库文档明确要求「leave fields that have no information as blank, don’t use any placeholder」）；complex.id = 0 具有明确的「无配对信息」语义
6	标签标识	✅	标签即抗原表位（antigen.epitope），字段名明确；另有 antigen.gene 与 antigen.species 提供蛋白质与物种层级标签
7	罕见类分组	❌	表位分布极端长尾，多数表位样本量不足；官方无罕见类合并策略，需使用者自行设定门槛或分组
8	偏倚评估	✅	官方文档与多篇同行评审论文明确讨论 HLA 偏斜、表位覆盖偏斜、物种与链型偏斜；本 Wiki §7.1 系统整理
9	数据字典	✅	仓库 README 完整列出列名与定义；每个 release 附带 .meta.txt 元数据文件；本 Wiki §4.1 整理为字段字典
10	信息性缺失解释	⚠️	空值语义清晰（未提供/未解析），但不同缺失原因（文献未报告 vs 自动化解析失败）未在数据层进一步区分，需结合 cdr3fix.* 判断
11	设备记录	⚠️	method.sequencing / method.singlecell 记录测序方式，但无统一平台型号字段（如具体测序仪或流式细胞仪型号）；10x Genomics 等数据集以 chunk 命名间接体现
12	共线性	⚠️	mhc.a / mhc.b / mhc.class 存在强关联（I 类记录 mhc.b 常为 B2M）；v.segm 与 cdr3 首段重叠（CDR3 起始残基来自 V 段），同时作为特征会引入共线性
13	编码映射	✅	V/J 基因名映射至 IMGT 命名；物种名、方法学取值受词表约束；proofreading/gene_aliases.tsv 与 species_aliases.tsv 提供别名映射
14	时间戳处理	⚠️	记录本身不含时间戳字段，时间信息通过 reference.id 回溯至文献发表年份；数据层无采集日期或随访时间
15	划分建议	❌	官方不提供任何划分建议或切分脚本；本 Wiki §5 基于社区惯例整理推荐策略
16	泄漏讨论	⚠️	官方未专门讨论泄漏问题，但提供 meta.subject.id 与 reference.id 使分组划分可实现；本 Wiki §5.3 系统讨论四类泄漏源
17	标签分布	✅	表位分布可从数据直接统计（本 Wiki §4.2 给出头部表位计数与唯一表位数演进）；无需额外文档
18	测量偏倚	✅	vdjdb.score 基于测序方式、克隆频率、鉴定方式、验证手段四维度量化测量可靠性；论文报告评分与独立复现概率的相关性
19	外部验证建议	⚠️	官方未提供外部验证协议；但社区已形成交叉数据库验证与湿实验验证的实践，本 Wiki §5.5 整理
20	版本记录	✅	GitHub Releases 提供完整版本标签与日期；Zenodo 归档提供永久 DOI；仓库含 36 个 release
21	预处理脚本	⚠️	官方提供数据库装配脚本（Groovy / Python 版）与 CI 校验流程，但不提供面向机器学习任务的数据清洗、划分与负样本构造脚本
22	合规要求	✅	许可证明确为 CC BY-NC 4.0；FAIRsharing 记录完整标注访问条件与许可；禁止商业使用是明确的合规边界
23	多模态对齐	⚠️	序列与 MHC/表位通过 complex.id 对齐；结构证据通过 meta.structure.id（PDB ID）关联，但结构覆盖比例低；官网另提供 AI 预测结构作为独立分区
24	去标识化	✅	不存储原始测序读长与直接标识符；供者标识为研究内部伪匿名；但 TCR 序列与 HLA 组合具准可识别性，需遵守原始文献条款

DAIMS 评分：16.5 / 24

评分解读：VDJdb 在标识体系（#2）、缺失编码（#5）、标签标识（#6）、偏倚评估（#8）、数据字典（#9）、编码映射（#13）、测量偏倚（#18）、版本记录（#20）、合规（#22）、去标识化（#24）十个维度表现优异，这些恰好是「策展型数据库」的核心能力——它有严格的格式规范、可审计的溯源链、明确的证据分级和清晰的许可边界。扣分集中在三类：一是面向机器学习任务的配套完全缺失（#15 划分建议、#21 预处理脚本均为 ❌ 或 ⚠️，无官方切分、无负样本构造、无任务定义）；二是统计可处理性问题（#7 罕见类分组缺失、#4 重复行需自行去重、#1 多值列需展开）；三是元数据粒度不足（#11 无统一设备型号、#14 无时间戳、#10 缺失原因未细分）。

对你意味着什么：把 VDJdb 当作「高质量标注语料」而非「开箱即用的基准」来使用。具体行动建议：第一，在项目立项时就把「任务定义 + 负样本构造 + 划分策略」当作自研工作量的核心部分排期，不要指望官方给你现成的评测协议；第二，把 score ≥ 2 作为默认筛选阈值，并在方法学中记录该选择；第三，读取数据后第一件事是展开多值列并按 (cdr3, gene, epitope) 去重，第二件事是按 meta.subject.id 做分组切分——这两步不做，后续所有性能数字都不可信；第四，若研究结论要对外发表，务必额外做一次独立外部验证（跨数据库或湿实验），因为库内约半数标签不可复现；第五，商业用途需提前与维护方协商许可，CC BY-NC 4.0 不允许直接商用。

§7.8 外部验证矩阵

外部数据集/场景	来源机构	评估任务	性能指标	相对内部变化	关键发现
VDJdb（TCRβ，22 个表位）	数据库自身	表位特异性二分类（LOSO）	TCRGP 均值 AUROC 0.863（全 CDRβ）/ 0.806（仅 CDR3β）；TCRdist 0.783 / 0.743；RF 0.796；DeepTCR 0.776-0.777	基线	使用全部 CDRβ 区优于仅用 CDR3β；模型能对完全新序列做出预测
VDJdb-without-10x 基准	数据库（剔除 10x 数据集）	表位分类	Cross-TCR-interpreter ROC AUC 0.9445 / APS 0.7600；NetTCR-2.0 0.9492 / 0.7262；PanPep 0.9009 / 0.6435	基线	在配对 α-β 链输入下主流方法 ROC AUC 接近；APS 差异更能区分方法优劣
McPAS-TCR → VDJdb 交叉评估	两个独立数据库	单表位结合预测（SPB）	ERGO 在 GLCTLVAML / NLVPMVATV / GILGFVFTL 上 VDJdb 版 AUC 0.816 / 0.835 / 0.843（McPAS 版 0.803 / 0.835 / 0.843）	与同源训练相当	跨数据库训练/评估的性能接近，说明两库在常见病毒表位上覆盖相似
VDJdb 作为 NetTCR-2.1 外部评测集（927 条阳性 / 4 个表位）	数据库	外部泛化评测	相似度过滤可带来约 5% 平均 AUC 提升（未加权）/ 4%（加权）	过滤后提升	训练集与评测集的重叠程度显著影响结果，去泄漏处理是必要的
独立功能复测（对 VDJdb 沉积记录的大规模重新实验）	独立研究团队	反应性复现	约 50% 的 TCR-pMHC 反应性声明得到确认；据此发布验证子集 TCRvdb	显著下降	历史训练数据存在大量标签噪声，「数据库收录」不等于「验证通过」
单 CDR3 精确匹配注释 vs dextramer 金标准	第三方教程	组库注释一致性	仅 CDR3 匹配：996 次调用中 41% 一致；加 V 基因约束：4 次调用中 100% 一致	准确率大幅提升但覆盖骤降	单 CDR3 查库天然歧义，需引入 V 基因或相似度约束

§8 基准性能与生态

§8.1 排行榜

下表汇总在 VDJdb 或其标准子集上报告过性能的代表性方法。各数值不可直接比较，原因见下方说明。

排名	模型	性能	年份	关键技术	完整引用	代码
1	NetTCR-2.0	ROC AUC 0.9492 / APS 0.7262（VDJdb-without-10x）	2021	双链卷积神经网络，同时输入 CDR3α 与 CDR3β	Montemurro A, et al. NetTCR-2.0: sequential and structural integration for TCR-peptide binding prediction. Front Immunol. 2021;12:706096. DOI 10.3389/fimmu.2021.706096	https://github.com/mnielLab/NetTCR-2.0
2	Cross-TCR-interpreter	ROC AUC 0.9445 / APS 0.7600（同类基准）	2023	深度神经网络，α/β 双链 CDR3 联合表征	Springer I, et al. Cross-TCR-interpreter: a deep learning approach to predict TCR-pMHC interaction. Front Bioinform. 2023;3:1274599. DOI 10.3389/fbinf.2023.1274599	https://github.com/SpringerI/CrossTCRinterpreter
3	PanPep	ROC AUC 0.9009 / APS 0.6435	2023	基于元学习的少样本新表位适配框架	Wang Y, et al. PanPep: a meta-learning framework for peptide-TCR binding prediction across epitopes. Nat Mach Intell. 2023;5:1045-1056. DOI 10.1038/s42256-023-00714-5	https://github.com/bm2-lab/PanPep
4	TCRGP	均值 AUROC 0.863（全 CDRβ，LOSO）/ 0.806（仅 CDR3β）	2021	高斯过程 + 序列核，支持不确定性估计	Jokinen E, Huuhtanen J, Mustjoki S, Heinonen M, Lähdesmäki H. Predicting recognition between T cell receptors and epitopes with TCRGP. PLoS Comput Biol. 2021;17(3):e1008814. DOI 10.1371/journal.pcbi.1008814	https://github.com/EmiliaJokinen/TCRGP
5	ERGO-II	AUC 0.816-0.894（多个表位，SPB 任务）	2020	自编码器 + LSTM，可整合 V/J 基因与 MHC 类型	Springer I, Besser H, Tickotsky-Moskovitz N, Dvorkin S, Louzoun Y. Prediction of specific TCR-peptide binding from large dictionaries of TCR-peptide pairs. Front Immunol. 2020;11:1803. DOI 10.3389/fimmu.2020.01803	https://github.com/IdoSpringer/ERGO-II
6	DeepTCR	均值 AUROC 0.776-0.777（LOSO）	2021	卷积 + 循环网络的 TCR 序列分类框架	Sidhom JW, Larman HB, Pardoll DM, Baras AS. DeepTCR is a deep learning framework for revealing sequence concepts within T-cell repertoires. Nat Commun. 2021;12:1605. DOI 10.1038/s41467-021-21879-w	https://github.com/sidhomj/DeepTCR
7	TCRdist	均值 AUROC 0.783（全 CDRβ）/ 0.743（仅 CDR3β）	2021（作为基准复现）	基于 CDR 相似度度量的最近邻方法，无需训练	复现值见 Jokinen et al. 2021（同上）；原方法见 Dash P, et al. Nature. 2017;547:89-93. DOI 10.1038/nature22383	https://github.com/phbradley/tcr-dist
8	随机森林基线	均值 AUROC 0.796	2021	传统机器学习基线	复现值见 Jokinen et al. 2021（同上）	—

⚠️ 数值不可直接比较的五个原因：（1）数据集子集不同——有的用全库，有的用剔除 10x Genomics 的版本（VDJdb-without-10x），两者难度差异显著；（2）划分策略不同——LOSO、留一表位、留一研究与随机划分的结果不可互换，随机划分数值系统性偏高；（3）正负样本构造不同——交换 TCR、随机氨基酸串、真实组库阴性样本三种策略的难度依次递增，随机串会显著夸大性能；（4）指标不同——ROC AUC 与 APS 在不平衡数据上给出的排序可能不一致，仅报 AUC 会掩盖低精度问题；（5）版本不同——数据库持续更新，不同论文使用的 release 快照不同，测试集内容随之变化。

§8.2 SOTA 总结与选型建议

当前在 VDJdb 上表现最好的方法普遍采用「配对 α-β 链联合输入 + 深度架构」的范式，ROC AUC 可稳定达到 0.94 以上。但这一成绩有三个重要限定：第一，评估口径多为已知表位的二分类，而非留一表位的零样本预测；第二，训练与评测数据常与 10x Genomics 数据集高度重叠，存在记忆效应；第三，APS 指标通常只有 0.64-0.76，说明在高召回区域精度仍然有限。

选型建议按场景划分：小样本或需要不确定性量化时选 TCRGP（高斯过程天然提供方差估计，且在仅 CDR3β 的小数据场景仍稳健）；需要配对 α/β 链输入时选 NetTCR-2.0/2.1 或 Cross-TCR-interpreter；需要对新表位做快速适配时选 PanPep 或基于蛋白质语言模型的微调方案；需要快速可解释的基线时选 TCRdist（无需训练，可直接做相似度分析与聚类）；需要与已发表结果对齐时选 ERGO-II（发表较早，复现资料完整）。无论选哪个，都应在自己的留一表位评测集上重新验证，不要直接引用论文数值作为项目预期性能。

§8.3 评测协议建议

协议要素	推荐做法
任务定义	明确声明是单表位二分类、多表位多分类还是留一表位零样本预测；三者不可混用同一结论
数据版本	固定 release tag 并记录 SHA256；在方法学中写明
正样本筛选	默认 `vdjdb.score >= 2`；同时报告全量与 score ≥ 1 的结果做敏感性分析
去重	按 (cdr3, gene, antigen.epitope) 去重；配对任务按 complex.id 透视
划分	按 meta.subject.id 做 GroupKFold；额外报告留一表位结果
去泄漏	计算测试集到训练集的 TCRdist 最近邻距离，剔除低于阈值的样本并报告剔除数量
负样本	使用同库其它表位的 TCR（交换策略）；报告正负比
指标	同时报告 ROC AUC 与 APS；给出 per-epitope 明细与加权平均
分层报告	按表位规模、MHC 类别、病原物种、score 层级分别报告
外部验证	至少做一次跨数据库（McPAS-TCR）或独立数据集的验证

数据集	关系	说明
IEDB	互补	以表位为中心的免疫表位数据库，近年新增 TCR 关联子集；与 VDJdb 构成「表位广度 vs 特异性标注深度」的互补
McPAS-TCR	互补	病理关联的 TCR 序列目录，可与 VDJdb 做交叉验证
PIRD / TBAdb	互补	含已知抗原的 TCR 与 BCR 序列库
TCRdb 2.0	规模互补	约 7 亿条 TCR 序列的景观型资源，几乎不含特异性标签
IMGT	上游依赖	胚系 V/D/J 基因序列参考，是 VDJdb 解析 V/J 段的基础
TCR3d 2.0 / STCRDab	结构互补	TCR-pMHC 三维结构库，与 VDJdb 的序列-特异性关联互补
ATLAS	结构+亲和力互补	野生型与突变型 TCR-pMHC 相互作用的结构与结合亲和力数据
TRAIT	规模与深度互补	整合序列、结构与亲和力的 TCR-抗原交互库，含数百万非互作 TCR

§8.5 关键论文 Top 5-10

Shugay M, Bagaev DV, Zvyagin IV, et al. VDJdb: a curated database of T-cell receptor sequences with known antigen specificity. Nucleic Acids Res. 2018;46(D1):D419-D427. — 数据库首发论文，定义了数据模型、置信度评分体系与策展流程，是理解 VDJdb 设计哲学的起点。
Bagaev DV, Vroomans RMA, Samir J, et al. VDJdb in 2019: database extension, new analysis infrastructure and a T-cell receptor motif compendium. Nucleic Acids Res. 2020;48(D1):D1057-D1062. — 报告数据库扩容逾 5 倍，引入 AIRR-seq 在线批量注释与 TCR motif 汇编（501 个 motif 覆盖 40 个表位）。
Goncharov M, Bagaev D, Shcherbinin D, et al. VDJdb in the pandemic era: a compendium of T cell receptors specific for SARS-CoV-2. Nat Methods. 2022;19(9):1017-1019. — 2019-2022 年更新，重点汇编新冠特异性 TCR，是目前引用 VDJdb 时推荐的规范引用。
Jokinen E, Huuhtanen J, Mustjoki S, Heinonen M, Lähdesmäki H. Predicting recognition between T cell receptors and epitopes with TCRGP. PLoS Comput Biol. 2021;17(3):e1008814. — 建立 VDJdb 上的 LOSO 评测协议与多方法对照基准（TCRGP/TCRdist/RF/DeepTCR），是理解 VDJdb 基准数字来源的关键论文。
Springer I, Besser H, Tickotsky-Moskovitz N, Dvorkin S, Louzoun Y. Prediction of specific TCR-peptide binding from large dictionaries of TCR-peptide pairs. Front Immunol. 2020;11:1803. — 提出 ERGO/ERGO-II 并在 McPAS 与 VDJdb 上做交叉评估，提供了跨数据库泛化的早期证据。
Springer I, et al. Cross-TCR-interpreter: a deep learning approach to predict TCR-pMHC interaction. Front Bioinform. 2023;3:1274599. — 在 VDJdb-without-10x 基准上给出系统性方法对照，包含 APS 指标，是当前较完整的评测参考。
Wang Y, et al. PanPep: a meta-learning framework for peptide-TCR binding prediction across epitopes. Nat Mach Intell. 2023;5:1045-1056. — 面向新表位少样本适配的元学习方法，代表处理 VDJdb 表位长尾问题的技术路线。
Milighetti M, Nagano Y, Henderson J, et al. Systematic analysis of CDR contacts and pairing constraints between T cell receptor chains. Bioinformatics. 2026. — 基于 VDJdb 分析 CDR 间接触与 α-β 配对约束，同时明确指出 VDJdb 数据偏斜、MHC 等位基因信息偶缺、含错误注释序列三项局限，是引用该数据集局限性的权威出处。

§8.6 社区活跃度

指标	数值	时点
GitHub 仓库累计提交	1,322 次	2026 年检索
公开 release 数	36 个	2026 年检索
Open issues	70 个	2025-03
Closed issues	223 个	2025-03
NGDC Database Commons 综合排名	183 / 6,932（97.374 百分位）	2026 年检索
Interaction 类排名	29 / 1,202	2026 年检索
首发论文引用	453 次（Europe PMC 口径）	2026-05-30
NAR 2020 更新论文引用	333 次（Europe PMC 口径）	2026-05-30
Nature Methods 2022 论文引用	167 次（IBCh）/ 165 次 Scopus / 242 次 Dimensions	2026 年检索

社区活跃度评价：issues 与 pull request 双通道并行，投稿流程对领域研究者开放且文档完整；近年引入 AI 辅助策展（Claude Code / GitHub Copilot skills）与 Python 装配脚本，维护活跃度良好。相对而言，用户侧的教程与第三方封装（immunarch、lymphoseq、omicverse、TIRTLtools 等）丰富，说明实际使用生态成熟。

§8.7 生态快照

资源	类型	链接	Star 截至 2026-09	推荐理由
antigenomics/vdjdb-db	官方仓库	https://github.com/antigenomics/vdjdb-db	未公开计数	数据库源头，含 chunks、装配脚本、评分规则与投稿指南
antigenomics/vdjdb-standalone	官方注释工具	https://github.com/antigenomics/vdjdb-standalone	未公开计数	基于 VDJtools 的命令行注释器，适合批量处理
VDJdb 网页端	官方服务	https://vdjdb.cdr3.net/	—	Browse / Annotation / Motif / Structure 五大分区，支持组库批量注释
immunarch（R）	社区工具	https://github.com/immunomind/immunarch	未公开计数	R 生态中最主流的免疫组库分析包，内置 VDJdb 注释接口
lymphoseq（Python）	社区工具	https://lymphoseq.readthedocs.io/	未公开计数	Python 侧封装，自动缓存并查询 VDJdb、McPAS-TCR
omicverse（Python）	社区工具	https://omicverse.github.io/	未公开计数	提供 `vdjdb_reference()` 一键加载与抗原注释、标签一致性评估
TIRTLtools（R）	社区工具	https://nicholasclark.github.io/TIRTLtools/	未公开计数	提供预处理好的 VDJdb 人源参考表及聚类分析流程

§9 相关资源与引用

§9.1 官方资源

资源	地址	说明
VDJdb 官方主页	https://vdjdb.cdr3.net/	数据库浏览、检索、组库注释入口
VDJdb 镜像站点	https://vdjdb.com/	功能分区说明与快速导航
GitHub 主仓库	https://github.com/antigenomics/vdjdb-db	数据 chunks、装配脚本、评分规则、投稿指南
Release 下载页	https://github.com/antigenomics/vdjdb-db/releases	全部历史版本与最新版下载
最新 slim 表直链	https://github.com/antigenomics/vdjdb-db/releases/latest/download/vdjdb.slim.txt	端用户推荐入口
独立注释工具	https://github.com/antigenomics/vdjdb-standalone	命令行批量注释
Web 应用源码与文档	https://vdjdb-web.readthedocs.io/en/latest/intro.html	网页端文档与 API 说明
REST API 元信息	https://vdjdb.cdr3.net/api/database/meta	数据库元信息查询
FAIRsharing 记录	https://fairsharing.org/10.25504/FAIRsharing.nwz68	标准化资源描述与许可信息
NGDC Database Commons	https://ngdc.cncb.ac.cn/databasecommons/database/id/3270	数据库档案与引用统计

§9.2 教程与社区

资源	说明
immunarch 数据库注释教程	R 生态下下载与注释 VDJdb 的完整流程，含本地装配步骤
omicverse AIRR 教程	Python 生态下的抗原注释、标签一致性评估与收敛性分析示例
lymphoseq 文档	Python 侧数据库查询与缓存机制说明
VDJdb GitHub Issues	投稿流程、字段规范讨论与新数据集公告

§9.3 BibTeX 引用

@article{Shugay2018VDJdb,
  title     = {{VDJdb}: a curated database of {T}-cell receptor sequences with known antigen specificity},
  author    = {Shugay, Mikhail and Bagaev, Dmitry V. and Zvyagin, Ivan V. and Vroomans, Renske M. and Crawford, Jeremy Chase and Dolton, Garry and Komech, Ekaterina A. and Sycheva, Anastasiya L. and Koneva, Anna E. and Egorov, Evgeniy S. and Eliseev, Alexey V. and Van Dyk, Ewald and Dash, Pradyot and Attaf, Meriem and Rius, Cristina and Ladell, Kristin and McLaren, James E. and Matthews, Katherine K. and Clemens, E. Bridie and Douek, Daniel C. and Luciani, Fabio and van Baarle, Debbie and Kedzierska, Katherine and Kesmir, Can and Thomas, Paul G. and Price, David A. and Sewell, Andrew K. and Chudakov, Dmitriy M.},
  journal   = {Nucleic Acids Research},
  volume    = {46},
  number    = {D1},
  pages     = {D419--D427},
  year      = {2018},
  doi       = {10.1093/nar/gkx760},
  pmid      = {28977646}
}

@article{Bagaev2020VDJdb,
  title     = {{VDJdb} in 2019: database extension, new analysis infrastructure and a {T}-cell receptor motif compendium},
  author    = {Bagaev, Dmitry V. and Vroomans, Renske M. A. and Samir, Jerome and Stervbo, Ulrik and Rius, Cristina and Dolton, Garry and Greenshields-Watson, Alexander and Attaf, Meriem and Egorov, Evgeniy S. and Zvyagin, Ivan V. and Babel, Nina and Cole, David K. and Godkin, Andrew J. and Sewell, Andrew K. and Kesmir, Can and Chudakov, Dmitriy M. and Luciani, Fabio and Shugay, Mikhail},
  journal   = {Nucleic Acids Research},
  volume    = {48},
  number    = {D1},
  pages     = {D1057--D1062},
  year      = {2020},
  doi       = {10.1093/nar/gkz874},
  pmid      = {31588507}
}

@article{Goncharov2022VDJdb,
  title     = {{VDJdb} in the pandemic era: a compendium of {T} cell receptors specific for {SARS-CoV-2}},
  author    = {Goncharov, Mikhail and Bagaev, Dmitry and Shcherbinin, Dmitrii and Zvyagin, Ivan and Bolotin, Dmitry and Thomas, Paul G. and Minervina, Anastasia A. and Pogorelyy, Mikhail V. and Ladell, Kristin and McLaren, James E. and Price, David A. and Nguyen, Thi H. O. and Rowntree, Louise C. and Clemens, E. Bridie and Kedzierska, Katherine and Dolton, Garry and Rius, Cristina Rafael and Sewell, Andrew and Samir, Jerome and Luciani, Fabio and Zornikova, Ksenia V. and Khmelevskaya, Alexandra A. and Sheetikov, Saveliy A. and Efimov, Grigory A. and Chudakov, Dmitry and Shugay, Mikhail},
  journal   = {Nature Methods},
  volume    = {19},
  number    = {9},
  pages     = {1017--1019},
  year      = {2022},
  doi       = {10.1038/s41592-022-01578-0},
  pmid      = {35970936}
}

@article{Jokinen2021TCRGP,
  title     = {Predicting recognition between {T} cell receptors and epitopes with {TCRGP}},
  author    = {Jokinen, Emmi and Huuhtanen, Jani and Mustjoki, Satu and Heinonen, Markus and L{\"a}hdesm{\"a}ki, Harri},
  journal   = {PLoS Computational Biology},
  volume    = {17},
  number    = {3},
  pages     = {e1008814},
  year      = {2021},
  doi       = {10.1371/journal.pcbi.1008814}
}

§9.4 引用指南

引用数据库本身：推荐引用最新方法学论文 Goncharov et al., Nature Methods 2022（DOI 10.1038/s41592-022-01578-0），并在方法学中同时注明使用的 release 版本与下载日期。若工作侧重数据库架构与评分体系，应同时引用 Shugay et al. 2018；若侧重批量注释功能与 motif 资源，应同时引用 Bagaev et al. 2020。

引用具体数据记录：应追溯到原始文献（reference.id 字段中的 PubMed ID），而非仅引用 VDJdb。数据库条款要求「原始研究被恰当引用」，这是 VDJdb 收录的前提条件。

许可合规要点：VDJdb 采用 CC BY-NC 4.0，署名与非商业性使用是硬性条件。商业用途（包括在商业产品中使用其数据或基于其训练的模型）需另行协商。此外应遵守原始贡献文献各自的使用条款，尤其是涉及人类样本的研究。

§10 AI 使用声明卡

§10.1 AI 模型列表

环节	使用的 AI 模型/工具	用途
资料检索	WebSearch 检索工具	定位官方站点、论文、Releases 页面与社区讨论
内容起草	大语言模型（CodeBuddy Code 内置模型）	章节结构编排、中文表达撰写、代码示例构建
代码生成	大语言模型	§6 全部 Python 示例（数据加载、预处理、DataLoader、评估）
事实核对	人工 + 检索来源交叉验证	逐条核对 FACTS.md 中每条事实的来源 URL

§10.2 AI 参与范围

AI 参与的具体工作包括：整合多来源检索结果并归纳为结构化事实清单；按写作规范编排 §0-§10 章节结构；撰写中文正文表述；生成可运行的 Python 代码示例；整理表格与对比矩阵；翻译与规范英文学术术语。AI 未参与的工作包括：数据库的直接访问与实测（本页面写作过程中未下载或运行过 VDJdb 数据）；为任何规模数字或性能数字提供未经检索来源支持的估计；对医学结论做独立判断。

§10.3 输入来源列表

Shugay M, Bagaev DV, Zvyagin IV, et al. VDJdb: a curated database of T-cell receptor sequences with known antigen specificity. Nucleic Acids Res. 2018;46(D1):D419-D427. https://pubmed.ncbi.nlm.nih.gov/28977646/
Bagaev DV, Vroomans RMA, Samir J, et al. VDJdb in 2019: database extension, new analysis infrastructure and a T-cell receptor motif compendium. Nucleic Acids Res. 2020;48(D1):D1057-D1062. https://orca.cardiff.ac.uk/id/eprint/126624/1/Bagaev et al 2019.pdf
Goncharov M, Bagaev D, Shcherbinin D, et al. VDJdb in the pandemic era: a compendium of T cell receptors specific for SARS-CoV-2. Nat Methods. 2022;19(9):1017-1019. https://pubmed.ncbi.nlm.nih.gov/35970936/csv
VDJdb 官方站点. https://vdjdb.com/
antigenomics/vdjdb-db GitHub 仓库 README（数据库规范、评分规则、投稿指南）. https://github.com/antigenomics/vdjdb-db
antigenomics/vdjdb-db Releases 页面（版本历史）. https://www.github.com/antigenomics/vdjdb-db/releases
VDJdb 首发论文 Table 1（物种/MHC/链型分布）. https://pmc.ncbi.nlm.nih.gov/articles/PMC5753233/table/tbl1/
VDJdb 评分评估 Table 2（评分与独立复现相关性）. https://ard.bmj.com/lookup/external-ref?access_num=10.1093/nar/gkx760&link_type=DOI
Jokinen E, et al. Predicting recognition between T cell receptors and epitopes with TCRGP. PLoS Comput Biol. 2021;17(3):e1008814. https://pmc.ncbi.nlm.nih.gov/articles/PMC8023491/table/pcbi.1008814.t002/
Springer I, et al. Cross-TCR-interpreter. Front Bioinform. 2023;3:1274599. https://public-pages-files-2025.frontiersin.org/journals/bioinformatics/articles/10.3389/fbinf.2023.1274599/pdf
Springer I, et al. Prediction of specific TCR-peptide binding from large dictionaries of TCR-peptide pairs. Front Immunol. 2020;11:1803. https://www.frontiersin.org/journals/immunology/articles/10.3389/fimmu.2020.01803
Data-driven filtering for denoising of TCRpMHC single-cell data: a benchmark. bioRxiv. https://www.biorxiv.org/content/10.1101/2023.02.01.526310.full
Milighetti M, et al. Systematic analysis of CDR contacts and pairing constraints between T cell receptor chains. Bioinformatics. 2026. https://www.ovid.com/00124336-202608000-00035
FAIRsharing 资源记录（许可与访问条件）. https://fairsharing.org/10.25504/FAIRsharing.nwz68
NGDC Database Commons VDJdb 档案（机构、引用统计）. https://ngdc.cncb.ac.cn/databasecommons/database/id/3270
Zenodo 归档版本（pyvdjdb-2025-02-21）. https://zenodo.org/records/598037
omicverse AIRR 教程（注释一致率实测）. https://omicverse.github.io/omicverse-pages/Tutorials-airr/t_airr_04_tcr.html
TIRTLtools VDJdb 参考表说明. https://nicholasclark.github.io/TIRTLtools/reference/vdj_db.html
AI Developments for T and B Cell Receptor Modeling and Therapeutic Design（标签噪声与复测证据）. https://ar5iv.labs.arxiv.org/html/2601.17138
immunarch VDJdb 注释教程. https://rdrr.io/cran/immunarch/f/vignettes/web_only_v0/v11_db.Rmd

§10.4 人工校验表

内容模块	审核者	审核方式	审核状态
frontmatter 与 schema_org	千方病案医学编辑部	字段完整性与占位 URL 规范核验	✅ 已通过
INFOBOX 字段	千方病案医学编辑部	逐项核对来源，动态数据标注检索时点	✅ 已验证
§0 声明与免责	千方病案医学编辑部	固定文本与审核日期一致性核验	✅ 已通过
§1 概览与对比	千方病案医学编辑部	规模数字与来源交叉核对	✅ 已验证
§2 医学背景与 ICD/SNOMED 映射	千方病案医学编辑部（医学审核）	术语与编码准确性核查	✅ 已通过
§3 规格与置信度评分体系	千方病案医学编辑部	评分规则逐条比对官方 README	✅ 已验证
§4 数据结构与 DAIMS 字段字典	千方病案医学编辑部（数据工程审核）	字段名与多值语义核验	✅ 已通过
§5 划分与泄漏分析	千方病案医学编辑部（数据工程审核）	泄漏源分类与缓解措施可操作性核查	✅ 已验证
§6 代码与坑点	千方病案医学编辑部（数据工程审核）	代码逻辑与坑点真实性核查	✅ 已通过
§7 DAIMS 24 项与偏倚分析	千方病案医学编辑部	评分与说明一致性核验	✅ 已验证
§8 基准与引用	千方病案医学编辑部	数值与文献引用完整性核查	✅ 已通过
§9 资源与 BibTeX	千方病案医学编辑部	链接有效性与引用格式核验	✅ 已验证
§10 AI 声明	千方病案医学编辑部	参与范围与来源列表完整性核查	✅ 已通过

§10.5 AI 生成章节标注

本页面全部章节（§0-§10）均由 AI 依据 §10.3 所列来源起草，并经千方病案医学编辑部按 §10.4 表格逐模块人工校验。其中 §6 代码块为 AI 生成的示例实现，逻辑经人工审查但未在真实数据集上完整执行；§6.5 坑点内容基于官方文档、同行评审论文报告的局限性与社区实测经验整理，每条的参考链接均可追溯至原始出处。

§10.6 最后人工审核日期

2026-09-05

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