RareQ教程(下):从安装代码到单细胞/空间应用场景

写在前面

上一篇推文我们主要解读了 RareQ 的 Nature Communications 文章和功能框架。简单说，RareQ 是一个用于识别单细胞和细胞分割空间组学数据中稀有细胞群的 R 包。它的核心不是重新发明一套前处理流程，而是接在 Seurat 等常规流程之后，利用 kNN 图中的邻域连通性 Q 值来发现小而紧密的细胞群。

这一篇更偏实操：RareQ 怎么安装、怎么跑、需要准备什么对象、关键参数怎么理解，以及它适合应用在哪些场景。

先说结论：如果你已经会 Seurat，那么 RareQ 的上手成本并不高。最关键的一步是，在 FindNeighbors() 里设置 return.neighbor = TRUE，让 Seurat 对象保留 RareQ 需要的 neighbor slot。

RareQ 的安装

RareQ 是 R 包，GitHub README 给出的安装方式如下：

library(devtools)install_github("fabotao/RareQ")

根据 GitHub README，主要依赖包括：

R >= 4.0.0Seurat >= 4.0.2Signac >= 1.9.0  # 仅在 scATAC-seq 预处理时需要

如果你使用的是 conda 环境，可以先准备一个相对干净的 R 环境，再安装 Seurat、Signac 和 RareQ。由于单细胞包依赖较多，建议不要直接在长期使用的旧 R 环境里硬装。

conda create -n rareq_r r-base=4.3 -yconda activate rareq_r

然后进入 R：

install.packages("devtools")install.packages("Seurat")devtools::install_github("fabotao/RareQ")

如果 GitHub 网络不稳定，也可以从 Zenodo 下载归档源码，或先在服务器上配置 GitHub mirror。安装完成后：

library(RareQ)library(Seurat)

scRNA-seq 最小可运行流程

RareQ 官方 README 使用 Jurkat 示例数据演示 scRNA-seq 流程。这里整理成更通用的骨架。

library(RareQ)library(Seurat)# 1. 构建 Seurat 对象sc_object <- CreateSeuratObject(  counts = counts,  project = "sc_object",  min.cells = 3)# 2. 标准 scRNA-seq 预处理sc_object <- NormalizeData(sc_object)sc_object <- FindVariableFeatures(sc_object, nfeatures = 2000)sc_object <- ScaleData(sc_object)sc_object <- RunPCA(sc_object, npcs = 50)sc_object <- RunUMAP(sc_object, dims = 1:50)# 3. 关键步骤：保存 neighbor 信息sc_object <- FindNeighbors(  object = sc_object,  k.param = 20,  compute.SNN = FALSE,  prune.SNN = 0,  reduction = "pca",  dims = 1:50,  force.recalc = FALSE,  return.neighbor = TRUE)# 4. RareQ 识别 major 和 rare clusterscluster <- FindRare(sc_object)table(cluster)sc_object$RareQ_cluster <- clusterDimPlot(sc_object, group.by = "RareQ_cluster", label = TRUE)

注意这里的 FindNeighbors() 不只是为了后续 Seurat 聚类，而是 RareQ 的输入基础。RareQ 会读取 sc_object@neighbors 中保存的邻居矩阵，所以如果忘了 return.neighbor = TRUE，通常会报 neighbor slot 不存在。

FindRare 参数怎么理解

RareQ 的核心函数是：

FindRare(  sc_object,  assay = "RNA",  k = 6,  Q_cut = 0.6,  ratio = 0.2,  max_iter = 100)

几个参数的含义可以这样理解：

我建议第一次运行先用默认参数。若结果看起来过碎或过合并，再围绕 k、Q_cut、ratio 做小范围敏感性分析。

结果怎么解释

RareQ 输出的是一个 cluster assignment 向量，既包括 major clusters，也包括 rare clusters。后续不能只看 table(cluster)，还要做标准注释和验证。

table(sc_object$RareQ_cluster)DimPlot(sc_object, group.by = "RareQ_cluster", label = TRUE)markers <- FindAllMarkers(  sc_object,  group.by = "RareQ_cluster",  only.pos = TRUE,  min.pct = 0.1,  logfc.threshold = 0.25)head(markers)

建议对每个小 cluster 做下面几类检查：

