tooluniverse-immune-repertoire-analysis

ToolUniverse 免疫受体库分析

用于分析 T 细胞受体（TCR）和 B 细胞受体（BCR）受体库测序数据的综合技能，可用于表征适应性免疫应答、克隆扩增和抗原特异性。

领域推理

受体库多样性反映了免疫历史。高克隆性——少数克隆占据主导地位——表明存在抗原驱动的扩增，常见于活动性感染、肿瘤浸润淋巴细胞或慢性刺激。低多样性则提示免疫缺陷或治疗导致的淋巴细胞减少。得出结论前，务必将观测指标与健康供者的参考分布进行比较；在健康成人中，Shannon 熵为 7 并不异常，但在化疗后则令人担忧。

查证，不要猜测

• 克隆型频率阈值、CDR3 长度范围和趋同比率：查询 IEDB 或 VDJdb；不要凭记忆臆测数值。
• 扩增克隆的表位特异性：搜索 iedb_search_tcell_assays 和 BVBRC_search_epitopes；切勿仅凭 CDR3 推断抗原身份。
• 健康供者中的 V 基因家族使用偏倚：获取已发表的参考数据或查询 ImmPort；不要假设基线分布均匀。
• 测序深度是否足够：根据实际数据计算稀释曲线；不要猜测深度是否足够。

---

概述

适应性免疫受体库测序（AIRR-seq）通过对 TCR 和 BCR 可变区进行高通量测序，全面分析 T 细胞和 B 细胞群体。本技能提供一个包含 8 个阶段的工作流，用于：

• 克隆型识别与追踪
• 多样性与克隆性评估
• V(D)J 基因使用分析
• CDR3 序列表征
• 克隆扩增与趋同检测
• 表位特异性预测
• 与单细胞表型分析相结合
• 纵向受体库追踪

---

核心工作流

阶段 1：数据导入与克隆型定义

从常见格式（MiXCR、ImmunoSEQ、AIRR 标准、10x Genomics VDJ）加载 AIRR-seq 数据。将列统一为：cloneId、count、frequency、cdr3aa、cdr3nt、v_gene、j_gene、chain。使用以下三种方法之一来定义克隆型：

• cdr3aa：仅使用 CDR3 氨基酸序列
• cdr3nt：核苷酸 CDR3 序列
• vj_cdr3：V 基因 + J 基因 + CDR3aa（最常用，推荐）

按克隆型聚合数据，按计数排序，并分配排名。

阶段 2：多样性与克隆性分析

计算受体库的多样性指标：

• Shannon 熵：总体多样性（越高 = 多样性越高）
• Simpson 指数：随机抽取两个克隆时，它们属于同一克隆的概率
• Inverse Simpson：有效克隆型数量
• Gini 系数：克隆型分布的不平等程度
• 克隆性：1 - Pielou 均匀度（越高 = 克隆性越强）
• 丰富度：独特克隆型的数量

生成稀释曲线，评估测序深度是否足够。

阶段 3：V(D)J 基因使用分析

分析按克隆型计数加权的 V 和 J 基因使用模式：

• V 基因家族使用频率
• J 基因家族使用频率
• V-J 配对频率
• 对偏倚使用情况进行统计检验（与均匀预期进行卡方检验）

阶段 4：CDR3 序列分析

表征 CDR3 序列：

• 长度分布：TCR CDR3 通常为 12-18 个氨基酸；BCR CDR3 通常为 10-20 个氨基酸
• 氨基酸组成：按克隆型频率加权
• 标记异常的长度分布（可能表明存在 PCR 偏倚）

阶段 5：克隆扩增检测

识别频率高于阈值的扩增克隆型（默认值：第 95 百分位数）。跨多个时间点纵向追踪克隆型，以测量其持续性、平均/最高频率和倍数变化。

阶段 6：趋同与公共克隆型

• 趋同重组：不同核苷酸序列产生相同的 CDR3 氨基酸序列（抗原驱动选择的证据）
• 公共克隆型：多个样本/个体共有的克隆型（可能表明存在共同的抗原应答）

第 7 阶段：表位预测与特异性

查询表位数据库，查找已知的 TCR-表位关联：

