用途
ETE Toolkit 4（包名 ete4）用于处理已有的系统发育树或其他层次树。它不替代序列比对或系统发育推断软件：对于原始序列，应先用 MAFFT 等比对工具和 IQ-TREE 2、FastTree 等推断工具生成树，再将结果载入 ETE。
主要能力
- 读取 Newick/Nexus 树，进行检查、注释、变换、定根、剪枝，并写出 Newick 树。
- 比较拓扑结构并计算系统发育距离。
- 使用 TreePattern 查找重复的子树拓扑。
- 使用 PhyloTree 分析基因树，包括检测复制与物种形成事件。
- 查询本地 NCBI 或 GTDB 分类数据库。
- 使用 SmartView 交互式探索大树，或渲染 PNG；可选 Qt treeview 渲染 PNG/PDF/SVG。
版本与安装
该技能面向 ETE 4.4.0（2025 年 9 月 3 日发布）。文档地址为 https://etetoolkit.github.io/ete/ ；etetoolkit.org/docs/latest 页面虽名为 latest，实为 ETE 3 旧文档。
安装固定版本基础包：
uv pip install "ete4==4.4.0"
按需添加可视化扩展：
# SmartView 静态 PNG 截图
uv pip install "ete4[render-sm]==4.4.0"
# 旧版 Qt 渲染器，支持 PNG、PDF、SVG
uv pip install "ete4[treeview]==4.4.0"
确认环境：
uv run --with "ete4==4.4.0" python -c "import ete4; print(ete4.__version__)"
无需凭据。NCBI 与 GTDB 工作流会下载公共分类数据，可能占用大量磁盘空间。
使用方式
ETE 4 与 ETE 3 存在 API 差异，不应将示例静默改回 ETE 3：包与导入为 ete4 而非 ete3；文件输入传入打开的文件对象，字符串用于 Newick 文本；Newick 选择使用 parser= 而非 format=；节点元数据使用 props、add_prop()、add_props()；leaves()、descendants() 等方法返回迭代器；node.is_leaf 与 node.is_root 是属性而非方法；节点查找使用 tree["name"] 而非 tree & "name"。移植旧代码可参考 references/migration-ete3-to-ete4.md。
快速上手示例：
from pathlib import Path
from ete4 import Tree
with Path("tree.nw").open(encoding="utf-8") as handle:
tree = Tree(handle, parser=1) # parser 1: internal node names
print(tree.to_str(props=["name", "dist"], compact=True))
print("Leaves:", list(tree.leaf_names()))
focal = tree["species1"]
focal.add_props(host="human", status="focal")
tree.prune(
["species1", "species2", "species3"],
preserve_branch_length=True,
)
tree.set_midpoint_outgroup()
tree.write(
outfile="processed.nw",
parser=1,
props=["host", "status"],
)
parser 选择需谨慎，parser 不匹配是 NewickError、内部标签丢失或支持值被读作名称的最常见原因。
核心工作流包括：查看与变换树（遍历、注释、查找共同祖先、写出 NHX）；比较两个拓扑（robinson_foulds 返回 RF、max_rf、共有叶、边集等）；用 PhyloTree 检测复制与物种形成事件（get_descendant_evol_events，物种重叠判断是基于所给拓扑与命名函数的推断，非直系同源的独立证据）；查询分类（NCBITaxa 的 get_name_translator、get_topology；ETE 4 也提供 GTDBTaxa，注意不要混用 NCBI 数字 TaxID 与 GTDB 字符串标识）；可视化（tree.explore() 交互式 SmartView，tree.render_sm() 生成 PNG 截图，需要矢量 PDF/SVG 时使用 Qt treeview 渲染器）。
内置脚本
在技能目录下运行，使用 uv run --with 固定隔离运行时。tree_operations.py 支持 stats、ascii、convert、reroot、prune、compare 子命令；quick_visualize.py 支持交互式 SmartView、SmartView PNG 和 Qt treeview 矢量输出。prune 可用 --keep-file taxa.txt 指定每行一个分类单元；脚本对歧义或缺失的名称会拒绝执行，而非静默生成部分树。
适用场景
适用于已有树文件的注释、比较、剪枝、定根、分类查询与可视化，以及基因树事件分析和大树交互探索。
限制与注意事项
- 不替代序列比对与系统发育推断。
- RF 比较依赖共有叶标签，需要有意义且最好唯一的名称；需明确采用有根还是无根比较。
- 节点名称不必唯一，tree["A"] 返回首个匹配，重复时应用 list(tree.search_nodes(name="A")) 并校验数量。
- 任意多分支解析只是显示或算法便利，不是进化证据。
- 报告结果前应确认 parser 保留内部名称、支持值与枝长；检查空叶名与重复叶名；说明树按有根还是无根处理；剪枝时仅在需保持成对距离不变时保留枝长；记录 ETE 版本、parser、定根方法、剪枝集合与分类数据库快照。
- 大树优先使用迭代器，重复查询后代内容使用 get_cached_content()。
- 不得编造结果、参数、标识符、引用或统计；无法运行或验证时应明确说明。
- 涉及费用、共享 GPU 或云配额、个人或患者数据、不可撤销操作前应先询问。
参考文档
references/api_reference.md（核心类、parser、属性、遍历、I/O、拓扑与比较）、references/workflows.md（分析模式、验证、调和、批处理、大树处理）、references/visualization.md（SmartView、布局/faces、PNG 截图、Qt 矢量渲染）、references/taxonomy.md（NCBI 与 GTDB 设置、翻译、拓扑、注释、可复现性）、references/migration-ete3-to-ete4.md（破坏性 API 变更与移植清单）。
权威上游来源：文档 https://etetoolkit.github.io/ete/ ；ETE 3 到 ETE 4 迁移 https://etetoolkit.github.io/ete/3to4.html ；发布 https://github.com/etetoolkit/ete/releases ；PyPI https://pypi.org/project/ete4/ ；源码 https://github.com/etetoolkit/ete ；可视化图库 https://github.com/etetoolkit/ete-gallery 。