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 ellapsed 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

Tree IO

read([format])	Create a new TreeNode instance from a file.
write(file[, format])	Write an instance of TreeNode to a file.

Tree navigation

ancestors([include_self])	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([nodes])	Find the lowest common ancestor of a list of nodes.
neighbors([ignore])	Return all nodes that are neighbors of the current node.
path(other[, include_ends])	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([include_self])	Perform level order traversal over tree.
non_tips([include_self])	Iterate over non-tip nodes descended from the current node.
postorder([include_self])	Perform postorder traversal over tree.
pre_and_postorder([include_self])	Perform traversal over tree, visiting nodes before and after.
preorder([include_self])	Perform preorder traversal over tree.
tips([include_self])	Iterate over tips descended from the current node.
traverse([self_before, self_after, include_self])	Traverse over tree.

Tree copying

copy([deep])	Return a copy of self using an iterative approach.
deepcopy()	Return a deep copy of self using an iterative approach.
subtree([tip_list])	Make a copy of the subtree.

Tree manipulation

append(node[, uncache])	Add a node to self's children.
bifurcate([insert_length, include_self, uncache])	Convert the tree into a bifurcating tree.
extend(nodes[, uncache])	Add a list of nodes to self's children.
insert(node[, distance, branch_attrs, uncache])	Insert a node into the branch connecting self and its parent.
pop([index, uncache])	Remove and return a child node by index position from self.
prune([uncache])	Collapse single-child nodes in the tree.
remove(node[, uncache])	Remove a child node by identity from self.
remove_by_func(func[, uncache])	Remove nodes of a tree that meet certain criteria.
remove_deleted(func[, uncache])	Remove nodes of a tree that meet certain criteria.
shear(names[, strict, prune, inplace, uncache])	Refine a tree such that it just has the desired tip names.
shuffle([k, names, shuffler, n])	Randomly shuffle tip names of the tree.
unpack([uncache])	Unpack an internal node in place.
unpack_by_func(func[, uncache])	Unpack internal nodes of a tree that meet certain criteria.

Tree rerooting

root_at([node, above, reset, branch_attrs, ...])	Reroot the tree at the provided node.
root_at_midpoint([reset, branch_attrs, ...])	Reroot the tree at the midpoint of the two tips farthest apart.
root_by_outgroup(outgroup[, above, reset, ...])	Reroot the tree with a given set of taxa as outgroup.
unroot([side, uncache])	Convert a rooted tree into unrooted.
unrooted_copy([parent, branch_attrs, ...])	Walk the tree unrooted-style and return a copy.
unrooted_deepcopy([parent])	Walk the tree unrooted-style and returns a new deepcopy.
unrooted_move([branch_attrs, uncache])	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(func, cache_attrname[, ...])	Cache attributes on nodes of the tree through a postorder traversal.
clear_caches([attr, lookup])	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(name)	Find a node by name.
find_all(name)	Find all nodes that match a given name.
find_by_func(func)	Find all nodes in a tree that meet certain criteria.
find_by_id(node_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([within, include_tips, ...])	Return all bipartitions within the tree under self.
cophenet([endpoints, use_length])	Return a distance matrix between each pair of tips in the tree.
count([tips])	Get the count of nodes in the tree.
depth([ancestor, include_root, use_length, ...])	Calculate the depth of the current node.
distance(other[, use_length, missing_as_zero])	Calculate the distance between self and another node.
height([include_self, use_length, ...])	Calculate the height of the current node.
is_bifurcating([strict, include_self])	Check if the tree is bifurcating.
maxdist([use_length])	Return the maximum distance between any pair of tips in the tree.
observed_node_counts(tip_counts)	Return counts of node observations from counts of tip observations.
subset([include_self])	Return a subset of taxa descending from self.
subsets([within, include_full, ...])	Return all subsets of taxa defined by nodes descending from self.
total_length([nodes, include_stem, include_self])	Calculate the total length of branches descending from self.

Tree comparison

compare_biparts(other[, proportion])	Calculate the difference of bipartitions between two trees.
compare_cophenet(other[, sample, metric, ...])	Calculate the distance between two trees based on cophenetic distances.
compare_rfd(other[, proportion, rooted])	Calculate Robinson-Foulds distance between two trees.
compare_subsets(other[, shared_only, proportion])	Calculate the difference of subsets between two trees.
compare_wrfd(other[, metric, rooted, ...])	Calculate weighted Robinson-Foulds distance or variants between two trees.

Tree visualization

ascii_art([show_internal, compact])

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(linkage_matrix, id_list)	Return tree from SciPy linkage matrix.
from_taxdump(nodes[, names])	Construct a tree from the NCBI taxonomy database.
from_taxonomy(lineage_map)	Construct a tree from a taxonomy.
to_array([attrs, nan_length_value])	Return an array representation of self.
to_taxonomy([allow_empty, filter_f])	Return a taxonomy representation of self.

Special methods

__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.

Special methods (inherited)

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

Details

default_write_format = '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.