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

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

Tree traversal

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

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.
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.
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.
prune([uncache])	Collapse single-child nodes in the tree.
shear(names[, strict, prune, inplace, uncache])	Refine a tree such that it just has the desired tip names.
unpack([uncache])	Unpack an internal node in place.
unpack_by_func(func[, uncache])	Unpack internal nodes of a tree that meet certain criteria.
bifurcate([insert_length, uncache])	Convert the tree into a bifurcating tree.
shuffle([k, names, shuffler, n])	Randomly shuffle tip names of the tree.

Tree rerooting

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([parent, branch_attrs, uncache])	Walk the tree unrooted-style and rearrange it.
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.

Tree searching

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

Tree analysis

count([tips])	Get the count of nodes in the tree.
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.
bipart()	Return a bipartition of the tree at the current branch.
biparts([within, include_tips, ...])	Return all bipartitions within the tree under self.
assign_supports()	Extract support values from internal node labels of a tree.
is_bifurcating([strict])	Check if the tree is bifurcating.
observed_node_counts(tip_counts)	Return counts of node observations from counts of tip observations.
depth([ancestor, include_root, use_length, ...])	Calculate the depth of the current node.
accumulate_to_ancestor([ancestor, ...])	Calculate the depth of the current node.
height([include_self, use_length, ...])	Calculate the height of the current node.
total_length([nodes, include_stem, include_self])	Calculate the total length of branches descending from self.
descending_branch_length([nodes, ...])	Calculate the total length of branches descending from self.
distance(other[, use_length, missing_as_zero])	Calculate the distance between self and another node.
maxdist([use_length])	Return the maximum distance between any pair of tips in the tree.
get_max_distance([use_length])	Return the maximum distance between any pair of tips in the tree.
cophenet([endpoints, use_length])	Return a distance matrix between each pair of tips in the tree.
tip_tip_distances([endpoints, use_length])	Return a distance matrix between each pair of tips in the tree.
compare_rfd(other[, proportion, rooted])	Calculate Robinson-Foulds distance between two trees.
compare_wrfd(other[, metric, rooted, ...])	Calculate weighted Robinson-Foulds distance or variants between two trees.
compare_subsets(other[, shared_only, proportion])	Calculate the difference of subsets between two trees.
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_tip_distances(other[, sample, ...])	Calculate the distance between two trees based on cophenetic distances.

Tree visualization

ascii_art([show_internal, compact])

Return a string containing an ascii drawing of the tree.

Format conversion

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