PhyloNode#

class PhyloNode(*args, **kwargs)#

Attributes:

length
parent: parent of this node
source

Methods

`ancestors`()	Returns all ancestors back to the root.
`append`(i)	Appends i to self.children, in-place, cleaning up refs.
`ascii_art`([show_internal, compact])	Returns a string containing an ascii drawing of the tree.
`balanced`()	Tree 'rooted' here with no neighbour having > 50% of the edges.
`bifurcating`([eps, constructor, name_unnamed])	Wrap multifurcating with a num of 2
`child_groups`()	Returns list containing lists of children sharing a state.
`child_parent_map`()	return dict of {<child name>: <parent name>, ...}
`compare_by_names`(other)	Equality test for trees by name
`compare_by_subsets`(other[, exclude_absent_taxa])	Returns fraction of overlapping subsets where self and other differ.
`compare_by_tip_distances`(other[, sample, ...])	discontinued
`compare_name`(other)	Compares TreeNode by name
`copy`([memo, _nil, constructor])	Returns a copy of self using an iterative approach
`copy_topology`([constructor])	Copies only the topology and labels of a tree, not any extra data.
`deepcopy`([memo, _nil, constructor])	Returns a copy of self using an iterative approach
`descendant_array`([tip_list])	Returns numpy array with nodes in rows and descendants in columns.
`distance`(other)	Returns branch length between self and other.
`extend`(items)	Extends self.children by items, in-place, cleaning up refs.
`get_connecting_edges`(name1, name2)	returns a list of edges connecting two nodes.
`get_connecting_node`(name1, name2)	Finds the last common ancestor of the two named edges.
`get_distances`([names])	returns pairwise distance matrix
`get_edge_names`(tip1name, tip2name[, clade, ...])	Return the list of stem and/or sub tree (clade) edge name(s).
`get_edge_vector`([include_root])	Collect the list of edges in postfix order
`get_figure`([style])	gets Dendrogram for plotting the phylogeny
`get_max_tip_tip_distance`()	Returns the max tip-to-tip distance between any pair of tips
`get_newick`([with_distances, semicolon, ...])	Return the newick string of node and its descendents
`get_node_matching_name`(name)	find the edge with the name
`get_node_names`([include_self, tips_only])	Return a list of edges from this edge - may or may not include self.
`get_nodes_dict`()	Returns a dict keyed by node name, value is node
`get_param_value`(param, edge)	returns the parameter value for named edge
`get_root`()	Returns root of the tree self is in.
`get_sub_tree`(name_list[, ignore_missing, ...])	A new instance of a sub tree that contains all the otus that are listed in name_list.
`get_tip_names`([include_self])	return the list of the names of all tips contained by this edge
`get_xml`()	Return XML formatted tree string.
`index_in_parent`()	Returns index of self in parent.
`insert`(index, i)	Inserts an item at specified position in self.children.
`is_root`()	Returns True if the current is a root, i.e. has no parent.
`is_tip`()	Returns True if the current node is a tip, i.e. has no children.
`isroot`()	Returns True if root of a tree, i.e. no parent.
`istip`()	Returns True if is tip, i.e. no children.
`iter_nontips`([include_self])	Iterates over nontips descended from self
`iter_tips`([include_self])	Iterates over tips descended from self, [] if self is a tip.
`last_common_ancestor`(other)	Finds last common ancestor of self and other, or None.
`lca`(other)	Finds last common ancestor of self and other, or None.
`levelorder`([include_self])	Performs levelorder iteration over tree
`lin_rajan_moret`(tree2)	return the lin-rajan-moret distance between trees
`lowest_common_ancestor`(tipnames)	Lowest common ancestor for a list of tipnames
`make_tree_array`([dec_list])	Makes an array with nodes in rows and descendants in columns.
`max_tip_tip_distance`()	returns the max distance between any pair of tips
`multifurcating`(num[, eps, constructor, ...])	return a new tree with every node having num or few children
`name_unnamed_nodes`()	sets the Data property of unnamed nodes to an arbitrary value
`non_tip_children`()	Returns direct children in self that have descendants.
`nontips`([include_self])	Returns nontips descended from self.
`pop`([index])	Returns and deletes child of self at index (default: -1)
`postorder`([include_self])	performs postorder iteration over tree
`pre_and_postorder`([include_self])	Performs iteration over tree, visiting node before and after.
`preorder`([include_self])	Performs preorder iteration over tree.
`prune`([keep_root])	removes nodes with one child
`reassign_names`(mapping[, nodes])	Reassigns node names based on a mapping dict
`remove`(target)	Removes node by name instead of identity.
`remove_deleted`(is_deleted)	Removes all nodes where is_deleted tests true.
`remove_node`(target)	Removes node by identity instead of value.
`root_at_midpoint`()	return a new tree rooted at midpoint of the two tips farthest apart
`rooted`(edge_name)	Returns a new tree with split at edge_name
`rooted_at`(edge_name)	Return a new tree rooted at the provided node.
`rooted_with_tip`(outgroup_name)	A new tree with the named tip as one of the root's children
`same_shape`(other)	Ignores lengths and order, so trees should be sorted first
`same_topology`(other)	Tests whether two trees have the same topology.
`scale_branch_lengths`([max_length, ultrametric])	discontinued
`separation`(other)	Returns number of edges separating self and other.
`set_max_tip_tip_distance`()	discontinued
`set_param_value`(param, edge, value)	set's the value for param at named edge
`set_tip_distances`()	discontinued
`siblings`()	Returns all nodes that are children of the same parent as self.
`sorted`([sort_order])	An equivalent tree sorted into a standard order.
`subset`()	Returns set of names that descend from specified node
`subsets`()	Returns all sets of names that come from specified node and its kids
`tip_children`()	Returns direct children of self that are tips.
`tip_to_root_distances`([names, default_length])	returns the cumulative sum of lengths from each tip to the root
`tip_to_tip_distances`([names, default_length])	Returns distance matrix between all pairs of tips, and a tip order
`tips`([include_self])	Returns tips descended from self, [] if self is a tip.
`tips_within_distance`(distance)	Returns tips within specified distance from self
`to_json`()	returns json formatted string {'newick': with edges and distances, 'edge_attributes': }
`to_rich_dict`()	returns {'newick': with node names, 'edge_attributes': {'tip1': {'length': ...}, ...}}
`total_descending_branch_length`()	Returns total descending branch length from self
`total_length`()	returns the sum of all branch lengths in tree
`traverse`([self_before, self_after, include_self])	discontinued
`tree_distance`(other[, method])	Return the specified tree distance between this and another tree.
`unrooted`()	A tree with at least 3 children at the root.
`unrooted_deepcopy`([constructor, parent])	Returns a deepcopy of the tree using unrooted traversal.
`write`(filename[, with_distances, format])	Save the tree to filename

