上个月帮一位做肿瘤免疫的老师看单细胞数据，发现他还在用最原始的方法——把Cell Ranger跑出来的聚类结果截图，然后挨个去数据库里查marker基因。我问他为什么不直接用Loupe Browser，他的回答特别典型：“那不是个看图的软件吗？”这大概是对Loupe Browser最常见的误解了。它看起来是个图形化查看器，实际上是把10x Genomics单细胞数据变成可交互探索、可快速注释、可输出结论的完整工作台。

这篇内容我会直接从实战角度出发，从数据怎么来、界面怎么看、marker怎么鉴定，到聚类怎么改、结果怎么导回Seurat和Scanpy，把Loupe Browser的完整使用链路拆开讲一遍。适合刚接触单细胞数据分析、正在为密密麻麻的聚类图发愁的同学，也适合那些已经在用Seurat但想让结果更容易跟合作者沟通的资深玩家。

1. Loupe Browser在单细胞分析流程里的准确位置：不是替代Seurat，而是补充

1.1 从fastq到可视化，Loupe Browser到底是哪个环节

单细胞转录组的数据分析链路其实非常清晰。上游是10x Genomics的Cell Ranger，也就是一个命令行工具，负责把原始的fastq测序文件比对到参考基因组、生成基因表达矩阵、跑聚类和降维。下游是Seurat、Scanpy这类需要写代码的分析框架，用来做更精细的批次校正、差异分析、拟时序、细胞通讯等。

Loupe Browser的位置恰好卡在中间。它是一跨平台的桌面软件，直接读取Cell Ranger的输出结果，不依赖任何编程环境。我经常打一个比方：Cell Ranger是工厂，负责把测序原始数据加工成“半成品”，Seurat是需要编程能力才能操作的分析台，而Loupe Browser更像一台显微镜——它不负责生产数据，但它能让你第一时间把完整的细胞图谱看在眼里。

这一点在真实项目里有多重要？Cell Ranger跑完后会在outs目录下生成一个cloupe.cloupe文件，里面已经包含了完整的降维坐标、聚类结果、全基因表达矩阵。这个文件的格式是专门给Loupe Browser用的。也就是说，10x Genomics官方在设计数据分析链条的时候，就已经把Loupe定位成“Cell Ranger和下游编程分析之间的那扇窗口”。

1.2 它能帮你省下多少时间

很多生信同学的问题是：列出来的聚类已经跑完了，但到底每群是什么细胞，还要靠R代码去提取每个cluster的top基因，再拿去做富集或者手动查询。这套流程熟练的话也需要大半天。用Loupe Browser的话，打开文件之后点一个cluster，表达量最高的基因列表马上就显示出来，配合经典marker基因在线验证，15到30分钟完成一轮初步注释是很正常的速度。

还有一个容易被忽略的价值：协作。做临床或者湿实验的同事通常不会R语言，你给他一个Seurat对象，他根本不知道怎么看。但如果你把cloupe文件发过去，他自己装一个免费的Loupe Browser就能打开，翻一翻聚类、查一查基因，还能放大缩小看某个细胞群的空间分布。这种交互式的沟通方式，比截几张图发微信有效得多。

1.3 它不能做什么

我不建议任何人用Loupe Browser包打天下。它没有拟时序分析，没有细胞通讯推断，复杂的批次效应校正也实现不了。对于正式发表的论文，那些需要精确统计模型支撑的分析结果，最终还是要回到Seurat或Scanpy里完成。

Loupe真正的定位是两件事：第一，快速探索阶段，让你对数据有个整体把握；第二，结果呈现阶段，让你把注释好的数据以直观的方式分享给别人。明白这个边界，用起来才不会指望它做出本来不属于它的东西。

2. 准备工作：cloupe文件怎么生成、版本怎么匹配

2.1 三条最常见的cloupe数据来源

第一种来源是cellranger count。这是最常规的单样本分析流程，一条命令跑完，输出目录里就带outs/cloupe.cloupe：

