在单细胞转录组项目里，只要一跑 inferCNV，几乎每个人都要跟热图下面那棵 dendrogram 较几回劲。最近我就收到一个特别典型的提问：“热图下方的分层聚类树上只显示 observed 这个标签，我明明期望看到 0-9 号上皮细胞亚群的具体分组信息，这该怎么解决？”这个问题我当时也踩过，一眼看过去上下两难：热图倒是出来了，可聚类树上的标签完全不是你注释文件里的那些亚群，任谁都会懵。其实这不代表 inferCNV 跑挂了，而是它可能压根没拿到你以为它拿到了的那张分组注释表。这篇文章我就把背后的原因拆干净，再给你一套从快速判断、排查到复现修复的完整操作，新手照着抄也来得及。
inferCNV 输出热图下方的 dendrogram，本质上是把样本或亚群按推断出来的拷贝数变异信号做了层次聚类，正常情况下列名标签应该来自你输入的注释文件，也就是 0-9 号上皮亚群。如果只出现 observed，很多时候就是注释文件没有正确被识别，或者你用来画图的参数让所有细胞被归到了一个叫做 observed 的大组里。接下来我会从图结构、注释格式、聚类参数三个层面逐一切入，最后给出不重跑也能改的方案。如果你正好卡在这，别急，按下面的思路走一遍，基本都能改回来。
1. 先复现问题：热图正常、树不正常的常见表现
1.1 “observed”这个标签到底是从哪里冒出来的
inferCNV 的核心逻辑，是拿每个细胞的表达量沿染色体位置滑动计算，然后与一组参考细胞对比，得出每个位置的相对拷贝数信号。最后画出来的热图，列是细胞，行是按染色体排序的基因，红蓝色块代表拷贝数增益或缺失。为了让结果更直观，包会自动对细胞或者亚群做层次聚类，生成 dendrogram 挂在热图边缘。
这就涉及一个问题：聚类树上的叶节点标签来自哪里？正常情况下，inferCNV 会读取你提供的注释文件，根据第二列的分组信息把细胞分成若干个组，然后对每个小组的平均信号做层次聚类，所以聚类树的每个叶节点标签应该是 “0 号亚群”“1 号亚群” 这种你定义好的组名。
如果你看到叶节点标签只有一个 observed，那说明在 inferCNV 眼里，所有的细胞并没有被拆分成多个小簇，而是全部被当成了一组“观测细胞”。这个 observed 不是你想表达的上皮亚群，它是 inferCNV 对“你要分析的主体细胞”的默认命名。换句话说，你辛辛苦苦准备的 0-9 号分组信息，它压根没看到。
1.2 快速判断：是绘图参数问题，还是对象本身就没有分组信息
拿到这种“只有 observed”的热图，第一件事不是急着重跑，而是先确认 inferCNV 对象里到底存了什么。如果你用readRDS读回输出目录里的infercnv.obj，可以执行：
obj <- readRDS("infercnv_output/infercnv.obj")然后看看对象里跟注释相关的字段。inferCNV 对象通常会保留输入时的注释分组，你可以尝试：
table(obj@tumor_subclusters)如果对象里只有一组名字，说明问题出在初建对象那一步；如果对象里有 0-9 号分组，但画出来的图仍然只显示 observed，那就是绘图参数的问题。这个快速判断能帮你少走很多弯路，我习惯把它放在整个排查流程的第一步。
2. 为什么树上的标签不是你的分组：从 inforCNV 图结构拆原因
2.1 热图下方的 dendrogram 是怎么画出来的
inferCNV 画图时，并不是拿原始细胞直接画树，而是会对“表达量的均值矩阵”做聚类。如果你在运行 inferCNV 时指定了注释文件，它会把同一个亚群里的所有细胞先合并成一条平均信号，再对亚群信号做层次聚类。这样出来的树，叶节点就是亚群名，比如 0、1、2……9。
但这里有一个隐藏逻辑：如果你传给CreateInfercnvObject的annotations_file格式不正确，inferCNV 可能会拒绝读取第二列，或者把所有行都读成同一个组。更宽松的做法是把每一个细胞当作一组，但那样树会非常大，而且容易出问题。为了容错，开发者给了一个默认组名，就是 observed。所以当树标签只有 observed，基本可以断定：注释文件没有被正确解析，或者一切细胞都落进了同一个组。
2.2 “observed”和“reference”在图里的分工
inferCNV 的热图通常会把观测细胞和参考细胞分开放置，左侧/上方可能是参考组，右侧/下方可能是观测组，或者反过来。在plot_cnv函数里，有两个专门控制图例标题的参数：obs_title和ref_title，默认值一个是"Observed"，一个是"Reference"。
如果你调用plot_cnv时没有显式设置这两个参数，图例上自然会出现 observed。注意这个 observed 是热图区域的大标题，不是聚类树叶节点的分组标签。可很多初学者会把这两者混在一起看，以为自己看到的就是树标签。所以你要先确认：你截图里那个 observed 是贴在热图区块上的大标题，还是树叶子上密集排列的文本。如果是大标题，那其实没问题，你只需要找到真正显示 0-9 号标签的位置，或者调整绘图尺寸。
如果是树叶标签，才需要进入第三步的注释排查。
3. 核心排查：三个最容易埋坑的位置
3.1 注释文件格式是不是让 inferCNV“看不懂”了
我见过最多的问题，就是注释文件格式不对。inferCNV 对annotations_file的要求非常死板：必须两列，第一列是细胞 barcode，第二列是分组名，不能有表头，列与列之间用 Tab 分隔，单元格不能有引号、空格或中文逗号。如果你在 Excel 里编辑后直接另存为 CSV，或者为了方便自己看加了个表头，inferCNV 就会把表头那行也读成一个细胞，后面的分组全部错位。
更隐蔽的错误是 barcode 对不上。比如表达矩阵的列名是AAACCTGGTAA-1，但注释文件里写成了AAACCTGGTAA_1，或者少了后面的-1，inferCNV 在做匹配时就会漏掉大量细胞。漏掉之后，它能读到的有效注释就很少，最终可能整个分析只剩一个默认组 observed。
建议用一个简单命令检查注释与表达矩阵的重合度：
counts <- readRDS("counts.rds") ann <- read.table("annotation.txt", header = FALSE, sep = "\t", stringsAsFactors = FALSE) sum(ann$V1 %in% colnames(counts))如果匹配数远低于细胞总数，说明你的注释文件里有一批 barcode 对不上，需要回到 Seurat 或上游分析里重新导出一份干净的注释。
3.2ref_group_names参数是不是写错了
inferCNV 不是“跑完就结束”的工具，它必须要你指定哪些组是参考组。在CreateInfercnvObject里，ref_group_names是一个字符串向量，里面的值必须和注释文件第二列里的某些组名完全一致。如果你有 0-9 号上皮亚群，又单独有一个正常上皮或免疫细胞作为参考，你就应该把那个参考组名写进ref_group_names。
这里容易翻车的地方是空格。比如注释文件里写的是normal，但代码里写的是"normal "或者"Normal"，inferCNV 就会找不到参考组。更严重的是，如果你的注释文件里所有细胞都被标成了observed，而ref_group_names只写了某个不存在的名字，inferCNV 会认为没有参考细胞，于是把所有细胞都当成观测细胞，结果就是热图下方的树只有一个 observed 标签。
正确的做法是保证注释和参数严格一致，并且至少留一个组作为参考组。参考组不一定是正常上皮，免疫细胞、基质细胞都常被拿来当参考背景，关键是这些细胞不能有大规模拷贝数变异。
3.3 绘图时是不是勾了不合适的cluster_by参数
inferCNV 运行完之后，画图函数的cluster_by参数也会影响树上标签。这个参数用来控制聚类层级，如果设成"sample"，树的叶节点会按样本名聚类，标签自然变成样本名；默认情况可能是"subclusters"，这时会按注释文件中的分组聚类，标签就是你的亚群名。
如果你在plot_cnv里覆盖了这个参数，比如设了cluster_by = "obs"，那聚类树会基于全部观测细胞而不是分组来做，叶节点标签可能就只剩一个 observed。所以当你重绘热图时，建议显式写成：
plot_cnv(infercnv_obj, out_dir = "replot", cluster_by = "subclusters", obs_title = "tumor", ref_title = "normal")这样能最大程度避免把树标签误压成 observed。
4. 实操修复：重新准备注释并重跑 inferCNV
4.1 从 Seurat 对象重新生成注释文件
如果确认注释文件这关没过，就别抱侥幸心理了，直接重新生成一份干净的注释，然后重跑 inferCNV。这里给你一套我常用的“抄作业”代码。
假设你有一个 Seurat 对象seu，其中seu@meta.data$celltype里的值是 0-9 号上皮亚群，并且还有一部分细胞是normal参考组，处理流程如下：
library(infercnv) # 导出计数矩阵，注意选 counts 而不是 data，inferCNV 推荐用原始计数 counts <- GetAssayData(seu, slot = "counts") # 构造两列注释 ann <- data.frame( barcode = colnames(counts), group = as.character(seu$celltype), stringsAsFactors = FALSE ) # 输出前先检查 group 分布 table(ann$group) # 写文件：无表头，Tab分隔，不自动加引号 write.table(ann, file = "annotation_for_infercnv.txt", sep = "\t", row.names = FALSE, col.names = FALSE, quote = FALSE)导出之后一定要回去核对一眼ann的 barcode 是否与counts列名完全一致，包括-1后缀。不一致的话，需要在导出前统一格式，比如：
colnames(counts) <- gsub("\\.", "-", colnames(counts))4.2 构建对象并正确运行 inferCNV
有了新注释，再写CreateInfercnvObject就好办了。关键是把ref_group_names写对：
gene_order <- read.table("gene_order.txt", sep = "\t", header = FALSE, stringsAsFactors = FALSE) infercnv_obj <- CreateInfercnvObject( raw_counts_matrix = counts, annotations_file = "annotation_for_infercnv.txt", gene_order_file = "gene_order.txt", ref_group_names = c("normal") ) infercnv_obj <- infercnv::run( infercnv_obj, cutoff = 0.1, out_dir = "infercnv_with_labels", cluster_by = "subclusters", denoise = TRUE, HMM = TRUE, num_threads = 4 )跑完去输出目录看infercnv.png。如果注释文件里的 group 列正确，下方 dendrogram 的叶节点就会对应出现你设置的 0-9 号标签，而不是孤零零一个 observed。需要提醒的是，cluster_by = "subclusters"对细胞数量有要求，如果每个亚群细胞太少，inferCNV 可能会警告并合并簇，这时标签会变少，但不至于只剩下 observed。
5. 不想重跑？用 plot_cnv 重绘和手动改标签的补救法
5.1 用已有对象加上正确绘图参数重绘
如果你已经跑完 inferCNV，并且确认对象里的注释分组是正确的，只是绘图时被某个参数带偏了，那完全可以不重跑。直接用plot_cnv再画一次就行。
obj <- readRDS("infercnv_output/infercnv.obj") plot_cnv(obj, out_dir = "replot_after_fix", title = "InferCNV", obs_title = "tumor", ref_title = "normal", cluster_by = "subclusters")这里cluster_by = "subclusters"是关键，它会强制按亚群聚类并显示相应标签。如果你更习惯用自定义色板，还可以传custom_color_palette参数。这个方案适合那些只想快速出图、不想花十几分钟重算的人。
5.2 如果对象里就只有一个组，怎么硬救
救命的是，有些时候我们可以直接修改 inferCNV 对象里的 dendrogram 叶子标签，把 observed 改成期望的标签。但前提是树里面确实有多个叶子。如果树只有一个叶子，那改标签也救不回来，说明模型根本没有分组信息，必须重跑。
如果树叶子其实是多个，只是标签写错了，可以这样操作：
obj <- readRDS("infercnv_output/infercnv.obj") # 看看树结构 str(obj@tumor_subclusters) # 找到 dendrogram 对象 dend <- obj@tumor_subclusters$dendrogram # 如果叶子数目跟你的分组数一致，就可以改标签 labels(dend) <- desired_group_labels # 写回对象 obj@tumor_subclusters$dendrogram <- dend # 重绘 plot_cnv(obj, out_dir = "replot_after_editing", cluster_by = "subclusters")这个操作更适合已经确认分组数一致的情况。如果叶子数远远多于实际亚群数，比如每个细胞都独立一个叶子，那改标签會非常复杂，不如回到第 4 节重新跑。总体上，我个人的习惯是：能重跑就重跑，因为 inferCNV 运行了几十分钟，重画一张图可省不了太多时间，而重跑能保证注释、聚类、树绘制的全链路一致。
6. 常见问题速查表与避坑心得
6.1 一张表帮你快速定位
| 现象 | 可能原因 | 优先解决方式 |
|---|---|---|
| 树标签只有一个 observed | 注释文件读取失败或所有细胞被归为一组 | 检查并修正注释文件，重跑 inferCNV |
| 热图区块上写着 observed 但树标签正常 | 没有设置obs_title参数 | 在plot_cnv中指定obs_title = "tumor" |
| 注释文件里的分组是 0-9，但输出树标签是数字编号 | cluster_by指定了"sample" | 改成"subclusters"重绘 |
| barcode 在注释和计数矩阵里匹配不上 | 分隔符或后缀不一致 | 统一 barcode 格式后重新生成注释 |
ref_group_names写了但报错 | 字符串有空格或大小写不一致 | 用dput(unique(ann$group))检查精确值 |
| 每个亚群细胞太少，标签合并 | 亚群细胞数不够 | 合并亚群，或使用更大的 cut 阈值 |
6.2 我踩过坑之后总结的三条实战经验
第一，注释文件永远先读回来再看一眼，不要迷信在 R 里数据框是对的，写出去就会对。最稳的方法是把write.table写出的文件再用read.table读一遍，确认格式和分组数没问题，再喂给 inferCNV。
第二，参考组不是越多越好。inferCNV 需要参考组足够“正常”，如果你把一些本身有大段 CNV 的细胞放进去当参考，热图的对比会失真，聚类树也会偏向异常组，标签可能变得奇怪。最好先看 UMAP 里细胞分布，把明确正常的细胞用作参考。
第三，别忽视输出目录里的日志。inferCNV 在跑的过程里会输出一些 warning，比如 “found 1 groups of cells” 之类的提示，看到这种日志基本就能提前预判树标签会变成 observed。日志比图诚实得多，早发现问题可以省下大量无效等待。
这个内容后续还可以这样扩展：如果你想进一步美化热图，可以提取 inferCNV 对象里的表达矩阵和聚类树，用 ComplexHeatmap 自己组装出更多注释条带，包括 p 值、基因模块等。但在那之前，把树标签这个基础问题解决掉，是最让人踏实的一步。至少在我见过的项目里，改好注释再跑一遍后，那股“明明注释了却看不见”的憋屈感瞬间就会消失。
