单细胞分析

新增一位患者,怎样沿用旧图谱的坐标和注释,再验证映射靠不靠谱?

作者:发布于 2026-11-17约 9 分钟阅读
在固定参考图上用整位留出供者复核九邻居投票和拒判,检查高票错分

项目已经有一张按供者审核过的免疫细胞图谱,新来一位患者后,最方便的做法是沿用上次的坐标和注释。怎么证明那张图也适合他?先别急着解释新患者的投影,可以把一位已有人工作过注释的供者暂时藏起来,按新来的数据走一遍,再打开真值核对。除了看能否猜中 T、B 和髓系细胞,还要问图谱没收录的状态会被分到哪里,以及九个邻居全都投同一票时,是否仍会分错。

在固定参考图上用整位留出供者复核九邻居投票和拒判,检查高票错分

下载完整代码、示例数据与参考输出(ZIP) · 下载图文操作手册(PDF)

先把图谱、盲测和真正未知的查询分开

教学数据里,前三位供者一共一百八十颗细胞,构成参考。每位都有 T、B 和髓系三种标签。第四位有六十六颗,作为整位留出的盲测供者,只在最后判分时读她的参考真值。第五位同样有六十六颗,在输入表中不提供任何真值,模拟真正的新样本。参考、盲测和查询各用独立条码和供者字段。不要随机打散全部细胞再做训练测试:同一位患者的细胞同时进入两边,会让模型有机会利用患者特有的技术偏差或表达背景,得到的成绩比面对新患者乐观。

先解压资料包,运行下面两行。代码从同一份教学计数中按供者角色拆组,所有选择模型参数的步骤均限制在参考数据内。先在每颗细胞内部按文库总量归一化并取对数,再用参考细胞独立选出有方差的特征,估计每个基因的中心和尺度,拟合九维 PCA。把所得均值、标准差和基因顺序直接用于留出与查询细胞,避免新患者贡献的数据反过来改变参考。真实环境若收到的是独立矩阵,应按相同基因编号显式对齐,并列出无法映射的特征。静默把缺失的测量写成零,可能把一整类新细胞推向错误位置。

python -m pip install -r requirements.txt
python run.py --input example --out results

把坐标映射和标签判断分别验算

首先在参考的主成分得分上拟合 UMAP,保存参考坐标。新数据先经过同一个 PCA,再调用同一个 UMAP 模型的 transform 得到查询点的二维位置。函数运行后脚本重新比较所有原参考坐标,与映射前逐元素一致。这样成果才能叫沿用旧图谱。把全部供者合并后重算 UMAP,也能画出一张看似熟悉的图,但是原来的点可能已经换了坐标,不适合和旧版本逐点叠放。UMAP 的新点投影仍依赖训练数据是否覆盖查询分布,原图没见过的状态在二维图中照样会有一个位置。UMAP 投影新数据的官方教程

标签判断发生在九维参考得分空间,不使用肉眼看到的二维屏幕距离。为每颗查询细胞找到九个最近的参考邻居,计算票数最多的标签及其所占比例,同时记录第九近邻的距离。如果邻居互相意见不一,或者九个最近点整体离它都过远,就保留未分配并写清原因。本练习用训练参考内部、排除同供者后第九近邻距离的百分之九十八分位数作为距离参考。这是可以修改的教学规则,并非疾病或组织的通用阈值。下面两个函数都能在下载包中找到,亦可从条码表独立核对一颗细胞的投票与距离。

def cross_donor_radius(ref_scores, ref_donors, k, quantile):
    distances=cdist(ref_scores,ref_scores)
    distances[ref_donors[:,None]==ref_donors[None,:]]=np.inf
    kth=np.partition(distances,k-1,axis=1)[:,k-1]
    if not np.isfinite(kth).all():
        raise ValueError("Not enough reference neighbors from different donors.")
    return float(np.quantile(kth,quantile))
def predict(query, reference, ref_labels, k, vote_min, radius):
    distances=cdist(query,reference)
    indices=np.argsort(distances,axis=1,kind="stable")[:,:k]
    results=[]
    for i,neighbor_ids in enumerate(indices):
        nearest_labels=ref_labels[neighbor_ids]
        votes=Counter(nearest_labels)
        ranked=sorted(votes.items(),key=lambda item:(-item[1],item[0]))
        label,count=ranked[0]
        fraction=count/k
        distance=float(distances[i,neighbor_ids[-1]])
        flags=[]
        if fraction<vote_min:flags.append("mixed_vote")
        if distance>radius:flags.append("far")
        results.append((label,fraction,distance,"|".join(flags) or "pass",label if not flags else "unassigned"))
    return results,indices