ConsensusRare：什么时候需要共识分析

RareQ README 还提供了 ConsensusRare()，用于多次打乱细胞顺序运行 FindRare()，再通过 consensus clustering 聚合结果。

cluster <- ConsensusRare(  sc_object,  assay = "RNA",  reduction = "pca",  dims = 1:50,  k.param = 20,  k = 6,  Q_cut = 0.6,  ratio = 0.2,  reps = 30)table(cluster)sc_object$RareQ_consensus <- clusterDimPlot(sc_object, group.by = "RareQ_consensus", label = TRUE)

它的用途不是替代 FindRare()，而是做稳定性检查。比如你发现了一个很有意思的 0.2% 小群体，但担心它对细胞顺序或初始化敏感，就可以用 ConsensusRare() 验证它是否稳定出现。

缺点也很明确：更慢、更耗内存。大数据集上不建议一开始就跑，可以先用 FindRare() 快速定位候选，再对重点数据做共识分析。

多模态数据怎么接入

RareQ 的关键输入是低维 embedding 和 kNN neighbor graph，所以它并不局限于 RNA 表达矩阵。

CITE-seq

CITE-seq 可以分别从 RNA、ADT 或 WNN embedding 角度找 rare cells。

# 常规 RNA 流程obj <- NormalizeData(obj, assay = "RNA")obj <- FindVariableFeatures(obj, assay = "RNA")obj <- ScaleData(obj, assay = "RNA")obj <- RunPCA(obj, assay = "RNA", reduction.name = "pca")# ADT 流程可用 CLR 等标准处理obj <- NormalizeData(obj, assay = "ADT", normalization.method = "CLR")# 如果已经完成 WNN 分析，可基于 WNN/sPCA 或相应 reduction 构建 neighborsobj <- FindNeighbors(  object = obj,  reduction = "pca",  dims = 1:30,  k.param = 20,  compute.SNN = FALSE,  prune.SNN = 0,  return.neighbor = TRUE)obj$RareQ_RNA <- FindRare(obj, assay = "RNA")

实际使用时要注意 assay 和 neighbor slot 的对应关系。最稳妥的方式是每做一种 embedding，就清楚记录它对应的 assay、reduction 和 neighbor 名称。

scATAC-seq

scATAC-seq 通常先用 Signac 做 TF-IDF、SVD/LSI，再基于低维 embedding 构建 kNN。

library(Signac)library(Seurat)library(RareQ)obj <- RunTFIDF(obj)obj <- FindTopFeatures(obj, min.cutoff = "q0")obj <- RunSVD(obj)obj <- FindNeighbors(  object = obj,  reduction = "lsi",  dims = 2:30,  k.param = 20,  compute.SNN = FALSE,  prune.SNN = 0,  return.neighbor = TRUE)obj$RareQ_ATAC <- FindRare(obj, assay = "ATAC")

论文方法中也提到，scATAC-seq 常排除第一个 SVD component，因为它可能与 fragment number 高相关。这个细节在 ATAC 分析中很重要。

Xenium / cell-segmented spatial data

对于 Xenium、EEL FISH 这类细胞分割后的空间转录组数据，RareQ 可以把每个 cell 当作节点，用表达特征降维后构建 kNN，再识别空间上小而有组织结构意义的群体。

sp_obj <- NormalizeData(sp_obj)sp_obj <- FindVariableFeatures(sp_obj)sp_obj <- ScaleData(sp_obj)sp_obj <- RunPCA(sp_obj, npcs = 30)sp_obj <- FindNeighbors(  object = sp_obj,  reduction = "pca",  dims = 1:30,  k.param = 20,  compute.SNN = FALSE,  prune.SNN = 0,  return.neighbor = TRUE)sp_obj$RareQ_cluster <- FindRare(sp_obj)

空间数据的重点不是只看 UMAP，而是要把 RareQ cluster 映射回组织坐标：

ImageDimPlot(sp_obj, group.by = "RareQ_cluster")

如果某个 rare cluster 在 UMAP 上很小，但在组织中位于 TLS、血管周围、肿瘤侵袭边界或特定解剖层，它的生物学价值就会明显提高。

应用场景一：肿瘤微环境稀有免疫细胞