• IEDB（iedb_search_tcell_assays）：按序列或 MHC 类别搜索 T 细胞检测记录；使用 iedb_search_epitopes 和 sequence_contains 搜索基序
• BVBRC（BVBRC_search_epitopes）：最适合基于生物体发现表位（例如，使用 taxon_id="2697049" 搜索 SARS-CoV-2）；返回表位序列以及 T 细胞/B 细胞检测计数
• VDJdb（VDJDB_* 工具——截至撰写本文时有 228,214 条整理后的记录）：
  • VDJDB_search_cdr3——按 CDR3 氨基酸序列（精确匹配或子串）搜索，以查找其是否有记录在案的抗原特异性
  • VDJDB_get_antigen_specificity——反向查询：给定 epitope（抗原肽序列，例如 "GLCTLVAML"），查找所有已确认能识别该表位的 TCR，并提供 mhc.a/mhc.class 限制、antigen.gene/antigen.species 来源以及 reference.id（PMID）
  • VDJDB_get_database_summary——记录数量和可用列，适用于构建筛选查询前查看
  • 已验证实时查询：VDJDB_get_antigen_specificity({"epitope": "GLCTLVAML"}) 会返回针对这一广为人知的 EBV BMLF1 表位（受 HLA-A*02:01 限制）的真实 TCR，每个结果均包含其 CDR3、V/J 片段和来源 PMID——相较于仅根据 CDR3 推断，这是直接且置信度更高的表位特异性查询途径
• PubMed 文献（PubMed_search_articles）：搜索 CDR3 与表位/抗原/特异性相关内容
• IEDB 详情工具：iedb_get_epitope_antigens（关联表位→抗原）、iedb_get_epitope_mhc（MHC 限制）

第 8 阶段：与单细胞数据整合

将 TCR/BCR 克隆型关联到配对单细胞 RNA-seq 的细胞表型：

• 将克隆型映射到细胞条形码
• 在 UMAP 上识别扩增克隆型的表型
• 分析克隆型与簇的关联（交叉制表）
• 查找簇特异性克隆型（某个簇中占比 >80% 的细胞）
• 差异基因表达：比较扩增细胞与未扩增细胞

---

ToolUniverse 工具集成

使用的关键工具：

• iedb_search_tcell_assays - T 细胞检测记录（序列、MHC 类别筛选条件）
• iedb_search_bcell - B 细胞检测记录
• iedb_search_epitopes - 使用 sequence_contains 搜索表位基序
• BVBRC_search_epitopes - 基于生物体发现表位（最适合病原体特异性查询）
• VDJDB_search_cdr3 / VDJDB_get_antigen_specificity - 经整理的 CDR3 到表位特异性查询（超过 228K 条记录）
• NCBI_SRA_search_runs - 查找公开的 TCR/BCR-seq 数据集（使用 strategy="AMPLICON"）
• ImmPort_search_studies - NIAID 免疫学研究（疫苗试验、流式细胞术）
• PubMed_search_articles - TCR/BCR 特异性文献
• UniProt_get_entry_by_accession - 抗原蛋白信息

与其他技能集成：

• tooluniverse-single-cell - 单细胞转录组学
• tooluniverse-rnaseq-deseq2 - Bulk RNA-seq 分析
• tooluniverse-variant-analysis - 体细胞超突变分析（BCR）

---

快速入门

from tooluniverse import ToolUniverse

# 1. Load data
tcr_data = load_airr_data("clonotypes.txt", format='mixcr')

# 2. Define clonotypes
clonotypes = define_clonotypes(tcr_data, method='vj_cdr3')

# 3. Calculate diversity
diversity = calculate_diversity(clonotypes['count'])
print(f"Shannon entropy: {diversity['shannon_entropy']:.2f}")

# 4. Detect expanded clones
expansion = detect_expanded_clones(clonotypes)
print(f"Expanded clonotypes: {expansion['n_expanded']}")

# 5. Analyze V(D)J usage
vdj_usage = analyze_vdj_usage(tcr_data)

# 6. Query epitope databases
top_clones = expansion['expanded_clonotypes']['clonotype'].head(10)
epitopes = query_epitope_database(top_clones)

