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.
A list of children nodes
Converts a tree to 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 an exact and complete copy of current node.
Permanently deletes a node’s feature.
Deletes node from the tree structure. Notice that this method makes ‘disapear’ the node from the tree structure. This means that children from the deleted node are transferred to the next available parent.
Example:
/ C
root-|
| / B
\--- H |
\ A
> root.delete(H) 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
Returns a string containing an ascii drawing of the tree.
Parameters: |
|
---|
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 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. |
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.
It returns the set of all possible partitions under a node. Note that current implementation is quite inefficient when used in very large trees.
t = Tree(“((a, b), e);”) partitions = t.get_partitions()
# Will return: # a,b,e # a,e # b,e # a,b # e # b # a
Returns an indepent list of sister nodes.
Returns the absolute root node of current tree structure.
Return True if current node is a leaf.
Returns True if current node has no parent
Returns an iterator over all descendant nodes.
Parameters: | is_leaf_fn (None) – See TreeNode.traverse() for documentation. |
---|
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. |
---|
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 in order to conserve only a selected list of leaf or internal nodes. The minimum number of internal nodes (the deepest as possible) are kept to conserve the topological relationship among the provided list of nodes.
Variables: | nodes – a list of node names or node objects that must be kept |
---|
Examples:
t = Tree("(((A:0.1, B:0.01):0.001, C:0.0001):1.0[&&NHX:name=I], (D:0.00001):0.000001[&&NHX:name=J]):2.0[&&NHX:name=root];")
node_C = t.search_nodes(name="C")[0]
t.prune(["A","D", node_C])
print t
Removes a child from this node (parent and child nodes still exit but are no longer connected).
Removes a node’s 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: |
|
---|
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 in _nid
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)