组库成千上万条序列？RIOT 入门：批量 V(D)J 注释与 AIRR 输出

发表于 | 分类于
BCR 组库、百万 FASTA、Spark 流水线——RIOT（riot-na）如何核酸/蛋白双通道批注释、输出 AIRR 标准表，安装与用法一篇读懂。

导读：BCR/TCR 高通量测序一次产出成千上万条序列，你需要 V/D/J 是谁、是否 productive、能否直接进组库 pipeline。RIOT（pip install riot-na）专为这类批量注释设计：核酸和蛋白都能吃，输出对齐 AIRR 标准。

抗体高通量测序与组库筛选往往一次产出成千上万条序列，你需要快速得到：V/D/J 胚系是谁、CDR 边界在哪、序列是否有效（productive）、能否直接接入下游数据库。RIOT（Rapid Immunoglobulin Overview Tool，快速免疫球蛋白总览工具）由波兰 Natural Antibody 团队开源，PyPI 包名为 riot-na，正是为这类批量序列注释场景设计。

需要澄清一点：RIOT 做的是免疫球蛋白序列层面的结构域注释与编号（可变区、FR/CDR、胚系归属），不是 AlphaFold 一类三维坐标结构预测工具。

段末注释：AIRR 兼有生物学含义（某样本全部 BCR/TCR 序列集合）与数据标准含义（MiAIRR 元数据 + Rearrangement 等 Schema）；详见 文件格式说明 - AIRR。

官方资源：GitHub NaturalAntibody/riot_na · PyPI riot-na · Colab 示例

1. RIOT 能做什么

图 1　RIOT 工作流：序列输入 → Rust 预过滤 → 胚系比对与编号 → AIRR 格式输出（科普示意）

能力 说明
双输入类型 核苷酸（NT）与氨基酸（AA）序列均可直接注释
V(D)J 胚系指派 输出 v_call、d_call、j_call、c_call 等
多编号方案 IMGT、Kabat、Chothia、Martin，CLI/API 一键切换
生产力判断 productive、stop_codon、vj_in_frame、移码标志等
高通量 Rust 预过滤 + 多进程；支持 FASTA 批处理
多结构域 单条融合蛋白中多个 Ig 域分别编号（bispecific、CAR 等）
标准输出 扩展 AIRR Rearrangement 字段，便于组库 pipeline 对接
自定义胚系库 支持 CUSTOM 物种，可自建 OGRDB 风格数据库

一句话定位：RIOT 是「核酸 + 蛋白都能吃、本地跑得动、输出够标准」的抗体序列注释引擎，适合测序后处理与 Spark/HPC 批量化。

[!tip] 快速记住
组库百万条 + 要 AIRR 标准表 → 优先 RIOT。

2. 工作原理

2.1 Rust 预过滤 + 胚系比对

RIOT 核心分两层：

  1. riot_prefiltering（Rust）：对查询序列做快速预筛选，缩小候选胚系空间，显著降低全库比对的计算量。
  2. Python 比对与编号层：将序列与内置胚系库比对，完成 V(D)J 基因调用、FR/CDR 切分，并按所选方案映射到位点编号。

胚系数据主要来自 OGRDB（Open Germline Receptor Database，开放胚系受体数据库）；恒定区 C 基因 参考 NCBI IgBLAST 发布库。默认覆盖 人（Homo sapiens） 与 鼠（Mus musculus），也支持导入自定义库（见官方第二份 Colab）。

2.2 核酸通道 vs 氨基酸通道

图 2　RIOT 核酸（NT）与氨基酸（AA）双通道及共享胚系库（科普示意）

通道 API 入口 特有逻辑
NT create_riot_nt() 可检测反向互补、vj_in_frame、移码；输出翻译序列 sequence_aa
AA create_riot_aa() 直接对蛋白序列编号；可选 extend_alignment 保留 V 基因上游未比对片段

两条通道共享编号方案与物种过滤参数，输出结构分别对应 AirrRearrangementEntryNT 与 AirrRearrangementEntryAA。

2.3 多结构域模式

开启 --multiple-domains（或 API 中 return_all_domains=True）时，RIOT 不再只返回最佳单域匹配，而是：

  • 在一条长肽/融合蛋白中检测多个 Ig 可变域；
  • 为每个域单独给出编号结果与域边界（segment_start / segment_end）；
  • 适用于双特异性抗体、CAR 构建体等一条序列含多个 VH/VL 的情形。

3. 安装与环境