---

结果解读推理框架

证据分级

等级	标准	示例
强	克隆扩增频率 > 1%，已确认存在趋同重组，在 IEDB/VDJdb 中匹配到表位	CDR3 频率为 5%，有 3 种编码相同氨基酸的核苷酸变体，并且在 IEDB 中有匹配结果
中等	扩增克隆（0.1-1%），V(D)J 偏倚显著（chi-sq p < 0.01），部分匹配表位	克隆频率为 0.5%，存在 TRBV20-1 偏倚，在 VDJdb 中找到相似的 CDR3 基序
弱	低频扩增（0.01-0.1%），仅有一个时间点，没有表位数据库匹配结果	中度扩增的克隆，但无趋同现象或已知特异性
证据不足	低于检测阈值，测序深度 < 10,000 个克隆型，无重复样本	单例克隆型，可能是 PCR/测序伪影

解读指南

• 克隆性指标：Shannon 多样性衡量受体库的整体复杂度（数值越高，多样性越高；健康血液中的典型范围为 5-12）。Gini 系数的范围为 0（完全均匀）至 1（单个克隆占主导）；数值 > 0.3 表示可能存在克隆扩增。克隆性（1 - Pielou's evenness）> 0.2 表示存在中度克隆优势；> 0.5 表示存在强烈的寡克隆扩增（常见于活动性感染或肿瘤浸润淋巴细胞）。
• V(D)J 使用情况的意义：V 或 J 基因使用偏倚（与预期均匀分布相比，卡方检验 p < 0.01）可能表明存在抗原驱动的选择。然而，即使在健康受体库中，基线 V 基因使用情况也并非均匀分布，这是由基因组邻近性和重组效率造成的。尽可能与健康供者参考分布比较，而不是与均匀分布进行比较。
• CDR3 汇聚的含义：汇聚性重组（不同核苷酸序列产生相同 CDR3 氨基酸序列）是抗原驱动选择的有力证据，因为彼此独立的重组事件汇聚到相同受体上。个体间共享的公共克隆型会进一步增强这一推断。扩增克隆的汇聚比（每个氨基酸序列对应的核苷酸变体数）> 2 值得关注。
• 测序深度：稀释曲线趋于平台表示测序深度充足。如果曲线仍在上升，则丰富度和多样性估算值会偏低。建议的最低测序深度：bulk TCR-seq 总读取数为 50,000-100,000。
• 纵向追踪：跨时间点持续存在且频率稳定或升高的克隆，表明其受到抗原驱动而维持。短暂扩增后消失的克隆可能反映急性反应。

综合问题

1. 观察到的克隆扩增模式（Gini 系数、最高克隆频率）是否符合预期的免疫背景（例如，疫苗接种后扩增、肿瘤浸润淋巴细胞寡克隆性）？
2. 是否在队列中的多个个体间发现了汇聚的 CDR3 序列，提示存在针对共同抗原的公共反应？
3. 扩增的克隆型是否表现出 V 基因使用偏倚，且与已知的抗原特异性受体库特征一致（例如，CMV 特异性反应中 TRBV20-1 富集）？
4. 测序深度是否充足（稀释曲线已达到平台），足以可靠估算多样性指标并检测低频扩增克隆？
5. 对于纵向数据，克隆动态（扩增、收缩、持续存在）是否与临床结局或治疗反应相关？

---

参考文献

• Dash P, et al. (2017) Quantifiable predictive features define epitope-specific T cell receptor repertoires. Nature
• Glanville J, et al. (2017) Identifying specificity groups in the T cell receptor repertoire. Nature
• Stubbington MJT, et al. (2016) T cell fate and clonality inference from single-cell transcriptomes. Nature Methods
• Vander Heiden JA, et al. (2014) pRESTO: a toolkit for processing high-throughput sequencing raw reads of lymphocyte receptor repertoires. Bioinformatics

---

另请参阅

• ANALYSIS_DETAILS.md - 全部 8 个阶段的详细代码片段
• USE_CASES.md - 完整用例（免疫疗法、疫苗、自身免疫、单细胞整合）和最佳实践