brokilon.core.tree module

This is a minimal copy/modification of the tree related code from ete3. Please see ete3 for more detail and the original code. LB: This is here because I don’t need the full dependency and also don’t want to have to wait for them to update to newer versions or fix problems…

exception brokilon.core.tree.NewickError(value)

Bases: Exception

Exception class designed for NewickIO errors.

brokilon.core.tree.Tree

alias of TreeNode

exception brokilon.core.tree.TreeError(value='')

Bases: Exception

A problem occurred during a TreeNode operation

class brokilon.core.tree.TreeNode(newick=None, format=0, dist=None, support=None, name=None, quoted_node_names=False)

Bases: object

_iter_descendants_levelorder(is_leaf_fn=None)

Iterate over all desdecendant nodes.

_iter_descendants_postorder(is_leaf_fn=None)

_iter_descendants_preorder(is_leaf_fn=None)

Iterator over all descendant nodes.

add_child(child=None, name=None, dist=None, support=None)

Adds a new child to this node. If child node is not suplied as an argument, a new node instance will be created.

Parameters:

• child (None) – the node instance to be added as a child.

• name (None) – the name that will be given to the child.

• dist (None) – the distance from the node to the child.

• support (None) – the support value of child partition.

Returns:

The child node instance

add_feature(pr_name, pr_value)

Add or update a node’s feature.

add_features(**features)

Add or update several features.

property children

get_cached_content(store_attr=None, container_type=<class 'set'>, leaves_only=True, _store=None)

Returns a dictionary pointing to the preloaded content of each internal node under this tree. Such a dictionary is intended to work as a cache for operations that require many traversal operations.

Parameters:

• store_attr (None) – Specifies the node attribute that should be cached (i.e. name, distance, etc.). When none, the whole node instance is cached.

• _store – (internal use)

get_common_ancestor(*target_nodes, **kargs)

Returns the first common ancestor between this node and a given list of ‘target_nodes’.

Examples:

t = tree.Tree("(((A:0.1, B:0.01):0.001, C:0.0001):1.0[&&NHX:name=common], (D:0.00001):0.000001):2.0[&&NHX:name=root];")
A = t.get_descendants_by_name("A")[0]
C = t.get_descendants_by_name("C")[0]
common =  A.get_common_ancestor(C)
print common.name

get_distance(target, target2=None, topology_only=False)

Returns the distance between two nodes. If only one target is specified, it returns the distance between the target and the current node.

Parameters:

• target – a node within the same tree structure.

• target2 – a node within the same tree structure. If not specified, current node is used as target2.

• topology_only (False) – If set to True, distance will refer to the number of nodes between target and target2.

Returns:

branch length distance between target and target2. If topology_only flag is True, returns the number of nodes between target and target2.

get_leaves(is_leaf_fn=None)

Returns the list of terminal nodes (leaves) under this node.

Parameters:

is_leaf_fn (None) – See TreeNode.traverse() for documentation.

get_tree_root()

Returns the absolute root node of current tree structure.

is_leaf()

Return True if current node is a leaf.

is_root()

Returns True if current node has no parent

iter_descendants(strategy='levelorder', is_leaf_fn=None)

Returns an iterator over all descendant nodes.

Parameters:

is_leaf_fn (None) – See TreeNode.traverse() for documentation.

iter_leaves(is_leaf_fn=None)

Returns an iterator over the leaves under this node.

Parameters:

is_leaf_fn (None) – See TreeNode.traverse() for documentation.

iter_prepostorder(is_leaf_fn=None)

Iterate over all nodes in a tree yielding every node in both pre and post order. Each iteration returns a postorder flag (True if node is being visited in postorder) and a node instance.

iter_search_nodes(**conditions)

Search nodes in an iterative way. Matches are yielded as they are being found. This avoids needing to scan the full tree topology before returning the first matches. Useful when dealing with huge trees.

search_nodes(**conditions)

Returns the list of nodes matching a given set of conditions.

Example:

tree.search_nodes(dist=0.0, name="human")

property support

traverse(strategy='levelorder', is_leaf_fn=None)

Returns an iterator to traverse the tree structure under this node.

Parameters:

• strategy ("levelorder") – set the way in which tree will be traversed. Possible values are: “preorder” (first parent and then children) ‘postorder’ (first children and the parent) and “levelorder” (nodes are visited in order from root to leaves)

• is_leaf_fn (None) – If supplied, is_leaf_fn function will be used to interrogate nodes about if they are terminal or internal. is_leaf_fn function should receive a node instance as first argument and return True or False. Use this argument to traverse a tree by dynamically collapsing internal nodes matching is_leaf_fn.

property up

write(features=None, outfile=None, format=0, is_leaf_fn=None, format_root_node=False, dist_formatter=None, support_formatter=None, name_formatter=None, quoted_node_names=False)

Returns the newick representation of current node. Several arguments control the way in which extra data is shown for every node:

Parameters:

• features – a list of feature names to be exported using the Extended Newick Format (i.e. features=[“name”, “dist”]). Use an empty list to export all available features in each node (features=[])

• outfile – writes the output to a given file

• format – defines the newick standard used to encode the tree. See tutorial for details.

• format_root_node (False) – If True, it allows features and branch information from root node to be exported as a part of the newick text string. For newick compatibility reasons, this is False by default.

• is_leaf_fn – See TreeNode.traverse() for documentation.

Example:

t.write(features=["species","name"], format=1)

brokilon.core.tree._get_features_string(self, features=None)

Generates the extended Newick NHX string with extra data about a node.

brokilon.core.tree._parse_extra_features(node, NHX_string)

Reads node’s extra data form its NHX string. NHX uses this format: [&&NHX:prop1=value1:prop2=value2]

brokilon.core.tree._read_newick_from_string(nw, root_node, matcher, formatcode, quoted_names)

Reads a newick string in the New Hampshire format.

brokilon.core.tree._read_node_data(subnw, current_node, node_type, matcher, formatcode)

Reads a leaf node from a subpart of the original newick tree

brokilon.core.tree._translate_nodes(root, *nodes)

brokilon.core.tree.compile_matchers(formatcode)

brokilon.core.tree.extract_edge_set(t, attr_t)

brokilon.core.tree.format_node(node, node_type, format, dist_formatter=None, support_formatter=None, name_formatter=None, quoted_names=False)

brokilon.core.tree.read_newick(newick, root_node=None, format=0, quoted_names=False)

Reads a newick tree from either a string or a file, and returns an ETE tree structure.

A previously existent node object can be passed as the root of the tree, which means that all its new children will belong to the same class as the root(This allows to work with custom TreeNode objects).

You can also take advantage from this behaviour to concatenate several tree structures.

brokilon.core.tree.write_newick(rootnode, features=None, format=1, format_root_node=True, is_leaf_fn=None, dist_formatter=None, support_formatter=None, name_formatter=None, quoted_names=False)

Iteratively export a tree structure and returns its NHX representation.