Modifying tree edges with mod¶
The submodule toytree.mod includes many options for efficiently modifying a tree. In this section we describe methods for modifying tree edges (dist values). While it is possible to accomplish this by editing attributes of the Node objects themselves, such as their .dist, this can be error-prone if you are not highly experienced. Instead, the we provide a suite of methods for this.
import toytree
# example tree for demonstrations
tree = toytree.rtree.unittree(ntips=6, seed=123)
tree.draw();
Module-level versus Object-level APIs¶
The methods in toytree.mod can also be called directly from ToyTree objects using the object-level API.
# module level API takes tree as the first arg
rtree = toytree.mod.edges_extend_tips_to_align(tree)
# object-level API knows the tree is the object to operate on
rtree = tree.mod.edges_extend_tips_to_align()
Methods¶
edges_extend_tips_to_align¶
Return a ToyTree with tips Node dists extended to align. Tip Node dists are extended to align with the Node that is farthest from the root (defined as height=0). This is a simple way to make a tree ultrametric.
rtree = toytree.rtree.rtree(ntips=5)
mod_tree = toytree.mod.edges_extend_tips_to_align(rtree,)
toytree.mtree([rtree, mod_tree]).draw(scale_bar=True);
edges_scale_to_root_height¶
Return ToyTree rescaled to a specific total tree height. Edge lengths (Node dist values) are all multiplied by a constant
factor to make the root Node height align at the specified height. By default the tree is scaled to set the root crown height,
but if the tree has a dist value assigned to the treenode it can alternatively be scaled to set the stem height using include_stem=True.
mod_tree = toytree.mod.edges_scale_to_root_height(tree, 10.)
toytree.mtree([tree, mod_tree]).draw(scale_bar=True);
edges_set_node_heights¶
Return a ToyTree with one or more Node heights set explicitly.
Enter a dictionary mapping node queries to heights. Nodes that
are not included as keys will remain at there existing height, but
their dist values may be changed to modify the heights of other
Nodes, since height is an emergent property of the dist values of
many connected Nodes. This same operation can be achieved using set_node_data
to set node heights, but is explicitly defined as a separate function name
to make it clear to users as an option for manipulating edge lengths.
mod_tree = toytree.mod.edges_set_node_heights(tree, {0: 0.1, -1: 2, "r3": 0.2})
toytree.mtree([tree, mod_tree]).draw(scale_bar=True, node_sizes=15, node_labels="idx");
edges_slider¶
Return ToyTree with node heights randomly shifted within bounds. Node heights are moved up or down uniformly between their parent and highest child node heights in 'levelorder' (from root to tips). Root and tip heights are fixed, only internal node heights change.
mod_tree1 = toytree.mod.edges_slider(tree, prop=0.5, seed=123)
mod_tree2 = toytree.mod.edges_slider(tree, prop=0.5, seed=321)
toytree.mtree([tree, mod_tree1, mod_tree2]).draw(scale_bar=True, node_sizes=15, node_labels="idx");
Model-based edge scaling¶
IN DEVELOPMENT...
Penalized likelihood¶