3to4

Migrating from ete3 to ete4

ETE v4 introduces many changes with respect to v3, including the names of some function names and arguments.

General considerations

In ete3 there are two classes that are identical, TreeNode and Tree (since a node is a tree in itself). In ete4 there is only the Tree class.

In ete3, a node has necessarily a name, a distance and support (which default to '', 0, and 1 respectively). In ete4 they don't have to have them. If you request them (node.name, node.dist, node.support) for a node that doesn't have them, ete4 returns None.

A node contains all its properties in a dictionary called props. In particular, reading special properties like name (which can be done with node.name) is equivalent to node.props.get('name').

Changes in syntax

This is a summary of the main changes to consider when adapting a program using ete3 to ete4:

ete3	ete4	notes
t & 'A'	t['A']	You can refer to a node by its name, or by a tuple that identifies its position as in t[0,1,0] for the node that comes from the root's 1st child, then its 2nd child, and then its 1st child
t.get_tree_root()	t.root
t.is_root()	t.is_root
t.is_leaf()	t.is_leaf
Tree(filename)	Tree(open(filename))	The Tree constructor now interprets strings as newicks (no double-guessing), and file objects as files containing newicks
Tree(name='Hi', dist=1, support=1)	Tree({'name': 'Hi', 'dist': 1, 'support': 1})	The constructor now admits arbitrary properties for the node, in the form of a dict
Tree(nw, format=1)	Tree(nw, parser=1)	Since format is a reserved word in Python 3, we use parser instead to identify which parser to use when reading a newick
t.get_leaves(), t.iter_leaves()	t.leaves()	All such functions now return iterators (similar to Python's range()), which can be converted to lists with list(...)
t.get_ancestors()	t.ancestors()
t.get_edges(), t.iter_edges()	t.edges()
t.get_leaf_names()	t.leaf_names()
t.get_descendants(), t.iter_descendants()	t.descendants()
t.get_leaves_by_name()	t.search_leaves_by_name()
t.get_ascii()	t.to_str()	It can now fine-tune the representation with different arguments (and produces a nicer / more modern text output)
t.convert_to_ultrametric()	t.to_ultrametric()	Also, new implementation that keeps the relative sizes of branches closer to the original tree
topology_only=...	topological=...	Argument used in several functions (to_ultrametric(), ladderize(), get_distance(), get_farthest_leaf(), etc., which was inconsistently used in ete3)
feature(s)=..., attribute(s)=..., property(ies)=...	prop(s)=...	Arguments used in several functions (they all refer to the same thing, arbitrary properties attached to a node, which are elements of its node.props dictionary
attr=..., target_attr=...	prop=...	Argument used in get_topology_id(), is_monophiletic() and others
popup_prop_keys=...	include_props=..., exclude_props=...	Argument in explore() and others
t.get_common_ancestor(n1, n2, n3)	t.common_ancestor([n1, n2, n3])	Shorter name, and by accepting a list the function can accept other optional arguments unambiguously
A.get_distance(B)	t.get_distance(A, B)
t.swap_children()	t.reverse_children(), t.swap_children()	t.swap_children() now only works for 2 children, otherwise it is unclear what "swapping" means
t.populate(size, names_library, random_branches, dist_range, support_range)	t.populate(size, names, model, dist_fn, support_fn)	The tree can be randomly generated according to different models (yule or uniform), and accept arbitrary functions to randomly generate distances and supports
nw = t.write(format=f, dist_formatter="%0.1f", name_formatter="TEST-%s", support_formatter="SUP-%0.1f")	parser = newick.make_parser(f, dist='%0.1f', name='TEST-%s', support='SUP-%0.1f') nw = t.write(parser=parser)	ete4 parsers are more general, and we can create customized simple ones using newick.make_parser()
t.write(props=[], format=1)	t.write(props=None, parser=1)	props=None (the default) means write all the extended properties, otherwise it is a list of the properties to write (so, none if it is an empty list like props=[])

New syntax

New in ete4:

ete4	notes
Tree(nw, parser='support')	In addition to numbers, some parsers have easy to remember aliases (in this case, interpret field in internal nodes as support, same as parser=0)
node.id	Tuple like (0, 1, 0)
node.level	Number of nodes between node and root