3.1 依赖

  • Python ≥ 3.10，< 4
  • C 编译器（scikit-bio 等依赖需要）

3.2 PyPI 安装（推荐）

官方提供各平台预编译 wheel，一般无需本地编译 Rust：

1
pip install riot-na

验证：

1
riot_na --help

3.3 Docker 与源码

仓库含 Dockerfile，适合容器化部署。从源码开发需 Poetry + Rust + maturin 编译 riot_prefiltering 模块，步骤见 GitHub README。

4. 用法

4.1 命令行 CLI

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 单条核酸序列，默认 IMGT 编号，JSON 打印到 stdout
riot_na -s GGGCGTTTTGGCAC...

# FASTA 批处理，输出 CSV
riot_na -f input.fasta -o results.csv

# 氨基酸输入 + Chothia 编号 + 人源胚系
riot_na -s QVQLQQSGAEVVRSGASVKLSCTAS... --input-type AA --scheme CHOTHIA --species HOMO_SAPIENS

# 多结构域融合蛋白
riot_na -f fusion.fasta --multiple-domains true -o domains.csv

# 多核并行（默认物理核数）
riot_na -f big.fasta -p 16 -o out.csv

常用参数：

参数 含义
-f / -s FASTA 文件或单条序列
-o 输出 CSV（缺省 stdout）
--scheme IMGT / KABAT / CHOTHIA / MARTIN
--species HOMO_SAPIENS / MUS_MUSCULUS / CUSTOM
--input-type NT（默认）或 AA
-p 并行进程数
--multiple-domains 返回所有检测到的 Ig 域

4.2 Python API

核酸：

1
2
3
4
5
6
7
8
9
from riot_na import create_riot_nt, Organism, Scheme

riot_nt = create_riot_nt(allowed_species=(Organism.HOMO_SAPIENS,))
result = riot_nt.run_on_sequence(
    header="seq1",
    query_sequence="GAACCAAACTGACTGTCCTAGGCCAGCCCAAGTCTTCGCCATCAGTCACCCTGTTTCCACCTTCCCCTGAAGAGCTAAAAAAA",
    scheme=Scheme.IMGT,
)
print(result.v_call, result.productive, result.numbering_scheme)

氨基酸：

1
2
3
4
5
6
7
8
9
from riot_na import create_riot_aa, Organism, Scheme

riot_aa = create_riot_aa(allowed_species=(Organism.HOMO_SAPIENS,))
result = riot_aa.run_on_sequence(
    header="vh1",
    query_sequence="QVTLKESGPVLVKPTETLTLTCTVSGFSLSNARMGVSWIRQPPGKALEWLAHIFSNDEKSYSTSLKSRLTISKDTSKSQVVLTMTNMDPGDTATYYCARRGGTIFGVVIILVRRPPL",
    scheme=Scheme.KABAT,
    extend_alignment=True,
)

4.3 多进程与 Spark

RiotNumberingNT/AA 对象内含 Rust 预过滤状态，不可 pickle，不能直接传入 multiprocessing.Pool 或 Spark UDF 作为参数。

正确做法：在 worker 内调用 get_or_create_riot_nt() / get_or_create_riot_aa() 缓存包装器，每个进程自行获取实例。官方 README 提供 mp.Pool 与 PySpark UDF 完整示例；纯 Python 方案见仓库 riot_na/api/api_mp.py。

5. 输出字段（AIRR 扩展）

RIOT 结果对象基于 AIRR Rearrangement Schema 裁剪扩展，所有字段必填但可空（除 sequence_header、sequence 外）。AIRR（Adaptive Immune Receptor Repertoire，适应性免疫受体组库）在此指 AIRR Community 制定的组库数据交换标准；Rearrangement 即单条 V(D)J 注释记录。完整定义见 文件格式说明 - AIRR 与 官方 Rearrangement Schema。

段末注释：AIRR 兼有生物学含义（某样本全部 BCR/TCR 序列集合）与数据标准含义（MiAIRR 元数据 + Rearrangement 等 Schema）；RIOT 输出属于后者。

核心字段包括：

类别 代表字段 含义
胚系调用 v_call, d_call, j_call, c_call 最佳匹配的胚系等位基因
编号 numbering_scheme, scheme_residue_mapping 所用方案与位点—残基映射
区域序列 fwr1_aa…cdr3_aa 等 按方案切分的 FR/CDR 片段
有效性 productive, stop_codon, vj_in_frame 是否为可表达的有效重排
比对 v_sequence_alignment, junction, junction_aa 与胚系的比对与连接区
验证标志 conserved_C23_present 等 保守半胱氨酸/色氨酸等位点检查

