一张自动注释表有八十四行,每一颗细胞都有名字。把“剪枝后标签”也展开,会发现十二行已经变成空值。剩下的标签是不是都可以用了?这个练习中,还有十二颗细胞得到很坚定的 T 标签,分数并不低,只有查看未参与拟合的基因,才看出它们和参考的覆盖范围不相符。下面用真实运行的 SingleR 和可独立复算的分数表,分别处理“模型自己拿不准”和“模型在缺少正确选项时仍选得很坚定”这两个问题。

下载完整代码、示例数据与参考输出(ZIP) · 下载图文操作手册(PDF)
先把用于训练和用于复核的输入拆开
教学参考有五类、一百一十颗细胞,每类二十二颗。查询部分有八十四颗,代表几类不同难度的输入。模型使用一百一十个模拟表达特征,独立存放的标记面板和教学设计答案从不进入拟合。数据是为展示错误机制而构造的,所有分数、微调结果和剪枝值则由随包的 R 脚本调用 SingleR 实际产生。轻量下载允许读者只用 Python 重算检查表;有 R 环境的读者可以从参考矩阵、参考标签和查询矩阵重新拟合,两种方式都不需另找示例。
输入的参考计数先按各自全库总量归一化并取对数,然后选用经典标记策略运行 SingleR。模型可用的答案只来自参考已提供的标签。真实项目首先应问参考来自哪个组织、年龄和状态,细分的层次能不能覆盖本次查询。只要参考里没有一个类,分类器就无法从参考中直接输出那个名字。在训练范围之外另存一套真正有区分能力的标记,可减少使用同一批基因训练又验证带来的循环论证;但来自同一表达实验的标记仍共享技术误差,不能替代蛋白或独立样本等证据。SingleR 软件包和实现文档
python -m pip install -r requirements.txt
python run.py --input example --out results
# 安装了 R 和 SingleR 时,可在数据副本中重新拟合
Rscript fit_singler.R example
pred <- SingleR(test=query, ref=ref, labels=labels, de.method="classic",
fine.tune=TRUE, prune=TRUE, BPPARAM=BiocParallel::SerialParam())
scores <- as.matrix(pred$scores)
assigned <- as.character(pred$labels)
margin_median <- scores[cbind(seq_len(nrow(scores)),match(assigned,colnames(scores)))] -
apply(scores,1,median)
至少区分三个数字和一个缺失值
原始分数表里每个查询细胞对每个参考标签都有分数。第一种量是最终所指派标签在该原始分数矩阵中的值。第二种量是这个值减去同一颗细胞对所有标签的分数中位数,用来衡量它比通常的参考匹配水平高出多少。第三种量来自微调阶段,是最好与下一候选的微调得分差。微调可能重新选择用来区分相近标签的特征,因此不宜拿原始分数排序的前两项相减来伪造微调差距。不同版本的 SingleR 用不同字段存放微调结果,包内兼容两种导出方式,并保留实跑的软件环境。SingleR 注释诊断与剪枝
def verified_delta(row):
scores=[float(v) for k,v in row.items() if k.startswith("score_")]
assigned=float(row["score_"+row["assigned"]])
return assigned-float(np.median(scores))
最后一个值是剪枝后是否还保留该标签。模型会根据被指派到各标签的一群细胞的分数差分布等信息,识别相对可疑的指派。已经被剪枝的细胞仍能有一个原始最佳匹配,如果导出时只复制原标签列,就会让模型明示的疑虑全部消失。反过来,剪枝后仍有名字说明它通过了当前参考和规则下的检查;如果整个参考缺失某种查询亚型,仍然可能发生一致的错认。最好在同一行并排留着原标签、剪枝后标签、两个差值和人工审阅理由,再另外出一列给图上实际使用的展示标签。
| 实际拟合中的条码 | 原指派、剪枝后 | 分数减中位、微调差 | 留出的标记提供了什么 |
|---|---|---|---|
| Q_00_00 | T,保留 T | 约 0.336、0.279 | T 面板支持 |
| Q_05_00 | 基质,剪枝为空 | 约 0.110、0.039 | 标记缺少单一谱系支持 |
| Q_06_00 | T,保留 T | 约 0.340、0.302 | NK 样面板阳性,T 面板无支持 |
两个得分都很高,却需要给出不同结论
把第一颗和第三颗对照。第三颗的两个差值甚至略高,仅靠机械提高分数下限,很难保住第一颗而排掉第三颗。看单独留出的标记,第一颗具有成套 CD3D、TRAC,第三颗则有 GNLY、KLRD1 的 NK 样支持,T 面板没有相应证据。模拟中参考故意未收录 NK 样类,而这一组查询在模型使用的特征上与 T 非常相近,展示了系统性误判可以在同一类细胞中反复发生。因为杀伤相关标记在真正的细胞毒性 T 里同样可能出现,实践中宜把第三颗写作“参考标签与独立面板冲突,未确定”,再结合更全面的 T 谱系、受体或蛋白核验。
def examine(row, markers):
if row["pruned"] in ("","NA"):return "unassigned","SingleR_pruned"
supported={name for name,genes in PANELS.items() if all(int(markers[g])>=2 for g in genes)}
if row["assigned"] in supported and len(supported)==1:return row["assigned"],"marker_supported"
if supported:return "unassigned","marker_conflict"
return "unassigned","no_panel_support"
模型实际剪掉十二颗模糊表达查询。它们的原始指派分散在五种参考标签里,并非全被挤到某一个异常类别。另有十二颗参考未收录的查询全部进入 T,剪枝后也全部保留 T,直到独立面板复核才被转为未确定。五个参考内类别各有十二颗,合计六十颗同时获得模型和面板支持。因为示例刻意构造了这几组,切勿把二十四除以八十四当作 SingleR 在所有样本上的误判率。读者应学习检查流程,并在自己的组织和研究设计上分别估计保留率、冲突率和参考缺失状况。
从结果表挑出最值得人工看的十行
先筛出“保留了标签但面板冲突”的条码,并按与中位数的差值从高到低看。大差值通常容易得到信任,恰是检查系统性缺类时值得优先回查的一批。再挑几颗分数差很小但面板相当清晰的细胞,查看是不是参考中的两个细标签属于同一个大谱系。这样可以把“应该保留粗层级”与“完全无从判断”区别开。例如两种相近的 T 亚型分不开,但 CD3 及受体证据都很充分,保留 T 大类有助于后续计数;在两种完全不同谱系之间同时出现强冲突,才值得暂时把整个大类也留空。
import csv
from pathlib import Path
with Path("results/cell_review.tsv").open(encoding="utf8") as handle:
rows = [r for r in csv.DictReader(handle, delimiter="\t") if r["reason"] == "marker_conflict"]
for row in sorted(rows, key=lambda r: float(r["delta_median"]), reverse=True)[:10]:
print(row["barcode"], row["assigned"], row["delta_median"], row["review_label"])
接着把这些条码按供者与文库分开,看看冲突者是否来自一个低质量文库,还是多个处理批次都出现相似模式。若只落在一个文库,先检查基因编号映射、原始深度、环境背景和模态连接。有时自动注释器使用的是规范基因编号,而复核面板按旧符号拼接,两张表的数据都在,却会制造一整类细胞没有标记的假象。若多个独立样本都落到同一个勉强相似的参考类,就查该参考有没有收录本研究组织里的候选状态,并寻找更匹配的第二份参考。换参考时连同原标签、每轮猜测和原因并列保留,不要把第一次的矛盾覆盖掉。
这个包还有一项容易操作的练习。复制输入目录,移去只供教程评分的设计答案表,再运行。逐条码标签和未确定原因应逐项相同,因为判读阶段只读模型结果及留出的标记;少掉的是事后用来对照设计的汇总表。真实项目本来没有这样一份答案,正需要另外标明哪些证据仅来自表达、哪些已有独立样本支持、哪些能够在同一条码的其他模态检验。把证据层级写进图注,也能让同事明白图中一块灰色是模型剪枝、参考覆盖不足,还是研究者刻意保留了边界。
如果最终要比较两组患者的细胞比例,再分别报每组被剪枝和因面板冲突转为未确定的份额。倘若一组本来就有更多参考未覆盖的状态,先删除未确定者再计算其余类型的百分比,可能把剩下的类都被动放大。
交付时给出参考的版本、包含和缺少的类别、输入特征清单和逐条码检查表,可以让另一位合作者从同一份数据再现未确定的原因。需要对多队列反复更换参考、批量比较剪枝后保留比例时,可以将训练脚本和固定的验证面板放入云生信科研服务器租赁环境并保留各轮结果。