parse_token
root

ancestors()#: Returns all ancestors back to the root.

append(i) → None#: Appends i to self.children, in-place, cleaning up refs.

ascii_art(show_internal=True, compact=False)#

Returns a string containing an ascii drawing of the tree.

Parameters:

show_internal: includes internal edge names.
compact: use exactly one line per tip.

balanced()#

Tree ‘rooted’ here with no neighbour having > 50% of the edges.

Usage:: Using a balanced tree can substantially improve performance of the likelihood calculations. Note that the resulting tree has a different orientation with the effect that specifying clades or stems for model parameterisation should be done using the ‘outgroup_name’ argument.

bifurcating(eps=None, constructor=None, name_unnamed=False)#: Wrap multifurcating with a num of 2

child_groups()#

Returns list containing lists of children sharing a state.

In other words, returns runs of tip and nontip children.

child_parent_map() → dict[str, str]#: return dict of {<child name>: <parent name>, …}

compare_by_names(other)#: Equality test for trees by name

compare_by_subsets(other, exclude_absent_taxa=False)#

Returns fraction of overlapping subsets where self and other differ.

Other is expected to be a tree object compatible with PhyloNode.

Note: names present in only one of the two trees will count as mismatches: if you don’t want this behavior, strip out the non-matching tips first.

compare_by_tip_distances(other, sample=None, dist_f=<function distance_from_r>, shuffle_f=<bound method Random.shuffle of <random.Random object>>)#: discontinued

compare_name(other)#: Compares TreeNode by name

copy(memo=None, _nil=None, constructor: None = None)#: Returns a copy of self using an iterative approach

copy_topology(constructor=None)#

Copies only the topology and labels of a tree, not any extra data.

Useful when you want another copy of the tree with the same structure and labels, but want to e.g. assign different branch lengths and environments. Does not use deepcopy from the copy module, so _much_ faster than the copy() method.

deepcopy(memo=None, _nil=None, constructor: None = None)#: Returns a copy of self using an iterative approach

descendant_array(tip_list=None)#