完整字段表见 GitHub README · Data format 与 AIRR Rearrangement Schema 官方文档。下游组库分析、克隆筛选、突变统计可直接消费这些列，无需再手写解析 V-QUEST 网页结果。

6. 典型应用场景

场景 RIOT 能帮你什么
BCR/TCR 测序后处理 批量 V(D)J 注释 + productive 过滤
杂交瘤 / 单克隆验证 快速确认胚系与 CDR3 序列
组库数据标准化 输出 AIRR 兼容表，接入 Immcantation 等生态
双特异性 / CAR 构建体 --multiple-domains 拆分多 VH/VL
编号方案对照 同一批序列切换 IMGT/Kabat/Chothia
Spark / HPC 流水线 多进程 + 缓存 API，适合百万级 FASTA

7. 优缺点

7.1 优势

  1. NT + AA 统一工具：不必为核酸与蛋白各维护一套注释流程。
  2. 速度快：Rust 预过滤 + 并行，适合大规模组库。
  3. 开放胚系库：内置 OGRDB，支持自定义扩展。
  4. 输出标准化：AIRR 扩展格式，利于数据库与 pipeline 对接。
  5. 安装简单：PyPI wheel 开箱即用；提供 Docker 与 Colab。
  6. 多编号方案：IMGT、Kabat、Chothia、Martin 一处切换。

7.2 局限

  1. 物种覆盖：默认真人/鼠；其他物种需自定义胚系库。
  2. 主要面向 Ig：TCR 等需确认库与测试覆盖是否满足项目需求。
  3. 不做三维结构预测：不输出原子坐标或复合物建模。
  4. 许可限制：非商业机构可免费非商业使用；商业用途需查阅 LICENSE。
  5. 多进程注意点：须用 get_or_create_* 包装器，否则 pickle 报错。

8. 功能边界

RIOT 聚焦 免疫球蛋白序列的 V(D)J 注释与编号，下列任务超出其设计范围：

问题 RIOT 能否直接解决
预测抗体三维结构坐标 否
抗原—抗体对接或亲和力 否
全蛋白非 Ig 结构域注释 否（仅 Ig 相关域）
在线交互式免疫遗传学数据库浏览 否（本地/CLI 工具）
仅恒定区深度注释 有限（有 c_call，非主线）

擅长回答：这条序列（核酸或蛋白）的 V/D/J 是谁、按所选方案 FR/CDR 怎么编号、是否 productive、能否导出成 AIRR 表。

9. 实践建议

  1. 先定输入类型：测序原始读段用 NT；表达/预测蛋白用 AA 并视情况开 extend_alignment。
  2. 固定版本：记录 pip show riot-na 版本与胚系库发布日期，便于结果复现。
  3. 并行用缓存 API：get_or_create_riot_nt/aa，不要跨进程传递 create_riot_* 对象。
  4. 融合蛋白开多域模式：长序列含多个 VH/VL 时务必 --multiple-domains true。
  5. 核对保守位点标志：conserved_C23_present 等可用于快速 QC 异常编号。
  6. 自定义库：非人鼠项目参考官方 Colab：构建自定义胚系库。

10. 小结

维度 要点
本质 开源高通量抗体序列注释引擎（riot-na）
输入 核酸或氨基酸；单条 / FASTA
核心输出 V(D)J 调用 + 多方案编号 + AIRR 扩展字段
技术亮点 Rust 预过滤、多进程、多结构域、双通道 API
擅长 组库后处理、批量胚系注释、pipeline 标准化
局限 非结构预测、默认人鼠、商业许可需单独确认

RIOT 回答的是：「这批免疫球蛋白序列，遗传学上怎么注释、按哪种编号方案切分、能否直接进组库分析 pipeline」。

参考文献与链接

  1. Dudzic P. et al. RIOT—Rapid Immunoglobulin Overview Tool. Briefings in Bioinformatics (2024). doi:10.1093/bib/bbae632
  2. GitHub：https://github.com/NaturalAntibody/riot_na
  3. PyPI：https://pypi.org/project/riot-na/
  4. Colab 入门：示例 notebook
  5. OGRDB：https://ogrdb.org/
  6. AIRR 格式说明：fileformat-airr · AIRR Standards
-------------本文结束感谢您的阅读-------------