免疫组库分析12：TCR、BCR序列相似性网络分析-NAIR包介绍(1)

三兔测序学社

发布于 2026-04-17 16:49:26

1440

编者语：

在人工智能时代，其实许多R包说明书只需要上传到AI上就能马上解读含义与用法。那为什么还有翻译出来发表了？以前是人写好文章让AI校对。现在让AI写完文章，人工校对。AI是智能，我是人工。另外，这是一个自己使用过的R包，并在免疫组库相关文章中加以引用说明。其实用到的代码也不过几行而已，但当我写完这个R包的相关使用说明，却足足写了４篇文章，一遍翻译一遍学习。免疫组库实验是我开启生信分析的起点，从TCR、BCR实验方法的建立、DNA测序文库构建、高通量测序下机进行生信分析再到文章发表。因此免疫组库分析系列文章要继续更新下去，成为一件值得做的事情。

一、NAIR概述与核心功能

软件定义：NAIR是一个序列相似性网络分析R包，用于分析T细胞和B细胞的适应性免疫组库（Adaptive Immune Repertoire）序列。

主要目标：识别特定的克隆簇（Clusters）和克隆（Clones）。计算节点和簇的局部及全局网络属性，揭示免疫库网络的结构组织。

二、支持的数据类型

NAIR支持针对T细胞受体（TCR）或B细胞受体（BCR）的多种测序数据：

单细胞数据（Single-cell data）：每一行代表一个单独的细胞。

批量数据（Bulk data）：每一行代表一个独特的TCR/BCR克隆（包含V-D-J基因和核苷酸序列的独特组合），通常包含克隆丰度（如克隆计数、频率）的测量值。

三、网络构建模型：

NAIR将免疫库建模为网络图的逻辑如下：

节点定义：每个细胞（单细胞数据）或克隆（批量数据）作为一个节点。

边的建立：基于受体序列（核苷酸或氨基酸）的相似性。

使用汉明距离（Hamming）或莱文斯坦距离（Levenshtein）衡量节点对之间的差异。当距离低于指定阈值时，两个节点之间建立连接。

特殊处理：对于单细胞数据，可同时考虑两条链（如α链和β链）的序列来确定细胞间的相似性。

聚类分析：使用多种算法将网络图划分为密集连接的子图（簇）。

可视化：生成可自定义的网络图，节点可根据疾病状态、样本、克隆丰度等元数据着色。

四、安装与操作指南

安装方式： CRAN版本：

install.packages("NAIR")

开发版本：通过devtools::install_github从GitHub源码安装。

devtools::install_github(
  "mlizhangx/Network-Analysis-for-Repertoire-Sequencing-",
  dependencies = TRUE, 
  build_vignettes = TRUE
)

五、核心函数与工作流程

主函数： buildRepSeqNetwork() 或别名 buildNet()。

功能包括数据过滤、网络构建、聚类分析、属性计算及绘图。

特色分析流程：关联簇搜索：在批量数据中寻找与二元变量（如疾病状态、治疗结果）相关的TCR/BCR簇。

公共簇搜索：识别跨样本共享的相似克隆（例如CDR3氨基酸序列差异不超过一个氨基酸）。

NAIR通过将免疫库转化为网络图，为研究者提供了一套从数据处理到可视化、从结构分析到临床关联挖掘的完整工具链，是探索适应性免疫系统复杂性的有力手段

六、具体功能举例说明

1.模拟数据下载

set.seed(42)
library(NAIR)
dir_out <- tempdir()
toy_data <- simulateToyData()
head(toy_data)
#>        CloneSeq CloneFrequency CloneCount SampleID
#> 1 TTGAGGAAATTCG    0.007873775       3095  Sample1
#> 2 GGAGATGAATCGG    0.007777102       3057  Sample1
#> 3 GTCGGGTAATTGG    0.009094910       3575  Sample1
#> 4 GCCGGGTAATTCG    0.010160859       3994  Sample1
#> 5 GAAAGAGAATTCG    0.009336593       3670  Sample1
#> 6 AGGTGGGAATTCG    0.010369470       4076  Sample1

