ivy.tree module

The Node class and functions for creating trees from Newick strings, etc.

ivy does not have a Tree class per se, as most functions operate directly on Node objects.

ivy.tree.C(leaves, internals)

class ivy.tree.Node(**kwargs)

Bases: object

A basic Node class with attributes and references to child nodes (‘children’, a list) and ‘parent’.

Keyword Arguments:  

• id – ID of the node. If not provided, is set using builtin id function
• ni (int) – Node index.
• li (int) – Leaf index.
• isroot (bool) – Is the node a root.
• isleaf (bool) – Is the node a leaf.
• label (str) – Node label.
• length (float) – Branch length from node to parent
• support – Bootstrap support values
• age (float) – Age of the node in time units.
• parent (Node) – Parent of the ndoe.
• children (list) – List of node objects. Children of node
• nchildren (int) – Number of children
• left – The “left” node
• treename – Name of tree
• comment – Comments for tree

add_child(child, reindex=True)

Mutate function Add child as child of self

Parameters:

• child (Node) – A node object
• reindex (bool) – Whether to recalculate index attributes after mutating

ape_node_idx()

ascii(*args, **kwargs)

Create ascii tree.

Keyword Arguments:  

• unitlen (float) – How long each unit should be rendered as. Defaults to 3.
• minwidth (float) – Minimum width of the plot. Defaults to 50
• maxwidth (float) – Maximum width of the plot. Defaults to None
• scaled (bool) – Whether or not the tree is scaled. Defaults to False
• show_internal_labels (bool) – Whether or not to show labels on internal nodes. Defaults to True.

Returns:

Ascii tree to be shown with print().

Return type:

str

bgrep(s, ignorecase=True)

Find branches (internal nodes) by regular-expression search of labels

Parameters:

• s (str) – String to search.
• ignorecase (bool) – Indicates to ignore case. Defaults to true.

Returns:

A list of node objects whose labels were matched by s.

Return type:

lsit

bisect_branch(distance=0.5, reindex=True)

Mutate function. Add new node as parent to self in the middle of branch to parent.

Parameters:

• distance (float) – What percentage along branch to place new node. Defaults to 0.5 (bisection). Higher numbers set the new node closer to the parent, lower numbers set it closer to child.
• reindex (bool) – Whether to recalculate index attributes after mutating

Returns:

A new node.

Return type:

Node

clades()

Get internal nodes descended from self

Returns:A list of internal nodes descended from (and not including) self. Return type:list

collapse(add=False, reindex=True)

Mutate function

Remove self and collapse children to polytomy

Parameters:

• add (bool) – Whether or not to add self’s length to children’s length.
• reindex (bool) – Whether to recalculate index attributes after mutating

Returns:

Parent of self

Return type:

Node

copy(recurse=True, _par=None)

Return a shallow copy of self. If recurse = False, do not copy children, parents, or any attribute that is Node.

Parameters:recurse (bool) – Whether or not to copy children as well as self. Returns:A copy of self. Return type:Node

descendants(order=u'pre', v=None, f=None)

Return a list of nodes descendant from self - but _not_ including self!

Parameters:

• order (str) – Indicates wether to return nodes in preorder or postorder sequence. Optional, defaults to “pre”
• f (function) – filtering function that evaluates to True if desired node is called as the first parameter.

Returns:

A list of nodes descended from self not including self.

Return type:

list

drop_tip(nodes)

Return a NEW TREE with the given tips dropped from it. Does not affect old tree.

Parameters:nodes (list) – Leaf nodes or labels of leaf nodes Returns:Node – New root node with tips dropped Return type:Node

excise(reindex=True)

Mutate function For ‘knees’: remove self from between parent and single child

Parameters:reindex (bool) – Whether to recalculate index attributes after mutating tree.

find(f, *args, **kwargs)

Find descendant nodes (generator version)

Parameters:f – Function or a string. If a string, it is converted to a function for finding f as a substring in node labels. Otherwise, f should evaluate to True if called with a desired node as the first parameter. Yields:Node – Found nodes in preorder sequence.

findall(f, *args, **kwargs)

Find descendant nodes (list version)

Parameters:f – Function or a string. If a string, it is converted to a function for finding f as a substring in node labels. Otherwise, f should evaluate to True if called with a desired node as the first parameter. Yields:Node – Found nodes in preorder sequence.

get(f, *args, **kwargs)

Return the first node found by node.find()

Parameters:

• f (function) – A function that evaluates to True if desired node is called as the first parameter.
• **kwargs (*args,) –

  Additional args called by f

Returns:

The first node found by node.find()

Return type:

Node

get_root()

get_siblings()

Return list of siblings of node

graft(node, reindex=True)

Mutate function Add node as sister to self. :param node: Node to graft to tree :type node: Node :param reindex: Whether to recalculate index attributes after mutating tree. :type reindex: bool

grep(s, ignorecase=True)

Find nodes by regular-expression search of labels

Parameters:

• s (str) – String to search.
• ignorecase (bool) – Indicates to ignore case. Defaults to true.

Returns:

A list of node objects whose labels were matched by s.

Return type:

lsit

internals(f=None)

Return a list nodes that have children (internal nodes)

Parameters:f (function) – A function that evaluates to true if called with desired node as the first input Returns:A list of internal nodes that are true for f (if f is given) Return type:list

is_same_tree(tree)

Test if two trees are the same (same topology, characteristics, labels, etc.) Ignores IDs by default.

Parameters:

• tree (Node) – Another tree to compare to
• verbose (bool) – Whether or not to print a message containing the non-matching properties

Returns:

Whether or not the trees are the same.

Return type:

bool

ismono(*leaves)

Test if leaf descendants are monophyletic