Returns numpy array with nodes in rows and descendants in columns.

A value of 1 indicates that the decendant is a descendant of that node/ A value of 0 indicates that it is not

Also returns a list of nodes in the same order as they are listed in the array.

tip_list is a list of the names of the tips that will be considered, in the order they will appear as columns in the final array. Internal nodes will appear as rows in preorder traversal order.

distance(other)#: Returns branch length between self and other.

extend(items) → None#: Extends self.children by items, in-place, cleaning up refs.

get_connecting_edges(name1, name2)#

returns a list of edges connecting two nodes.

If both are tips, the LCA is excluded from the result.

get_connecting_node(name1, name2)#: Finds the last common ancestor of the two named edges.

get_distances(names: list[str] | None = None) → DistanceMatrix#: returns pairwise distance matrix

get_edge_names(tip1name, tip2name, clade=True, stem=False, outgroup_name=None)#

Return the list of stem and/or sub tree (clade) edge name(s). This is done by finding the common intersection, and then getting the list of names. If the clade traverses the root, then use the outgroup_name argument to ensure valid specification.

Parameters:

tip1/2name: edge 1/2 names
stem: whether the name of the clade stem edge is returned.
clade: whether the names of the edges within the clade are returned
outgroup_name: if provided the calculation is done on a version of the tree re-rooted relative to the provided tip.
Usage:: The returned list can be used to specify subtrees for special parameterisation. For instance, say you want to allow the primates to have a different value of a particular parameter. In this case, provide the results of this method to the parameter controller method set_param_rule() along with the parameter name etc..

get_edge_vector(include_root: bool = True) → list[Self]#

Collect the list of edges in postfix order

Parameters:

include_root: specifies whether root edge included

get_figure(style='square', **kwargs)#

gets Dendrogram for plotting the phylogeny

Parameters:

stylestring: ‘square’, ‘angular’, ‘radial’ or ‘circular’
kwargs: arguments passed to Dendrogram constructor

get_max_tip_tip_distance() → tuple[float, tuple[str, str], Self]#

Returns the max tip-to-tip distance between any pair of tips

Returns:

dist, tip_names, internal_node

get_newick(with_distances: bool = False, semicolon: bool = True, escape_name: bool = True, with_node_names: bool = False, with_root_name: bool = False) → str#

Return the newick string of node and its descendents

Parameters:

with_distances: include value of node length attribute if present.
semicolon: end tree string with a semicolon
escape_name: if any of these characters []’”() are within the nodes name, wrap the name in single quotes
with_node_names: includes internal node names
with_root_name: if True and with_node_names, the root node will have its name included

get_node_matching_name(name: str) → Self#

find the edge with the name

Raises:

TreeError if no edge with the name is found

get_node_names(include_self: bool = True, tips_only: bool = False) → list[str]#

Return a list of edges from this edge - may or may not include self. This node (or first connection) will be the first, and then they will be listed in the natural traverse order.

Parameters:

include_selfbool: excludes self.name from the result
tips_onlybool: only tips returned

get_nodes_dict()#

Returns a dict keyed by node name, value is node

Will raise TreeError if non-unique names are encountered

get_param_value(param, edge)#: returns the parameter value for named edge

get_root() → Self#: Returns root of the tree self is in.

get_sub_tree(name_list: list[str], ignore_missing: bool = False, tips_only: bool = False, as_rooted: bool = False) → Self#

A new instance of a sub tree that contains all the otus that are listed in name_list.

Parameters:

ignore_missing: if False, get_sub_tree will raise a ValueError if name_list contains names that aren’t nodes in the tree
tips_only: only tip names matching name_list are allowed
as_rooted: if True, the resulting subtree root will be as resolved. Otherwise, the subtree is coerced to have the same number of children as self.

get_tip_names(include_self: bool = False) → list[str]#: return the list of the names of all tips contained by this edge

get_xml()#: Return XML formatted tree string.

index_in_parent() → int#: Returns index of self in parent.

insert(index, i) → None#: Inserts an item at specified position in self.children.

is_root() → bool#: Returns True if the current is a root, i.e. has no parent.

is_tip() → bool#: Returns True if the current node is a tip, i.e. has no children.

isroot()#: Returns True if root of a tree, i.e. no parent.

istip() → bool#: Returns True if is tip, i.e. no children.

iter_nontips(include_self: bool = False) → Generator[Self, None, None]#

Iterates over nontips descended from self

Parameters:

include_self: if True (default is False), will return the current node as part of the list of nontips if it is a nontip.

