alterlab-etetoolkit

ETE Toolkit 技能

概述

ETE（Environment for Tree Exploration）是一款用于系统发育和层级树分析的工具包。它可用于操作树、分析进化事件、可视化结果，并与生物数据库集成，以支持系统基因组学研究和聚类分析。

ete3 还是 ete4？

此技能及其参考资料中的示例均基于 ete3 3.1.3 编写；目前大多数已发布的工作流仍会导入它。不过，ete3 自 2023 年 5 月以来就没有发布过新版本，而 ete4（4.4.0，2025 年 9 月） 是仍在维护的版本。移植时请谨慎：ete4 的 API 并非可直接替换。

ete3	ete4
from ete3 import Tree	from ete4 import Tree
Tree("t.nw", format=1)	Tree(open("t.nw"), parser=1) — 关键字是 parser
tree.iter_leaves() / get_leaves()	tree.leaves()
通过 node.add_feature() 添加自定义特征	使用 node.props[...] 字典
基于 Qt 的 show() / render()（需要 PyQt5）	基于浏览器的 explore()，支持自适应缩放，并支持 GTDB 分类

编写代码前，请检查安装的是哪个版本（python -c "import ete4"），并在方法说明中注明目标版本。

适用场景

• 解析、遍历或重新格式化树文件（Newick / NHX / PhyloXML / NeXML）
• 对树进行剪枝、定根、折叠或解析多分叉
• 检测复制／物种形成事件，并从基因树推断直系同源基因／旁系同源基因
• 查询 NCBI Taxonomy（taxid／名称转换、谱系、分类树）
• 生成适用于出版的 PDF/SVG/PNG 树图
• 比较树（Robinson-Foulds）或分析聚类树状图

核心功能

ETE 提供六类功能。每类功能都有详细且可直接复制使用的代码，见参考资料（请参阅下方索引）。

1. 树操作 — 跨格式输入／输出、遍历（前序／后序／层序）、拓扑编辑（剪枝、定根、折叠）、距离、RF 树比较。
2. 系统发育分析 — 比对关联、物种命名、复制／物种形成检测（物种重叠或协调分析）、直系同源／旁系同源分析。
3. NCBI Taxonomy — 本地缓存数据库、taxid↔名称转换、谱系检索、分类树构建、树注释。
4. 可视化 — 导出 PNG/PDF/SVG、矩形／圆形布局、NodeStyle、Face 对象、布局函数、交互式 GUI。
5. 聚类分析 — ClusterTree、数据矩阵关联、轮廓系数／Dunn 指数、热图视图。
6. 树比较 — Robinson-Foulds（原始值和归一化值）、分区／二分分析、批量成对距离矩阵。

核心工作流

标准的最简模式——加载、编辑、保存：

from ete3 import Tree

# Load tree from file (format 1 = with internal node names)
tree = Tree("tree.nw", format=1)

# Prune to taxa of interest, preserving branch lengths
tree.prune(["species1", "species2", "species3"], preserve_branch_length=True)

# Midpoint root
tree.set_outgroup(tree.get_midpoint_outgroup())

# Save
tree.write(outfile="rooted_tree.nw")

选择类时：通用拓扑操作使用 Tree/TreeNode，基因树和进化分析使用 PhyloTree，带数据矩阵的树状图使用 ClusterTree，分类查询使用 NCBITaxa。

不会触发

场景	改用
从未比对的序列构建树（比对 + 模型选择 + 最大似然推断）	alterlab-phylogenetics
基于比对计算距离矩阵、多样性指标或排序分析	alterlab-scikit-bio
在更广泛的 Biopython 工作流中进行树输入／输出（Bio.Phylo）	alterlab-biopython
对非树网络运行通用图算法	alterlab-networkx
对扩增子读段进行分类学分类	alterlab-qiime2-amplicon

命令行脚本

• scripts/tree_operations.py — 统计信息、格式转换、重新定根、剪枝、ASCII 视图。 示例：python scripts/tree_operations.py reroot tree.nw rooted.nw --midpoint
• scripts/quick_visualize.py — 使用圆形布局、支持度着色和 DPI 控制，快速渲染 PDF/PNG。示例： python scripts/quick_visualize.py tree.nw out.pdf --mode c --color-by-support

参考索引

需要详细信息时，请加载相关文件：

• references/api_reference.md — 所有 ETE 类和方法（Tree、 PhyloTree、ClusterTree、NCBITaxa）的完整 API：参数、返回类型和代码示例。
• references/workflows.md — 按任务分类的工作流模式（树操作、系统发育分析、 比较、分类学集成、聚类）。
• references/visualization.md — 完整的可视化指南：TreeStyle、NodeStyle、 Face、布局函数和高级渲染。
• references/use_cases.md — 端到端的实际用例（系统发育基因组学流程、批量 预处理、出版用图、自动化多树分析）。
• references/setup_and_troubleshooting.md — 安装、NCBI 分类法首次运行设置和 故障排除（导入、Qt 渲染、内存、数据库损坏）。
• references/newick_and_best_practices.md — Newick/NHX 格式规范（0-100）和最佳实践清单。

AlterLab Academic Skills 套件的一部分。