cellranger count --id=sample_01 \ --transcriptome=/path/to/refdata-cellranger-GRCCh38 \ --fastqs=/path/to/fastq \ --sample=sample_01 \ --expect-cells=5000

运行结束后你可以直接检查输出：

ls sample_01/outs/ # cloupe.cloupe filtered_feature_bc_matrix/ metrics_summary.csv ...

第二种来源是cellranger aggr。当你手上有多个样本需要合并分析、消除样本间测序深度差异时，会用它来合并，输出同样是cloupe格式。合并后的loupe文件里会自动携带每个细胞的样本来源信息，方便后续按样本分组比较。

第三种来源跟数据类型有关。如果你做的是5'端免疫组库分析，VDJ的产物是.vloupe文件；如果做的是Visium空间转录组，输出的loupe文件会包含空间位置信息，可以直接在Loupe Browser里查看基因在组织切片上的空间表达分布。这些不同格式的文件，Loupe Browser根据你安装的模块不同，可以一起打开。

2.2 版本兼容这条坎，我建议你直接记住结论

cloupe文件内部记录了版本信息，低版本的Loupe Browser打不开高版本Cell Ranger生成的文件。这个坑我踩过不止一次：有一次是Cell Ranger刚升级，旧版Loupe怎么都打不开新跑出来的文件，报错提示模糊，排查了半天才发现是版本问题。

实操建议就三条。第一，升级之前先去10x Genomics官方支持页面对比一下版本兼容矩阵，这比盲目升级靠谱。第二，如果你长时间不升级Cell Ranger，也不要频繁升级Loupe Browser，保持两者都在一个相对稳定的Gap内。第三，团队协作时，最好约定所有人都用同一版本的Loupe Browser，这样传文件不会出现“你这边打得开我这边打不开”的情况。

2.3 打开文件后，界面先看什么

初次打开cloupe文件，界面中间的画布显示的就是t-SNE或者UMAP降维后的散点图，每个点代表一个细胞，颜色对应聚类分组。顶部或左侧面板可以切换降维方式，我个人的习惯是优先看UMAP——同一份数据在UMAP下的分群结构通常比t-SNE更清晰，类群之间的边界更干净。

左侧的聚类面板会列出所有聚类的编号，每个编号旁边有细胞数量和比例。底部信息栏显示的是当前选中细胞或者当前选中基因的表达信息。第一次拿到文件，建议不要急着操作，先整体观察三件事。

第一，分群是否干净，有没有大量重叠的细胞群；第二，有没有极小比例的异常群，这类群往往是双细胞或者血小板残留，需要在后续注释时特别留意；第三，整体是否符合实验预期，比如PBMC数据应该有明确的淋巴细胞群、单核细胞群，如果全挤成一团，那上游分析可能需要重新审视。

3. 核心实操：从聚类浏览到细胞类型注释，完整跑一遍

3.1 聚类面板是你的启动器

左侧Clusters面板里每一个编号就是一类细胞。随便点中一个cluster，Loupe会自动计算该群与其余细胞相比表达差异最显著的基因，并把排序结果展示出来。这些top基因就是初始注释的核心线索。

我是这么用的：PBMC数据里，点开cluster 0，如果top列表里出现的是CD3D、CD3E、IL7R，那这个群大概率是T细胞；点开另一个cluster，如果MS4A1、CD79A、CD79B排在最前面，这是B细胞跑不掉。整个过程相当于“翻牌”，翻几下，数据的整体格局就有了。

你不需要把所有cluster一次性全注释完。第一轮先用top基因把所有cluster分成大方向：淋巴细胞、髓系细胞、其他。第二轮再针对大方向去细分，比如T细胞群里继续看是CD4阳性还是CD8阳性，单核细胞群里看是经典单核还是非经典单核。

3.2 marker基因验证：用叠加分布替代猜测