iter_tips(include_self=False)#: Iterates over tips descended from self, [] if self is a tip.

last_common_ancestor(other)#

Finds last common ancestor of self and other, or None.

Always tests by identity.

lca(other)#

Finds last common ancestor of self and other, or None.

Always tests by identity.

property length: float | None#

levelorder(include_self: bool = True) → Generator[Self, None, None]#: Performs levelorder iteration over tree

lin_rajan_moret(tree2) → int#

return the lin-rajan-moret distance between trees

float: the Lin-Rajan-Moret distance

Notes

This is a distance measure that exhibits superior statistical properties compared to Robinson-Foulds. It can only be applied to unrooted trees.

see: Lin et al. 2012 A Metric for Phylogenetic Trees Based on Matching IEEE/ACM Transactions on Computational Biology and Bioinformatics vol. 9, no. 4, pp. 1014-1022, July-Aug. 2012

lowest_common_ancestor(tipnames: list[str]) → Self#

Lowest common ancestor for a list of tipnames

This should be around O(H sqrt(n)), where H is height and n is the number of tips passed in.

make_tree_array(dec_list=None)#

Makes an array with nodes in rows and descendants in columns.

A value of 1 indicates that the decendant is a descendant of that node/ A value of 0 indicates that it is not

also returns a list of nodes in the same order as they are listed in the array

max_tip_tip_distance() → tuple[float, tuple[str, str]]#

returns the max distance between any pair of tips

Also returns the tip names that it is between as a tuple

multifurcating(num, eps=None, constructor=None, name_unnamed=False)#

return a new tree with every node having num or few children

Parameters:

numint: the number of children a node can have max
epsfloat: default branch length to set if self or constructor is of PhyloNode type
constructor: a TreeNode or subclass constructor. If None, uses self
name_unnamedbool: names unnamed nodes

name_unnamed_nodes() → None#

sets the Data property of unnamed nodes to an arbitrary value

Internal nodes are often unnamed and so this function assigns a value for referencing.

non_tip_children()#: Returns direct children in self that have descendants.

nontips(include_self=False)#: Returns nontips descended from self.

property parent: Self | None#: parent of this node

static parse_token(token: str) → tuple[str | None, dict]#

pop(index=-1)#: Returns and deletes child of self at index (default: -1)

postorder(include_self: bool = True) → Generator[Self, None, None]#: performs postorder iteration over tree

pre_and_postorder(include_self: bool = True) → Generator[Self, None, None]#: Performs iteration over tree, visiting node before and after.

preorder(include_self: bool = True) → Generator[Self, None, None]#: Performs preorder iteration over tree.

prune(keep_root: bool = False) → None#

removes nodes with one child

Parameters:

keep_root: if True, a root with a single child is retained.

Notes

Mutates the tree in-place. Internal nodes with only one child will be merged (except as specified by keep_root).

reassign_names(mapping: dict[str, str], nodes: list[Self] | None = None) → None#

Reassigns node names based on a mapping dict

mapping : dict, old_name -> new_name nodes : specific nodes for renaming (such as just tips, etc…)

remove(target) → bool#

Removes node by name instead of identity.

Returns True if node was present, False otherwise.

remove_deleted(is_deleted) → None#

Removes all nodes where is_deleted tests true.

Internal nodes that have no children as a result of removing deleted are also removed.

remove_node(target: Self) → bool#

Removes node by identity instead of value.

Returns True if node was present, False otherwise.

root() → Self#

root_at_midpoint() → Self#

return a new tree rooted at midpoint of the two tips farthest apart

this fn doesn’t preserve the internal node naming or structure, but does keep tip to tip distances correct. uses unrooted_deepcopy()

rooted(edge_name: str) → Self#

Returns a new tree with split at edge_name

Parameters:

edge_name: name of the edge to split at. The length of edge_name will be halved. The new tree will have two children.

rooted_at(edge_name)#

Return a new tree rooted at the provided node.

Usage:: This can be useful for drawing unrooted trees with an orientation that reflects knowledge of the true root location.

rooted_with_tip(outgroup_name)#: A new tree with the named tip as one of the root’s children

same_shape(other)#: Ignores lengths and order, so trees should be sorted first

same_topology(other) → bool#: Tests whether two trees have the same topology.

scale_branch_lengths(max_length: int = 100, ultrametric: bool = False) → None#: discontinued

separation(other)#: Returns number of edges separating self and other.

set_max_tip_tip_distance() → None#: discontinued