用一份混淆表看出总体正确率遮住的问题

打开 validation_confusion.tsv。行是第四位供者的已知状态,列是最后接受的标签或未分配。二十个真实 B 都进入 B,二十个髓系也全部正确。二十个真实 T 中十七个进入 T,另外三个被接受为 B。还有六个特意设计成参考未收录状态的细胞,其中五颗标为未分配,一颗错误接收为 T。若先删掉所有未分配再算准确率,得到的是“被模型接收者中有多少正确”;如果希望评估能给整位患者多少有效答案,需把拒判的总数和各类的覆盖一同报告。

盲测真值 细胞数 获得参考标签 其中主要错误
B 20 20 0
T 20 20 有 3 颗错判成 B
髓系 20 20 0
参考中未收录的状态 6 1 这 1 颗被接收为 T,另 5 颗拒判

再到 assignments.tsv 查 P4_C001。该条码的九个邻居全投 B,距离约三点七七,低于示例中的参考阈值约六点四八,因此被接受为 B,但它的预设真值是 T。紧随其后的两个条码也是九票一致却分错。例子刻意为这三颗细胞赋予接近 B 表型的测量值,展示“参考邻居很一致”与“真实身份正确”的距离。真实项目应对此类条码回查多个谱系标记、测序深度、双细胞和参考注释本身,而不是因得票率达到百分之百就将其写成确定无疑。票数还是离散的,九票中一票就超过十个百分点,不能当成已经校准的事件概率。

没见过的状态投进来,为什么仍然会有名字

近邻总能在有限的参考标签里找到最接近的点。如果参考缺少自然杀伤细胞、急性应答状态或该组织特有谱系,那么投票第一名也只能来自现有标签。示例让六颗未收录状态与参考标记的组合分开,其中仍有一颗跨过了接收门槛,说明只靠距离和投票不能完全识别图谱外情况。保留 top_label 作为候选,并将实际接受的 assigned 与 review_reason 单独输出,后续就能找出“有一个最近类别,但仍需核实”的细胞。若分层参考给出大类可靠、细小亚群不稳,可以发布较粗标签,并把细亚群保留为候选。

接着比较图栏的两幅散点。两边灰色底图是相同的旧参考,左边叠加留出的已知供者,右边叠加真正未知的那位。显示输入条码的投影分布是有用的质量检查,但如果一个新条码正落在旧 T 群的中心,仍应核对它的投票和原始标记。资料包中可将 reference_coordinates.tsv 与 query_coordinates.tsv 自行叠图,两表用各自条码命名,没有把新患者的输入悄悄写回原参考标签。若团队原本使用 Seurat 的参考投影,可按已有训练管线调用相应的映射和标签转移工具,再重复相同的整位留出核验。Seurat 参考映射实例

换成自己的患者,先写验收再打开新样本

先挑一个与实际新样本技术和组织来源相近的已注释患者,用其余人拟合参考。重复留出不同患者,会比只留出一位更容易发现某个批次或特定细胞类别长期不适配。检查每一类的总数、被接受数、正确数和错误去向。小类只有两颗时,一次错分就改变一半比例,需要把分子分母一并写进表格。对于临床或实验上特别重要的标签,可以预先写好最低覆盖和允许误差,或约定哪些冲突必须另外检查,不要看到真正新患者的理想结果后才反推阈值。

最后可把 settings.json 的距离分位数改小,写到新目录重跑,查看那五颗未分配、三个高票错分和原本正确的细胞分别发生了什么。严格门槛通常会让更多条码需要复查,未必能排除仍很靠近训练 B 细胞的高票错分。第五位患者只有预测和审查标记,不可能仅凭程序给出“准确率百分之多少”。交付时并列保存参考版本、投影坐标、盲测混淆表及新样本候选,后续新患者才可以沿用同一口径。若实验室连续按同一参考处理多批查询,可以根据首批实测的模型内存与投影耗时安排云生信科研服务器租赁。

把知识用于当前任务

下一步可以直接开始分析

按研究目标查找在线工具、课程、计算资源或完整分析服务。

按目标找方案仍有疑问,联系客服 ↗