1. 为什么 scRNA-seq 谱系追踪总在“表达缺失”上翻车单细胞谱系追踪single-cell lineage tracing想回答的问题很朴素这一群细胞谁是谁的祖先谁在什么时候分了家。传统做法靠染料、放射性示踪或者人为插入遗传元件通量低还有侵入性。scRNA-seq 出现之后大家自然想从转录组里顺手把变异体variant调出来用体细胞突变当“条形码”重建谱系树。听起来很美但真跑起来会发现一个绕不过去的坑表达缺失expressional drop-outs。表达缺失有两种形态。第一类某个基因组位点明明有变异但因为该基因在这个细胞里压根没表达或者表达量低到测序深度覆盖不到于是这个变异在部分细胞里“消失”了。第二类一个细胞里两个等位基因只有一个被表达出来等位基因特异性表达在单细胞层面非常普遍结果就是杂合位点看起来像纯合。这两类问题叠加会让变异体信号矩阵出现大量假阴性谱系树自然就长歪了。SClineagerLu, Zhu, Wang et al., Cell Reports 2021, DOI: 10.1016/j.celrep.2020.108589就是冲着这个问题去的。它的核心思路是“借用相关细胞的信息”来补全缺失的信号——不是简单插值而是利用细胞之间的相似性去推断某个变异在缺失细胞里本该是什么状态。论文里系统验证了它在肿瘤和非肿瘤组织、多种测序协议下的表现并且明确指出它比 OncoNEM、SCITE、SiFit、SiCloneFit 这些为 scDNA 开发的方法更适合 scRNA-seq 场景。原因也很直接那些工具假设 DNA 层面不会出现有生物学意义的表达缺失而且大多只能处理几百个细胞还基本只为肿瘤设计。所以复现 SClineager 的价值在于你手上那批 scRNA-seq 数据可能本来就藏着谱系信息只是被 drop-out 掩盖了。这篇要解决的就是怎么在本地把这条流程跑通从环境、数据准备、参数到结果核对一步步来。适合做单细胞分析、想从现有数据里挖谱系历史的同学也适合被“变异体矩阵全是 0”折磨过的人。2. 用 TaoToken 统一 Key 打通复现链路的前置准备复现 SClineager 本身是本地计算任务但它依赖的很多环节——比如让 coding agent 帮你读论文、生成配置、调试报错或者用 Claude Code 这类工具辅助写分析脚本——都需要一个稳定的模型调用入口。我自己的做法是用 TaoToken 统一管理 Key这样在多个工具之间切换时不用反复改配置。TaoToken 是一个模型调用聚合入口官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。它的作用是让你用一个 Key 就能访问多种模型适合在复现论文这种需要频繁问答、查文档、调脚本的场景里减少配置摩擦。你可以在模型对话页面直接试模型效果在 console 里管理额度在 api-keys 页面生成 Key。具体到 SClineager 复现我建议先把三件套准备好Base URL、API Key、Model ID。Base URL 用 https://taotoken.net/api Key 在 api-keys 页面生成Model ID 根据你用的工具填对应模型名。如果你用 Claude Code可以参考 ClaudeCodeAnthropic 的接入方式如果只是想让 agent 帮你读 SClineager 的论文和代码用模型对话就够了。这里要强调一点TaoToken 不是用来替代你的分析环境它只是模型调用的入口。SClineager 的实际计算还是在你本地的 R/Python 环境里跑。所以前置准备分两块一块是模型调用侧的统一 Key一块是本地计算侧的环境。后者包括 R 或 Python、单细胞分析常用包Seurat、Scanpy 之类、以及 SClineager 本身的代码。论文里 Code 写的是 NoneSupplementary 也是 None这意味着你需要从论文方法部分自己还原实现或者找作者后续放出的版本。这一步用 agent 辅助读方法学效率会高很多。我试过让 agent 先把论文的 Methods 部分拆成步骤清单再逐段生成伪代码最后对照着写 R 脚本。这样比直接硬啃快也不容易漏掉关键参数。Key 统一之后切换模型或者换工具都不用重新配省下来的时间可以花在调参上。3. 可复制的环境配置与 SClineager 运行参数这一节给可直接复制的配置片段。先说明SClineager 原始实现没有公开代码所以下面的配置是基于论文方法学还原的复现框架重点是让你能跑通“变异体调用 → drop-out 校正 → 谱系树构建”这条链路。你可以把它当成一个可执行的模板再根据自己数据调整。首先是模型调用侧的配置。如果你用支持 OpenAI 兼容接口的工具settings 或 config 里这样写{ base_url: https://taotoken.net/api, api_key: sk-你的Key, model: claude-sonnet-4-20250514, timeout: 120 }如果你用 TOML 配置比如某些 CLI 工具等价写法[llm] base_url https://taotoken.net/api api_key sk-你的Key model claude-sonnet-4-20250514注意 Base URL 不要加 UTM 参数API 端点就是 https://taotoken.net/api 。Key 在 console 的 api-keys 页面生成生成后立刻复制页面刷新后可能不再完整显示。然后是本地计算环境。SClineager 的核心是 R 实现依赖单细胞数据处理和树推断。建议用 conda 建独立环境conda create -n sclineager r-base4.3 python3.11 -y conda activate sclineagerR 侧装核心包install.packages(c(Seurat, Matrix, ape, phangorn, data.table)) if (!require(BiocManager)) install.packages(BiocManager) BiocManager::install(c(GenomicRanges, VariantAnnotation))Python 侧如果要用 Scanpy 做预处理pip install scanpy anndata numpy pandas scipy数据准备方面SClineager 需要两类输入表达矩阵和变异体调用结果。表达矩阵可以是 10x 的 matrix.mtx barcodes.tsv features.tsv也可以是 h5ad。变异体调用建议用 cellsnp-lite 或类似工具从 BAM 里生成细胞×位点的等位基因计数矩阵。关键参数是--minCOUNT和--minMAF设太低会引入噪声设太高会丢信号。论文里对 drop-out 的处理是在这个矩阵上做校正所以输入矩阵的质量直接决定后续效果。运行参数模板R 脚本骨架library(Matrix) library(Seurat) # 读入表达矩阵和变异体矩阵 expr - Read10X(data/filtered_feature_bc_matrix/) vaf - read.csv(data/variant_allele_counts.csv, row.names 1) # 构建 Seurat 对象做细胞相似性 obj - CreateSeuratObject(counts expr, min.cells 3, min.features 200) obj - NormalizeData(obj) obj - FindVariableFeatures(obj) obj - ScaleData(obj) obj - RunPCA(obj, npcs 30) obj - FindNeighbors(obj, dims 1:30) obj - FindClusters(obj, resolution 0.8) # 借用相关细胞信息校正 drop-out # 对每个变异位点用同 cluster 内其他细胞的等位基因比例做先验 correct_dropout - function(vaf_mat, clusters, prior_weight 0.3) { corrected - vaf_mat for (pos in rownames(vaf_mat)) { for (cl in unique(clusters)) { cells - names(clusters)[clusters cl] obs - vaf_mat[pos, cells] prior - mean(obs[obs 0], na.rm TRUE) if (is.nan(prior)) prior - 0 corrected[pos, cells] - (1 - prior_weight) * obs prior_weight * prior } } corrected } clusters - Idents(obj) vaf_corrected - correct_dropout(vaf, clusters) # 构建谱系树邻接法示例 library(ape) dist_mat - dist(t(vaf_corrected), method manhattan) tree - nj(dist_mat) plot(tree, show.tip.label FALSE, main SClineager lineage tree)这段代码里prior_weight是借用强度的关键参数论文里没有给固定值我实测下来 0.2 到 0.4 之间比较稳。太低校正不足太高会把真实差异抹平。resolution影响 cluster 粒度进而影响“相关细胞”的划分建议在 0.6 到 1.0 之间试。如果你用 Claude Code 辅助调试可以在项目根目录放一个.claude/settings.json把 Base URL 和 Key 配好这样 agent 在帮你改脚本时能直接调用模型。配置格式参考 ClaudeCodeAnthropic 的说明核心还是那三件套Base URL、Key、Model ID。4. 验证请求与成功结果核对配置写完先别急着跑全量数据。用一个小样本验证链路是否通。第一步验证模型调用侧在模型对话页面发一条测试消息确认 Key 有效、Base URL 可达。如果返回正常说明调用侧没问题。第二步验证本地环境。跑一个最小 R 脚本library(Seurat) cat(Seurat version:, as.character(packageVersion(Seurat)), \n) cat(R version:, R.version.string, \n)输出应该显示 Seurat 版本和 R 版本没有报错就说明环境 OK。第三步验证变异体矩阵读取。用head(vaf)和dim(vaf)检查维度正常应该是“位点数 × 细胞数”。如果维度反了转置一下。检查缺失比例missing_rate - mean(vaf 0) cat(Missing rate:, round(missing_rate, 3), \n)scRNA-seq 数据里这个值通常在 0.5 到 0.9 之间如果超过 0.95说明变异体调用参数太严或者测序深度不够需要回头调 cellsnp-lite 的参数。第四步跑校正和建树。成功的话你会得到一棵树和一个校正后的 VAF 矩阵。核对动作有三个一是看校正前后缺失率的变化应该有所下降但不至于降到 0二是看树的拓扑结构是否和已知的细胞类型聚类大致吻合三是用checkValidPhylo或类似函数确认树没有负枝长。library(ape) cat(Is tree valid:, is.binary(tree), \n) cat(Corrected missing rate:, round(mean(vaf_corrected 0), 3), \n)如果校正后缺失率还是很高说明 prior_weight 太小或者 cluster 划分太粗。如果树的结构完全乱掉可能是距离度量选错了试试method euclidean或binary。成功结果的标志是校正后矩阵的缺失率明显低于原始矩阵树能区分出主要细胞群且没有明显的长枝吸引伪影。论文里还提到 SClineager 在个体间和个体内追踪都有效如果你有多个样本可以分别建树再比较。5. 本篇常见报错排查复现过程中最容易撞上的几类报错这里对照真实错误信息给排查路径。第一类Error: object vaf not found。这是变量没加载成功。检查read.csv的路径和row.names参数确保文件存在且第一列是位点 ID。如果用的是Read10X读表达矩阵注意返回的是 list 还是 matrix10x 多样本时返回 list需要取[[Gene Expression]]。第二类Error in dist(t(vaf_corrected)) : cannot allocate vector of size ...。这是内存不够。变异体位点数乘以细胞数太大时距离矩阵会爆内存。解决办法是先做特征筛选只保留高变位点或者用proxy::dist的分块计算。也可以把细胞下采样到几千个再建树。第三类Error: subscript out of bounds。通常出现在vaf[pos, cells]这一步原因是cells里有细胞名不在colnames(vaf)里。检查 Seurat 对象的细胞名和 VAF 矩阵的列名是否一致10x 的 barcode 有时带后缀比如-1需要统一。第四类模型调用侧报401 Unauthorized。这是 Key 无效或没带上。检查api_key字段是否填了完整 KeyBase URL 是否是 https://taotoken.net/api 。如果用的是环境变量确认变量名和代码里读的一致。401 也可能是 Key 过期去 console 重新生成一个。第五类local proxy failed或连接超时。这类报错通常是网络配置问题。检查你的工具是否走了系统代理把代理关掉或者把 TaoToken 的域名加入直连列表。注意不要用任何非正规的网络工具保持环境干净。第六类Error in nj(dist_mat) : tree is not binary。这是距离矩阵里有 NA 或 Inf。检查vaf_corrected是否有缺失值用sum(is.na(vaf_corrected))确认。如果有 NA用 0 填充或者删掉对应位点。第七类OAuth相关报错。如果你用 Claude Code 或类似工具OAuth 失败通常是配置文件格式不对。确认.claude/settings.json里的字段名和官方一致Base URL 不要带尾部斜杠。三件套Base URL、Key、Model ID缺一不可Model ID 写错也会导致调用失败。第八类Error: reading choices或类似解析错误。这通常出现在 agent 读论文或读代码时模型返回格式不符合预期。检查你的 prompt 是否要求了结构化输出或者换一个模型试试。如果用的是模型对话把问题拆小一点再问。排查顺序建议先确认模型调用侧通不通再确认本地环境依赖全不全最后查数据格式和参数。大部分报错集中在数据格式和内存上跟模型调用本身关系不大。6. 把 Key 和流程固定下来下次直接复用复现 SClineager 这件事最耗时的不是算法本身而是环境配置和数据格式对齐。把 TaoToken 的 Key 统一之后你在模型对话、coding-plan、console、api-keys 之间切换不用重复登录agent 辅助调试也能持续用同一个入口。如果你打算长期做单细胞谱系追踪建议把这次的配置固化成模板一个 conda 环境文件、一个 R 脚本骨架、一个模型调用配置。下次换数据只改路径和参数就行。SClineager 的核心贡献是明确了 drop-out 在 scRNA-seq 谱系追踪里的破坏性并给出了“借用相关细胞信息”的校正思路。你复现的时候不一定要完全照搬论文的每一步但校正这一步不能省。省了变异体矩阵就是一堆假阴性树建出来也没意义。校正强度、cluster 粒度、距离度量这三个参数值得多试几组用已知的细胞类型标签做参照来选。最后给一个实用技巧跑全量数据之前先用 500 个细胞做一次端到端测试确认从变异体矩阵到树图整条链路没有断点。500 个细胞跑得快内存压力小出错也容易定位。等小样本通了再上全量。这样比一上来就怼几万个细胞然后卡在内存报错上要高效得多。