ETE Toolkit 4

Escopo

Use o ETE 4 para trabalhar com uma árvore existente:

• Leia Newick/Nexus, depois inspecione, anote, transforme, enraíze, pode e escreva árvores Newick
• Compare topologias e calcule distâncias filogenéticas
• Encontre topologias de subárvores repetidas com TreePattern
• Analise árvores de genes com PhyloTree
• Consulte bancos de dados de taxonomia locais NCBI ou GTDB
• Explore árvores grandes interativamente com SmartView
• Renderize PNG com SmartView ou PNG/PDF/SVG com o treeview Qt opcional

O ETE não substitui software de alinhamento de sequências ou inferência filogenética. Para sequências brutas, primeiro use MAFFT ou outro alinhador e IQ-TREE 2, FastTree, ou outra ferramenta de inferência; depois, carregue a árvore resultante no ETE.

Alvo Atual

Esta habilidade tem como alvo ETE 4.4.0, lançado em 3 de setembro de 2025 e verificado como o lançamento PyPI atual em 30 de setembro de 2026. O núcleo, a filogenia, a taxonomia sintética local e as verificações auxiliares visam este pacote lançado, não alterações não lançadas em desenvolvimento. Veja references/review.md para cobertura executada e limitações.

Use https://etetoolkit.github.io/ete/ para a documentação do ETE 4. As páginas etetoolkit.org/docs/latest são documentação legada do ETE 3, apesar do nome do URL.

Não traduza silenciosamente estes exemplos de volta para o ETE 3:

• Pacote e importação: ete4, não ete3
• Entrada de arquivo: passe um objeto de arquivo aberto; use strings para texto Newick e não confie em heurísticas de string de caminho mantidas no ETE 4.4.0
• Seleção Newick: parser=, não format=
• Metadados de nó: props, add_prop() e add_props()
• Iteração: leaves(), descendants() e métodos relacionados retornam iteradores
• Predicados: node.is_leaf e node.is_root são propriedades, não métodos
• Busca de nó: tree["name"], não tree & "name"

Para portar código antigo, carregue references/migration-ete3-to-ete4.md.

Instalação

Instale o pacote base fixado:

uv pip install "ete4==4.4.0"

Adicione apenas o extra de visualização exigido pelo fluxo de trabalho:

# 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"

Confirme o ambiente ativo:

uv run --no-project --isolated --with "ete4==4.4.0" python -c "import ete4; print(ete4.__version__)"

Nenhuma credencial é necessária. Os fluxos de trabalho NCBI e GTDB baixam dados de taxonomia públicos e podem consumir um espaço em disco considerável; veja references/taxonomy.md antes da primeira atualização.

Início Rápido

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"],
)

Escolha o parser deliberadamente. Uma incompatibilidade de parser é a causa mais comum de NewickError, perda de rótulos internos ou valores de suporte sendo lidos como nomes. Veja references/api_reference.md.

Fluxos de Trabalho Principais

Inspecionar e transformar uma árvore

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,
)

Nomes de nós não precisam ser únicos. tree["A"] retorna a primeira correspondência; use list(tree.search_nodes(name="A")) e valide a contagem quando duplicatas forem possíveis.

Comparar duas topologias

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,

…