skbio.tree.TreeNode

class skbio.tree.TreeNode(name=None, length=None, support=None, parent=None, children=None)

Represent a node within a tree.

A TreeNode instance stores links from a node to its parent node and optionally child nodes. In addition, it can represent the length of the branch connecting itself and its parent, and the support of this branch.

Parameters:

namestr or None

Name of the node. It is common for tips in particular to have names, for instance, in a phylogenetic tree where the tips correspond to taxa. Internal nodes and the root may also have names.

lengthfloat, int, or None

Length of the branch connecting this node to its parent. Can represent elapsed time, amount of mutations, or other measures of evolutionary distance.

supportfloat, int, or None

Support value of the branch connecting this node to its parent. Can be bootstrap value, posterior probability, or other measures of the confidence or frequency of this branch.

parentTreeNode or None

Parent node to which this node is connected. A node without a parent is the root of the tree.

childrenlist of TreeNode or None

Child nodes to which this node is connected. A node without any children is a tip (leaf) of the tree.

Notes

A tree is a graph in which any two nodes (vertices) are connected by exactly one path. The TreeNode class is capable of representing various tree structures, including binary trees, phylogenetic trees, and other hierarchical systems such as taxonomies and ontologies. While the class is versatile, many of its terms and methods are specifically designed for phylogenetic analysis.

In scikit-bio, trees are modeled as a collection of interconnected TreeNode objects, each representing a single node in the tree. There is no explicit class for the entire tree, a clade, or a branch (edge). Instead, a tree is implicitly defined by its root node, from which the entire tree can be traversed. Starting from any node, one can navigate up to its parent and ancestors, down to its children and descendants, or sideways to its siblings.

The underlying data structure of a tree composed of TreeNode objects is an ordered, rooted tree. However, the TreeNode class has the flexibility to handle unrooted and unordered trees as well, which are common in phylogenetics.

Attributes

default_write_format

Default write format for this object: newick.

Tree IO

read	Create a new TreeNode instance from a file.
write	Write an instance of TreeNode to a file.

Tree navigation

ancestors	Return all ancestral nodes from self back to the root.
has_children	Check if the current node has any children.
is_root	Check if the current node is the root of a tree.
is_tip	Check if the current node is a tip of a tree.
lca	Find the lowest common ancestor of a list of nodes.
neighbors	Return all nodes that are neighbors of the current node.
path	Return the list of nodes in the path from self to another node.
root	Return root of the tree which contains self.
siblings	Return all nodes that are siblings of the current node.

Tree traversal

levelorder	Perform level order traversal over tree.
non_tips	Iterate over non-tip nodes descended from the current node.
postorder	Perform postorder traversal over tree.
pre_and_postorder	Perform traversal over tree, visiting nodes before and after.
preorder	Perform preorder traversal over tree.
tips	Iterate over tips descended from the current node.
traverse	Traverse over tree.

Tree copying

copy	Return a copy of self using an iterative approach.

Tree manipulation

append	Add a node to self's children.
bifurcate	Convert the tree into a bifurcating tree.
extend	Add a list of nodes to self's children.
insert	Insert a node into the branch connecting self and its parent.
pop	Remove and return a child node by index position from self.
prune	Collapse single-child nodes in the tree.
remove	Remove a child node by identity from self.
remove_by_func	Remove nodes of a tree that meet certain criteria.
shear	Refine a tree such that it just has the desired tip names.
shuffle	Randomly shuffle tip names of the tree.
unpack	Unpack an internal node in place.
unpack_by_func	Unpack internal nodes of a tree that meet certain criteria.

Tree rerooting

root_at	Reroot the tree at the provided node.
root_at_midpoint	Reroot the tree at the midpoint of the two tips farthest apart.
root_by_outgroup	Reroot the tree with a given set of taxa as outgroup.
unroot	Convert a rooted tree into unrooted.
unrooted_copy	Walk the tree unrooted-style and return a copy.
unrooted_move	Walk the tree unrooted-style and rearrange it.

Tree searching

assign_ids	Assign topologically stable unique IDs to all nodes of the tree.
cache_attr	Cache attributes on nodes of the tree through a postorder traversal.
clear_caches	Delete node attribute and lookup caches of a tree.
create_caches	Construct an internal lookup table to facilitate searching by name.
has_caches	Check if the current tree has caches.
find	Find a node by name.
find_all	Find all nodes that match a given name.
find_by_func	Find all nodes in a tree that meet certain criteria.
find_by_id	Find a node by ID.
index_tree	Index a tree for rapid lookups within a tree array.

Tree analysis

bipart	Return a bipartition of the tree at the current branch.
biparts	Return all bipartitions within the tree under self.
cophenet	Return a distance matrix between each pair of tips in the tree.
count	Get the count of nodes in the tree.
depth	Calculate the depth of the current node.
distance	Calculate the distance between self and another node.
height	Calculate the height of the current node.
is_bifurcating	Check if the tree is bifurcating.
maxdist	Return the maximum distance between any pair of tips in the tree.
observed_node_counts	Return counts of node observations from counts of tip observations.
subset	Return a subset of taxa descending from self.
subsets	Return all subsets of taxa defined by nodes descending from self.
total_length	Calculate the total length of branches descending from self.

Tree comparison

compare_biparts	Calculate the difference of bipartitions between two trees.
compare_cophenet	Calculate the distance between two trees based on cophenetic distances.
compare_rfd	Calculate Robinson-Foulds distance between two trees.
compare_subsets	Calculate the difference of subsets between two trees.
compare_wrfd	Calculate weighted Robinson-Foulds distance or variants between two trees.

Tree visualization

ascii_art

Return a string containing an ascii drawing of the tree.

Format conversion

assign_supports	Extract support values from internal node labels of a tree.
from_linkage_matrix	Construct tree from a SciPy linkage matrix.
from_taxdump	Construct a tree from the NCBI taxonomy database.
from_taxonomy	Construct a tree from a taxonomy.
to_array	Return an array representation of self.
to_taxonomy	Return a taxonomy representation of self.

Special methods

__copy__	Return a shallow copy.
__deepcopy__	Return a deep copy.
__getitem__	Slice the children of self.
__iter__	Iterate over the children of self.
__len__	Return the number of children of self.
__str__	Return a Newick string of self, with names and distances.

Special methods (inherited)

__eq__	Return self==value.
__ge__	Return self>=value.
__getstate__	Helper for pickle.
__gt__	Return self>value.
__hash__	Return hash(self).
__le__	Return self<=value.
__lt__	Return self<value.
__ne__	Return self!=value.

Details

default_write_format = 'newick'

Default write format for this object: newick.

__copy__()

Return a shallow copy.

__deepcopy__(memo)

Return a deep copy.

__getitem__(i)

Slice the children of self.

__iter__()

Iterate over the children of self.

__len__()

Return the number of children of self.

__str__()

Return a Newick string of self, with names and distances.