Parameters:*leaves (Node) – At least two leaf Node objects or labels Returns:Are the leaf descendants monophyletic? Return type:bool

iterleaves()

Yield leaves descendant from self

iternodes(f=None)

List of nodes descendant from self - including self :Yields: Node –

Nodes descended from self (including self) in

preorder sequence

iternodes_cached(f=None, force=False)

Cached version of iternodes. Faster, but requires that the tree is static and not being changed.

keep_tip(nodes)

Return a NEW TREE containing only the given tips.

Parameters:nodes (list) – Leaf nodes or labels of leaf notes Returns:Node – New root node containing only given tips Return type:Node

labeled()

Return a list of all descendant nodes that are labeled

Returns:All descendants of self that are labeled (including self) Return type:list

ladderize(reverse=False, reindex=True)

Mutate function Rotate nodes so tree is ordered by clade size.

WARNING: May cause strange results with functions that rely on

pre- and post- ordering of nodes

leaf_distances(measure=u'length')

RR: I don’t quite understand the structure of the output.

leafsets(d=None, labels=False)

return a mapping of nodes to leaf sets (nodes or labels)

leaves(f=None)

Return a list of leaves. Can be filtered with f.

Parameters:f (function) – A function that evaluates to True if called with desired node as the first input Returns:A list of leaves that are true for f (if f is given) Return type:list

lgrep(s, ignorecase=True)

Find leaves by regular-expression search of labels

Parameters:

• s (str) – String to search.
• ignorecase (bool) – Indicates to ignore case. Defaults to true.

Returns:

A list of node objects whose labels were matched by s.

Return type:

lsit

makeroot(shift_labels=False)

shift_labels: flag to shift internal parent-child node labels when internode polarity changes; suitable e.g. if internal node labels indicate unrooted bipartition support

max_tippath(first=True)

Get the maximum length from self to a leaf node

mrca(*nodes)

Find most recent common ancestor of nodes

Parameters:*nodes (Node) – Node objects Returns:The MRCA of nodes Return type:Node

ntaxa()

Number of leaves descended from self

order_subtrees_by_size(n2s=None, recurse=False, reverse=False)

Order interal clades by size

postiter(f=None)

Yield nodes in postorder sequence

preiter(f=None)

Yield nodes in preorder sequence

prune(reindex=True)

Mutate function Remove self if self is not root.

All descendants of self are also removed

Parameters:reindex (bool) – Whether to recalculate index attributes after mutating tree. Returns:

Parent of self. If parent had only two children,

parent is now a ‘knee’ and can be removed with excise.

Return type:Node

reindex(node, n=0, d=0, ni=0, li=0, ii=0, pi=0)

Iteratively attach ‘ni’, ‘ii’, ‘pi’, and ‘li’ attributes to nodes

remove_child(child, reindex=True)

Mutate function. Remove child from self.

Parameters:

• child (Node) – A node object that is a child of self
• reindex (bool) – Whether to recalculate index attributes after mutating

reroot(newroot, distance=0.5)

Reroot the tree between newroot and its parent. By default, the new node is halfway in between newroot and its current parent. Works by unrooting the tree, then rerooting it at the new node.

Returns a NEW tree. Does not affect old tree

Parameters:

• newroot – Node or str of node label. Cannot be child of current root.
• distance (float) – What percentage along branch to place new node. Defaults to 0.5 (bisection). Higher numbers set the new node closer to the parent, lower numbers set it closer to child.

Returns:

Root node of new rerooted tree.

Return type:

Node

rootpath(end=None, stop=None)

Iterate over parent nodes toward the root, or node end if encountered.

Parameters:

• end (Node) – A Node object to iterate to (instead of iterating towards root). Optional, defaults to None
• stop (function) – A function that returns True if desired node is called as the first parameter. Optional, defaults to None

Yields:

Node – Nodes in path to root (or end).

rootpath_length(end=None)

Get length from self to root(if end is None) or length from self to an ancestor node (if end is an ancestor to self)

Parameters:end (Node) – A node object Returns:The length from self to root/end Return type:float

set_iternode_cache()

Store iteration order for faster access.

subtree_mapping(labels, clean=False)

Find the set of nodes in ‘labels’, and create a new tree representing the subtree connecting them. Nodes are assumed to be non-nested.

Returns:a mapping of old nodes to new nodes and vice versa. Return type:dict

TODO: test this, high bug probability

tiplabels()

List of labels of leaves descended from self, in preorder sequence

write(outfile=None, format=u'newick', length_fmt=u':%g', end=True, clobber=False)

ivy.tree.clade_sizes(node, results={})

Map node and descendants to number of descendant tips

ivy.tree.cls(root)

Get clade sizes of whole tree :param * root: A root node

Returns:

• A dict mapping nodes to clade sizes

ivy.tree.load_chars(filename, colNames=True, rowNames=False)

Given a filename pointing to a CSV with species names as column one and characters as remaining columns, return a dictionary mapping names to characters

ivy.tree.read(data, format=None, treename=None, ttable=None)

Read a single tree from data, which can be a Newick string, a file name, or a file-like object with tell and ‘read` methods. treename is an optional string that will be attached to all created nodes.

Parameters:data – A file or file-like object or newick string Returns:The root node. Return type:Node

ivy.tree.readmany(data, format=u'newick')

Iterate over trees from a source.

ivy.tree.remove_singletons(root, add=True)

Remove descendant nodes that are the sole child of their parent

ivy.tree.traverse(node)

recursive preorder iterator based solely on .children attribute

ivy.tree.write(node, outfile=None, format=u'newick', length_fmt=u':%g', clobber=False)

ivy.tree.write_newick(node, outfile=None, length_fmt=u':%g', end=False, clobber=False)