etetoolkit

ETE Toolkit 4

范围

使用 ETE 4 处理现有树：

• 读取 Newick/Nexus，然后检查、注释、转换、定根、剪枝并写出 Newick 树
• 比较拓扑结构并计算系统发育距离
• 使用 TreePattern 查找重复的子树拓扑结构
• 使用 PhyloTree 分析基因树
• 查询本地 NCBI 或 GTDB 分类数据库
• 使用 SmartView 交互式探索大型树
• 使用 SmartView 渲染 PNG，或使用可选的 Qt treeview 渲染 PNG/PDF/SVG

ETE 不能取代序列比对或系统发育推断软件。对于原始序列，请先使用 MAFFT 或其他比对工具，以及 IQ-TREE 2、FastTree 或其他推断工具；然后将生成的树加载到 ETE 中。

当前目标

此技能面向 ETE 4.4.0。该版本于 2025 年 9 月 3 日发布，并已验证为 2026 年 7 月 23 日的当前 PyPI 版本。

使用 https://etetoolkit.github.io/ete/ 查看 ETE 4 文档。 etetoolkit.org/docs/latest 页面是旧版 ETE 3 文档，尽管 URL 名称看起来像最新文档。

请勿将这些示例悄然改回 ETE 3：

• 包和导入：使用 ete4，而非 ete3
• 文件输入：传入已打开的文件对象；Newick 文本使用字符串，不要依赖 ETE 4.4.0 中保留的路径字符串启发式处理
• 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。

安装

安装固定版本的基础包：

uv pip install "ete4==4.4.0"

仅添加工作流所需的可视化额外组件：

# SmartView static PNG screenshots
uv pip install "ete4[render-sm]==4.4.0"

# Legacy Qt renderer for PNG, PDF, and 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 工作流会下载公开的分类数据，可能占用大量磁盘空间；首次更新前请参阅 references/taxonomy.md。

快速入门

from pathlib import Path

from ete4 import Tree

# Use an open file object for files; reserve strings for Newick text.
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()))

# Search and annotate.
focal = tree["species1"]
focal.add_props(host="human", status="focal")

# Keep selected tips while preserving pairwise branch-length distances.
tree.prune(
    ["species1", "species2", "species3"],
    preserve_branch_length=True,
)

# Root and serialize explicitly.
tree.set_midpoint_outgroup()
tree.write(
    outfile="processed.nw",
    parser=1,
    props=["host", "status"],
)

请谨慎选择解析器。解析器不匹配是导致 NewickError、内部标签丢失或支持值被读作名称的最常见原因。请参阅 references/api_reference.md。

核心工作流

检查和转换树

from ete4 import Tree

tree = Tree("((A:1,B:1)CladeAB:0.4,C:2)Root;", parser=1)

for node in tree.traverse("preorder"):
    label = node.name if node.name is not None else node.id
    print(label, node.level, node.is_leaf, node.dist)

tree["A"].add_prop("group", "case")
tree["B"].add_prop("group", "control")

mrca = tree.common_ancestor("A", "B")
print(mrca.name)

tree.write(
    outfile="annotated.nhx",
    parser=1,
    props=["group"],
    format_root_node=True,
)

节点名称不必唯一。tree["A"] 会返回第一个匹配项；如果名称可能重复，请使用 list(tree.search_nodes(name="A")) 并验证匹配数量。

比较两个拓扑结构

from ete4 import Tree

tree_a = Tree("((A,B),(C,D));")
tree_b = Tree("((A,C),(B,D));")

(
    rf,
    max_rf,
    common_leaves,
    edges_a,
    edges_b,
    discarded_a,
    discarded_b,
) = tree_a.robinson_foulds(tree_b)

normalized_rf = rf / max_rf if max_rf else 0.0
print(rf, max_rf, normalized_rf, sorted(common_leaves))

RF 比较使用共有的叶标签，并要求名称有意义，最好唯一。请明确判断在科学上应进行有根还是无根比较。

检测复制和物种形成事件

from ete4 import PhyloTree

gene_tree = PhyloTree(
    "((Hsa|g1,Ptr|g1),(Hsa|g2,Mmu|g1));",
    sp_naming_function=lambda name: name.split("|", 1)[0],
)

for event in gene_tree.get_descendant_evol_events(sos_thr=0.0):
    relationship = "speciation/orthology" if event.etype == "S" else "duplication/paralogy"
    print(relationship, sorted(event.in_seqs), sorted(event.out_seqs))

物种重叠判断是根据所提供的拓扑结构和命名函数得出的推断，并非独立的直系同源证据。请显式传入命名函数，并使用有根且完全二叉的基因树。若需严格的协调分析，请使用经过整理的物种树和 gene_tree.reconcile(species_tree)。

查询分类数据

from ete4 import NCBITaxa

ncbi = NCBITaxa()
names = ["Homo sapiens", "Pan troglodytes", "Mus musculus"]
name_to_taxids = ncbi.get_name_translator(names)

missing = [name for name in names if name not in name_to_taxids]
if missing:
    raise ValueError(f"Names not resolved by NCBI taxonomy: {missing}")

taxids = [name_to_taxids[name][0] for name in names]
taxonomy_tree = ncbi.get_topology(taxids)
print(taxonomy_tree.to_str(props=["sci_name", "rank"]))

