core.tree.PhyloNode
core.tree.PhyloNode(
name,
children=None,
parent=None,
params=None,
name_loaded=True,
length=None,
support=None,
)Store information about a tree node. Mutable.
Parameters: name: label for the node, assumed to be unique. children: list of the node’s children. parent: parent to this node params: dict containing arbitrary parameters for the node. name_loaded: ?
Attributes
| Name | Description |
|---|---|
| parent | parent of this node |
Methods
| Name | Description |
|---|---|
| ancestors | Returns all ancestors back to the root. |
| append | Appends i to self.children, in-place, cleaning up refs. |
| ascii_art | Returns a string containing an ascii drawing of the tree. |
| balanced | Tree ‘rooted’ here with no neighbour having > 50% of the edges. |
| bifurcating | Wrap multifurcating with a num of 2 |
| child_parent_map | return dict of { |
| compare_by_names | Equality test for trees by name |
| compare_by_subsets | Returns fraction of overlapping subsets where self and other differ. |
| compare_name | Compares PhyloNode by name |
| copy | Returns a copy of self using an iterative approach |
| descendant_array | Returns numpy array with nodes in rows and descendants in columns. |
| distance | Returns branch length between self and other. |
| extend | Extends self.children by items, in-place, cleaning up refs. |
| get_connecting_edges | returns a list of edges connecting two nodes. |
| get_connecting_node | Finds the last common ancestor of the two named edges. |
| get_edge_names | Return the list of stem and/or sub tree (clade) edge name(s). |
| get_edge_vector | Collect the list of edges in postfix order |
| get_figure | 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 | Return the newick string of node and its descendents |
| get_node_matching_name | find the edge with the name |
| get_node_names | 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 | returns the parameter value for named edge |
| get_root | Returns root of the tree self is in. |
| get_sub_tree | A new instance of a sub tree that contains all the otus that are |
| get_tip_names | return the list of the names of all tips contained by this edge |
| index_in_parent | Returns index of self in parent. |
| insert | 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 | Iterates over nontips descended from self |
| iter_tips | Iterates over tips descended from self, [] if self is a tip. |
| ladderise | Return an equivalent tree nodes using a ladderise sort. |
| last_common_ancestor | Finds last common ancestor of self and other, or None. |
| levelorder | Performs levelorder iteration over tree |
| lin_rajan_moret | return the lin-rajan-moret distance between trees |
| lowest_common_ancestor | Lowest common ancestor for a list of tipnames |
| make_tree_array | 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 | 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 | Returns nontips descended from self. |
| pop | Returns and deletes child of self at index (default: -1) |
| postorder | performs postorder iteration over tree |
| pre_and_postorder | Performs iteration over tree, visiting node before and after. |
| preorder | Performs preorder iteration over tree. |
| prune | removes nodes with one child |
| reassign_names | Reassigns node names based on a mapping dict |
| remove | Removes node by name instead of identity. |
| remove_deleted | Removes all nodes where should_delete tests true. |
| remove_node | Removes node by identity instead of value. |
| renamed_nodes | returns a copy of the tree with nodes renamed according to name_map |
| root_at_midpoint | return a new tree rooted at midpoint of the two tips farthest apart |
| rooted | Returns a new tree with split at edge_name |
| rooted_at | Return a new tree rooted at the provided node. |
| rooted_with_tip | A new tree with the named tip as one of the root’s children |
| same_shape | Ignores lengths and order, so trees should be sorted first |
| same_topology | Tests whether two trees have the same topology. |
| separation | Returns number of edges separating self and other. |
| set_param_value | set’s the value for param at named edge |
| siblings | Returns all nodes that are children of the same parent as self. |
| sorted | An equivalent tree with tips in sort_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 | returns the cumulative sum of lengths from each tip to the root |
| tip_to_tip_distances | Returns distance matrix between all pairs of tips, and a tip order |
| tips | Returns tips descended from self, [] if self is a tip. |
| tips_within_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, |
| total_descending_branch_length | Returns total descending branch length from self |
| total_length | returns the sum of all branch lengths in tree |
| tree_distance | Return the specified tree distance between this and another tree. |
| unrooted | A tree with at least 3 children at the root. |
| unrooted_deepcopy | Returns a deepcopy of the tree using unrooted traversal. |
| write | Save the tree to filename |
ancestors
core.tree.PhyloNode.ancestors()Returns all ancestors back to the root.
append
core.tree.PhyloNode.append(i)Appends i to self.children, in-place, cleaning up refs.
ascii_art
core.tree.PhyloNode.ascii_art(show_internal=True, compact=False)Returns a string containing an ascii drawing of the tree.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| show_internal | bool | includes internal edge names. | True |
| compact | bool | use exactly one line per tip. | False |
balanced
core.tree.PhyloNode.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
core.tree.PhyloNode.bifurcating(eps=None, name_unnamed=False)Wrap multifurcating with a num of 2
child_parent_map
core.tree.PhyloNode.child_parent_map()return dict of {
compare_by_names
core.tree.PhyloNode.compare_by_names(other)Equality test for trees by name
compare_by_subsets
core.tree.PhyloNode.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_name
core.tree.PhyloNode.compare_name(other)Compares PhyloNode by name
copy
core.tree.PhyloNode.copy(memo=None)Returns a copy of self using an iterative approach
descendant_array
core.tree.PhyloNode.descendant_array(tip_list=None)Returns numpy array with nodes in rows and descendants in columns.
True indicates that the decendant is a descendant of that node False 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
core.tree.PhyloNode.distance(other)Returns branch length between self and other.
extend
core.tree.PhyloNode.extend(items)Extends self.children by items, in-place, cleaning up refs.
get_connecting_edges
core.tree.PhyloNode.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
core.tree.PhyloNode.get_connecting_node(name1, name2)Finds the last common ancestor of the two named edges.
get_edge_names
core.tree.PhyloNode.get_edge_names(
tip_name_1,
tip_name_2,
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
| Name | Type | Description | Default |
|---|---|---|---|
| tip_name_1 | str | edge 1/2 names | required |
| stem | bool | whether the name of the clade stem edge is returned. | False |
| clade | bool | whether the names of the edges within the clade are returned | True |
| outgroup_name | str | None | if provided the calculation is done on a version of the tree re-rooted relative to the provided tip. | None |
| 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.. |
required |
get_edge_vector
core.tree.PhyloNode.get_edge_vector(include_root=True)Collect the list of edges in postfix order
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| include_root | bool | specifies whether root edge included | True |
get_figure
core.tree.PhyloNode.get_figure(style='square', **kwargs)gets Dendrogram for plotting the phylogeny
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| style | string | ‘square’, ‘angular’, ‘radial’ or ‘circular’ | 'square' |
| kwargs | Any | arguments passed to Dendrogram constructor | {} |
get_max_tip_tip_distance
core.tree.PhyloNode.get_max_tip_tip_distance()Returns the max tip-to-tip distance between any pair of tips
Returns
| Name | Type | Description |
|---|---|---|
| (dist, tip_names, internal_node) |
get_newick
core.tree.PhyloNode.get_newick(
with_distances=False,
semicolon=True,
escape_name=True,
with_node_names=False,
with_root_name=False,
with_support=False,
)Return the newick string of node and its descendents
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| with_distances | bool | include value of node length attribute if present. | False |
| semicolon | bool | end tree string with a semicolon | True |
| escape_name | bool | if any of these characters []’“() are within the nodes name, wrap the name in single quotes | True |
| with_node_names | bool | includes internal node names | False |
| with_root_name | bool | if True and with_node_names, the root node will have its name included | False |
| with_support | bool | include the value of node.support for every node that has one. Integer-valued supports are written without a trailing .0. The root is only emitted when with_root_name is True. |
False |
get_node_matching_name
core.tree.PhyloNode.get_node_matching_name(name)find the edge with the name
Raises
| Name | Type | Description |
|---|---|---|
| TreeError if no edge with the name is found |
get_node_names
core.tree.PhyloNode.get_node_names(include_self=True, tips_only=False)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
| Name | Type | Description | Default |
|---|---|---|---|
| include_self | bool | excludes self.name from the result | True |
| tips_only | bool | only tips returned | False |
get_nodes_dict
core.tree.PhyloNode.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
core.tree.PhyloNode.get_param_value(param, edge)returns the parameter value for named edge
get_root
core.tree.PhyloNode.get_root()Returns root of the tree self is in.
get_sub_tree
core.tree.PhyloNode.get_sub_tree(
names,
ignore_missing=False,
tips_only=False,
as_rooted=False,
)A new instance of a sub tree that contains all the otus that are listed in name_list.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| ignore_missing | bool | if False, get_sub_tree will raise a ValueError if name_list contains names that aren’t nodes in the tree | False |
| tips_only | bool | only tip names matching name_list are allowed | False |
| as_rooted | bool | if True, the resulting subtree root will be as resolved. Otherwise, the subtree is coerced to have the same number of children as self. | False |
get_tip_names
core.tree.PhyloNode.get_tip_names(include_self=True)return the list of the names of all tips contained by this edge
index_in_parent
core.tree.PhyloNode.index_in_parent()Returns index of self in parent.
insert
core.tree.PhyloNode.insert(index, i)Inserts an item at specified position in self.children.
is_root
core.tree.PhyloNode.is_root()Returns True if the current is a root, i.e. has no parent.
is_tip
core.tree.PhyloNode.is_tip()Returns True if the current node is a tip, i.e. has no children.
isroot
core.tree.PhyloNode.isroot()Returns True if root of a tree, i.e. no parent.
istip
core.tree.PhyloNode.istip()Returns True if is tip, i.e. no children.
iter_nontips
core.tree.PhyloNode.iter_nontips(include_self=False)Iterates over nontips descended from self
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| include_self | bool | if True (default is False), will return the current node as part of the list of nontips if it is a nontip. | False |
iter_tips
core.tree.PhyloNode.iter_tips(include_self=False)Iterates over tips descended from self, [] if self is a tip.
ladderise
core.tree.PhyloNode.ladderise()Return an equivalent tree nodes using a ladderise sort.
Notes
Children are ordered by their number of descendant tips with ties broken by alphabetical sort of node names.
last_common_ancestor
core.tree.PhyloNode.last_common_ancestor(other)Finds last common ancestor of self and other, or None.
Always tests by identity.
levelorder
core.tree.PhyloNode.levelorder(include_self=True)Performs levelorder iteration over tree
lin_rajan_moret
core.tree.PhyloNode.lin_rajan_moret(tree2)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
core.tree.PhyloNode.lowest_common_ancestor(tip_names)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
core.tree.PhyloNode.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
core.tree.PhyloNode.max_tip_tip_distance()returns the max distance between any pair of tips
Also returns the tip names that it is between as a tuple
multifurcating
core.tree.PhyloNode.multifurcating(num, eps=None, name_unnamed=False)return a new tree with every node having num or few children
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| num | int | the number of children a node can have max | required |
| eps | float | default branch length to set if self or constructor is of PhyloNode type a PhyloNode or subclass constructor. If None, uses self | None |
| name_unnamed | bool | names unnamed nodes | False |
name_unnamed_nodes
core.tree.PhyloNode.name_unnamed_nodes()sets the Data property of unnamed nodes to an arbitrary value
Internal nodes are often unnamed and so this function assigns a Internal nodes are often unnamed and so this function assigns a value for referencing.
non_tip_children
core.tree.PhyloNode.non_tip_children()Returns direct children in self that have descendants.
nontips
core.tree.PhyloNode.nontips(include_self=False)Returns nontips descended from self.
pop
core.tree.PhyloNode.pop(index=-1)Returns and deletes child of self at index (default: -1)
postorder
core.tree.PhyloNode.postorder(include_self=True)performs postorder iteration over tree
pre_and_postorder
core.tree.PhyloNode.pre_and_postorder(include_self=True)Performs iteration over tree, visiting node before and after.
preorder
core.tree.PhyloNode.preorder(include_self=True)Performs preorder iteration over tree.
prune
core.tree.PhyloNode.prune(keep_root=False, params_merge_callback=None)removes nodes with one child
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| keep_root | bool | If True, a root with a single child is retained. | False |
| params_merge_callback | Callable[[dict[str, Any], dict[str, Any]], dict[str, Any]] | None | How to merge two params dicts when pruning. The first argument is the parent node’s params, the second argument is the child node’s params. It should return the new params dictionary. | None |
Notes
Mutates the tree in-place. Internal nodes with only one child will be merged (except as specified by keep_root).
reassign_names
core.tree.PhyloNode.reassign_names(mapping, nodes=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
core.tree.PhyloNode.remove(target)Removes node by name instead of identity.
Returns True if node was present, False otherwise.
remove_deleted
core.tree.PhyloNode.remove_deleted(should_delete)Removes all nodes where should_delete tests true.
Internal nodes that have no children as a result of removing deleted are also removed.
remove_node
core.tree.PhyloNode.remove_node(target)Removes node by identity instead of value.
Returns True if node was present, False otherwise.
renamed_nodes
core.tree.PhyloNode.renamed_nodes(name_map)returns a copy of the tree with nodes renamed according to name_map
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| name_map | dict[str, str] | dict of {old_name: new_name, …} | required |
root_at_midpoint
core.tree.PhyloNode.root_at_midpoint()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
core.tree.PhyloNode.rooted(edge_name)Returns a new tree with split at edge_name
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| edge_name | str | name of the edge to split at. The length of edge_name will be halved. The new tree will have two children. | required |
rooted_at
core.tree.PhyloNode.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
core.tree.PhyloNode.rooted_with_tip(outgroup_name)A new tree with the named tip as one of the root’s children
same_shape
core.tree.PhyloNode.same_shape(other)Ignores lengths and order, so trees should be sorted first
same_topology
core.tree.PhyloNode.same_topology(other)Tests whether two trees have the same topology.
separation
core.tree.PhyloNode.separation(other)Returns number of edges separating self and other.
set_param_value
core.tree.PhyloNode.set_param_value(param, edge, value)set’s the value for param at named edge
siblings
core.tree.PhyloNode.siblings()Returns all nodes that are children of the same parent as self.
Note: excludes self from the list. Dynamically calculated.
sorted
core.tree.PhyloNode.sorted(sort_order=None)An equivalent tree with tips in sort_order.
Notes
If sort_order 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 smallest index tip on the left.
subset
core.tree.PhyloNode.subset()Returns set of names that descend from specified node
subsets
core.tree.PhyloNode.subsets()Returns all sets of names that come from specified node and its kids
tip_children
core.tree.PhyloNode.tip_children()Returns direct children of self that are tips.
tip_to_root_distances
core.tree.PhyloNode.tip_to_root_distances(
names=None,
default_length=1,
*,
node_length=False,
)returns the cumulative sum of lengths from each tip to the root
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| names | list[str] | None | list of tip names to calculate distances for, defaults to all | None |
| default_length | float | value to use for edges that no length value | 1 |
tip_to_tip_distances
core.tree.PhyloNode.tip_to_tip_distances(names=None, default_length=None)Returns distance matrix between all pairs of tips, and a tip order
tips
core.tree.PhyloNode.tips(include_self=False)Returns tips descended from self, [] if self is a tip.
tips_within_distance
core.tree.PhyloNode.tips_within_distance(distance)Returns tips within specified distance from self
Branch lengths of None will be interpreted as 0
to_json
core.tree.PhyloNode.to_json()returns json formatted string {‘newick’: with edges and distances, ‘edge_attributes’: }
to_rich_dict
core.tree.PhyloNode.to_rich_dict()returns {‘newick’: with node names, ‘edge_attributes’: {‘tip1’: {‘length’: …}, …}}
total_descending_branch_length
core.tree.PhyloNode.total_descending_branch_length()Returns total descending branch length from self
total_length
core.tree.PhyloNode.total_length()returns the sum of all branch lengths in tree
tree_distance
core.tree.PhyloNode.tree_distance(other, method=None)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
| Name | Type | Description | Default |
|---|---|---|---|
| other | PhyloNode | The other tree to calculate the distance between. | required |
| 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”. | None |
Returns
| Name | Type | Description |
|---|---|---|
| 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
core.tree.PhyloNode.unrooted()A tree with at least 3 children at the root.
unrooted_deepcopy
core.tree.PhyloNode.unrooted_deepcopy(parent=None)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
core.tree.PhyloNode.write(filename, with_distances=True, format_name=None)Save the tree to filename
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| filename | str | os.PathLike[str] | path to write the tree to. | required |
| with_distances | bool | whether branch lengths are included in string. | True |
| format_name | str | None | default is newick, json is alternate. Argument overrides the filename suffix. All attributes are saved in the xml format. Value overrides the file name suffix. | None |
Notes
Only the cogent3 json and newick tree formats are supported.