1. 为什么 nhood_enrichment 画出来的图总是不对空间转录组做到邻域分析这一步很多人会卡在cellcharter的nhood_enrichment上。尤其是 10X Visium HD、华大 Stereo-seq、CODEX 这类高精度平台一个切片动辄几十万到上百万个细胞或 bin跑完聚类再画邻域富集热图结果要么是一片空白要么颜色全糊在一起要么直接报KeyError。你以为是算法有问题其实八成是输入格式或者cluster_key参数没对上。nhood_enrichment干的事情说白了很简单它统计不同空间簇在物理邻域里互相挨着的频率然后跟随机分布下的期望值做比较算出富集或耗竭的 z-score。图不对通常不是统计本身错了而是喂进去的adata里cluster_key指向的那一列根本不存在、类型不对或者邻域图压根没建。高精度平台数据量大这些问题会被放大报错信息还经常指向底层让人摸不着头脑。这篇就按排障的思路走先讲清楚nhood_enrichment到底依赖哪些前置条件再讲怎么用 TaoToken 给 Codex 配好模型通道让 Codex 对照cellcharter官方示例帮你逐项核对adata.obs字段和条件分组最后把可复制的配置、验证请求和常见报错都过一遍。TaoToken 在这里的角色只是给 Codex 提供一个可消耗的模型通道它不参与绘图也不碰你的数据。2. 先搞懂 nhood_enrichment 的前置依赖在动手配通道之前得先明白这个函数要什么。cc.gr.nhood_enrichment的核心参数就两个adata和cluster_key。它内部会去读adata.obs[cluster_key]然后基于adata.obsp里的空间邻接矩阵做统计。所以图不对基本逃不出下面这几个原因。第一cluster_key对应的列不存在或者名字写错。比如你聚类完存的是spatial_cluster结果传参时写成了spatial_clusters函数不会温柔提示直接抛KeyError。第二这一列的类型不是 category。cellcharter内部很多地方按类别处理如果是普通 object 或者 string统计出来的类别顺序会乱热图的行列就对不上。第三空间邻接图没建。nhood_enrichment依赖adata.obsp[spatial_connectivities]如果你只跑了聚类没跑sq.gr.spatial_neighbors或者跑的时候library_key没设对邻接矩阵就是空的。高精度平台 HD 还有个特殊点数据里往往有多个样本adata.obs[sample]是多类别。做单条件邻域富集时你得先把数据子集出来比如adata_balbc adata[adata.obs[condition] BALBc]否则跨样本的邻域会被混在一起算图自然不对。做差异邻域富集diff_nhood_enrichment时condition_key、library_key、condition_groups三个参数的配合更容易出错后面会单独讲。注意nhood_enrichment的输入必须是已经建好空间邻接图的adata且cluster_key列必须是 category 类型。这两条不满足后面怎么调参都是白费。3. 用 TaoToken 给 Codex 配好模型通道排障这件事靠自己一行行读源码效率低让 Codex 对照官方示例帮你核对字段和参数会快很多。但 Codex 需要一个稳定的模型通道这里就用 TaoToken。先打开 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 创建账号进控制台生成一个 API Key。地址是 https://taotoken.net/api 注意这个是不带 UTM 的纯 API 入口配置 Base URL 时用它。拿到 Key 之后在 Codex 的配置里把 Base URL 填成https://taotoken.net/api模型名按你订阅的通道填。如果你还没建 Key直接去 https://taotoken.net/api-keys 生成。配置完可以先用模型对话页面 https://taotoken.net/models 发一条测试消息确认通道通了再往下走。长期做编码和 Agent 任务的话Coding Plan 页面 https://taotoken.net/coding-plan 里有更细的通道说明。配好之后你就可以把adata.obs的字段结构、cluster_key的取值、以及你用的cellcharter版本贴给 Codex让它对照官方 tutorial 里的codex_mouse_spleen示例逐项检查你的调用哪里不一致。这一步的关键是Codex 只负责帮你比对和推理真正的数据操作还是在你本地跑。3.1 Codex 配置片段下面是一个典型的配置写法把 Base URL 和 Key 换成你自己的即可。不同版本的 Codex 配置字段名可能略有差异以你本地实际为准。# codex 配置示例 model_provider: taotoken base_url: https://taotoken.net/api api_key: sk-你的TaoToken密钥 model: 你订阅的模型名配好之后重启 Codex让它加载新配置。如果用的是命令行方式可以直接在环境变量里指定export OPENAI_BASE_URLhttps://taotoken.net/api export OPENAI_API_KEYsk-你的TaoToken密钥3.2 让 Codex 核对字段的提示词通道通了之后把下面这段提示词发给 Codex让它帮你定位问题。提示词里把你自己数据的实际情况替换进去。我在用 cellcharter 的 cc.gr.nhood_enrichment 画空间转录组邻域富集图 数据是 10X Visium HDadata.obs 里有 sample、condition、spatial_cluster 三列。 spatial_cluster 是我用 cc.tl.Cluster 跑出来的n_clusters11。 现在报错 KeyError: spatial_cluster但这一列明明存在。 请对照 cellcharter 官方 codex_mouse_spleen 示例 帮我检查 cluster_key 参数、adata.obs 列类型、以及空间邻接图是否建好。Codex 会结合官方示例给你一份核对清单你照着逐项确认就行。4. 可复制的完整配置与调用下面把从数据准备到出图的完整流程整理一遍重点标出容易出错的参数。这段代码可以直接改改就用前提是你的adata已经做完降维和聚类。import squidpy as sq import cellcharter as cc import scanpy as sc import pandas as pd # 1. 确认 cluster_key 列存在且为 category assert spatial_cluster in adata.obs.columns, spatial_cluster 列不存在 adata.obs[spatial_cluster] adata.obs[spatial_cluster].astype(category) # 2. 建空间邻接图library_key 指向样本列 sq.gr.spatial_neighbors( adata, library_keysample, coord_typegeneric, delaunayTrue, ) # 3. 单条件邻域富集先子集再算 adata_balbc adata[adata.obs[condition] BALBc].copy() cc.gr.nhood_enrichment( adata_balbc, cluster_keyspatial_cluster, ) cc.pl.nhood_enrichment( adata_balbc, cluster_keyspatial_cluster, annotateTrue, vmin-1, vmax1, ) # 4. 差异邻域富集跨条件比较 cc.gr.diff_nhood_enrichment( adata, cluster_keyspatial_cluster, condition_keycondition, library_keysample, pvaluesTrue, n_jobs15, n_perms100, ) cc.pl.diff_nhood_enrichment( adata, cluster_keyspatial_cluster, condition_keycondition, condition_groups[MRL, BALBc], annotateTrue, figsize(7, 7), significance0.05, )几个参数要特别留意。sq.gr.spatial_neighbors里的library_key必须指向样本列高精度平台多切片时这个不设对邻接图会跨样本连边。cc.gr.nhood_enrichment的cluster_key要和聚类时存进adata.obs的列名完全一致大小写都不能差。diff_nhood_enrichment的condition_groups顺序会影响热图方向[MRL, BALBc]和反过来画出来的图是镜像的按你的生物学问题定。n_perms控制置换检验次数100 次够看趋势正式分析建议 1000 次以上。n_jobs按你机器核数设设太大反而会因为内存争抢变慢。significance是差异图里标注显著性的阈值0.05 是常规选择。5. 验证请求与成功结果配置和代码都就位后怎么确认图是对的先跑一个最小验证。取adata_balbc只保留两个空间簇跑nhood_enrichment看输出的矩阵形状是不是(2, 2)对角线是不是接近 0 或者正值。如果形状不对说明cluster_key的类别数和你以为的不一样。# 最小验证只取两个簇 adata_test adata_balbc[ adata_balbc.obs[spatial_cluster].isin( adata_balbc.obs[spatial_cluster].cat.categories[:2] ) ].copy() cc.gr.nhood_enrichment(adata_test, cluster_keyspatial_cluster) print(adata_test.uns[spatial_cluster_nhood_enrichment][zscore].shape)正常输出应该是(2, 2)。如果报KeyError回去检查列名如果形状是(1, 1)或者更大说明子集没取对。验证通过后再跑完整的cc.pl.nhood_enrichment热图的行列标签应该和adata.obs[spatial_cluster].cat.categories完全一致颜色范围在vmin-1, vmax1之间分布合理不会全是一个色。差异图那边跑完diff_nhood_enrichment后adata.uns里会多出对应的 z-score 和 p-value 矩阵。你可以打印出来看显著富集的格子 p-value 应该小于 0.05z-score 绝对值偏大。如果全是 NaN多半是condition_groups里的条件名和adata.obs[condition]的取值对不上。6. 本篇常见报错排查排障时按下面这个顺序查基本能覆盖九成问题。报错/现象可能原因排查动作KeyError: spatial_cluster列名拼写不一致或未写入 obsprint(adata.obs.columns)核对热图行列标签乱序cluster_key列不是 category.astype(category)转换图全空白/全同色空间邻接图未建或为空检查adata.obsp是否有spatial_connectivities跨样本邻域混算library_key未设或设错确认spatial_neighbors的library_keydiff_nhood_enrichment全 NaNcondition_groups名称不匹配打印adata.obs[condition].unique()置换检验跑不动n_perms过大或n_jobs过高先降到 100 次、n_jobs4试跑还有一个隐蔽的坑高精度平台 HD 的adata.X如果是稀疏矩阵某些版本的cellcharter在计算时会因为内存布局问题给出错误结果。可以在跑之前adata.X adata.X.tocsr()转一下格式。另外如果你在聚类时用了X_cellcharter这个 repnhood_enrichment不会去读它它只认cluster_key指向的 obs 列别把 rep 名字和 cluster 列名搞混。排查过程中如果拿不准把报错原文和adata.obs的dtypes贴给 Codex让它对照官方示例帮你判断。通道配置参考 https://taotoken.net/api-keys 接入文档在 https://taotoken.net/doc 里面有更细的参数说明。7. 把通道和排障流程固定下来整套流程跑通之后建议把 Codex 的配置和排查提示词存成一个模板。下次再遇到nhood_enrichment出图不对直接套模板让 Codex 核对不用每次从头描述。TaoToken 的通道在这里就是个稳定的模型入口你把它配好剩下的推理和比对交给 Codex数据操作留在本地。长期做空间转录组分析的话Coding Plan 页面 https://taotoken.net/coding-plan 里有针对 Agent 场景的通道说明适合把这类排障流程固化下来。模型对话页面 https://taotoken.net/models 可以随时验证通道是否正常。ClaudeCodeAnthropic 相关的接入方式在 https://taotoken.net/claude-code-anthropic 有说明按需取用。最后提醒一句nhood_enrichment的图对不对根子上取决于cluster_key那一列和空间邻接图。把这两样确认好再让 Codex 帮你比对参数比盲目调vmin、vmax有用得多。