自动列出的top基因只能给方向和线索，最终下结论还是要靠经典marker基因逐一验证。这一步在Loupe Browser里非常直观：在基因搜索框输入CD8A，画布上的细胞会按表达量被点亮，颜色深浅代表表达量高低，不表达的细胞保持灰色。你还可以继续叠加CD4、CD8B、NKG7等更多marker，看看它们的表达模式是否互补或者重叠。

这里有一个容易翻车的细节。比如你要给某个T细胞亚群定性，CD4和CD8A理论上应该呈现互补模式——CD4阳性的细胞群和CD8阳性的细胞群应该分布在不同的位置。如果你发现某一群细胞同时高表达CD4和CD8A，不要急着下结论，这可能对应双阳性T细胞，也可能是细胞双粘连体（doublet）造成的干扰，需要结合数据的双细胞评分进一步确认。

常用的人PBMC注释marker，这张表可以帮你快速对照：

用这组marker在你的数据里逐个验证一遍，基本就能覆盖PBMC样本里最常见的细胞类型。如果你做的是肿瘤组织样本，需要额外关注成纤维细胞、内皮细胞、肿瘤上皮细胞相关的marker，例如COL1A1、PECAM1、EPCAM。

3.3 手动注释与命名规范

确认某个cluster的细胞类型后，可以给它重命名。Loupe Browser支持在聚类列表上直接修改identity，把默认的“Cluster 0”改成“CD4+ T Cell”这类可读性强的名字。修改结果会保存到cloupe文件中，后续画图、导出表格、分享给别人时都会沿用新名字。

另外Loupe也支持把若干个cluster合并成一个细胞类型。比如你有两个cluster通过marker验证都指向CD8+ T细胞，那就可以把它们合并。这个功能在实际注释中很常用，能有效减少“把一类细胞人为拆成两群”的干扰。

这里强烈建议你保留一套注释操作规范：文件另存为一个新的cloupe文件，不要在原始文件上直接改。我就吃过亏，有一次想试一下不同合并方式，直接在原文件上反复操作，最后注释信息乱成一团，只能重新跑了一遍Cell Ranger才恢复底稿。每次分析前复制一份原始文件作为不可变底稿，是成本最低的保护措施。

4. 进阶分析：重新聚类、组间比较与功能富集

4.1 用自定义聚类回答“这群里还有什么”

默认聚类数不一定是最优的。这是单细胞分析里的老问题，尤其是当一个大的细胞类型内部实际上是异质的时候。比如你明确知道某一群是T细胞，但T细胞内部有CD4+、CD8+、调节性T细胞等多种状态，它们在默认聚类里可能被扔在同一个大群里，掩盖了内部的异质性。

Loupe Browser的重新聚类功能可以解决这个问题。操作路径在聚类面板里选择Find Clusters，可以对选定细胞重新运行图聚类算法，并设定一个聚类数量的搜索范围。这个过程实际上就是在做不需要写代码的“子聚类”。

我举一个真实项目里的例子。有一次分析肿瘤浸润免疫细胞，T细胞大群一直不能干净区分，因为调节性T细胞（Treg）和CD4+常规T细胞共享很多基因特征。我在Loupe里选中T细胞亚群做重聚类，把聚类数范围设置在5到10之间，跑完之后立刻出现了一个FOXP3和CTLA4高表达的小群——这就是Treg。后续我再用marker验证，结论就非常扎实了。

4.2 多组样本之间的比例变化怎么看

如果你做了cellranger aggr合并分析，cloupe文件里会保留每个细胞来自哪个样本的信息。Loupe Browser的群体比较功能可以针对某一细胞类型，统计它在不同样本中的占比差异。

具体操作很简单：在界面上选择要比较的细胞群，设定样本分组变量，就能看到比例变化的统计结果。比如说你有一个治疗组和一个对照组，想快速知道治疗之后CD8+ T细胞的比例有没有上升，用这个功能半分钟就能得到直观结果。

