ETE 4 本地分类学实战用 NCBITaxa 与 GTDBTaxa 构建可复现的 NCBI/GTDB 注释管线scientific-agent-skills 指南【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills导读本文围绕 scientific-agent-skills 仓库中 etetoolkit 技能的 taxonomy.md 参考文档展开系统讲解 ETE 4.4.0 提供的两个本地 SQLite 分类学接口基于 NCBI Taxonomy 的NCBITaxa与基于 Genome Taxonomy DatabaseGTDB的GTDBTaxa。读完本文你将掌握分类学数据库的首次构建与存储管理、构造函数参数语义、显式更新与离线复用模式、名称与 TaxID 的双向翻译、谱系与分类阶元查询、后代类群检索、最小连通拓扑构建以及如何将分类学注释批量写入PhyloTree树对象最终形成一套可溯源、可离线运行、可验证的生产级分类学标注流程。ETE 4 的两大本地分类学接口ETE 4当前技能锁定版本 4.4.0安装与适用范围见 SKILL.md不再依赖在线查询服务做日常分类学解析而是提供两个本地 SQLite 后端NCBITaxa面向 NCBI Taxonomy 的本地接口负责物种科学名、TaxID、谱系、分类阶元rank与子代类群的查询GTDBTaxa面向基因组分类学数据库GTDB的本地接口使用 GTDB 特有的字符串标识符体系。二者能力对称均可完成标识符翻译、谱系与阶元检索、后代类群查找、最小连通拓扑topology构建以及向PhyloTree对象批量写入分类学注释。在 api_reference.md 的公开类清单中这两个类与Tree、PhyloTree、SeqGroup、EvolTree并列导出from ete4 import ( EvolTree, GTDBTaxa, NCBITaxa, PhyloTree, SeqGroup, Tree, )需要特别强调的是NCBI 的数字 TaxID 与 GTDB 的字符串标识符互不通用混用会导致解析失败或错误注释这一点在 migration-ete3-to-ete4.md 的“Taxonomy Changes”一节中也有明确提醒。数据存储、首次占用与前提条件存储路径与磁盘占用ETE 4 将解析后的分类学数据库存放在默认目录~/.local/share/ete/这是相对 ETE 3 的重要迁移点ETE 3 时代的典型路径是~/.etetoolkit/taxa.sqlite而 ETE 4 已经迁移至上述位置见 migration-ete3-to-ete4.md。关于官方教程中“约 600 MB NCBI、约 72 MB GTDB”的表述应将其理解为本地首次使用后的磁盘占用footprint估计而不是压缩包的网络下载体积。归档文件大小随版本发布波动可能远小于该数值但解析后的 SQLite 数据库、遍历缓存与临时转换文件叠加在一起仍需要预留充足磁盘空间。在磁盘受限或离线任务中切勿让程序在运行时“意外地”触发数据库创建或刷新——这正是本文后面要重点讲解“显式更新 固定 dbfile”模式的原因。无需凭证NCBI 与 GTDB 两条路径都使用公开下载的分类学数据不需要任何 API key 或凭据。唯一的外部依赖是首次构建数据库时的网络访问后续离线分析可完全脱离网络详见“缓存与离线模式”一节。构造函数与关键参数两个类共享同一套构造语义from ete4 import GTDBTaxa, NCBITaxa ncbi NCBITaxa( dbfileNone, taxdump_fileNone, memoryFalse, updateTrue, ) gtdb GTDBTaxa( dbfileNone, taxdump_fileNone, memoryFalse, )四个核心参数的作用与适用场景参数默认值作用使用建议dbfileNone显式指定解析后的 SQLite 数据库文件路径可复现/离线分析时必须显式给出并在多次运行间复用同一文件taxdump_fileNone指定本地分类学归档如taxdump.tar.gz用于创建或更新数据库已事先下载归档时传入可避免重复网络下载memoryFalse为True时把数据库整体加载进内存供反复查询加速需要高频重复查询的交互式会话中使用updateTrue仅NCBITaxa存在设为False可关闭构造函数内部的 schema 更新路径离线或固定快照场景必须设为False防止构造时联网关于updateTrue的重要澄清当数据库不存在时构造过程会自动创建或下载它。但一个常见误解是updateTrue会在每次构造时把已有数据库刷新到最新分类学内容——事实并非如此。已有数据库不会仅仅因为updateTrue就被刷新只有显式调用update_taxonomy_database()才会触发内容级刷新。因此想要“最新的分类学内容”请调用显式更新方法见下一节想要“完全可复现的分析”请固定dbfile并在构造时传updateFalse。显式更新数据库与 ETE 4.4.0 的更新器注意事项三种更新方式获取最新 NCBI taxonomyfrom ete4 import NCBITaxa ncbi NCBITaxa(updateFalse) ncbi.update_taxonomy_database()获取最新 GTDB taxonomyfrom ete4 import GTDBTaxa gtdb GTDBTaxa() gtdb.update_taxonomy_database()使用已经下载好的本地归档构建/更新离线友好ncbi.update_taxonomy_database(taxdump.tar.gz) gtdb.update_taxonomy_database(gtdb_taxdump.tar.gz)生产溯源记录在生产分析中每当更新分类学数据库都应当记录以下元数据以支撑可审计性来源数据库NCBI 还是 GTDB获取日期与上游发布版本如可得归档文件与解析后数据库的校验和checksumETE 版本应用的任何过滤条件或分类阶元上限。此外不要在多步骤分析的中途替换共享数据库——步骤之间必须使用同一个快照否则跨步骤的注释会因分类学版本漂移而失去一致性。ETE 4.4.0 更新器已知注意事项这是 taxonomy.md 中记录的重要工程细节直接关系到更新行为的正确性NCBI 刷新会下载官方 taxdump 归档并校验其 MD5 伴随文件sidecar确保下载完整性。GTDB 刷新使用的是 ETE 转换后的 NCBI 风格 dump而不是 GTDB 原始数据库文件。GTDB 新鲜度检查的已知问题ETE 4.4.0 的 GTDB 新鲜度检查会请求一个当前 ETE-data 位置并不存在的 MD5 sidecar因此一次“名义上的更新”可能表现为重新下载数据而非报告“已是最新”。这是版本级行为遇到重复下载时不必惊讶。临时文件分类学转换会在进程工作目录中创建临时文件。更新操作应在可控、可写的目录中运行若更新被中断需要清理残留的临时文件。NCBI 标识符翻译科学名 → TaxIDfrom ete4 import NCBITaxa ncbi NCBITaxa() queries [Homo sapiens, Pan troglodytes, Mus musculus] name_to_taxids ncbi.get_name_translator(queries) for query in queries: candidates name_to_taxids.get(query, []) if not candidates: print(unresolved:, query) elif len(candidates) 1: print(ambiguous:, query, candidates) else: print(query, candidates[0])get_name_translator返回的每个条目都是一个列表因为一个名称可能对应多个分类学记录同名异种、拼写变体等。不要不加检查地直接取下标 0——正确处理歧义是名称翻译环节的第一原则。TaxID → 科学名taxid_to_name ncbi.get_taxid_translator([9606, 9598, 10090]) print(taxid_to_name)get_taxid_translator接收 TaxID 列表返回{taxid: sci_name}映射常用于把谱系中的一串数字 ID 还原为可读名称。谱系与分类阶元查询给定一个 TaxID以人类9606为例可以同时取出完整的祖先谱系、每个祖先的名称与阶元taxid 9606 lineage ncbi.get_lineage(taxid) names ncbi.get_taxid_translator(lineage) ranks ncbi.get_rank(lineage) for ancestor in lineage: print(ancestor, names.get(ancestor), ranks.get(ancestor, no rank))注意这里全部使用.get()而不是直接下标访问并非每个分类学节点都保证带有全部注释属性例如某些节点没有 rank此时ranks.get(ancestor, no rank)会给出安全的回退值。后代类群检索从某个分类单元出发向下枚举全部子代descendants ncbi.get_descendant_taxa(Homo) print(ncbi.translate_to_names(descendants))折叠到物种级以下只保留到种不再细分亚种species ncbi.get_descendant_taxa( Homo, collapse_subspeciesTrue, )返回 ETE 树对象而不只是 ID 列表便于进一步可视化或导出tree ncbi.get_descendant_taxa( Homo, collapse_subspeciesTrue, return_treeTrue, ) print(tree.to_str(props[sci_name, taxid, rank]))一个实用的规模预警大型内部类群如某些门、纲级分类单元可能包含数量庞大的后代。在将完整结果物化materialize或打印之前应先评估返回规模避免内存与输出的失控。这与 workflows.md 中“大树优先用生成器”的原则一脉相承。用 NCBI 构建最小连通拓扑把若干 TaxID 放入同一棵树得到连接它们的最小分类学拓扑taxids [9606, 9598, 10090, 7707, 8782] tree ncbi.get_topology( taxids, intermediate_nodesFalse, collapse_subspeciesFalse, annotateTrue, ) print(tree.to_str(props[sci_name, rank, taxid]))保留全部中间分类学节点tree ncbi.get_topology( [2, 33208], intermediate_nodesTrue, annotateTrue, )三个关键参数的含义intermediate_nodes是否保留连接这些 TaxID 所需的中间分类学节点False时拓扑尽量精简collapse_subspecies是否折叠亚种级以下的细分annotate是否在返回的树节点上写入sci_name、rank、taxid等注释属性。必须区分的概念分类拓扑 ≠ 分子系统发育这是本文最重要的一条科学解释红线get_topology生成的树是分类学层级结构classification hierarchy它的枝长或缺失的中间阶元不代表分子系统发育关系。绝不能把这种拓扑当作系统发育树去解读演化时序或枝长意义。同样的警示也出现在 workflows.md 的第 9 节与第 13 节ETE 负责操作和解读已有拓扑不负责替上游的建树方法“擦屁股”。GTDB 查询GTDB 标识符格式GTDB 的标识符是字符串按前缀区分分类学层级或基因组归属典型示例d__Bacteria p__Firmicutes_B f__Korarchaeaceae GB_GCA_020833055.1 RS_GCF_000019605.1其中d__/p__/c__/o__/f__/g__/s__分别对应界、门、纲、目、科、属、种GB_/RS_前缀标识 GTDB 代表性/参考基因组。硬性规则不要把 GTDB 字符串传给NCBITaxa也不要把 NCBI 数字 TaxID 传给GTDBTaxa。后代类群查询from ete4 import GTDBTaxa gtdb GTDBTaxa() descendants gtdb.get_descendant_taxa(f__Thorarchaeaceae) print(descendants)构建 GTDB 拓扑queries [ p__Huberarchaeota, o__Peptococcales, f__Korarchaeaceae, ] tree gtdb.get_topology( queries, intermediate_nodesTrue, collapse_subspeciesTrue, annotateTrue, ) print(tree.to_str(props[sci_name, rank]))GTDB 与 NCBI 的体系差异GTDB 与 NCBI 的分类学结论可以互相不一致二者使用不同的数据来源、发布周期、命名法与分类学框架。因此在论文或报告中必须指明使用的是哪一套体系在没有明确映射策略的情况下不要混用两套标签。这与技能整体“state which one was used”的质量原则一致。为 PhyloTree 批量注释分类学信息annotate_ncbi_taxa/annotate_gtdb_taxa是连接“树分析”与“分类学数据库”的桥梁支持三种取 ID 的方式。方式一叶子名本身就是 TaxIDfrom ete4 import PhyloTree tree PhyloTree(((9606,9598),10090);) taxid_to_name, taxid_to_lineage, taxid_to_rank tree.annotate_ncbi_taxa( taxid_attrname, ) print(tree.to_str(props[name, sci_name, taxid, rank]))方式二从复合名中提取 TaxID当叶子名是9606|protA这类“TaxID|蛋白质ID”复合结构时通过sp_naming_function指定如何从名字中解析出分类标识符tree PhyloTree( ((9606|protA,9598|protB),10090|protC);, sp_naming_functionlambda name: name.split(|, 1)[0], ) tree.annotate_ncbi_taxa(taxid_attrspecies)注意sp_naming_function提取的值会写入species属性因此这里taxid_attrspecies。方式三显式自定义属性最稳妥当叶子名不是稳定的分类学标识符时例如通用蛋白代号优先使用显式映射tree PhyloTree(((protA,protB),protC);) taxids { protA: 9606, protB: 9598, protC: 10090, } for leaf in tree.leaves(): leaf.add_prop(ncbi_taxid, taxids[leaf.name]) tree.annotate_ncbi_taxa(taxid_attrncbi_taxid)add_prop是 ETE 4 的节点元数据 API区别于 ETE 3 的add_features详见 api_reference.md。用 GTDB 注释 PhyloTreefrom ete4 import PhyloTree tree PhyloTree( ((GB_GCA_020833055.1|protA,GB_GCA_003344655.1|protB), RS_GCF_000019605.1|protC);, sp_naming_functionlambda name: name.split(|, 1)[0], ) tree.annotate_gtdb_taxa(taxid_attrspecies) print(tree.to_str(props[name, sci_name, rank]))注释方法的行为细节两类注释方法都具备一个共同能力在可能的情况下从子节点推断内部节点的分类学归属internal-node taxonomy inference并且都会返回它们实际使用的翻译器映射如taxid_to_name等。当分析需要可审计的记录时请保留这些返回的映射它们构成了注释链路的完整证据。缓存与离线模式可控网络步骤 固定快照这是面向集群、容器与离线环境的标准落地模式分两步走。第一步在受控的网络步骤中准备数据库。from ete4 import NCBITaxa db_path taxonomy/ncbi_taxa.sqlite ncbi NCBITaxa(dbfiledb_path, updateFalse) ncbi.update_taxonomy_database(taxonomy/taxdump.tar.gz)这里先以本地归档构建固定路径的 SQLite 数据库全程使用updateFalse关闭构造期的 schema 更新避免节外生枝。第二步分析任务中只读地使用被钉住的数据库。ncbi NCBITaxa( dbfiletaxonomy/ncbi_taxa.sqlite, updateFalse, )对于只读容器或集群任务把数据库挂载到显式路径避免依赖“家目录默认路径不可写”的隐性假设。这种模式把“数据准备”与“数据分析”彻底解耦网络只出现在准备阶段后续所有分析任务零网络、零重下载、结果可逐字节复现。生产溯源与验证清单在正式使用分类学注释之前taxonomy.md 给出的验证清单值得逐条过一遍确认标识符体系先确认手头标识符是 NCBI 数字 TaxID 还是 GTDB 字符串检测未解析与多重解析对名称翻译结果做 unresolved / ambiguous 检查绝不静默取第一个候选核对 accessions 前缀与发布约定确认GB_/RS_等前缀及发布约定与所用 GTDB 快照一致记录数据库来源与校验和来源、获取日期、上游版本、归档与解析库 checksum、ETE 版本、过滤条件与 rank 上限区分分类拓扑与推断系统发育分类层级树不是分子系统发育不得混淆解读更新后复查阶元与学名变化数据库更新后rank 与 scientific name 可能随发布而变化需重新核验按需导出只导出下游真正需要的注释属性避免把内部注释属性一并写进输出文件这与 workflows.md 中“propsNone会写出全部属性应显式指定props列表”的告诫一致。与 ETE 3 的迁移要点若你正从 ETE 3 移植分类学代码migration-ete3-to-ete4.md 的“Taxonomy Changes”一节给出了三条核心差异导入对象变化from ete3 import NCBITaxa变为from ete4 import NCBITaxa, GTDBTaxa且 GTDB 是 ETE 4 新增的一等公民支持数据库路径变化从~/.etetoolkit/taxa.sqlite迁移到~/.local/share/ete/标识符体系隔离NCBI 数字 TaxID 与 GTDB 字符串标识符不可互换。总结ETE 4 的NCBITaxa与GTDBTaxa把分类学工作从“在线查库”推进到“本地 SQLite 显式快照 离线复用”的工程化阶段。本文给出的完整操作路径——构造参数、显式更新、名称/TaxID 翻译、谱系与后代查询、最小拓扑构建、PhyloTree三式注释以及“固定 dbfile updateFalse”的缓存离线模式——可以在 scientific-agent-skills 的 etetoolkit 技能环境中直接落地。继续深入可参阅仓库内的 api_reference.md公开类与方法签名、workflows.md分类学拓扑与完整分析模式、migration-ete3-to-ete4.md迁移清单以及技能主文档 SKILL.md安装、脚本与适用范围。【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
ETE 4 本地分类学实战用 NCBITaxa 与 GTDBTaxa 构建可复现的 NCBI/GTDB 注释管线scientific-agent-skills 指南【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills导读本文围绕 scientific-agent-skills 仓库中 etetoolkit 技能的 taxonomy.md 参考文档展开系统讲解 ETE 4.4.0 提供的两个本地 SQLite 分类学接口基于 NCBI Taxonomy 的NCBITaxa与基于 Genome Taxonomy DatabaseGTDB的GTDBTaxa。读完本文你将掌握分类学数据库的首次构建与存储管理、构造函数参数语义、显式更新与离线复用模式、名称与 TaxID 的双向翻译、谱系与分类阶元查询、后代类群检索、最小连通拓扑构建以及如何将分类学注释批量写入PhyloTree树对象最终形成一套可溯源、可离线运行、可验证的生产级分类学标注流程。ETE 4 的两大本地分类学接口ETE 4当前技能锁定版本 4.4.0安装与适用范围见 SKILL.md不再依赖在线查询服务做日常分类学解析而是提供两个本地 SQLite 后端NCBITaxa面向 NCBI Taxonomy 的本地接口负责物种科学名、TaxID、谱系、分类阶元rank与子代类群的查询GTDBTaxa面向基因组分类学数据库GTDB的本地接口使用 GTDB 特有的字符串标识符体系。二者能力对称均可完成标识符翻译、谱系与阶元检索、后代类群查找、最小连通拓扑topology构建以及向PhyloTree对象批量写入分类学注释。在 api_reference.md 的公开类清单中这两个类与Tree、PhyloTree、SeqGroup、EvolTree并列导出from ete4 import ( EvolTree, GTDBTaxa, NCBITaxa, PhyloTree, SeqGroup, Tree, )需要特别强调的是NCBI 的数字 TaxID 与 GTDB 的字符串标识符互不通用混用会导致解析失败或错误注释这一点在 migration-ete3-to-ete4.md 的“Taxonomy Changes”一节中也有明确提醒。数据存储、首次占用与前提条件存储路径与磁盘占用ETE 4 将解析后的分类学数据库存放在默认目录~/.local/share/ete/这是相对 ETE 3 的重要迁移点ETE 3 时代的典型路径是~/.etetoolkit/taxa.sqlite而 ETE 4 已经迁移至上述位置见 migration-ete3-to-ete4.md。关于官方教程中“约 600 MB NCBI、约 72 MB GTDB”的表述应将其理解为本地首次使用后的磁盘占用footprint估计而不是压缩包的网络下载体积。归档文件大小随版本发布波动可能远小于该数值但解析后的 SQLite 数据库、遍历缓存与临时转换文件叠加在一起仍需要预留充足磁盘空间。在磁盘受限或离线任务中切勿让程序在运行时“意外地”触发数据库创建或刷新——这正是本文后面要重点讲解“显式更新 固定 dbfile”模式的原因。无需凭证NCBI 与 GTDB 两条路径都使用公开下载的分类学数据不需要任何 API key 或凭据。唯一的外部依赖是首次构建数据库时的网络访问后续离线分析可完全脱离网络详见“缓存与离线模式”一节。构造函数与关键参数两个类共享同一套构造语义from ete4 import GTDBTaxa, NCBITaxa ncbi NCBITaxa( dbfileNone, taxdump_fileNone, memoryFalse, updateTrue, ) gtdb GTDBTaxa( dbfileNone, taxdump_fileNone, memoryFalse, )四个核心参数的作用与适用场景参数默认值作用使用建议dbfileNone显式指定解析后的 SQLite 数据库文件路径可复现/离线分析时必须显式给出并在多次运行间复用同一文件taxdump_fileNone指定本地分类学归档如taxdump.tar.gz用于创建或更新数据库已事先下载归档时传入可避免重复网络下载memoryFalse为True时把数据库整体加载进内存供反复查询加速需要高频重复查询的交互式会话中使用updateTrue仅NCBITaxa存在设为False可关闭构造函数内部的 schema 更新路径离线或固定快照场景必须设为False防止构造时联网关于updateTrue的重要澄清当数据库不存在时构造过程会自动创建或下载它。但一个常见误解是updateTrue会在每次构造时把已有数据库刷新到最新分类学内容——事实并非如此。已有数据库不会仅仅因为updateTrue就被刷新只有显式调用update_taxonomy_database()才会触发内容级刷新。因此想要“最新的分类学内容”请调用显式更新方法见下一节想要“完全可复现的分析”请固定dbfile并在构造时传updateFalse。显式更新数据库与 ETE 4.4.0 的更新器注意事项三种更新方式获取最新 NCBI taxonomyfrom ete4 import NCBITaxa ncbi NCBITaxa(updateFalse) ncbi.update_taxonomy_database()获取最新 GTDB taxonomyfrom ete4 import GTDBTaxa gtdb GTDBTaxa() gtdb.update_taxonomy_database()使用已经下载好的本地归档构建/更新离线友好ncbi.update_taxonomy_database(taxdump.tar.gz) gtdb.update_taxonomy_database(gtdb_taxdump.tar.gz)生产溯源记录在生产分析中每当更新分类学数据库都应当记录以下元数据以支撑可审计性来源数据库NCBI 还是 GTDB获取日期与上游发布版本如可得归档文件与解析后数据库的校验和checksumETE 版本应用的任何过滤条件或分类阶元上限。此外不要在多步骤分析的中途替换共享数据库——步骤之间必须使用同一个快照否则跨步骤的注释会因分类学版本漂移而失去一致性。ETE 4.4.0 更新器已知注意事项这是 taxonomy.md 中记录的重要工程细节直接关系到更新行为的正确性NCBI 刷新会下载官方 taxdump 归档并校验其 MD5 伴随文件sidecar确保下载完整性。GTDB 刷新使用的是 ETE 转换后的 NCBI 风格 dump而不是 GTDB 原始数据库文件。GTDB 新鲜度检查的已知问题ETE 4.4.0 的 GTDB 新鲜度检查会请求一个当前 ETE-data 位置并不存在的 MD5 sidecar因此一次“名义上的更新”可能表现为重新下载数据而非报告“已是最新”。这是版本级行为遇到重复下载时不必惊讶。临时文件分类学转换会在进程工作目录中创建临时文件。更新操作应在可控、可写的目录中运行若更新被中断需要清理残留的临时文件。NCBI 标识符翻译科学名 → TaxIDfrom ete4 import NCBITaxa ncbi NCBITaxa() queries [Homo sapiens, Pan troglodytes, Mus musculus] name_to_taxids ncbi.get_name_translator(queries) for query in queries: candidates name_to_taxids.get(query, []) if not candidates: print(unresolved:, query) elif len(candidates) 1: print(ambiguous:, query, candidates) else: print(query, candidates[0])get_name_translator返回的每个条目都是一个列表因为一个名称可能对应多个分类学记录同名异种、拼写变体等。不要不加检查地直接取下标 0——正确处理歧义是名称翻译环节的第一原则。TaxID → 科学名taxid_to_name ncbi.get_taxid_translator([9606, 9598, 10090]) print(taxid_to_name)get_taxid_translator接收 TaxID 列表返回{taxid: sci_name}映射常用于把谱系中的一串数字 ID 还原为可读名称。谱系与分类阶元查询给定一个 TaxID以人类9606为例可以同时取出完整的祖先谱系、每个祖先的名称与阶元taxid 9606 lineage ncbi.get_lineage(taxid) names ncbi.get_taxid_translator(lineage) ranks ncbi.get_rank(lineage) for ancestor in lineage: print(ancestor, names.get(ancestor), ranks.get(ancestor, no rank))注意这里全部使用.get()而不是直接下标访问并非每个分类学节点都保证带有全部注释属性例如某些节点没有 rank此时ranks.get(ancestor, no rank)会给出安全的回退值。后代类群检索从某个分类单元出发向下枚举全部子代descendants ncbi.get_descendant_taxa(Homo) print(ncbi.translate_to_names(descendants))折叠到物种级以下只保留到种不再细分亚种species ncbi.get_descendant_taxa( Homo, collapse_subspeciesTrue, )返回 ETE 树对象而不只是 ID 列表便于进一步可视化或导出tree ncbi.get_descendant_taxa( Homo, collapse_subspeciesTrue, return_treeTrue, ) print(tree.to_str(props[sci_name, taxid, rank]))一个实用的规模预警大型内部类群如某些门、纲级分类单元可能包含数量庞大的后代。在将完整结果物化materialize或打印之前应先评估返回规模避免内存与输出的失控。这与 workflows.md 中“大树优先用生成器”的原则一脉相承。用 NCBI 构建最小连通拓扑把若干 TaxID 放入同一棵树得到连接它们的最小分类学拓扑taxids [9606, 9598, 10090, 7707, 8782] tree ncbi.get_topology( taxids, intermediate_nodesFalse, collapse_subspeciesFalse, annotateTrue, ) print(tree.to_str(props[sci_name, rank, taxid]))保留全部中间分类学节点tree ncbi.get_topology( [2, 33208], intermediate_nodesTrue, annotateTrue, )三个关键参数的含义intermediate_nodes是否保留连接这些 TaxID 所需的中间分类学节点False时拓扑尽量精简collapse_subspecies是否折叠亚种级以下的细分annotate是否在返回的树节点上写入sci_name、rank、taxid等注释属性。必须区分的概念分类拓扑 ≠ 分子系统发育这是本文最重要的一条科学解释红线get_topology生成的树是分类学层级结构classification hierarchy它的枝长或缺失的中间阶元不代表分子系统发育关系。绝不能把这种拓扑当作系统发育树去解读演化时序或枝长意义。同样的警示也出现在 workflows.md 的第 9 节与第 13 节ETE 负责操作和解读已有拓扑不负责替上游的建树方法“擦屁股”。GTDB 查询GTDB 标识符格式GTDB 的标识符是字符串按前缀区分分类学层级或基因组归属典型示例d__Bacteria p__Firmicutes_B f__Korarchaeaceae GB_GCA_020833055.1 RS_GCF_000019605.1其中d__/p__/c__/o__/f__/g__/s__分别对应界、门、纲、目、科、属、种GB_/RS_前缀标识 GTDB 代表性/参考基因组。硬性规则不要把 GTDB 字符串传给NCBITaxa也不要把 NCBI 数字 TaxID 传给GTDBTaxa。后代类群查询from ete4 import GTDBTaxa gtdb GTDBTaxa() descendants gtdb.get_descendant_taxa(f__Thorarchaeaceae) print(descendants)构建 GTDB 拓扑queries [ p__Huberarchaeota, o__Peptococcales, f__Korarchaeaceae, ] tree gtdb.get_topology( queries, intermediate_nodesTrue, collapse_subspeciesTrue, annotateTrue, ) print(tree.to_str(props[sci_name, rank]))GTDB 与 NCBI 的体系差异GTDB 与 NCBI 的分类学结论可以互相不一致二者使用不同的数据来源、发布周期、命名法与分类学框架。因此在论文或报告中必须指明使用的是哪一套体系在没有明确映射策略的情况下不要混用两套标签。这与技能整体“state which one was used”的质量原则一致。为 PhyloTree 批量注释分类学信息annotate_ncbi_taxa/annotate_gtdb_taxa是连接“树分析”与“分类学数据库”的桥梁支持三种取 ID 的方式。方式一叶子名本身就是 TaxIDfrom ete4 import PhyloTree tree PhyloTree(((9606,9598),10090);) taxid_to_name, taxid_to_lineage, taxid_to_rank tree.annotate_ncbi_taxa( taxid_attrname, ) print(tree.to_str(props[name, sci_name, taxid, rank]))方式二从复合名中提取 TaxID当叶子名是9606|protA这类“TaxID|蛋白质ID”复合结构时通过sp_naming_function指定如何从名字中解析出分类标识符tree PhyloTree( ((9606|protA,9598|protB),10090|protC);, sp_naming_functionlambda name: name.split(|, 1)[0], ) tree.annotate_ncbi_taxa(taxid_attrspecies)注意sp_naming_function提取的值会写入species属性因此这里taxid_attrspecies。方式三显式自定义属性最稳妥当叶子名不是稳定的分类学标识符时例如通用蛋白代号优先使用显式映射tree PhyloTree(((protA,protB),protC);) taxids { protA: 9606, protB: 9598, protC: 10090, } for leaf in tree.leaves(): leaf.add_prop(ncbi_taxid, taxids[leaf.name]) tree.annotate_ncbi_taxa(taxid_attrncbi_taxid)add_prop是 ETE 4 的节点元数据 API区别于 ETE 3 的add_features详见 api_reference.md。用 GTDB 注释 PhyloTreefrom ete4 import PhyloTree tree PhyloTree( ((GB_GCA_020833055.1|protA,GB_GCA_003344655.1|protB), RS_GCF_000019605.1|protC);, sp_naming_functionlambda name: name.split(|, 1)[0], ) tree.annotate_gtdb_taxa(taxid_attrspecies) print(tree.to_str(props[name, sci_name, rank]))注释方法的行为细节两类注释方法都具备一个共同能力在可能的情况下从子节点推断内部节点的分类学归属internal-node taxonomy inference并且都会返回它们实际使用的翻译器映射如taxid_to_name等。当分析需要可审计的记录时请保留这些返回的映射它们构成了注释链路的完整证据。缓存与离线模式可控网络步骤 固定快照这是面向集群、容器与离线环境的标准落地模式分两步走。第一步在受控的网络步骤中准备数据库。from ete4 import NCBITaxa db_path taxonomy/ncbi_taxa.sqlite ncbi NCBITaxa(dbfiledb_path, updateFalse) ncbi.update_taxonomy_database(taxonomy/taxdump.tar.gz)这里先以本地归档构建固定路径的 SQLite 数据库全程使用updateFalse关闭构造期的 schema 更新避免节外生枝。第二步分析任务中只读地使用被钉住的数据库。ncbi NCBITaxa( dbfiletaxonomy/ncbi_taxa.sqlite, updateFalse, )对于只读容器或集群任务把数据库挂载到显式路径避免依赖“家目录默认路径不可写”的隐性假设。这种模式把“数据准备”与“数据分析”彻底解耦网络只出现在准备阶段后续所有分析任务零网络、零重下载、结果可逐字节复现。生产溯源与验证清单在正式使用分类学注释之前taxonomy.md 给出的验证清单值得逐条过一遍确认标识符体系先确认手头标识符是 NCBI 数字 TaxID 还是 GTDB 字符串检测未解析与多重解析对名称翻译结果做 unresolved / ambiguous 检查绝不静默取第一个候选核对 accessions 前缀与发布约定确认GB_/RS_等前缀及发布约定与所用 GTDB 快照一致记录数据库来源与校验和来源、获取日期、上游版本、归档与解析库 checksum、ETE 版本、过滤条件与 rank 上限区分分类拓扑与推断系统发育分类层级树不是分子系统发育不得混淆解读更新后复查阶元与学名变化数据库更新后rank 与 scientific name 可能随发布而变化需重新核验按需导出只导出下游真正需要的注释属性避免把内部注释属性一并写进输出文件这与 workflows.md 中“propsNone会写出全部属性应显式指定props列表”的告诫一致。与 ETE 3 的迁移要点若你正从 ETE 3 移植分类学代码migration-ete3-to-ete4.md 的“Taxonomy Changes”一节给出了三条核心差异导入对象变化from ete3 import NCBITaxa变为from ete4 import NCBITaxa, GTDBTaxa且 GTDB 是 ETE 4 新增的一等公民支持数据库路径变化从~/.etetoolkit/taxa.sqlite迁移到~/.local/share/ete/标识符体系隔离NCBI 数字 TaxID 与 GTDB 字符串标识符不可互换。总结ETE 4 的NCBITaxa与GTDBTaxa把分类学工作从“在线查库”推进到“本地 SQLite 显式快照 离线复用”的工程化阶段。本文给出的完整操作路径——构造参数、显式更新、名称/TaxID 翻译、谱系与后代查询、最小拓扑构建、PhyloTree三式注释以及“固定 dbfile updateFalse”的缓存离线模式——可以在 scientific-agent-skills 的 etetoolkit 技能环境中直接落地。继续深入可参阅仓库内的 api_reference.md公开类与方法签名、workflows.md分类学拓扑与完整分析模式、migration-ete3-to-ete4.md迁移清单以及技能主文档 SKILL.md安装、脚本与适用范围。【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
