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 に読み込みます。

現在の対象バージョン

このスキルの対象は、2025 年 9 月 3 日にリリースされ、2026 年 7 月 23 日時点で PyPI の最新リリースであることを確認した ETE 4.4.0 です。

ETE 4 のドキュメントには https://etetoolkit.github.io/ete/ を使用してください。etetoolkit.org/docs/latest のページは、URL 名にかかわらず、古い ETE 3 のドキュメントです。

次の例を ETE 3 の方式に黙って置き換えないでください。

• パッケージとインポート：ete3 ではなく ete4
• ファイル入力：開いたファイルオブジェクトを渡します。Newick テキストには文字列を使用し、ETE 4.4.0 に残るパス文字列の推測処理に依存しないでください
• Newick の選択：format= ではなく parser=
• ノードのメタデータ：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")) を使用して件数を検証してください。

2 つのトポロジーを比較する

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

1 行に 1 つの分類群を指定する場合は、--keep ... の代わりに --keep-file taxa.txt を使用してください。このスクリプトは、要求された名前が曖昧または見つからない場合、部分的なツリーを黙って生成せず、処理を拒否します。

可視化

# 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 の主要クラス、パーサー、プロパティ、トラバーサル、入出力、トポロジー、比較
• 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

エージェントの作業手順

1. 環境を確認します。 ツールのバージョン、リファレンスゲノム／アノテーションのビルド、入力形式（FASTQ、BAM、VCF、h5ad）を確認します。
2. 入力を明確にします。 データまたはユーザーから形式、識別子、パラメーターを確認します。結果に影響する値は推測せず、質問してください。
3. まず小規模なバージョンを実行します。 まず、少数のサブセット（1 サンプル、1 染色体、数千個の細胞）でパイプラインを実行します。
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 アラインメント、系統発生…