需要提醒的是，Loupe Browser的比例比较在统计模型上相对轻量。它适合快速探索和内部讨论，但如果要写进论文，还是建议把细胞分群和比例数据导出后，到Seurat或者Scanpy里用更完整的统计模型再跑一遍。

4.3 富集分析：Loupe先跑一遍，再用更细的数据库复核

Loupe Browser内置了基于marker基因列表的功能富集分析。选中某个cluster后，软件会基于该群的高表达基因去匹配已知的生物学通路，输出富集结果。这类分析很适合在探索阶段快速判断一大群细胞属于什么功能类型。

不过Loupe内置富集分析的数据库和算法相对固定，灵活性有限。我的操作习惯是分两步。第一步先用Loupe跑一遍，拿到初步的功能倾向；第二步把差异表达基因导出，到clusterProfiler（R）或者Enrichr这类在线工具里，用更细的数据库比如GO、KEGG、MSigDB再验证一次。两边结果一致，结论才算可靠。

如果Loupe的富集分析没有产生有效结果，先别怀疑数据，大概率是版本问题或者网络受限导致数据库检索失败。这个情况下直接走导出复核路线，反而更省时间。

5. 导出与互通：让Loupe的分析结果顺利回到Seurat和Scanpy生态

5.1 能从Loupe导出的核心资产

很多人用Loupe只停留在“看一下”的阶段，忽略了它其实是一个很好的产出工具。Loupe能导出的核心资产主要有四类：图像、聚类注释、差异表达结果和筛选后的细胞亚群列表。

图像导出时，一定要注意分辨率设置。如果打算放到论文配图或者学术海报里，尽量选择矢量图格式或者高分辨率位图。我踩过这个坑：早期有一次导出低分辨率截图放到组会PPT里，投到大屏幕上全是锯齿，被导师当场追着问图为什么这么糊，后来所有正式图都固定用高分辨率导出。

差异表达结果导出的是CSV表格，包含基因名、p值、log2倍数变化等完整字段。这个表很重要，它可以直接拖到Excel里做二次筛选，也可以用R读进来跟Seurat的差异分析结果做交叉验证。

5.2 把Seurat的注释结果导回Loupe，打通“反向链路”

Loupe不只是单行道，它同样支持把你的正式分析结果导回来看。10x官方提供了loupeR这个R包，专门用来把Seurat对象转成Loupe Browser可以打开的cloupe文件：

library(loupeR) CreateLoupeFileFromSeurat(seurat_object, output_name = "my_annotated_result")

运行完这行代码，就会生成一个新的cloupe文件。用Loupe Browser打开后，你在Seurat里做过的所有降维坐标、聚类信息、细胞注释全都会保留下来。这意味着你可以在Seurat里做好严谨分析，然后把它变成Loupe文件，用Loupe来画最终展示图或者跟合作者分享。

Python用户对应的是loupepy这个包。loupepy可以从anndata对象创建Loupe文件，也可以读取cloupe文件里的数据。Scanpy用户完整分析完后，一样可以用loupepy把结果转成可视化友好的格式。

这条反向链路打通之后，Loupe的作用就从“探索工具”升级成了“展示前端”。你的正式分析在Seurat/Scanpy里完成，展示和交互式沟通在Loupe里完成，各取所长，效果非常好。

5.3 团队协作时的文件管理建议

cloupe文件通常比较大，几十MB到几百MB都很常见，因为里面包含了完整的表达矩阵。团队共享时建议配合文件服务器或者网盘同步工具，而不是通过微信或者邮件传来传去。

另一个经验是，文件名里最好带上版本号和日期。比如20250115_CD8_subset_v2.cloupe。因为分析过程中你会不断生成新版本的注释结果，如果没有版本管理意识，很容易出现“发给你的不是最终版”这种尴尬情况。既然Loupe就能承担沟通媒介的功能，文件名规范就要跟上。

6. 实际爬坑记录：版本、性能、误操作这些常见问题，一次说清楚

6.1 打不开文件或者报错版本不一致