1.核心代码解释：

net <- buildNet(toy_data, "CloneSeq")

该功能需要两个核心参数：data，即一个包含AIRR-seq数据的数据框；以及seq_col，即指定包含TCR、BCR序列的列名或列索引，用于计算序列相似度

2：过滤数据：筛选序列长度、排除无关字符

#筛选序列长度
net <- buildNet(toy_data, "CloneSeq", min_seq_length = 10) 
#设定最小长度为10
#排除非标准字母/数字字符的序列，如果序列中包含连字符（-）、星号（*）、空格或其他特殊符号，这些序列都会被过滤掉。
net <- buildNet(toy_data, "CloneSeq", drop_matches = "\\W")

3、（Network Settings）的核心参数

3.1. 距离计算函数 (Distance Function) 该参数决定了如何量化两个 TCR/BCR 序列之间的差异。

默认方法：汉明距离 (Hamming Distance) 计算逻辑：计算两条等长序列在相同位置上的不同字符数量。处理机制：如果序列长度不同，较短的序列会被填充非匹配字符以匹配较长序列的长度。适用场景：适用于长度一致的序列比较。

替代方法：莱文斯坦距离 (Levenshtein Distance) 计算逻辑：计算将一个序列转换为另一个序列所需的最少单字符编辑次数（插入、删除、替换）。优势：能够处理不同长度的序列，特别适合包含插入或删除突变的序列。推荐场景：在构建 CDR-3 核苷酸序列相似性网络时，推荐使用此方法。注意：计算复杂度显著高于汉明距离，处理大规模数据集时需谨慎。代码示例：

# 使用莱文斯坦距离替代默认的汉明距离
net <- buildNet(toy_data, "CloneSeq", dist_type = "lev")

3.2. 距离截断值 (Distance Cutoff) 该参数控制网络构建的严格程度，决定了两个节点是否建立连接。定义：dist_type 函数计算出的距离是一个非负数值，数值越接近 0 表示相似度越高。默认规则：默认情况下，如果两条序列的距离不超过 1，则两个节点之间会建立一条边（Edge）。

严格度控制：

低截断值：要求更高的序列相似度才能形成连接。

dist_cutoff = 0：只有当两条序列完全相同时，节点才会连接。代码示例：

# 设置截断值为0，仅允许完全相同的序列连接

