Class TreeMixin

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

This is also useful for checking whether any matching element exists in
the tree, and can be used in a conditional expression.

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!)

: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 : {'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.

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')

Find each clade containing a matching element.

That is, find each element as with find_elements(), but return the
corresponding clade object. (This is usually what you want.)

:returns: an iterable through all matching objects, searching
    depth-first (preorder) by default.

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

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

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

Excluding `start`, including `finish`.

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

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

:Parameters:
    unit_branch_lengths : bool
        If True, count only the number of branches (levels in the tree).
        By default the distance is the cumulative branch length leading
        to the clade.

:returns: dict of {clade: depth}, where keys are all of the Clade
    instances in the tree, and values are the distance from the root to
    each clade (including terminals).

Calculate the sum of the branch lengths between two targets.

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

Return True if tree downstream of node is strictly bifurcating.

I.e., all nodes have either 2 or 0 children (internal or external,
respectively). The root may have 3 descendents and still be considered
part of a bifurcating tree, because it has no ancestor.

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

I.e., there exists a clade such that its terminals are the same set as
the given targets.

The given targets must be terminals of the tree.

To match both `Bio.Nexus.Trees` and the other multi-target methods in
Bio.Phylo, arguments to this method can be specified either of two ways:
(i) as a single list of targets, or (ii) separately specified targets,
e.g. is_monophyletic(t1, t2, t3) -- but not both.

For convenience, this method returns the common ancestor (MCRA) of the
targets if they are monophyletic (instead of the value True), and False
otherwise.

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

True if target is a descendent of this tree.

Not required to be a direct descendent.

To check only direct descendents of a clade, simply use list membership
testing: ``if subclade in clade: ...``

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

:returns: the parent clade.

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

Total branch lengths are preserved, i.e. the distance to each terminal
stays the same.

For example, this will safely collapse nodes with poor bootstrap
support:

    >>> tree.collapse_all(lambda c: c.confidence is not None and
    ...                   c.confidence < 70)

This implementation avoids strange side-effects by using level-order
traversal and testing all clade properties (versus the target
specification) up front. In particular, if a clade meets the target
specification in the original tree, it will be collapsed.  For example,
if the condition is:

    >>> tree.collapse_all(lambda c: c.branch_length < 0.1)

Collapsing a clade's parent node adds the parent's branch length to the
child, so during the execution of collapse_all, a clade's branch_length
may increase. In this implementation, clades are collapsed according to
their properties in the original tree, not the properties when tree
traversal reaches the clade. (It's easier to debug.) If you want the
other behavior (incremental testing), modifying the source code of this
function is straightforward.

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.

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 be a meaningful value.

:returns: parent clade of the pruned target

Generate n (default 2) new descendants.

In a species tree, this is a speciation event.

New clades have the given branch_length and the same name as this
clade's root plus an integer suffix (counting from 0). For example,
splitting a clade named "A" produces sub-clades named "A0" and "A1".