这是出现频率最高的问题。现象很直接：双击cloupe文件，Loupe弹出一个错误提示，大意是文件版本无法识别或者创建版本不一致。原因基本就一个，Cell Ranger生成数据和Loupe Browser打开数据之间的版本gap超出了兼容范围。

解决思路是按优先级排查：先升级Loupe Browser到最新版，重新打开文件；如果还是不行，确认Cell Ranger的具体版本号，到官方兼容矩阵里查对应Loupe版本；再不行，检查文件是否传输完整，用文件哈希比对一遍。我遇到过两次“打不开”最后排查下来是文件传了一半断了，不是版本问题。

6.2 加载大文件卡顿、内存占用飙升

cloupe文件携带了完整的细胞×基因表达矩阵，当你打开的是几万甚至几十万个细胞的数据时，内存占用会明显上升。这是正常的，不代表软件有问题。

处理办法有三个：第一，操作前关闭其他占内存的应用，给Loupe留出充足空间；第二，不要同时打开多个大型cloupe文件，Loupe的多标签页能力有限；第三，如果是几十万细胞级别的超大文件，建议用cellranger aggr时考虑是否可以通过过滤低质量细胞来控制文件大小，或者拆分到染色体层面？这个不推荐。更务实的方式是直接在数据量适中的子集上做探索，完整数据集的分析放Seurat/Scanpy里跑。

6.3 注释改乱之后怎么恢复

注释操作（重命名、合并、重新聚类）都会修改cloupe文件。如果直接在原始文件上反复操作，一旦改乱，返回去重来很麻烦。

两条经验供参考。第一，每次拿到新数据，第一时间复制一份原始cloupe文件存到一个“backup”目录里，以后只操作副本。第二，Loupe里的注释结果也支持导出备份，定期把当前注释状态导出成独立的文件，即使主文件损坏，也能从备份恢复大部分工作。

6.4 导出图片模糊、富集分析没结果

导出图片模糊的问题，几乎都是没有调整输出分辨率。Loupe不同版本的导出设置位置略有差异，但基本都有清晰度相关选项，正式出图时直接选最高档，或者使用启动图格式。

富集分析没结果，上面也提过，多数是网络或者数据库无法访问导致的。遇到这种情况不要死磕，把差异基因列表导出，用在线富集工具（比如Enrichr）跑一遍，效果往往更好。

下面用一张表总结这些问题，方便以后排查：

6.5 一个常被忽略的细节：细胞群颜色映射

Loupe Browser聚类颜色默认是按Cluster编号分配的。当你删除或者合并某个cluster之后，颜色映射可能会跟着变化，同一个颜色在不同的图片里可能代表不同的细胞类型。写报告的时候如果没注意这一点，很容易造成读者误会。

我的建议是，确定细胞类型注释后就锁定每个细胞类型的颜色，尽量不随便改动。一组图里保持颜色规则统一，比任何图例标注都直观。

7. 我的Loupe Browser使用心得，算是一个私人工作流

分享几套自己摸索出来的完整工作流组合。

对新项目，我拿到Cell Ranger结果后的流程是：先用Loupe Browser做一轮快速浏览，确认聚类质量，判断是否需要重跑上游参数。接着用Seurat做正式分析，包括批次校正、差异分析、细胞注释。分析完成后用loupeR把Seurat对象转成cloupe文件，再用Loupe Browser画出版级图像并把结果分享给合作者。

对合作者交流，我通常只传两个文件：一个是cloupe文件，一个是PDF版的注释总结。cloupe文件让他们自己交互式查看，PDF方便快速扫读核心结论。这种方法比任何截图都直观，也比抱着一堆R代码去解释高效得多。

Loupe Browser真正教会我的事情是：数据可视化不只是分析结束后的展示工具，它本身就应该是分析流程里的导航仪。先把整体结构看在眼里，才知道下一步往哪个方向深入分析。这一点，恰恰是命令行工具很难给你的体验。