biotite.sequence.phylo.TreeNode¶
- class biotite.sequence.phylo.TreeNode(children=None, distances=None, index=None)[source]¶
Bases:
object
TreeNode
objects are part of a rooted tree (e.g. alignment guide tree). There are twoTreeNode
subtypes:Leaf node - Cannot have child nodes but has an index referring to an array-like reference object.
Intermediate node - Has child nodes but no reference index
This subtype is determined based on whether child nodes were given to the constructor.
Every
TreeNode
has a reference to its parent node. A root node is node without a parent node, that is finalized using as_root(). The call of this function prevents that a the node can be used as child.TreeNode
objects are semi-immutable: The child nodes or the reference index are fixed at the time of creation. Only the parent can be set once, when the parent node is created.TreeNode
objects that are finalized using as_root() are completely immutable.All object properties are read-only.
- Parameters:
- children: array-like object of TreeNode, length=n, optional
The children of this node. As this causes the creation of an intermediate node, this parameter cannot be used in combination with index.
- distances: array-like object of float, length=n, optional
The distances of the child nodes to this node. Must be set if children is set.
- index: int, optional
Index to a reference array-like object (e.g. list of sequences or labels). Must be a positive integer. As this causes the creation of a leaf node, this parameter cannot be used in combination with the other parameters.
Examples
Creating leaf nodes:
>>> leaf1 = TreeNode(index=0) >>> leaf2 = TreeNode(index=1) >>> leaf3 = TreeNode(index=2)
Creating intermediate nodes as parent of those leaf nodes:
>>> inter = TreeNode([leaf1, leaf2], [5.0, 7.0]) >>> root = TreeNode([inter, leaf3], [3.0, 10.0]) >>> print(root) ((0:5.0,1:7.0):3.0,2:10.0):0.0
- Attributes:
- parentTreeNode
The parent node. None if node has no parent.
- childrentuple of TreeNode
The child nodes. None if node is a leaf node.
- indexint
The index to a reference array-like object. None if node is not a leaf node.
- distancefloat
Distance to parent node. None if parent is Ǹone.
- as_root()¶
Convert the node into a root node.
When a root node is used as child parameter in the construction of a potential parent node, a
TreeError
is raised.
- copy()¶
Create a deep copy of this
TreeNode
.The copy includes this node, its reference index and deep copies of its child nodes. The parent node and the distance to it is not included.
- distance_to(node, topological=False)¶
Get the distance of this node to another node.
The distance is the sum of all distances from this and the other node to the lowest common ancestor.
- Parameters:
- nodeTreeNode
The second node for distance calculation.
- Returns:
- distancefloat
The distance of this node to node.
- Raises:
- TreeError
If the nodes have no common ancestor.
Examples
>>> leaf1 = TreeNode(index=0) >>> leaf2 = TreeNode(index=1) >>> leaf3 = TreeNode(index=2) >>> inter = TreeNode([leaf1, leaf2], [5.0, 7.0]) >>> root = TreeNode([inter, leaf3], [3.0, 10.0]) >>> print(leaf1.distance_to(leaf2)) 12.0 >>> print(leaf1.distance_to(leaf3)) 18.0
- static from_newick(newick, labels=None)¶
Create a node and all its child nodes from a Newick notation.
- Parameters:
- newickstr
The Newick notation to create the node from.
- labelslist of str, optional
If the Newick notation contains labels, that are not parseable into reference indices, i.e. they are not integers, this parameter can be provided to convert these labels into reference indices. The corresponding index is the position of the label in the provided list.
- Returns:
- nodeTreeNode
The tree node parsed from the Newick notation.
- distancefloat
Distance of the node to its parent. If the newick notation does not provide a distance, it is set to 0 by default.
Notes
The provided Newick notation must not have a terminal semicolon. If you have a Newick notation that covers an entire tree, you may use the same method in the
Tree
class instead. Keep in mind that theTreeNode
class does support any labels on intermediate nodes. If the string contains such labels, they are discarded.
- get_indices()¶
Get an array of reference indices that leaf nodes of this node contain.
This method identifies all leaf nodes, which have this node as ancestor and puts the contained indices into an array. If this node is a leaf node itself, the array contains the reference index of this node as single element.
- Returns:
- indicesndarray, dtype=int32
The reference indices of direct and indirect child leaf nodes of this node.
Examples
>>> leaf0 = TreeNode(index=0) >>> leaf1 = TreeNode(index=1) >>> leaf2 = TreeNode(index=2) >>> leaf3 = TreeNode(index=3) >>> intr0 = TreeNode([leaf0, leaf2], [0, 0]) >>> intr1 = TreeNode([leaf1, leaf3], [0, 0]) >>> root = TreeNode([intr0, intr1], [0, 0]) >>> print(leaf0.get_indices()) [0] >>> print(intr0.get_indices()) [0 2] >>> print(intr1.get_indices()) [1 3] >>> print(root.get_indices()) [0 2 1 3]
- get_leaf_count()¶
” get_leaf_count()
Get the number of direct or indirect leaves of this ńode.
This method identifies all leaf nodes, which have this node as ancestor. If this node is a leaf node itself, 1 is returned.
- get_leaves()¶
Get a list of leaf nodes that are direct or indirect child nodes of this node.
This method identifies all leaf nodes, which have this node as ancestor. If this node is a leaf node itself, the list contains this node as single element.
- Returns:
- leaf_nodeslist
The leaf nodes, that are direct or indirect child nodes of this node.
- is_leaf()¶
Check if the node is a leaf node.
- Returns:
- is_leafbool
True if the node is a leaf node, false otherwise.
- is_root()¶
Check if the node is a root node.
- Returns:
- is_rootbool
True if the node is a root node, false otherwise.
- lowest_common_ancestor(node)¶
Get the lowest common ancestor of this node and another node.
- Parameters:
- nodeTreeNode
The node to get the lowest common ancestor with.
- Returns:
- ancestorTreeNode or None
The lowest common ancestor. None if the nodes have no common ancestor, i.e. they are not in the same tree
- to_newick(labels=None, include_distance=True)¶
Obtain the node represented in Newick notation.
The terminal semicolon is not included.
- Parameters:
- labelsiterable object of str
The labels the indices in the leaf nodes refer to
- include_distancebool
If true, the distances are displayed in the newick notation, otherwise they are omitted.
- round_distanceint, optional
If set, the distances are rounded to the given number of digits.
- Returns:
- newickstr
The Newick notation of the node.
Examples
>>> leaf1 = TreeNode(index=0) >>> leaf2 = TreeNode(index=1) >>> leaf3 = TreeNode(index=2) >>> inter = TreeNode([leaf1, leaf2], [5.0, 7.0]) >>> root = TreeNode([inter, leaf3], [3.0, 10.0]) >>> print(root.to_newick()) ((0:5.0,1:7.0):3.0,2:10.0):0.0 >>> print(root.to_newick(include_distance=False)) ((0,1),2) >>> labels = ["foo", "bar", "foobar"] >>> print(root.to_newick(labels=labels, include_distance=False)) ((foo,bar),foobar)