同事发来两张肿瘤免疫细胞的 UMAP。第一张里蓝色和橙色散点挤在一起,第二张中间出现一条空带。他想在汇报里写“两群细胞分化得更明显了”。分析记录却只显示绘图参数 min_dist 改过一次。怎样判断空带意味着什么?不用估计图上相隔多少毫米,直接查同一颗细胞的上游标签、输入图的边和投影后的邻居。这三个对象都有可以保存的数字,放在一起便能读懂两张图究竟改变了哪一层。

下载完整代码、示例数据与参考输出(ZIP) · 下载图文操作手册(PDF)
一份主成分表,两次真正的 UMAP 拟合
示例里有一百八十个模拟细胞,每个条码带八个主成分得分和一个预先给定的标签。三个标签各有六十个细胞,高维空间有一定重叠。把标签表故意倒序是有用的练习:忽视条码、直接按行给点着色,完全可能做出一张看似合理的错图。脚本先检查重复和覆盖,再按主成分表的顺序排列标签。标签只用于着色和事后核对,没有作为监督目标传入 UMAP。若真实数据来自多个患者,先给重复的原始条码加上捕获批次或样本前缀,确保一行对应一颗确定的细胞。
解压后用 Python 3.12 环境安装依赖,再执行命令。程序会拟合两次 UMAP,输出两组坐标、两张二维邻居名单、原图边权和对照图。第一次启动时底层库会进行编译,可以先打开输入表检查字段。看图之前先将 settings.json 中的参数抄下,包括算法用多少邻居、查看二维图时另取多少邻居、随机种子、固定的主成分和两个 min_dist 值。这样能避免把建图时的近邻数与最后数一数屏幕上最近的几个点混为一谈。
python -m pip install -r requirements.txt
python run.py --input example --out results
第一步先固定邻居,给两次拟合相同的边
UMAP 会依据高维输入寻找相近的细胞,用局部距离估计构建带权图,再求一个能呈现这种结构的低维布局。为了只考察布局参数,我们先从八个主成分计算一份欧氏近邻,交给两次拟合重复使用。示例参数十二包含查询细胞自己,所以每个条码最初列出另外十一个候选。程序显式构造自匹配项,避免换工具后因“是否包含自己”的约定不同,额外丢掉一个真正的邻居。下面这段实际参与了建图,适合拿来对照你项目中的距离度量和邻居数。UMAP 官方预计算近邻教程
def fix_knn(pcs, count):
if not 2 < count < len(pcs):
raise ValueError("Set k strictly between 2 and the cell count.")
search = NearestNeighbors(n_neighbors=count - 1, algorithm="brute", metric="euclidean").fit(pcs)
distances, indices = search.kneighbors() # no query: scikit-learn excludes self
self_indices = np.arange(len(pcs), dtype=np.int32)[:, None]
return (np.hstack((self_indices, indices)).astype(np.int32),
np.column_stack((np.zeros(len(pcs)), distances)).astype(np.float32))
在同一套近邻上,把 min_dist 从零点零五改为零点七五,固定 spread、迭代次数、初始化方式、软件布局模式和随机种子。这个参数影响嵌入中相近点聚得有多紧,不能把数值直接当作任意两点之间必须遵守的硬性最小距离。改变它也不会给数据补进新的分子或细胞。若两张图沿用不同随机种子、改了主成分数或者换了子集,观测到的差异就混入多项因素。先让一次改动只对应一个问题,之后可以另外检查种子和特征选择的影响。UMAP 官方参数示例
def fit_view(pcs, fixed_knn, min_dist, seed):
indices, distances = fixed_knn
model = UMAP(n_neighbors=indices.shape[1], min_dist=min_dist, spread=1.0,
metric="euclidean", random_state=seed, n_jobs=1, init="random",
n_epochs=250, compatibility_layout=True, force_approximation_algorithm=True,
precomputed_knn=(indices.copy(), distances.copy(), None))
model.fit(pcs)
return model.embedding_, model.graph_.tocsr()
程序还做了一项重要的核验。它从两次实际拟合的模型中分别取出图矩阵,将它们相减,去掉零值并数剩余条目。示例最终导出二千七百六十二条非零有向记录,两张图在每个有向条目上的权重都相等。对一个对称图,同一对细胞的两个方向通常会分别写入文件,因此这个数不能直接称为独立细胞对的数目。单个节点的最终度数也可能高于最初列出的十一个候选,因为其他细胞会把它选作邻居,图构建会合并两个方向的信息。不能拿超过十一这件事当作程序多算了几颗细胞。
第二步分别检查标签和二维邻居
打开 barcode_audit.tsv,选择第一颗细胞 cell_001。两次均显示标签 A,原图中有十二个带权邻居;而按二维图上的欧氏距离取最近的八颗细胞,两张名单只有五个名字重合。到 map_neighbors.tsv 中按该条码筛选,可以抄出各自的八个条码,取交集即可独立核对。再把只出现在一边的邻居放回 coordinates.tsv,看它们在另一幅图里是否只是排到了第九或第十。排名线附近小幅度的位置变化就能导致出入名单,尤其当周围有很多密集的点时。
def display_neighbors(coords, k):
distance = cdist(coords, coords)
np.fill_diagonal(distance, np.inf)
return np.argsort(distance, axis=1, kind="stable")[:, :k]
| 拿来比较的对象 | 怎样比较 | 本次示例 |
|---|---|---|
| 两个模型返回的高维模糊图 | 逐条码对齐,比较边权 | 2,762 条记录相等 |
| 已有的上游分群 | 逐条码对比两个标签字段 | 180 个均相同 |
| 两张二维图上的最近邻 | 比较每个焦点排名前八的集合 | 重合数中位数为 4 |
这里要坦白说明一件事。两个标签字段来自同一份上游表,所以标签完全相同是实验设计的结果,不能据此说所有聚类算法在一切参数下都稳定。这次要回答的是“只改绘图参数,会不会自动改写先前的分群”。有的工作流在 UMAP 的模糊图上聚类,有的在另一张共享近邻图上聚类,也有人直接拿二维坐标去重新聚类。最后一种做法的输入真的变了,当然可能得到新标签。真实项目中应从代码查清聚类函数读取的图名或矩阵名,在结果中明确说明,然后才谈更换布局对标签的影响。
如果两张图片的点数对不上,别急着分析空带。把两份坐标表的条码取交集,再分别列出只在一张出现的细胞。有些绘图脚本会排除标签缺失的点,有些会对最大的细胞群抽样,这两种情形都可能让图上某个角落看起来稀疏。先对完全相同的条码比较,再单独解释被漏画的细胞,可以省下不少排查时间。
一百八十颗都换了部分邻居,该怎样写图注
在这个固定版本的演示中,每颗细胞两张二维图的前八名至少换了一个,重合数的中位数是四。这个数值没有跨数据集的通用阈值。首先,两张图可以整体旋转、镜像或平移,直接相减横纵坐标会把无关变化也算进去;其次,近邻集合比较更关心同一细胞周围有哪些名字,因此能用条码向同事说明变化发生在哪。若要主张某个生物亚群确实独立,还应回表达矩阵查看多个标记在同一批细胞上是否共同出现,并查各供者、重复、组织区域或其他测量是否支持。图上清晰的空带本身无法给出这些证据。
做个十分钟的延伸练习。先保留原输出,把 display_neighbors 从八改为四,将第二次运行写进新目录。高维图的逐边核对仍应通过,但查四个最近点和查八个最近点得到的重合数上下界不同,所以要报告分母。再挑一个标签交界处的条码和一个内部条码,比较新增或消失的二维邻居来自哪些标签。假如边界细胞的标签和高维边权都稳定,可以把它描述为投影中的局部排布敏感;若同时改了图输入且原来的重要近邻也消失,就该回到表达和样本来源查原因。
提交结果时,保留两幅相同配色的图、主成分字段、建图参数、上游标签来源以及两列坐标对应的条码。给合作者的图注可以写“固定输入近邻和标签,展示两个紧密程度参数下的二维排布”,再补一行这次最关心的细胞是否换了高维邻居。这样对方即便只看到截图,也知道可以从哪个表追溯结论。将来如果要在更大项目中保存多套布局,先实测一轮构图和重复投影各自的时间及内存,超过现有设备容量时再据此选择云生信科研服务器租赁。
