Package Bio :: Package Phylo :: Module BaseTree :: Class TreeMixin
[hide private]
[frames] | no frames]

Class TreeMixin

source code

object --+
         |
        TreeMixin
Known Subclasses:

Methods for Tree- and Clade-based classes.

This lets Tree and Clade support the same traversal and searching operations without requiring Clade to inherit from Tree, so Clade isn't required to have all of Tree's attributes -- just 'root' (a Clade instance) and 'is_terminal()'.

Instance Methods [hide private]
 
_filter_search(self, filter_func, order, follow_attrs)
Perform a BFS or DFS traversal through all elements in this tree.
source code
 
find_any(self, *args, **kwargs)
Return the first element found by find_elements(), or None.
source code
 
find_elements(self, target=None, terminal=None, order='preorder', **kwargs)
Find all tree elements matching the given attributes.
source code
 
find_clades(self, target=None, terminal=None, order='preorder', **kwargs)
Find each clade containing a matching element.
source code
 
get_path(self, target=None, **kwargs)
List the clades directly between the root and the given target.
source code
 
get_nonterminals(self, order='preorder')
Get a list of all of this tree's nonterminal (internal) nodes.
source code
 
get_terminals(self, order='preorder')
Get a list of all of this tree's terminal (leaf) nodes.
source code
 
trace(self, start, finish)
List of all clade object between two targets in this tree.
source code
 
common_ancestor(self, *targets)
Most recent common ancestor (clade) of all the given targets.
source code
 
count_terminals(self)
Counts the number of terminal (leaf) nodes within this tree.
source code
 
depths(self, unit_branch_lengths=False)
Create a mapping of tree clades to depths (by branch length).
source code
 
distance(self, target1, target2=None)
Calculate the sum of the branch lengths between two targets.
source code
 
is_bifurcating(self)
Return True if tree downstream of node is strictly bifurcating.
source code
 
is_monophyletic(self, terminals)
MRCA of terminals if they comprise a complete subclade, or False.
source code
 
is_parent_of(self, target=None, **kwargs)
True if target is a descendent of this tree.
source code
 
is_preterminal(self)
True if all direct descendents are terminal.
source code
 
total_branch_length(self)
Calculate the sum of all the branch lengths in this tree.
source code
 
collapse(self, target=None, **kwargs)
Deletes target from the tree, relinking its children to its parent.
source code
 
collapse_all(self)
Collapse all the descendents of this tree, leaving only terminals.
source code
 
ladderize(self, reverse=False)
Sort clades in-place according to the number of terminal nodes.
source code
 
prune(self, target=None, **kwargs)
Prunes a terminal clade from the tree.
source code
 
split(self, n=2, branch_length=1.0)
Speciation: generate n (default 2) new descendants.
source code

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __init__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __str__, __subclasshook__

Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

_filter_search(self, filter_func, order, follow_attrs)

source code 

Perform a BFS or DFS traversal through all elements in this tree.

Returns:
generator of all elements for which 'filter_func' is True.

find_any(self, *args, **kwargs)

source code 

Return the first element found by find_elements(), or None.

This is also useful for checking whether any matching element exists in the tree.

find_elements(self, target=None, terminal=None, order='preorder', **kwargs)

source code 

Find all tree elements matching the given attributes.

The arbitrary keyword arguments indicate the attribute name of the sub-element and the value to match: string, integer or boolean. Strings are evaluated as regular expression matches; integers are compared directly for equality, and booleans evaluate the attribute's truth value (True or False) before comparing. To handle nonzero floats, search with a boolean argument, then filter the result manually.

If no keyword arguments are given, then just the class type is used for matching.

The result is an iterable through all matching objects, by depth-first search. (Not necessarily the same order as the elements appear in the source file!)

Example:

>>> from Bio.Phylo.IO import PhyloXMIO
>>> phx = PhyloXMLIO.read('phyloxml_examples.xml')
>>> matches = phx.phylogenies[5].find_elements(code='OCTVU')
>>> matches.next()
Taxonomy(code='OCTVU', scientific_name='Octopus vulgaris')
Parameters:
  • target (TreeElement instance, type, dict, or callable) - Specifies the characteristics to search for. (The default, TreeElement, matches any standard Bio.Phylo type.)
  • terminal (bool) - A boolean value to select for or against terminal nodes (a.k.a. leaf nodes). True searches for only terminal nodes, False excludes terminal nodes, and the default, None, searches both terminal and non-terminal nodes, as well as any tree elements lacking the 'is_terminal' method.
  • order (string ('preorder'|'postorder'|'level')) - Tree traversal order: 'preorder' (default) is depth-first search, 'postorder' is DFS with child nodes preceding parents, and 'level' is breadth-first search.

find_clades(self, target=None, terminal=None, order='preorder', **kwargs)

source code 

Find each clade containing a matching element.

That is, find each element as with find_elements(), but return the corresponding clade object.

get_path(self, target=None, **kwargs)

source code 

List the clades directly between the root and the given target.

Returns a list of all clade objects along this path, ending with the given target, but excluding the root clade.

trace(self, start, finish)

source code 

List of all clade object between two targets in this tree.

Excluding start, including finish.

common_ancestor(self, *targets)

source code 

Most recent common ancestor (clade) of all the given targets.

Edge cases:

  • If no target is given, returns self.root
  • If 1 target is given, returns the target
  • If any target is not found in this tree, raises a ValueError

depths(self, unit_branch_lengths=False)

source code 

Create a mapping of tree clades to depths (by branch length).

Returns:
dict of {clade: depth}

distance(self, target1, target2=None)

source code 

Calculate the sum of the branch lengths between two targets.

If only one target is specified, the other is the root of this tree.

is_monophyletic(self, terminals)

source code 

MRCA of terminals if they comprise a complete subclade, or False.

Returns:
common ancestor if terminals are monophyletic, otherwise False.

is_parent_of(self, target=None, **kwargs)

source code 

True if target is a descendent of this tree.

Not required to be a direct descendent.

collapse(self, target=None, **kwargs)

source code 

Deletes target from the tree, relinking its children to its parent.

Returns:
the parent clade.

collapse_all(self)

source code 

Collapse all the descendents of this tree, leaving only terminals.

To collapse only certain elements, use the collapse method directly in a loop with find_clades:

>>> for clade in tree.find_clades(branch_length=True, order='level'):
>>>     if (clade.branch_length < .5 and
>>>         not clade.is_terminal() and
>>>         clade is not self.root):
>>>         tree.collapse(clade)

Note that level-order traversal helps avoid strange side-effects when modifying the tree while iterating over its clades.

ladderize(self, reverse=False)

source code 

Sort clades in-place according to the number of terminal nodes.

Deepest clades are last by default. Use reverse=True to sort clades deepest-to-shallowest.

prune(self, target=None, **kwargs)

source code 

Prunes a terminal clade from the tree.

If taxon is from a bifurcation, the connecting node will be collapsed and its branch length added to remaining terminal node. This might be no longer a meaningful value.

Returns:
parent clade of the pruned target

split(self, n=2, branch_length=1.0)

source code 

Speciation: generate n (default 2) new descendants.

New clades have the given branch_length and the same name as this clade's root plus an integer suffix (counting from 0).