从 ETE 3 平滑迁移到 ETE 4scientific-agent-skills 项目中的完整 API 断代升级实战指南【免费下载链接】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-skillsETE 4 不是一次改改 import 就能用的小版本升级而是一次破坏性breaking的 API 修订。本指南以仓库中 迁移文档 为核心骨架结合 ETE 4.4.0 的实测行为与本仓库的源码佐证系统梳理从 ETE 3 移植代码时需要处理的每一个断点导入路径、构造与文件输入、属性模型、迭代器、Newick I/O 语义、距离与拓扑方法、Robinson-Foulds 返回值、PhyloTree 与分类学、可视化体系以及被移除的 ClusterTree。读完本文你将能够机械地把旧代码逐符号改写为 ETE 4 语法并借助验证片段与移植检查清单确保科学输出而非仅仅跑通。迁移基线版本与安装前提本仓库的 ETE 技能skills/etetoolkit/SKILL.md将当前目标锁定为ETE 4.4.0迁移文档所描述的全部行为均以该版本实测验证为准。版本时间线如下ETE 4.0.0 与 4.1.1 于 2025 年 3 月 28 日发布ETE 4.1.1 将 ETE 4 从 beta 状态转正并上线 PyPIETE 4.4.0 于 2025 年 9 月 3 日发布包名与首要导入均为ete4。安装时使用精确版本锁定uv pip install ete44.4.0仅当遗留项目确实需要 ETE 3 时才考虑并行安装。但切记不要在同一个代码路径中同时隐式使用两套 API。名称兼容边界必须显式命名、分开测试否则极易把 ETE 3 的调用约定悄悄带进 ETE 4 代码。本仓库的捆绑脚本在导入时同样做了强校验例如scripts/tree_operations.py会在缺少ete4时直接抛出带安装提示的退出信息try: import ete4 from ete4 import Tree from ete4.parser.newick import NewickError except ImportError as exc: raise SystemExit( ETE 4 is required. Install it with: uv pip install ete44.4.0 ) from exc导入变更包名、顶层类与可视化模块顶层导入ETE 3 时期常用的导入写法是from ete3 import NCBITaxa, PhyloTree, TreeETE 4 中Tree直接取代了 ETE 3 的TreeNode顶层导入变为from ete4 import GTDBTaxa, NCBITaxa, PhyloTree, TreeETE 3 同时暴露了功能等价的TreeNode与Tree类而 ETE 4 统一使用Tree。这意味着所有对TreeNode的引用都必须改写。Qt 可视化导入的迁移ETE 3from ete3 import NodeStyle, TextFace, TreeStyleETE 4from ete4.treeview import NodeStyle, TextFace, TreeStyle当前主推的 Web 可视化SmartView则使用from ete4.smartview import Layout, PropFace, TextFace这里有一个极易踩的坑SmartView 与 treeview 的TextFace是两种不同类型分别位于ete4.smartview与ete4.treeview不能混用。仓库的 可视化参考文档 也明确警告不要混用两套 Layout 与 Face 类。本仓库的 quick_visualize.py 恰好演示了两种体系的正确写法SmartView 使用Layout/PropFace/TextFace构建Layout对象Qt treeview 则使用NodeStyle/TreeStyle二者在脚本中通过--engine smartview|treeview显式切换。构造与文件输入消除路径歧义文件路径歧义被移除ETE 3 允许直接把文件名字符串传给构造器tree Tree(tree.nw, format1)ETE 4 明确区分Newick 文本字符串与文件输入文件必须通过已打开的文件对象传入from pathlib import Path with Path(tree.nw).open(encodingutf-8) as handle: tree Tree(handle, parser1)尽管 ETE 4.4.0 内部仍保留了路径型字符串的启发式判断但依赖它会导致输入行为含糊不清与文档约定冲突。仓库的 SKILL.md 与 api_reference.md 均将其列为铁律字符串只代表 Newick 文本文件一律用打开的文件对象。本仓库的所有脚本都遵循这一约定例如 tree_operations.py 中的load_treedef load_tree(path: Path, parser: ParserSpec) - Tree: if not path.is_file(): raise UserInputError(finput tree does not exist or is not a file: {path}) try: with path.open(encodingutf-8) as handle: return Tree(handle, parserparser) except (OSError, ValueError, TypeError, NewickError) as exc: raise UserInputError( fcould not parse {path} with Newick parser {parser!r}: {exc} ) from exc注意异常处理同时捕获NewickError这正是 api_reference.md 强调的在应用边界捕获窄异常并保留上下文的最佳实践——不要用裸except:掩盖 schema 错误。带属性创建新节点ETE 3tree Tree(nameroot, dist0, support1)ETE 4 改为通过字典传入任意初始属性tree Tree({name: root, dist: 0, support: 1})ETE 4 接受字典中的任意属性键这是新属性模型的自然延伸详见下一节。属性模型从 features 到 propsETE 3 强制要求 name、distance、support 三个默认属性。ETE 4 中这些属性可以缺省其便捷访问器可能返回None。这是许多迁移代码出现AttributeError或NoneType异常的根源node.name、node.dist、node.support都可能为None。节点元数据的 API 全面改名ETE 3node.add_feature(habitat, marine) node.add_features(groupcase, score0.8) print(node.features)ETE 4node.add_prop(habitat, marine) node.add_props(groupcase, score0.8) print(node.props)通用参数重命名规则一览feature/features→prop/propsattribute/attributes→prop/propsproperty/properties→prop/props对于判断自定义元数据是否存在不要再用hasattr(node, x)而应改用字典式检查if x in node.props: value node.props[x]api_reference.md 进一步补充了配套 APInode.get_prop(habitat, unknown)带默认值、node.del_prop(qc_pass)并指出name、dist、support是属性背书的便捷访问器即node.name node.props.get(name)。只有写入props的值才能参与搜索、序列化与可视化直接用 Python 属性赋值不会被 ETE 识别。查找、谓词与亲属关系ETE 3 的运算符查找、is_leaf()/is_root()方法调用等语法在 ETE 4 中均被替换ETE 3ETE 4tree Atree[A]tree.get_tree_root()tree.rootnode.is_leaf()node.is_leafnode.is_root()node.is_roottree.get_common_ancestor(a, b)tree.common_ancestor(a, b)node.get_ancestors()node.ancestors()tree.get_leaves_by_name(A)tree.search_leaves_by_name(A)注意is_leaf与is_root从方法变成了布尔属性调用括号会报错或产生意外行为。ETE 4 还新增了基于位置的 ID 索引node tree[0, 1, 0] print(node.id, node.level)按名称查找tree[A]返回首个匹配项因此在名称充当标识符时必须先验证唯一性。仓库在 tree_operations.py 中给出了规范做法——resolve_unique_node会同时拒绝找不到与匹配多个两种情况def resolve_unique_node(tree: Tree, name: str) - Tree: matches list(tree.search_nodes(namename)) if not matches: raise UserInputError(fnode not found: {name!r}) if len(matches) 1: raise UserInputError( fnode name is ambiguous ({len(matches)} matches): {name!r} ) return matches[0]迭代器重命名返回值全面迭代器化ETE 3ETE 4get_leaves()/iter_leaves()leaves()get_descendants()/iter_descendants()descendants()get_edges()/iter_edges()edges()get_leaf_names()leaf_names()get_ancestors()ancestors()ETE 4 的集合类方法返回迭代器而非列表leaves list(tree.leaves()) names list(tree.leaf_names())因此严禁直接调用len(tree.leaves())或对结果做下标索引必须先list()物化。对超大树而言保持迭代器是性能关键workflows.md 的Large Trees一节专门强调优先生成器逐叶处理仅在需要索引、排序或重复遍历时才list()物化反复查询后代内容时应使用get_cached_content(propname)缓存。文本与 Newick I/Oparser 关键字取代 formatETE 3tree Tree(newick, format1) newick tree.write(format1)ETE 4tree Tree(newick, parser1) newick tree.write(parser1)命名解析器别名包括name对应 parser 1内部字段为名称与support对应 parser 0内部字段为支持率。api_reference.md 给出常用解析器速查parser8全部节点命名、无强制枝长parser9仅叶命名parser100仅拓扑。解析器选错是NewickError、内部标签丢失、支持率被误读为名称的头号原因务必在批量处理前做一次往返校验见文末验证片段。ASCII 输出改名ETE 3print(tree.get_ascii(show_internalTrue))ETE 4print(tree.to_str(show_internalTrue, props[name, dist]))to_str()取代了get_ascii()并新增props参数控制终端树中展示的节点属性列。扩展属性语义反转重要陷阱ETE 3 中features[]表示导出全部可用特征ETE 4 的props语义正好相反tree.write(props[]) # 不导出任何扩展属性 tree.write(props[species, host]) # 只导出选定属性 tree.write(propsNone) # 导出全部可用属性这个反转极其重要。对外输出时必须使用显式属性列表否则propsNone会把内部标注全部泄露到共享文件中。api_reference.md 与 workflows.md 的注解元数据表一节都反复强调默认不写扩展属性写文件时显式指定props[host, location]之类清单。另外write()必须使用关键字参数。ETE 4 中write()的第一个位置参数是outfile而 ETE 3 代码往往把第一个位置参数当作特性选择直接移植会产生灾难性的错位。自定义格式化器ETE 3 直接在write()里传格式化字符串newick tree.write( format1, dist_formatter%0.1f, name_formatterTEST-%s, )ETE 4 改为用ete4.parser.newick.make_parser构建自定义解析器from ete4.parser import newick parser newick.make_parser( 1, dist%0.1f, nameTEST-%s, ) text tree.write(parserparser)这种解析器对象化的设计让 Newick 读写双方共享同一套字段映射读写的格式一致性更强。距离与拓扑ETE 3ETE 4A.get_distance(B)tree.get_distance(A, B)topology_onlyTruetopologicalTrueconvert_to_ultrametric()to_ultrametric()resolve_polytomy(recursiveTrue)resolve_polytomy(descendantsTrue)ETE 4 新增了直接的中点外群便捷方法tree.set_midpoint_outgroup()旧的两步模式仍然有效且适合需要审计的场景先取候选节点再落根midpoint tree.get_midpoint_outgroup() tree.set_outgroup(midpoint)ETE 4.4.0 还新增distance_matrix()新代码应使用它取代cophenetic_matrix()matrix tree.distance_matrix(squaredTrue)仓库的 tree_operations.py 展示了set_midpoint_outgroup(topological...)的完整用法——--topological控制按边数而非枝长计算中点并把落根方式写进日志Rerooted with branch-length midpoint这正是可复现分析要求记录落根方法的工程化体现。随机树生成ETE 3tree.populate( size, names_librarynames, random_branchesTrue, dist_range(0, 1), )ETE 4import random tree.populate( size, namesnames, modelyule, dist_fnrandom.random, support_fnlambda: 1, )变化要点names_library→namesrandom_branches与dist_range被modeldist_fnsupport_fn的组合取代。当生成的拓扑或枝长需要可复现时务必先设置随机种子。Robinson-Foulds 解包七元组ETE 4.4.0 的robinson_foulds()返回七个值( rf, max_rf, common, edges_self, edges_other, discarded_self, discarded_other, ) tree.robinson_foulds(other)所有只解包五个值的 ETE 3 示例都必须更新。参数名也改为prop_t1/prop_t2而非旧的特征导向名称。仓库脚本 tree_operations.py 的compare子命令完整解包了七元组并额外传入unrooted_trees、min_support_t1、min_support_t2参数随后输出normalized_rf rf / max_rf if max_rf else 0.0以及公共叶数与两端被丢弃的边数——这些正是 workflows.md 要求报告公共叶集合大小与丢弃边的可复现细节。此外要明确根树与无根树的 RF 回答的是不同科学问题比较前必须显式决定。PhyloTree 的变更与陷阱PhyloTree 的核心方法在 ETE 4 中保留但必须使用新的属性与迭代器语法from ete4 import PhyloTree tree PhyloTree( ((Hsa|g1,Ptr|g1),Mmu|g1);, sp_naming_functionlambda name: name.split(|, 1)[0], ) events tree.get_descendant_evol_events(sos_thr0.0) for leaf in tree.leaves(): print(leaf.name, leaf.species)三个关键陷阱必须显式传sp_naming_function。ETE 4.4.0 的源码默认值是None尽管旧文档描述过自动取前三个字符的规则但该规则并不可靠。种间重叠事件检测要求一棵有根、完全二叉fully bifurcating的基因树。不要把物种树传给get_descendant_evol_events()。ETE 4.4.0 中其签名只接受sos_thr严格的基因树/物种树比对reconciliation应使用reconciled_tree, events gene_tree.reconcile(species_tree)事件检测完成后通过属性字典读取结果node.props.get(evoltype)而不是依赖 ETE 3 的 feature 辅助方法。api_reference.md 明确指出get_descendant_evol_events将事件类型写入node.props[evoltype]不会恢复 ETE 3 的dupfeature。完整的事件检测与 reconciliation 对照示例见 workflows.md 的第 6、7 节——二者回答不同问题种间重叠依赖子裔间标签重叠reconciliation 需要物种树并可推断基因丢失。分类学数据迁移ETE 3 时代的经典路径~/.etetoolkit/taxa.sqliteETE 4 将分类学数据存放在~/.local/share/ete/官方文档中约 600 MB NCBI、72 MB GTDB的数字应理解为本地首次占用的磁盘估算而非压缩网络下载量。归档体积随版本浮动、可能小得多请为解析后的 SQLite 库与临时转换文件额外预留空间。分类学完整指南见 taxonomy.md其中还包含 ETE 4.4.0 更新器的已知注意点NCBI 刷新会校验 MD5 sidecarGTDB 的 freshness 检查会因 sidecar 缺失而重复下载等生产环境务必在受控工作目录中执行更新。ETE 4 新增了一等公民的 GTDB 支持from ete4 import GTDBTaxa注意NCBI 数字 TaxID 与 GTDB 字符串标识符不可互换。仓库的 SKILL 与 taxonomy 文档都明确警告不要混用两套标识体系。可视化迁移SmartView 优先推荐的 SmartView 路径from ete4 import Tree tree Tree(((A,B),C);) tree.explore() tree.render_sm(tree.png)自定义 SmartView 布局from ete4.smartview import Layout, PropFace def draw_node(node): if node.is_leaf: return PropFace(name, positionright) layout Layout(labels, draw_nodedraw_node) tree.explore(layouts[layout])SmartView 的样式字典与 Face 与TreeStyle/NodeStyle完全不兼容两者分属ete4.smartview与ete4.treeview两套体系。仓库的 visualization.md 给出了渲染器决策矩阵交互探索、超大树的折叠浏览、PNG 截屏用 SmartView必须输出矢量 PDF/SVG、或对物理尺寸与 DPI 有精确要求时用 Qt treeview。保留的 Qt treeviewETE 3from ete3 import NodeStyle, TreeStyleETE 4from ete4.treeview import NodeStyle, TreeStyle安装uv pip install ete4[treeview]4.4.0Qt treeview 仍是矢量 PDF/SVG 输出的选项ETE 4.4.0 中 SmartView 的render_sm()生成的是 PNG 截屏数据。静态 SmartView PNG 需要额外安装渲染依赖uv pip install ete4[render-sm]4.4.0quick_visualize.py 中render_smartview会强制校验输出后缀必须是.png并明确报错引导SmartView static output is PNG screenshot data; use a .png path or select --engine treeview for PDF/SVG这正是两套渲染器能力边界的工程化落地。聚类ClusterTree 已被移除ETE 3from ete3 import ClusterTreeETE 4.4.0 中ImportError: cannot import name ClusterTree from ete4不要把ClusterTree、联动矩阵画像linked matrix profiles、silhouette 或 Dunn 方法当作 ETE 4 的能力去写文档。正确做法是用维护中的聚类库如 SciPy完成矩阵计算与验证指标再用普通 ETETree承载并展示拓扑。仓库的 api_reference.md 也明确列出ClusterTree不在 ETE 4.4.0 导出之列并给出四步替代工作流见 workflows.md 第 12 节。命令行陷阱ete4 compare 不可用ETE 4.4.0 随附的ete4 compare命令内部仍以Tree(..., format...)调用已删除的关键字运行即失败。替代方案使用 Python 方法Tree.robinson_foulds()叶标签唯一时使用Tree.compare()或直接使用本技能自带的scripts/tree_operations.py compare帮助程序。同时避开Tree.compare(has_duplicationsTrue)路径——上游源码将 TreeKO 分支标记为可能损坏。仓库的 workflows.md 与 api_reference.md 对此给出了一致的警告。完整移植示例ETE 3 原代码from ete3 import Tree tree Tree(tree.nw, format1) node tree A node.add_feature(group, case) for leaf in tree.iter_leaves(): if leaf.is_leaf(): print(leaf.name) tree.write( outfileout.nhx, format1, features[group], )ETE 4 对应改写from pathlib import Path from ete4 import Tree with Path(tree.nw).open(encodingutf-8) as handle: tree Tree(handle, parser1) node tree[A] node.add_prop(group, case) for leaf in tree.leaves(): if leaf.is_leaf: print(leaf.name) tree.write( outfileout.nhx, parser1, props[group], )这个示例浓缩了本文全部关键变更文件对象输入、parser取代format、[]取代、add_prop取代add_feature、迭代器方法取代iter_*、属性取代方法调用、props显式导出。仓库的 tree_operations.py 还展示了save_tree的工程化写法——write()后按行尾规范化落盘、并在写文件前校验输出目录存在。机械式移植检查清单在遗留代码中搜索以下符号from ete3 TreeNode format features feature attributes attribute add_feature add_features .features get_ascii get_tree_root get_common_ancestor get_leaves iter_leaves get_descendants iter_descendants get_leaf_names get_leaves_by_name convert_to_ultrametric topology_only is_leaf() is_root() ClusterTree TreeStyle NodeStyle然后按序执行用本指南逐符号替换审查每一处 Newick 读写解析器有意识地转换迭代器消费逻辑验证属性导出语义props[]vspropsNone分离 SmartView 与 treeview 布局移除或重新设计ClusterTree工作流用包含名称、支持率、枝长、NHX 属性、重复叶尖、多歧分支的代表性树进行测试比较科学输出而非仅仅比较能否运行。第 8 条是本仓库反复强调的核心原则ETE 只是操作并解释给定的拓扑不会让上游的模型选择、比对质量或采样偏差消失见 workflows.md 的端到端系统发育学交接一节。运行 scripts/tree_operations.py 的stats子命令可以快速诊断树的重复叶名、多歧分支、无枝长节点等影响迁移验证的结构问题uv run --with ete44.4.0 python skills/etetoolkit/scripts/tree_operations.py \ stats tree.nw --parser 1验证片段迁移完成后用以下片段验证当前环境与基本 I/O 语义import ete4 from ete4 import Tree assert ete4.__version__ 4.4.0 tree Tree(((A:1,B:1)95:0.2,C:1);, parsersupport) assert list(tree.leaf_names()) [A, B, C] assert tree[A].is_leaf round_trip tree.write(parsersupport, props[]) assert round_trip ((A:1,B:1)95:0.2,C:1);这一往返断言直接验证了支持率被当作内部名称读入这类经典解析器错配问题也是 api_reference.md 建议的批量处理前先做一次往返检查的标准操作。延伸阅读迁移工作可与仓库内其他 ETE 4 参考文档配套使用SKILL.md — 技能总览、安装方式与核心工作流api_reference.md — ETE 4 核心类、解析器、遍历、I/O、拓扑与比较的完整速查workflows.md — 从验证到 reconciliation、批处理、大树的完整分析模式visualization.md — SmartView 布局、Face 与 Qt 矢量渲染的选择与用法taxonomy.md — NCBI/GTDB 首次使用、显式更新与可复现性注意点。原迁移文档中的上游链接官方迁移指南、release notes 等以 ETE 官方文档为准本仓库技能将etetoolkit.org/docs/latest明确标注为 ETE 3 的遗留文档查询 ETE 4 内容时应以官方 ETE 4 文档站点为权威来源。【免费下载链接】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），仅供参考