TreeNode (Tree) class is used to store a tree structure. A tree consists of a collection of TreeNode instances connected in a hierarchical way. Trees can be loaded from the New Hampshire Newick format (newick).
Parameters: |
|
||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Returns: | a tree node object which represents the base of the tree. |
** Examples: **
t1 = Tree() # creates an empty tree
t2 = Tree('(A:1,(B:1,(C:1,D:1):0.5):0.5);')
t3 = Tree('/home/user/myNewickFile.txt')
Adds a new child to this node. If child node is not suplied as an argument, a new node instance will be created.
Parameters: |
|
---|---|
Returns: | The child node instance |
Add a fixed face to the node. This type of faces will be always attached to nodes, independently of the layout function.
Parameters: |
|
---|
Add or update a node’s feature.
Add or update several features.
Adds a sister to this node. If sister node is not supplied as an argument, a new TreeNode instance will be created and returned.
Returns True if a given target attribute is monophyletic under this node for the provided set of values.
If not all values are represented in the current tree structure, a ValueError exception will be raised to warn that strict monophyly could never be reached (this behaviour can be avoided by enabling the ignore_missing flag.
Parameters: |
|
---|
Parameters: | unrooted (False) – If True, tree will be treated as unrooted, thus allowing to find monophyly even when current outgroup is spliting a monophyletic group. |
---|---|
Returns: | the following tuple IsMonophyletic (boolean), clade type (‘monophyletic’, ‘paraphyletic’ or ‘polyphyletic’), leaves breaking the monophyly (set) |
A list of children nodes
compare this tree with another using robinson foulds symmetric difference and number of shared edges. Trees of different sizes and with duplicated items allowed.
returns: a Python dictionary with results
Converts a tree into ultrametric topology (all leaves must have the same distance to root). Note that, for visual inspection of ultrametric trees, node.img_style[“size”] should be set to 0.
Returns a copy of the current node.
Variables: | method (cpickle) – Protocol used to copy the node |
---|
structure. The following values are accepted:
- “newick”: Tree topology, node names, branch lengths and branch support values will be copied by as represented in the newick string (copy by newick string serialisation).
- “newick-extended”: Tree topology and all node features will be copied based on the extended newick format representation. Only node features will be copied, thus excluding other node attributes. As this method is also based on newick serialisation, features will be converted into text strings when making the copy.
- “cpickle”: The whole node structure and its content is cloned based on cPickle object serialisation (slower, but recommended for full tree copying)
- “deepcopy”: The whole node structure and its content is copied based on the standard “copy” Python functionality (this is the slowest method but it allows to copy complex objects even if attributes point to lambda functions, etc.)
Permanently deletes a node’s feature.
Deletes node from the tree structure. Notice that this method makes ‘disappear’ the node from the tree structure. This means that children from the deleted node are transferred to the next available parent.
Parameters: | prevent_nondicotomic (True) – When True (default), delete |
---|
function will be execute recursively to prevent single-child nodes.
Parameters: | preserve_branch_length (False) – If True, branch lengths |
---|
of the deleted nodes are transferred (summed up) to its parent’s branch, thus keeping original distances among nodes.
Example:
/ C
root-|
| / B
\--- H |
\ A
> H.delete() will produce this structure:
/ C
|
root-|--B
|
\ A
Prints general information about this node and its connections.
Detachs this node (and all its descendants) from its parent and returns the referent to itself.
Detached node conserves all its structure of descendants, and can be attached to another node through the ‘add_child’ function. This mechanism can be seen as a cut and paste.
Branch length distance to parent node. Default = 0.0
New in version 2.3.
Given a tree with one or more polytomies, this functions returns the list of all trees (in newick format) resulting from the combination of all possible solutions of the multifurcated nodes.
versionadded: 2.2
Returns the list of all ancestor nodes from current node to the current tree root.
Returns a string containing an ascii drawing of the tree.
Parameters: |
|
---|
Returns a dictionary pointing to the preloaded content of each internal node under this tree. Such a dictionary is intended to work as a cache for operations that require many traversal operations.
Parameters: | store_attr (None) – Specifies the node attribute that |
---|
should be cached (i.e. name, distance, etc.). When none, the whole node instance is cached.
Parameters: | _store – (internal use) |
---|
Returns an independent list of node’s children.
Returns node’s closest descendant leaf and the distance to it.
Parameters: | topology_only (False) – If set to True, distance between nodes will be referred to the number of nodes between them. In other words, topological distance will be used instead of branch length distances. |
---|---|
Returns: | A tuple containing the closest leaf referred to the current node and the distance to it. |
Returns the first common ancestor between this node and a given list of ‘target_nodes’.
Examples:
t = tree.Tree("(((A:0.1, B:0.01):0.001, C:0.0001):1.0[&&NHX:name=common], (D:0.00001):0.000001):2.0[&&NHX:name=root];")
A = t.get_descendants_by_name("A")[0]
C = t.get_descendants_by_name("C")[0]
common = A.get_common_ancestor(C)
print common.name
Returns a list of all (leaves and internal) descendant nodes.
Parameters: | is_leaf_fn (None) – See TreeNode.traverse() for documentation. |
---|
Returns the distance between two nodes. If only one target is specified, it returns the distance bewtween the target and the current node.
Parameters: |
|
---|---|
Returns: | branch length distance between target and target2. If topology_only flag is True, returns the number of nodes between target and target2. |
New in version 2.3.
Returns the list of edges of a tree. Each egde is represented as a tuple of two elements, each containing the list of nodes separated by the edge.
Returns node’s farthest descendant node (which is always a leaf), and the distance to it.
Parameters: | topology_only (False) – If set to True, distance between nodes will be referred to the number of nodes between them. In other words, topological distance will be used instead of branch length distances. |
---|---|
Returns: | A tuple containing the farthest leaf referred to the current node and the distance to it. |
Returns the node’s farthest descendant or ancestor node, and the distance to it.
Parameters: | topology_only (False) – If set to True, distance between nodes will be referred to the number of nodes between them. In other words, topological distance will be used instead of branch length distances. |
---|---|
Returns: | A tuple containing the farthest node referred to the current node and the distance to it. |
Returns the list of terminal node names under the current node.
Parameters: | is_leaf_fn (None) – See TreeNode.traverse() for documentation. |
---|
Returns the list of terminal nodes (leaves) under this node.
Parameters: | is_leaf_fn (None) – See TreeNode.traverse() for documentation. |
---|
Returns a list of leaf nodes matching a given name.
Returns the node that divides the current tree into two distance-balanced partitions.
New in version 2.2.
Returns a list of nodes matching the provided monophyly criteria. For a node to be considered a match, all target_attr values within and node, and exclusively them, should be grouped.
Parameters: |
|
---|
Returns an indepent list of sister nodes.
New in version 2.3.
Returns the unique ID representing the topology of the current tree. Two trees with the same topology will produce the same id. If trees are unrooted, make sure that the root node is not binary or use the tree.unroot() function before generating the topology id.
This is useful to detect the number of unique topologies over a bunch of trees, without requiring full distance methods.
The id is, by default, calculated based on the terminal node’s names. Any other node attribute could be used instead.
Returns the absolute root node of current tree structure.
Branch length distance to parent node. Default = 0.0
Return True if current node is a leaf.
Returns True if current node has no parent
versionadded: 2.2
Iterates over the list of all ancestor nodes from current node to the current tree root.
Returns an iterator over all descendant nodes.
Parameters: | is_leaf_fn (None) – See TreeNode.traverse() for documentation. |
---|
New in version 2.3.
Iterate over the list of edges of a tree. Each egde is represented as a tuple of two elements, each containing the list of nodes separated by the edge.
Returns an iterator over the leaf names under this node.
Parameters: | is_leaf_fn (None) – See TreeNode.traverse() for documentation. |
---|
Returns an iterator over the leaves under this node.
Parameters: | is_leaf_fn (None) – See TreeNode.traverse() for documentation. |
---|
Iterate over all nodes in a tree yielding every node in both pre and post order. Each iteration returns a postorder flag (True if node is being visited in postorder) and a node instance.
Search nodes in an interative way. Matches are being yield as they are being found. This avoids to scan the full tree topology before returning the first matches. Useful when dealing with huge trees.
Sort the branches of a given tree (swapping children nodes) according to the size of each partition.
t = Tree("(f,((d, ((a,b),c)),e));")
print t
#
# /-f
# |
# | /-d
# ----| |
# | /---| /-a
# | | | /---|
# | | \---| \-b
# \---| |
# | \-c
# |
# \-e
t.ladderize()
print t
# /-f
# ----|
# | /-e
# \---|
# | /-d
# \---|
# | /-c
# \---|
# | /-a
# \---|
# \-b
Generates a random topology by populating current node.
Parameters: |
|
---|
range of values will be used to generate random distances.
Parameters: | support_range ((0,1)) – If random_branches is True, |
---|
this range of values will be used to generate random branch support values.
Prunes the topology of a node to conserve only the selected list of leaf internal nodes. The minimum number of nodes that conserve the topological relationships among the requested nodes will be retained. Root node is always conserved.
Variables: | nodes – a list of node names or node objects that should be retained |
---|---|
Parameters: | preserve_branch_length (False) – If True, branch lengths |
of the deleted nodes are transferred (summed up) to its parent’s branch, thus keeping original distances among nodes.
Examples:
t1 = Tree('(((((A,B)C)D,E)F,G)H,(I,J)K)root;', format=1)
t1.prune(['A', 'B'])
# /-A
# /D /C|
# /F| \-B
# | |
# /H| \-E
# | | /-A
#-root \-G -root
# | \-B
# | /-I
# \K|
# \-J
t1 = Tree('(((((A,B)C)D,E)F,G)H,(I,J)K)root;', format=1)
t1.prune(['A', 'B', 'C'])
# /-A
# /D /C|
# /F| \-B
# | |
# /H| \-E
# | | /-A
#-root \-G -root- C|
# | \-B
# | /-I
# \K|
# \-J
t1 = Tree('(((((A,B)C)D,E)F,G)H,(I,J)K)root;', format=1)
t1.prune(['A', 'B', 'I'])
# /-A
# /D /C|
# /F| \-B
# | |
# /H| \-E /-I
# | | -root
#-root \-G | /-A
# | \C|
# | /-I \-B
# \K|
# \-J
t1 = Tree('(((((A,B)C)D,E)F,G)H,(I,J)K)root;', format=1)
t1.prune(['A', 'B', 'F', 'H'])
# /-A
# /D /C|
# /F| \-B
# | |
# /H| \-E
# | | /-A
#-root \-G -root-H /F|
# | \-B
# | /-I
# \K|
# \-J
Removes a child from this node (parent and child nodes still exit but are no longer connected).
Removes a sister node. It has the same effect as `TreeNode.up.remove_child(sister)`
If a sister node is not supplied, the first sister will be deleted and returned.
Parameters: | sister – A node instance |
---|---|
Returns: | The node removed |
Renders the node structure as an image.
Variables: |
|
---|
Resolve all polytomies under current node by creating an arbitrary dicotomic structure among the affected nodes. This function randomly modifies current tree topology and should only be used for compatibility reasons (i.e. programs rejecting multifurcated node in the newick representation).
Parameters: |
|
---|
Returns the Robinson-Foulds symmetric distance between current tree and a different tree instance.
Parameters: |
|
---|---|
Returns: | (rf, rf_max, common_attrs, names, edges_t1, edges_t2, discarded_edges_t1, discarded_edges_t2) |
Returns the list of nodes matching a given set of conditions.
Example:
tree.search_nodes(dist=0.0, name="human")
Sets a descendant node as the outgroup of a tree. This function can be used to root a tree or even an internal node.
Parameters: | outgroup – a node instance within the same tree structure that will be used as a basal node. |
---|
Set ‘node_style’ as the fixed style for the current node.
Starts an interative session to visualize current node structure using provided layout and TreeStyle.
This function sort the branches of a given tree by considerening node names. After the tree is sorted, nodes are labeled using ascendent numbers. This can be used to ensure that nodes in a tree with the same node names are always labeled in the same way. Note that if duplicated names are present, extra criteria should be added to sort nodes.
Unique id is stored as a node._nid attribute
New in version 2.3.
process current tree structure to produce a standardized topology: nodes with only one child are removed and multifurcations are automatically resolved.
Branch support for current node
Swaps current children order.
Returns an iterator to traverse the tree structure under this node.
Parameters: |
|
---|
Unroots current node. This function is expected to be used on the absolute tree root node, but it can be also be applied to any other internal node. It will convert a split into a multifurcation.
Pointer to parent node
Returns the newick representation of current node. Several arguments control the way in which extra data is shown for every node:
Parameters: |
|
---|
Example:
t.get_newick(features=["species","name"], format=1)