set_param_value(param, edge, value) → None#: set’s the value for param at named edge

set_tip_distances() → None#: discontinued

siblings()#

Returns all nodes that are children of the same parent as self.

Note: excludes self from the list. Dynamically calculated.

sorted(sort_order=None)#: An equivalent tree sorted into a standard order. If this is not specified then alphabetical order is used. At each node starting from root, the algorithm will try to put the descendant which contains the lowest scoring tip on the left.

property source: str | None#

subset() → frozenset[str | None]#: Returns set of names that descend from specified node

subsets() → frozenset[frozenset[str]]#: Returns all sets of names that come from specified node and its kids

tip_children()#: Returns direct children of self that are tips.

tip_to_root_distances(names: list[str] | None = None, default_length: float = 1) → dict[str, float]#

returns the cumulative sum of lengths from each tip to the root

Parameters:

names: list of tip names to calculate distances for, defaults to all
default_length: value to use for edges that no length value

tip_to_tip_distances(names: list[str] | None = None, default_length: float | None = None) → DistanceMatrix#: Returns distance matrix between all pairs of tips, and a tip order

tips(include_self=False)#: Returns tips descended from self, [] if self is a tip.

tips_within_distance(distance)#

Returns tips within specified distance from self

Branch lengths of None will be interpreted as 0

to_json()#: returns json formatted string {‘newick’: with edges and distances, ‘edge_attributes’: }

to_rich_dict()#: returns {‘newick’: with node names, ‘edge_attributes’: {‘tip1’: {‘length’: …}, …}}

total_descending_branch_length() → float#: Returns total descending branch length from self

total_length() → float#: returns the sum of all branch lengths in tree

traverse(self_before: bool = True, self_after: bool = False, include_self: bool = True) → Iterator[Self]#: discontinued

tree_distance(other: TreeNode, method: str | None = None) → int#

Return the specified tree distance between this and another tree.

Defaults to the Lin-Rajan-Moret distance on unrooted trees. Defaults to the Matching Cluster distance on rooted trees.

Parameters:

other: TreeNode

The other tree to calculate the distance between.

method: str | None

The tree distance metric to use.

Options are: “rooted_robinson_foulds”: The Robinson-Foulds distance for rooted trees. “unrooted_robinson_foulds”: The Robinson-Foulds distance for unrooted trees. “matching_cluster”: The Matching Cluster distance for rooted trees. “lin_rajan_moret”: The Lin-Rajan-Moret distance for unrooted trees. “rrf”: An alias for rooted_robinson_foulds. “urf”: An alias for unrooted_robinson_foulds. “mc”: An alias for matching_cluster. “lrm”: An alias for lin_rajan_moret. “rf”: The unrooted/rooted Robinson-Foulds distance for unrooted/rooted trees. “matching”: The Lin-Rajan-Moret/Matching Cluster distance for unrooted/rooted trees.

Default is “matching”.

Returns:

int: the chosen distance between the two trees.

Notes

The Lin-Rajan-Moret distance [2] and Matching Cluster distance [1] display superior statistical properties than the Robinson-Foulds distance [3] on unrooted and rooted trees respectively.

References

[1]

Bogdanowicz, D., & Giaro, K. (2013). On a matching distance between rooted phylogenetic trees. International Journal of Applied Mathematics and Computer Science, 23(3), 669-684.

[2]

Lin et al. 2012 A Metric for Phylogenetic Trees Based on Matching IEEE/ACM Transactions on Computational Biology and Bioinformatics vol. 9, no. 4, pp. 1014-1022, July-Aug. 2012

[3]

Robinson, David F., and Leslie R. Foulds. Comparison of phylogenetic trees. Mathematical biosciences 53.1-2 (1981): 131-147.

unrooted() → Self#: A tree with at least 3 children at the root.

unrooted_deepcopy(constructor: Callable[[T, list[T]], T] | None = None, parent: Self | None = None) → Self#

Returns a deepcopy of the tree using unrooted traversal.

Each node is treated as connected to its parent and children. The resulting tree may contain unary internal nodes, which can be cleaned up using prune() afterward.

write(filename, with_distances=True, format=None) → None#

Save the tree to filename

Parameters:

filename: self
with_distances: whether branch lengths are included in string.
format: default is newick, xml and json are alternate. Argument overrides the filename suffix. All attributes are saved in the xml format. Value overrides the file name suffix.

Notes

Only the cogent3 json and xml tree formats are supported.