用途:把笔记本中的聚类后端对比流程封装成一个可复用任务,在已完成 PCA、必要时已构建邻接图的单细胞 AnnData 上选择并运行聚类后端。聚焦后端选择与输出契约,不负责预处理。
主要能力:通过 ov.utils.cluster(adata, method='leiden', use_rep='X_pca', random_state=1024, n_components=None, **kwargs) 分派到不同后端。源码支持 leiden、louvain、kmeans、GMM、mclust、mclust_R、schist、scICE 等方法。leiden 与 louvain 将 *kwargs 转发给 scanpy 在当前图上聚类,需先构建邻接图;GMM 与 mclust 使用 use_rep 指定的嵌入并需要 n_components,会写入 mclust 和 gmm_cluster;scICE 返回已拟合模型对象,并通过 add_to_adata(...) 向 adata.obs 添加一个或多个 scICE_k 列,运行时间受 resolution_range、n_steps、n_trials、n_boot 影响。
使用方式:先用 ov.pp.neighbors(adata, n_neighbors=15, n_pcs=50, use_rep="scaled|original|X_pca") 构建邻接图;再显式指定 method 调用 ov.utils.cluster。GMM 示例需传 use_rep 与 n_components=21;scICE 示例需传 use_rep、resolution_range=(4, 20)、n_boot=50、n_steps=11,并接收返回的模型对象。
适用场景:默认图聚类用 leiden;明确需要 Louvain 兼容性时用 louvain;希望在嵌入上做高斯混合软分配时用 GMM;希望按一致性引导选择簇数并接受额外 bootstrap 开销时用 scICE。
限制:不要用作预处理技能;必须显式指定 method;不要假设笔记本中的簇数对其他数据集是稳定的默认值;scICE_k* 是数据依赖的候选结果,后缀不固定;本技能不保证 ARI 或图形渲染,它们属于可选的下游报告。验证时应检查目标 obs 列是否添加,GMM 检查 mclust 与 gmm_cluster 两列,scICE 检查模型对象与至少一个 scICE_k* 列;如需对比后端,应在所有标签列存在后再计算 ARI 等指标。