简介：这份单细胞转录组数据查找指南配套项目代码，面向刚接触单细胞分析的生信初学者与需要快速定位公共数据的研究人员，帮助解决数据来源分散、检索效率低、下载易出错等问题。资源包共3个文件，以inscode项目配置、html页面和gitignore为主，整体约9KB，结构轻量，便于直接打开查阅或嵌入现有分析流程。内容围绕GEO、Single Cell Portal、Human Cell Atlas等常用数据库展开，重点演示如何用布尔逻辑运算符构建精确查询、利用GEO分类功能细化结果，并说明数据格式识别、质量检查、版本选择及许可协议与引用规则等下载注意事项。已有131人学习，适合希望系统掌握单细胞数据检索与获取思路、为后续细胞分化、肿瘤异质性或发育生物学分析打基础的读者参考。
1. 单细胞转录组数据查找指南：从一份代码包说起
做单细胞分析的人大概都有过这种体验：手头一堆 fastq 或矩阵文件，却不知道从哪一步开始查、用什么工具查、查完怎么对齐到参考注释。这份「单细胞转录组数据查找指南」代码包，解决的就是这个从原始数据到可解释结果的检索链路问题。它不是某个具体分析流程的教程，而是一套围绕「查找」这个动作组织起来的代码资源——帮你定位细胞类型、查找标记基因、检索公共数据集里的可比样本。适合已经跑过 CellRanger 或 STARsolo、手里有表达矩阵但卡在注释和检索环节的从业者。如果你还在纠结 Seurat 和 Scanpy 选哪个，这份资源不解决那个问题；但如果你已经有了矩阵，想知道怎么系统地「查」出生物学意义，它值得拆开看。
2. 数据查找的底层逻辑：为什么不能直接上聚类
2.1 查找的前提是矩阵已经过质控和标准化
很多人拿到表达矩阵第一件事就是跑聚类，然后对着 t-SNE 图发呆——这堆颜色不同的点到底代表什么？问题出在跳过了一个关键认知：单细胞数据的「查找」不是从聚类开始的，是从质控和标准化之后才真正有意义。原始计数矩阵里混着低质量细胞、双细胞、线粒体基因高表达细胞，这些噪声不清理，后面查出来的标记基因全是假阳性。
常见做法是先用 MAD 或百分位数法过滤掉 nFeature_RNA 过高或过低的细胞，再根据线粒体基因比例卡一道阈值。这一步没有统一标准，组织类型不同阈值差异很大。我一般会先把 nFeature_RNA 的分布画出来，看拐点在哪，而不是死记「200 到 2500」这种通用区间。标准化则优先选 SCTransform 或 logNorm，前者对测序深度的校正更稳，后者兼容性更好。
import scanpy as sc # 读取 10x 格式矩阵 adata = sc.read_10x_mtx( "filtered_feature_bc_matrix/", var_names="gene_symbols", cache=True ) # 基础质控指标计算 adata.var["mt"] = adata.var_names.str.startswith("MT-") sc.pp.calculate_qc_metrics( adata, qc_vars=["mt"], percent_top=None, log1p=False, inplace=True ) # 按分位数过滤，比固定阈值更适应不同组织 sc.pp.filter_cells(adata, min_genes=200) sc.pp.filter_genes(adata, min_cells=3) adata = adata[adata.obs["pct_counts_mt"] < 20, :].copy()这段代码的逻辑是先算质控指标再过滤，顺序不能反。min_genes=200是下限保护，防止空液滴被当成细胞；pct_counts_mt < 20对大多数组织够用，但心肌或肌肉样本可能要放宽到 30 甚至 40。参数改动的依据永远是你自己的数据分布，不是别人的经验值。
2.2 查找动作分三层：细胞类型、标记基因、公共数据
质控完的矩阵进入查找阶段，实际上有三个不同层面的「查」在同时发生。第一层是查细胞类型——这堆细胞属于什么类别，靠的是聚类加注释。第二层是查标记基因——每个簇里哪些基因显著高表达，用来支撑注释结论。第三层是查公共数据——你的样本和已发表数据集里的哪些细胞类型可以对齐，用来验证或补充。
这三层不是串行关系，而是互相印证。聚类结果告诉你「这里有五个簇」，标记基因告诉你「簇 2 高表达 CD3D 和 CD3E」，公共数据检索告诉你「这个表达模式和记忆 T 细胞一致」。缺了任何一层，结论都站不住。代码包里把这三层拆成了独立模块，可以单独调用，也可以串起来跑。
# 三层查找的串联示例 # 第一层：聚类 sc.pp.normalize_total(adata, target_sum=1e4) sc.pp.log1p(adata) sc.pp.highly_variable_genes(adata, n_top_genes=2000) sc.pp.pca(adata, n_comps=50) sc.pp.neighbors(adata, n_neighbors=15, n_pcs=30) sc.tl.leiden(adata, resolution=0.8) # 第二层：标记基因查找 sc.tl.rank_genes_groups(adata, "leiden", method="wilcoxon") marker_df = sc.get.rank_genes_groups_df(adata, group="0") # 第三层：公共数据比对（以 CellTypist 为例） # 需提前安装 celltypist 并下载模型 import celltypist predictions = celltypist.annotate(adata, model="Immune_All_Low.pkl") adata.obs["celltypist_label"] = predictions.predicted_labelsresolution=0.8是 Leiden 聚类的分辨率参数，值越大簇越多。0.8 是个折中起点，实际跑的时候我会从 0.4 到 1.2 各跑一遍，看哪个分辨率下簇的标记基因最干净。n_neighbors=15和n_pcs=30也是经验起点，数据量大的时候邻居数可以提到 20 到 30。CellTypist 的模型选择取决于你的组织类型，免疫细胞用 Immune_All_Low，其他组织要去官网查对应模型文件。
3. 代码包拆解：查找模块怎么调、参数怎么设
3.1 目录结构与模块职责
代码包解压后通常能看到几个核心目录：scripts/放可执行脚本，configs/放参数配置文件，utils/放公共函数，data/放示例数据或下载脚本。这种结构的好处是查找逻辑和参数分离，换数据集的时候只改 config 不动代码。
我一般先看configs/里的 yaml 或 json 文件，那里定义了所有可调参数：质控阈值、聚类分辨率、标记基因筛选的 logFC 和 p 值 cutoff、公共数据检索的模型路径。把这些参数集中管理，比散落在各个脚本里强得多。utils/里的函数通常是数据加载、格式转换、结果导出这些重复动作，读一遍能省很多重复造轮子的时间。
# 典型的代码包目录结构 single_cell_finder/ ├── scripts/ │ ├── 01_qc_filter.py │ ├── 02_cluster_annotate.py │ └── 03_marker_search.py ├── configs/ │ └── default_params.yaml ├── utils/ │ ├── io_utils.py │ └── plot_utils.py └── data/ └── download_example.sh01_qc_filter.py负责质控和过滤，02_cluster_annotate.py负责聚类和自动注释，03_marker_search.py负责标记基因查找和导出。三个脚本可以独立跑，也可以按顺序串。default_params.yaml里通常有注释说明每个参数的推荐范围和调整场景，这是最该先读的文件。
3.2 参数配置与运行方式
参数配置的核心原则是：先跑默认值看结果，再针对性调。不要一上来就改一堆参数，那样出了问题根本不知道是哪个参数导致的。默认参数一般是在通用数据集上验证过的，对大多数场景够用。
# default_params.yaml 示例 qc: min_genes: 200 max_genes: 6000 max_mt_pct: 20 min_cells: 3 cluster: n_top_genes: 2000 n_pcs: 30 n_neighbors: 15 resolution: 0.8 marker: method: "wilcoxon" logfc_threshold: 0.25 pval_cutoff: 0.05 min_pct: 0.1 annotation: model: "Immune_All_Low.pkl" majority_voting: truemax_genes: 6000是上限保护，防止双细胞被保留。logfc_threshold: 0.25是标记基因筛选的 log 倍数变化阈值，低于这个值的基因即使 p 值显著也可能没有生物学意义。min_pct: 0.1要求基因至少在 10% 的细胞里表达，过滤掉那些只在极少数细胞里出现的噪声。majority_voting: true是 CellTypist 的一个选项，让注释结果在聚类簇层面做多数投票，减少单细胞层面的抖动。
运行方式通常是命令行传参覆盖默认值：
python scripts/02_cluster_annotate.py \ --input data/processed.h5ad \ --config configs/default_params.yaml \ --resolution 1.0 \ --output results/clustered.h5ad--resolution 1.0覆盖了配置文件里的 0.8，这种命令行覆盖的优先级高于配置文件。跑完之后检查results/目录下的输出文件，通常包括聚类后的 h5ad、标记基因表格、注释结果表格和几张质控图。
3.3 查找结果的验证与导出
跑完查找流程不等于结束，验证环节才是决定结论能不能用的关键。我一般会做三件事：第一，把标记基因的 top 10 画成热图，看每个簇的基因表达模式是否干净；第二，把自动注释结果和手动注释结果做交叉表，看一致性；第三，把关键标记基因的表达量画在 UMAP 上，确认空间分布合理。
# 验证查找结果的三步操作 import pandas as pd # 第一步：标记基因热图 sc.pl.rank_genes_groups_heatmap( adata, n_genes=10, groupby="leiden", show_gene_labels=True, save="_marker_heatmap.pdf" ) # 第二步：注释一致性交叉表 cross_tab = pd.crosstab( adata.obs["leiden"], adata.obs["celltypist_label"] ) print(cross_tab) # 第三步：关键基因 UMAP sc.pl.umap( adata, color=["CD3D", "CD19", "CD14", "celltypist_label"], ncols=2, save="_key_markers.pdf" )热图看的是簇内一致性，如果某个簇的 top 基因热图很花，说明这个簇可能没分干净。交叉表看的是自动注释和聚类编号的对应关系，如果某个簇的注释结果特别分散，说明这个簇的细胞类型不纯。UMAP 看的是空间分布，CD3D 应该富集在 T 细胞区域，CD19 在 B 细胞区域，如果这些基因到处都有表达，说明数据质量有问题。
4. 避坑与排查：查找流程里最容易翻车的五个地方
4.1 现象：聚类簇数远多于预期，标记基因全是核糖体基因
原因通常是质控没做干净，低质量细胞和双细胞混在里面形成了假簇。核糖体基因高表达是低质量细胞的典型特征，它们聚在一起不是因为生物学相似，而是因为都快死了。
解决方法是回头检查质控步骤，把max_genes调低、max_mt_pct调严，重新跑一遍。如果核糖体基因仍然占主导，可以在高变基因选择时排除RPS和RPL开头的基因。
4.2 现象：自动注释结果和已知生物学完全对不上
原因可能是模型选错了。CellTypist 的 Immune_All_Low 模型只适用于免疫细胞，如果你拿它注释上皮细胞或神经元，结果必然离谱。另一个可能是输入数据的基因命名和模型训练时不一致，比如模型用 Ensembl ID 而你用 gene symbol。
解决方法是先确认组织类型，去模型列表里找对应的模型文件。基因命名不一致的话，用celltypist自带的转换函数或者手动做 ID 映射。跑之前先用adata.var_names[:5]看一眼基因名格式。
4.3 现象：标记基因查找结果里 logFC 很大但 p 值不显著
原因通常是该基因只在极少数细胞里表达，虽然表达量差异大，但统计检验的样本量不够。min_pct参数没卡住这类基因。
解决方法是在标记基因筛选时同时卡logfc_threshold和min_pct，两个条件都满足才保留。如果某个簇的细胞数本来就少，可以适当放宽min_pct但要在结果里标注出来。
4.4 现象：公共数据检索时找不到可比数据集
原因可能是检索关键词太窄，或者你的数据本身是罕见组织类型。公共数据库里的单细胞数据集覆盖度有限，不是所有组织都有现成的可比样本。
解决方法是先用标记基因去查，而不是用组织名去查。比如你查不到「胰腺导管上皮」的数据集，但可以用「EPCAM 高表达」这个特征去检索。另外可以放宽物种限制，小鼠和人的同源基因比对也能提供参考。
4.5 现象：整个流程跑完但 h5ad 文件打不开
原因通常是写入时用了不兼容的格式，或者磁盘空间不足导致文件截断。h5ad 对写入完整性要求很高，中途中断就会损坏。
解决方法是每次写入后立刻用sc.read_h5ad读一遍验证，确认文件完整再删中间文件。磁盘空间至少留出数据量三倍的余量，因为写入过程中会有临时文件。
5. 进阶技巧：用标记基因做跨数据集检索
查找流程跑通之后，最有价值的进阶用法是把标记基因列表当成「检索指纹」，去公共数据里找相似样本。具体做法是：从你的数据里导出每个簇的 top 50 标记基因，然后用这些基因去比对公共数据集的注释文件或表达矩阵，算 Jaccard 相似度或超几何检验 p 值。
# 用标记基因做跨数据集检索 from scipy.stats import hypergeom import numpy as np def marker_similarity(query_markers, ref_markers): """ query_markers: 你的数据里某个簇的标记基因列表 ref_markers: 公共数据集里某个细胞类型的标记基因列表 返回超几何检验的 p 值和 Jaccard 指数 """ query_set = set(query_markers) ref_set = set(ref_markers) overlap = query_set & ref_set union = query_set | ref_set # 超几何检验 M = 20000 # 人类基因总数近似值 n = len(ref_set) N = len(query_set) k = len(overlap) pval = hypergeom.sf(k - 1, M, n, N) jaccard = len(overlap) / len(union) if union else 0 return pval, jaccard # 示例：比对两个标记基因列表 query = ["CD3D", "CD3E", "CD2", "IL7R", "CCR7"] ref = ["CD3D", "CD3E", "CD2", "CD28", "ICOS", "CTLA4"] pval, jac = marker_similarity(query, ref) print(f"p-value: {pval:.2e}, Jaccard: {jac:.3f}")M=20000是人类基因总数的近似值，做超几何检验时作为背景。hypergeom.sf算的是「至少重叠 k 个基因」的概率，p 值越小说明两个标记基因列表越相似。Jaccard 指数是重叠数除以并集数，值越接近 1 越相似。这两个指标要一起看，p 值显著但 Jaccard 很低的情况说明重叠基因虽少但统计学上不偶然，可能是功能相关的核心基因。
我一般会把所有簇的标记基因和公共数据集里所有细胞类型的标记基因做两两比对，生成一个相似度矩阵，然后看每个簇最匹配的公共细胞类型是什么。这个矩阵还能用来发现数据集之间的批次效应——如果两个数据集里同一种细胞类型的标记基因相似度很低，说明批次效应严重，需要做整合。
从那以后我每次跑完查找流程，都会强制走一遍标记基因相似度矩阵，确认没有哪个簇是「孤儿簇」——和任何公共细胞类型都对不上。这种簇要么是新发现的稀有细胞类型，要么是质控没做干净留下的假簇，两种情况都值得回头查。希望帮到你。
本文还有配套的精品资源，点击获取