RareQ 很适合用于肿瘤免疫数据，尤其是寻找低比例但功能重要的髓系细胞、树突状细胞、增殖细胞、T cell 状态或 TLS 相关结构。

推荐分析路径：

1. 先做常规大类注释：T/NK、B/plasma、myeloid、epithelial/tumor、stromal、endothelial。 2. 对每个大类分别运行 RareQ，而不是全体细胞一锅跑。 3. 重点检查 rare myeloid、rare DC、rare proliferating tumor cells、rare exhausted/cytotoxic T cell states。 4. 结合 marker、通路、空间位置和临床分组判断生物学意义。

示例：

myeloid <- subset(obj, idents = c("Mono", "Macrophage", "DC"))myeloid <- RunPCA(myeloid, npcs = 30)myeloid <- FindNeighbors(  myeloid,  reduction = "pca",  dims = 1:30,  k.param = 20,  compute.SNN = FALSE,  prune.SNN = 0,  return.neighbor = TRUE)myeloid$RareQ_cluster <- FindRare(myeloid)

应用场景二：疾病相关 rare state

在 Alzheimer disease、炎症性疾病、纤维化、感染和自身免疫病中，少量细胞可能处在疾病相关 reactive state。RareQ 可以用来寻找这些低比例状态，再结合病例/对照、疾病分期或治疗反应做验证。

分析时建议不要直接说“发现新细胞类型”。更稳妥的说法是：

后续需要用 marker、通路、样本复现性和独立队列验证。

应用场景三：空间组学中的小结构

空间数据里，稀有群体的意义常常来自位置。比如 TLS、血管周围 niche、肿瘤边界、上皮隐窝、神经解剖层、炎症灶等。

RareQ 的结果如果只在 UMAP 上好看，价值还不够；必须映射回组织坐标。

推荐输出包括：

应用场景四：多组学中 RNA 看不到、蛋白/ATAC 看得到的小群体

CITE-seq 和 multiome 数据中，有些 rare cells 在 RNA 上并不明显，但 ADT 或 ATAC 信号很突出。RareQ 可以分别在 RNA、ADT、ATAC、WNN embedding 上运行，然后比较结果。

建议做一个对照表：

这样可以避免只用一种模态下结论。

不适合直接用 RareQ 的情况

RareQ 不是万能稀有细胞发现器。下面几类情况要谨慎：

1. 数据批次效应很强，且 rare cluster 与 batch 完全重合。 2. 样本量太少，某个 cluster 只来自一个样本。 3. QC 很差，低 UMI、高线粒体细胞形成小团块。 4. doublet 未处理，两个大群混合细胞被识别成稀有群体。 5. 研究问题本身关注连续轨迹，而不是离散小群体。

在这些场景中，RareQ 仍可作为探索工具，但不能直接作为结论来源。

一个推荐的完整分析清单

跑完 RareQ 后，建议按下面清单整理结果：

1. RareQ cluster 数量和每群细胞比例。 2. 每群的样本来源和批次分布。 3. 每群 QC 指标：nFeature、nCount、percent.mt、doublet score。 4. 每群 top marker genes。 5. 与常规 Seurat cluster 的对应关系。 6. 是否在多个样本中复现。 7. 是否与疾病、治疗、预后或空间区域相关。 8. 是否需要独立数据集或实验验证。

小结

RareQ 最适合放在常规单细胞/空间组学流程的中后段：前面仍然用 Seurat/Signac 做标准 QC、降维和邻居图构建，RareQ 负责进一步识别被常规聚类忽略的小而紧密的候选稀有群体。

对生信项目来说，它的价值不是替代人工注释，而是提供一个系统挖掘 rare cell candidates 的入口。真正能写进文章的结果，还需要 marker、通路、样本复现性、空间定位和临床/实验验证一起支撑。

参考资料

1.RareQ GitHub repository and tutorials: https://github.com/xiaolab-xjtu/RareQ

2.Fa B, Huang C, Ma Y, Zhao W, Xu Y, Xiao Z. Cell neighborhood topology directs rare cell population identification. Nature Communications. 2026;17:4618. DOI: 10.1038/s41467-026-71180-x. https://www.nature.com/articles/s41467-026-71180-x

3.RareQ Zenodo archive and tutorial data: https://doi.org/10.5281/zenodo.17190972

关注公众号，下回更新不迷路