net <- buildNet(toy_data, "CloneSeq", dist_cutoff = 0

3.3. 孤立节点处理 (Keep/Remove Isolated Nodes) 该参数决定网络中是否保留没有连接的节点。默认行为：drop_isolated_nodes = TRUE。默认情况下，仅保留至少与一个其他节点有边连接的节点，移除所有孤立节点。保留设置：若设置为 FALSE，网络将保留所有原始数据中的节点，即使它们没有任何连接（孤立节点）。代码示例：

net <- buildNet(toy_data, "CloneSeq", drop_isolated_nodes = FALSE)

4.网络属性和聚类分析

buildRepSeqNetwork() 还可以执行额外的分析，包括聚类分析（将网络图划分为密集连接的子图）和网络属性计算（描述网络的结构组织）。

4.1节点级网络属性 (Node-Level Network Properties)

节点级网络属性与网络图中的单个节点相关。

局部属性 (Local Properties)：给定节点的值仅取决于网络的一个子集。一个例子是给定节点的网络度（network degree），它代表直接通过边连接到给定节点的其他节点的数量。
全局属性 (Global Properties)：给定节点的值取决于网络中的所有节点。一个例子是节点的权威分数（authority score），它使用整个图的邻接矩阵计算得出（

在调用 buildRepSeqNetwork() 时设置 node_stats = TRUE，或者作为单独的步骤使用 addNodeStats()，可以计算节点级网络属性

net <- buildNet(toy_data, "CloneSeq", node_stats = TRUE)

4.2聚类分析 (Cluster Analysis)

聚类分析使用社区查找算法将网络图划分为簇（clusters）（密集连接的子图）。这些簇代表具有相似受体序列的克隆/细胞组。

在调用 buildRepSeqNetwork() 时设置 cluster_stats = TRUE，或者作为单独的步骤使用 addClusterStats()，可以执行聚类分析。

net <- buildNet(toy_data,"CloneSeq", cluster_stats =TRUE)

每个节点的簇成员身份被记录为节点元数据中的一个变量。簇属性（如节点计数和平均序列长度）包含在输出中的独立数据框中。

5.可视化

# 构建克隆序列网络，结果赋值给net变量
net <- buildNet(toy_data, "CloneSeq",                          # 必选参数：输入数据toy_data，以CloneSeq列为网络节点
                node_stats = TRUE,                              # 开启节点网络统计指标计算
                color_nodes_by = c("SampleID", "transitivity", "coreness"),  # 3种节点着色依据：样本ID、传递性、核数
                color_scheme = c("default", "plasma-1", "mako-1"),          # 对应3种配色：默认、plasma、mako
                color_title = c("", "Transitivity", "Coreness"),            # 对应3个图例标题
                size_nodes_by = "degree",                      # 按节点度（连接数）调整节点大小
                node_size_limits = c(0.1, 1.5),                 # 节点大小范围：最小0.1，最大1.5
                plot_title = NULL,                              # 不设置主标题
                plot_subtitle = NULL,                           # 不设置副标题
                print_plots = TRUE                              # 运行后自动显示网络图
)
saveNetworkPlots(net$plots, outfile = file.path(dir_out, "NAIR_net_3_plots.pdf"))  
#保存图片

6.输出文件

函数返回一个包含以下元素的列表：

#函数返回一个包含以下元素的列表
：
names(net)
#> [1] "details"          "igraph"           "adjacency_matrix" "node_data"       
#> [5] "plots"

具体如下

#Network 元数据 :details记录调用buildRepSeqNetwork（）时提供的参数值：
net$details
#> $seq_col
#> [1] "CloneSeq"
#> $dist_type
#> [1] "hamming"
#> $dist_cutoff
#> [1] 1
#> $drop_isolated_nodes
#> [1] TRUE
#> $nodes_in_network
#> [1] 122
#> $min_seq_length
#> [1] 3
#> $drop_matches
#> [1] "NULL"
#Node元数据节点_Data是包含网络节点元数据的数据，其中每一行对应网络图中的一个节点：

head(net$node_data)
#>         CloneSeq CloneFrequency CloneCount SampleID degree transitivity
#> 2  GGAGATGAATCGG    0.007777102       3057  Sample1      1          NaN
#> 5  GAAAGAGAATTCG    0.009336593       3670  Sample1      3    0.3333333
#> 8  GGGGAGAAATTGG    0.006220155       2445  Sample1      2    1.0000000
#> 11 GGGGGAGAATTGC    0.012969469       5098  Sample1      4    0.6666667
#> 12 GGGGGGGAATTGC    0.009079646       3569  Sample1     10    0.3555556
#> 13 AGGGGGAAATTGG    0.014941093       5873  Sample1      5    0.1000000
#>    eigen_centrality centrality_by_eigen betweenness centrality_by_betweenness
#> 2      1.977313e-17          0.00000000    0.000000                  0.000000
#> 5      1.123438e-16          0.00000000  108.000000                108.000000
#> 8      4.558649e-02          0.04558649    0.000000                  0.000000
#> 11     1.505537e-01          0.15055366    1.549451                  1.549451
#> 12     5.269180e-01          0.52691798   73.970918                 73.970918
#> 13     1.468234e-01          0.14682343   75.439560                 75.439560
#>    authority_score coreness   page_rank
#> 2     9.011927e-19        1 0.008196721
#> 5     6.388353e-18        2 0.010578507
#> 8     4.558649e-02        2 0.003936684
#> 11    1.505537e-01        4 0.005034736
#> 12    5.269180e-01        6 0.011491588
#> 13    1.468234e-01        3 0.008703523
Cluster Metadata
names(net$cluster_data)
#> [1] "cluster_id" "node_count" 
#> [3] "eigen_centrality_eigenvalue" "eigen_centrality_index" 
#> [5] "closeness_centrality_index" "degree_centrality_index" 
#> [7] "edge_density" "global_transitivity" 
#> [9] "assortativity" "diameter_length" 
#> [11] "max_degree" "mean_degree" 
#> [13] "mean_seq_length" "seq_w_max_degree"

#VisualPlots
#plots是一个列表，其中包含所有生成的图表，以及一个用于存储图表中节点布局的矩阵 graph_layout。每个图表均根据为节点着色所依据的变量进行命名。
names(net$plots)
#> [1] "SampleID"     "transitivity" "coreness"     "graph_layout"

7.结果保存

7.1输出目录若为 output_dir 参数提供目录路径，buildRepSeqNetwork() 会将其输出写入文件。若指定的输出目录不存在，将自动创建该目录。

7.2 输出文件格式

默认情况下，buildRepSeqNetwork() 返回的列表会以压缩的 RDS 格式保存。若文件需要在不同计算机之间传输，建议使用 RData 格式，可通过指定 output_type = "rda" 启用。

saveNetwork(net, output_dir = dir_out， output_name = "net", output_type = "rda" )

若需要在 R 环境以外使用分析结果，可指定 output_type = "individual"。此时列表中的每个元素将单独保存为文件，

saveNetwork(net, output_dir = dir_out, output_name = "net",output_type = "individual")

格式如下：节点数据（node_data）和聚类数据（cluster_data）：.csv 格式（使用 write.csv() 保存，聚类数据设置 row.names = FALSE）邻接矩阵（adjacency_matrix）：.mtx 格式详细信息（details）、网络图对象（igraph）和绘图布局（plots$graph_layout）：.txt 格式绘图结果（plots）：.rda（RData）格式

无论 output_type 如何设置，所有绘图结果都会输出至一个 PDF 文件，每页展示一张图。可通过 plot_width 和 plot_height 参数调整每页尺寸（单位：英寸），默认宽度为 12、高度为 10。

7.3 输出文件命名 默认情况下，所有保存的文件均以 MyRepSeqNetwork 为前缀。可通过 output_name 参数（接收字符串）自定义该前缀。当 output_type 为 "rds" 或 "rda" 时，仅保存两个文件（数据文件 + PDF 文件），文件名为自定义前缀 + 对应后缀。示例：若设置 output_name = "NetworkABC" 且 output_type = "rds"，生成的文件为 NetworkABC.rds 和 NetworkABC.pdf。当 output_type = "individual" 时，文件命名规则为自定义前缀 + 后缀标识，规则如下：详细信息：_Details.txt 网络图边列表：_EdgeList.txt 邻接矩阵：_AdjacencyMatrix.mtx 节点元数据：_NodeMetadata.csv 聚类元数据（若存在）：_ClusterMetadata.csv 绘图列表：_Plots.rda 绘图 PDF 文件：.pdf 绘图布局：_GraphLayout.txt 示例：若设置 output_name = "NetworkABC" 且 output_type = "individual"，节点元数据将保存为 NetworkABC_NodeMetadata.csv，PDF 绘图文件保存为 NetworkABC.pdf，绘图列表保存为 NetworkABC_Plots.rda，以此类推。

参考文档：

https://mlizhangx.github.io/Network-Analysis-for-Repertoire Sequencing-/articles/buildRepSeqNetwork.html

免疫组库分析合集

【生信分析】免疫组库基础分析1-V/D/J基因使用频率计算

【生信分析】免疫组库基础分析2-V/D/J基因使用频率可视化图

【生信分析】免疫组库基础分析3-基于V/D/J使用频率的聚类分析

【生信分析】免疫组库基础分析4-VJ/VDJ组合使用频率计算及可视化

【生信分析】免疫组库基础分析5-多样性分析及其指数计算公式

【生信分析】免疫组库基础分析6-克隆子的分布分析（优势克隆与罕见克隆）

【生信分析】免疫组库基础分析7-CDR3长度分析

【生信分析】免疫组库基础分析8-CDR3氨基酸使用频率

【生信分析】免疫组库基础分析9-CDR3 motif分析