ETE 4 还提供了 GTDBTaxa，用于以基因组为中心的细菌和古菌分类。请勿混用 NCBI 数字 TaxID 和 GTDB 字符串标识符。

可视化

交互式 SmartView：

from ete4 import Tree

tree = Tree("((A:1,B:1)90:0.2,C:1);", parser="support")
tree.explore()

SmartView 静态截图：

tree.render_sm("tree.png", w=1200, h=800)

render_sm() 会生成 PNG 截图数据；如果交付内容必须是矢量 PDF 或 SVG，请使用 Qt treeview 渲染器。请加载 references/visualization.md，了解布局、面部元素、远程探索和渲染器选择。

内置脚本

请在此技能目录中运行。以下命令通过 uv run --with 使用固定版本且隔离的 ETE 4 运行环境。

树操作

uv run --with "ete4==4.4.0" python scripts/tree_operations.py \
  stats tree.nw --parser 1
uv run --with "ete4==4.4.0" python scripts/tree_operations.py \
  ascii tree.nw --parser 1 --props name,dist
uv run --with "ete4==4.4.0" python scripts/tree_operations.py \
  convert tree.nw output.nw \
  --input-parser 1 --output-parser 1
uv run --with "ete4==4.4.0" python scripts/tree_operations.py \
  reroot tree.nw rooted.nw \
  --parser 1 --midpoint
uv run --with "ete4==4.4.0" python scripts/tree_operations.py \
  prune tree.nw pruned.nw \
  --parser 1 --keep species1 species2 species3
uv run --with "ete4==4.4.0" python scripts/tree_operations.py \
  compare tree_a.nw tree_b.nw

对于每行一个分类单元的文件，请使用 --keep-file taxa.txt，而非 --keep ...。 如果请求的名称有歧义或缺失，脚本会拒绝运行，而不会悄然生成不完整的树。

可视化

# Interactive SmartView
uv run --with "ete4==4.4.0" python scripts/quick_visualize.py \
  tree.nw --parser 1

# SmartView PNG (requires ete4[render-sm])
uv run --with "ete4[render-sm]==4.4.0" python scripts/quick_visualize.py \
  tree.nw tree.png \
  --parser support --mode circular --show-support --color-by-support

# Vector output via Qt treeview (requires ete4[treeview])
uv run --with "ete4[treeview]==4.4.0" python scripts/quick_visualize.py \
  tree.nw tree.svg \
  --parser 1 --engine treeview --title "Species phylogeny"

质量与解释检查

报告结果前：

1. 确认解析器保留了预期的内部名称、支持度和分支长度。
2. 在按名称查找或进行 RF 比较前，检查是否存在空叶名称和重复叶名称。
3. 说明树被视为有根树还是无根树。
4. 仅当保留的成对距离应保持不变时，才在剪枝时保留分支长度。
5. 将任意多分叉解析视为展示或算法上的便利，而非进化证据。
6. 在可复现分析中记录 ETE 版本、解析器、生根方法、剪枝集合和分类数据库快照。
7. 对大型树优先使用迭代器；对重复的后代内容查询，优先使用 get_cached_content()。

参考资料索引

仅加载任务所需的参考资料：

• references/api_reference.md — ETE 4 核心类、解析器、属性、遍历、I/O、拓扑结构和比较
• references/workflows.md — 完整的分析模式、验证、协调、批处理和大型树处理
• references/visualization.md — SmartView、布局/面板、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

Agent 操作流程

1. 检查环境。 确认工具版本、参考基因组/注释版本和输入格式（FASTQ、BAM、VCF、h5ad）。
2. 明确输入。 根据数据或用户确认格式、标识符和参数。任何会改变结果的值都应询问，不要猜测。
3. 先运行小规模版本。 先在小型子集（一个样本、一个染色体、几千个细胞）上运行流水线。
4. 执行完整任务，遵循上述说明和参考资料。
5. 验证结果。 在解释结果前，检查 QC 指标、样本身份、基因组版本一致性和批次效应。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及还有哪些不确定之处。

如果发生这种情况	请这样做
输入之间的基因组版本或标识符不匹配	停止并协调统一（liftover、ID 映射）后再继续。
这些说明中的函数、标志或端点在已安装版本中不存在	查阅已安装版本自己的文档（help()、--help、官方文档），进行调整并告知用户。切勿编造 API。
必需的输入、标识符或参数有歧义	询问用户，或在运行前明确说明所采用的假设。

完整性规则

• 切勿捏造结果、参数、标识符、引用或统计数据。如果无法运行或验证某项内容，请明确说明。
• 不要对统计数据无法支持的生物学意义作出解读；报告多重检验校正。
• 将此处特定于版本的细节视为可能过时：请根据已安装版本的官方文档进行确认。
• 对于需要付费、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，务必先征得同意。

相关技能

• biopython：提供 Biopython（Bio.Seq、Bio.SeqIO、Bio.Align、Bio.Entrez、Bio.Blast、Bio.PDB、Bio.Phylo、Bio.motifs、Bio.SeqUtils、Bio.Restriction），用于……
• scikit-bio：用于生物序列和群落生态学分析的 Python 库 scikit-bio：DNA/RNA/蛋白质序列、pair_align 比对、系统发育……