Back to index

python-biopython  1.60
Public Member Functions | Public Attributes | Properties | Private Member Functions
Bio.Phylo.PhyloXML.Phylogeny Class Reference
Inheritance diagram for Bio.Phylo.PhyloXML.Phylogeny:
Inheritance graph
[legend]
Collaboration diagram for Bio.Phylo.PhyloXML.Phylogeny:
Collaboration graph
[legend]

List of all members.

Public Member Functions

def __init__
def from_tree
def from_clade
def as_phyloxml
def to_phyloxml_container
def to_alignment
def __repr__
def randomized
def clade
def as_phyloxml
def root_with_outgroup
def root_at_midpoint
def is_terminal
def __format__
def format
def __str__
def __repr__
def find_any
def find_elements
def find_clades
def get_path
def get_nonterminals
def get_terminals
def trace
def common_ancestor
def count_terminals
def depths
def distance
def is_bifurcating
def is_monophyletic
def is_parent_of
def is_preterminal
def total_branch_length
def collapse
def collapse_all
def ladderize
def prune
def split

Public Attributes

 root
 rooted
 rerootable
 branch_length_unit
 type
 name
 id
 description
 date
 confidences
 clade_relations
 sequence_relations
 properties
 other

Properties

 confidence = property(_get_confidence, _set_confidence, _del_confidence)

Private Member Functions

def _get_confidence
def _set_confidence
def _del_confidence

Detailed Description

A phylogenetic tree.

:Parameters:
    root : Clade
        the root node/clade of this tree
    rooted : bool
        True if this tree is rooted
    rerootable : bool
        True if this tree is rerootable
    branch_length_unit : string
        unit for branch_length values on clades
    name : string
        identifier for this tree, not required to be unique
    id : Id
        unique identifier for this tree
    description : string
        plain-text description
    date : Date
        date for the root node of this tree
    confidences : list
        Confidence objects for this tree
    clade_relations : list
        CladeRelation objects
    sequence_relations : list 
        SequenceRelation objects
    properties : list
        Property objects
    other : list
        non-phyloXML elements (type `Other`)

Definition at line 130 of file PhyloXML.py.


Constructor & Destructor Documentation

def Bio.Phylo.PhyloXML.Phylogeny.__init__ (   self,
  root = None,
  rooted = True,
  rerootable = None,
  branch_length_unit = None,
  type = None,
  name = None,
  id = None,
  description = None,
  date = None,
  confidences = None,
  clade_relations = None,
  sequence_relations = None,
  properties = None,
  other = None 
)

Definition at line 168 of file PhyloXML.py.

00168 
00169             ):
00170         assert isinstance(rooted, bool)
00171         self.root = root
00172         self.rooted = rooted
00173         self.rerootable = rerootable
00174         self.branch_length_unit = branch_length_unit
00175         self.type = type
00176         self.name = name
00177         self.id = id
00178         self.description = description
00179         self.date = date
00180         self.confidences = confidences or []
00181         self.clade_relations = clade_relations or []
00182         self.sequence_relations = sequence_relations or []
00183         self.properties = properties or []
00184         self.other = other or []


Member Function Documentation

def Bio.Phylo.BaseTree.Tree.__format__ (   self,
  format_spec 
) [inherited]
Serialize the tree as a string in the specified file format.

This method supports the ``format`` built-in function added in Python
2.6/3.0.

:param format_spec: a lower-case string supported by `Bio.Phylo.write`
    as an output file format.

Definition at line 889 of file BaseTree.py.

00889 
00890     def __format__(self, format_spec):
00891         """Serialize the tree as a string in the specified file format.
00892 
00893         This method supports the ``format`` built-in function added in Python
00894         2.6/3.0.
00895 
00896         :param format_spec: a lower-case string supported by `Bio.Phylo.write`
00897             as an output file format.
00898         """
00899         if format_spec:
00900             from StringIO import StringIO
00901             from Bio.Phylo import _io
00902             handle = StringIO()
00903             _io.write([self], handle, format_spec)
00904             return handle.getvalue()
00905         else:
00906             # Follow python convention and default to using __str__
00907             return str(self)

Here is the caller graph for this function:

def Bio.Phylo.BaseTree.TreeElement.__repr__ (   self) [inherited]
Show this object's constructor with its primitive arguments.

Definition at line 216 of file BaseTree.py.

00216 
00217     def __repr__(self):
00218         """Show this object's constructor with its primitive arguments."""
00219         def pair_as_kwarg_string(key, val):
00220             if isinstance(val, basestring):
00221                 return "%s='%s'" % (key, _sugar.trim_str(unicode(val)))
00222             return "%s=%s" % (key, val)
00223         return u'%s(%s)' % (self.__class__.__name__,
00224                             ', '.join(pair_as_kwarg_string(key, val)
00225                                   for key, val in self.__dict__.iteritems()
00226                                   if val is not None and
00227                                   type(val) in (str, int, float, bool, unicode)
00228                                   ))

def Bio.Phylo.BaseTree.TreeElement.__repr__ (   self) [inherited]
Show this object's constructor with its primitive arguments.

Definition at line 216 of file BaseTree.py.

00216 
00217     def __repr__(self):
00218         """Show this object's constructor with its primitive arguments."""
00219         def pair_as_kwarg_string(key, val):
00220             if isinstance(val, basestring):
00221                 return "%s='%s'" % (key, _sugar.trim_str(unicode(val)))
00222             return "%s=%s" % (key, val)
00223         return u'%s(%s)' % (self.__class__.__name__,
00224                             ', '.join(pair_as_kwarg_string(key, val)
00225                                   for key, val in self.__dict__.iteritems()
00226                                   if val is not None and
00227                                   type(val) in (str, int, float, bool, unicode)
00228                                   ))

def Bio.Phylo.BaseTree.Tree.__str__ (   self) [inherited]
String representation of the entire tree.

Serializes each sub-clade recursively using ``repr`` to create a summary
of the object structure.

Definition at line 917 of file BaseTree.py.

00917 
00918     def __str__(self):
00919         """String representation of the entire tree.
00920 
00921         Serializes each sub-clade recursively using ``repr`` to create a summary
00922         of the object structure.
00923         """
00924         TAB = '    '
00925         textlines = []
00926         def print_tree(obj, indent):
00927             """Recursively serialize sub-elements.
00928 
00929             This closes over textlines and modifies it in-place.
00930             """
00931             textlines.append(TAB*indent + repr(obj))
00932             indent += 1
00933             for attr in obj.__dict__:
00934                 child = getattr(obj, attr)
00935                 if isinstance(child, TreeElement):
00936                     print_tree(child, indent)
00937                 elif isinstance(child, list):
00938                     for elem in child:
00939                         if isinstance(elem, TreeElement):
00940                             print_tree(elem, indent)
00941         print_tree(self, 0)
00942         return '\n'.join(textlines)
00943 

Definition at line 265 of file PhyloXML.py.

00265 
00266     def _del_confidence(self):
00267         self.confidences = []

Equivalent to self.confidences[0] if there is only 1 value.

See also: `Clade.confidence`, `Clade.taxonomy`

Definition at line 236 of file PhyloXML.py.

00236 
00237     def _get_confidence(self):
00238         """Equivalent to self.confidences[0] if there is only 1 value.
00239 
00240         See also: `Clade.confidence`, `Clade.taxonomy`
00241         """
00242         if len(self.confidences) == 0:
00243             return None
00244         if len(self.confidences) > 1:
00245             raise AttributeError("more than 1 confidence value available; "
00246                                  "use Phylogeny.confidences")
00247         return self.confidences[0]

def Bio.Phylo.PhyloXML.Phylogeny._set_confidence (   self,
  value 
) [private]

Definition at line 248 of file PhyloXML.py.

00248 
00249     def _set_confidence(self, value):
00250         if value is None:
00251             # Special case: mirror the behavior of _get_confidence
00252             self.confidences = []
00253             return
00254         if isinstance(value, float) or isinstance(value, int):
00255             value = Confidence(value)
00256         elif not isinstance(value, Confidence):
00257             raise ValueError("value must be a number or Confidence instance")
00258         if len(self.confidences) == 0:
00259             self.confidences.append(value)
00260         elif len(self.confidences) == 1:
00261             self.confidences[0] = value
00262         else:
00263             raise ValueError("multiple confidence values already exist; "
00264                              "use Phylogeny.confidences instead")

Return this tree, a PhyloXML-compatible Phylogeny object.

Overrides the `BaseTree` method.

Definition at line 207 of file PhyloXML.py.

00207 
00208     def as_phyloxml(self):
00209         """Return this tree, a PhyloXML-compatible Phylogeny object.
00210 
00211         Overrides the `BaseTree` method.
00212         """
00213         return self

def Bio.Phylo.BaseTree.Tree.as_phyloxml (   self,
  kwargs 
) [inherited]
Convert this tree to a PhyloXML-compatible Phylogeny.

This lets you use the additional annotation types PhyloXML defines, and
save this information when you write this tree as 'phyloxml'.

Definition at line 737 of file BaseTree.py.

00737 
00738     def as_phyloxml(self, **kwargs):
00739         """Convert this tree to a PhyloXML-compatible Phylogeny.
00740 
00741         This lets you use the additional annotation types PhyloXML defines, and
00742         save this information when you write this tree as 'phyloxml'.
00743         """
00744         from Bio.Phylo.PhyloXML import Phylogeny
00745         return Phylogeny.from_tree(self, **kwargs)

def Bio.Phylo.BaseTree.Tree.clade (   self) [inherited]
The first clade in this tree (not itself).

Definition at line 733 of file BaseTree.py.

00733 
00734     def clade(self):
00735         """The first clade in this tree (not itself)."""
00736         return self.root

def Bio.Phylo.BaseTree.TreeMixin.collapse (   self,
  target = None,
  kwargs 
) [inherited]
Deletes target from the tree, relinking its children to its parent.

:returns: the parent clade.

Definition at line 534 of file BaseTree.py.

00534 
00535     def collapse(self, target=None, **kwargs):
00536         """Deletes target from the tree, relinking its children to its parent.
00537 
00538         :returns: the parent clade.
00539         """
00540         path = self.get_path(target, **kwargs)
00541         if not path:
00542             raise ValueError("couldn't collapse %s in this tree"
00543                              % (target or kwargs))
00544         if len(path) == 1:
00545             parent = self.root
00546         else:
00547             parent = path[-2]
00548         popped = parent.clades.pop(parent.clades.index(path[-1]))
00549         extra_length = popped.branch_length or 0
00550         for child in popped:
00551             child.branch_length += extra_length
00552         parent.clades.extend(popped.clades)
00553         return parent

Here is the call graph for this function:

Here is the caller graph for this function:

def Bio.Phylo.BaseTree.TreeMixin.collapse_all (   self,
  target = None,
  kwargs 
) [inherited]
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.

Definition at line 554 of file BaseTree.py.

00554 
00555     def collapse_all(self, target=None, **kwargs):
00556         """Collapse all the descendents of this tree, leaving only terminals.
00557 
00558         Total branch lengths are preserved, i.e. the distance to each terminal
00559         stays the same.
00560 
00561         For example, this will safely collapse nodes with poor bootstrap
00562         support:
00563 
00564             >>> tree.collapse_all(lambda c: c.confidence is not None and
00565             ...                   c.confidence < 70)
00566 
00567         This implementation avoids strange side-effects by using level-order
00568         traversal and testing all clade properties (versus the target
00569         specification) up front. In particular, if a clade meets the target
00570         specification in the original tree, it will be collapsed.  For example,
00571         if the condition is:
00572 
00573             >>> tree.collapse_all(lambda c: c.branch_length < 0.1)
00574 
00575         Collapsing a clade's parent node adds the parent's branch length to the
00576         child, so during the execution of collapse_all, a clade's branch_length
00577         may increase. In this implementation, clades are collapsed according to
00578         their properties in the original tree, not the properties when tree
00579         traversal reaches the clade. (It's easier to debug.) If you want the
00580         other behavior (incremental testing), modifying the source code of this
00581         function is straightforward.
00582         """
00583         # Read the iterable into a list to protect against in-place changes
00584         matches = list(self.find_clades(target, False, 'level', **kwargs))
00585         if not matches:
00586             # No matching nodes to collapse
00587             return
00588         # Skip the root node -- it can't be collapsed
00589         if matches[0] == self.root:
00590             matches.pop(0)
00591         for clade in matches:
00592             self.collapse(clade)

Here is the call graph for this function:

def Bio.Phylo.BaseTree.TreeMixin.common_ancestor (   self,
  targets,
  more_targets 
) [inherited]
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

Definition at line 390 of file BaseTree.py.

00390 
00391     def common_ancestor(self, targets, *more_targets):
00392         """Most recent common ancestor (clade) of all the given targets.
00393 
00394         Edge cases:
00395         - If no target is given, returns self.root
00396         - If 1 target is given, returns the target
00397         - If any target is not found in this tree, raises a ValueError
00398         """
00399         paths = [self.get_path(t)
00400                  for t in _combine_args(targets, *more_targets)]
00401         # Validation -- otherwise izip throws a spooky error below
00402         for p, t in zip(paths, targets):
00403             if p is None:
00404                 raise ValueError("target %s is not in this tree" % repr(t))
00405         mrca = self.root
00406         for level in itertools.izip(*paths):
00407             ref = level[0]
00408             for other in level[1:]:
00409                 if ref is not other:
00410                     break
00411             else:
00412                 mrca = ref
00413             if ref is not mrca:
00414                 break
00415         return mrca

Here is the call graph for this function:

Here is the caller graph for this function:

Counts the number of terminal (leaf) nodes within this tree.

Definition at line 416 of file BaseTree.py.

00416 
00417     def count_terminals(self):
00418         """Counts the number of terminal (leaf) nodes within this tree."""
00419         return _sugar.iterlen(self.find_clades(terminal=True))

Here is the call graph for this function:

def Bio.Phylo.BaseTree.TreeMixin.depths (   self,
  unit_branch_lengths = False 
) [inherited]
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).

Definition at line 420 of file BaseTree.py.

00420 
00421     def depths(self, unit_branch_lengths=False):
00422         """Create a mapping of tree clades to depths (by branch length).
00423 
00424         :Parameters:
00425             unit_branch_lengths : bool
00426                 If True, count only the number of branches (levels in the tree).
00427                 By default the distance is the cumulative branch length leading
00428                 to the clade.
00429 
00430         :returns: dict of {clade: depth}, where keys are all of the Clade
00431             instances in the tree, and values are the distance from the root to
00432             each clade (including terminals).
00433         """
00434         if unit_branch_lengths:
00435             depth_of = lambda c: 1
00436         else:
00437             depth_of = lambda c: c.branch_length or 0
00438         depths = {}
00439         def update_depths(node, curr_depth):
00440             depths[node] = curr_depth
00441             for child in node.clades:
00442                 new_depth = curr_depth + depth_of(child)
00443                 update_depths(child, new_depth)
00444         update_depths(self.root, self.root.branch_length or 0)
00445         return depths

Here is the caller graph for this function:

def Bio.Phylo.BaseTree.TreeMixin.distance (   self,
  target1,
  target2 = None 
) [inherited]
Calculate the sum of the branch lengths between two targets.

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

Definition at line 446 of file BaseTree.py.

00446 
00447     def distance(self, target1, target2=None):
00448         """Calculate the sum of the branch lengths between two targets.
00449 
00450         If only one target is specified, the other is the root of this tree.
00451         """
00452         if target2 is None:
00453             return sum(n.branch_length for n in self.get_path(target1)
00454                        if n.branch_length is not None)
00455         mrca = self.common_ancestor(target1, target2)
00456         return mrca.distance(target1) + mrca.distance(target2)

Here is the call graph for this function:

def Bio.Phylo.BaseTree.TreeMixin.find_any (   self,
  args,
  kwargs 
) [inherited]
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.

Definition at line 263 of file BaseTree.py.

00263 
00264     def find_any(self, *args, **kwargs):
00265         """Return the first element found by find_elements(), or None.
00266 
00267         This is also useful for checking whether any matching element exists in
00268         the tree, and can be used in a conditional expression.
00269         """
00270         hits = self.find_elements(*args, **kwargs)
00271         try:
00272             return hits.next()
00273         except StopIteration:
00274             return None

Here is the call graph for this function:

def Bio.Phylo.BaseTree.TreeMixin.find_clades (   self,
  target = None,
  terminal = None,
  order = 'preorder',
  kwargs 
) [inherited]
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.

Definition at line 324 of file BaseTree.py.

00324 
00325             **kwargs):
00326         """Find each clade containing a matching element.
00327 
00328         That is, find each element as with find_elements(), but return the
00329         corresponding clade object. (This is usually what you want.)
00330 
00331         :returns: an iterable through all matching objects, searching
00332             depth-first (preorder) by default.
00333         """
00334         def match_attrs(elem):
00335             orig_clades = elem.__dict__.pop('clades')
00336             found = elem.find_any(target, **kwargs)
00337             elem.clades = orig_clades
00338             return (found is not None)
00339         if terminal is None:
00340             is_matching_elem = match_attrs
00341         else:
00342             def is_matching_elem(elem):
00343                 return ((elem.is_terminal() == terminal) and
00344                         match_attrs(elem))
00345         return self._filter_search(is_matching_elem, order, False)

Here is the call graph for this function:

Here is the caller graph for this function:

def Bio.Phylo.BaseTree.TreeMixin.find_elements (   self,
  target = None,
  terminal = None,
  order = 'preorder',
  kwargs 
) [inherited]
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')

Definition at line 276 of file BaseTree.py.

00276 
00277             **kwargs):
00278         """Find all tree elements matching the given attributes.
00279 
00280         The arbitrary keyword arguments indicate the attribute name of the
00281         sub-element and the value to match: string, integer or boolean. Strings
00282         are evaluated as regular expression matches; integers are compared
00283         directly for equality, and booleans evaluate the attribute's truth value
00284         (True or False) before comparing. To handle nonzero floats, search with
00285         a boolean argument, then filter the result manually.
00286 
00287         If no keyword arguments are given, then just the class type is used for
00288         matching.
00289 
00290         The result is an iterable through all matching objects, by depth-first
00291         search. (Not necessarily the same order as the elements appear in the
00292         source file!)
00293 
00294         :Parameters:
00295             target : TreeElement instance, type, dict, or callable
00296                 Specifies the characteristics to search for. (The default,
00297                 TreeElement, matches any standard Bio.Phylo type.)
00298             terminal : bool
00299                 A boolean value to select for or against terminal nodes (a.k.a.
00300                 leaf nodes). True searches for only terminal nodes, False
00301                 excludes terminal nodes, and the default, None, searches both
00302                 terminal and non-terminal nodes, as well as any tree elements
00303                 lacking the ``is_terminal`` method.
00304             order : {'preorder', 'postorder', 'level'}
00305                 Tree traversal order: 'preorder' (default) is depth-first
00306                 search, 'postorder' is DFS with child nodes preceding parents,
00307                 and 'level' is breadth-first search.
00308 
00309         Example
00310         -------
00311 
00312         >>> from Bio.Phylo.IO import PhyloXMIO
00313         >>> phx = PhyloXMLIO.read('phyloxml_examples.xml')
00314         >>> matches = phx.phylogenies[5].find_elements(code='OCTVU')
00315         >>> matches.next()
00316         Taxonomy(code='OCTVU', scientific_name='Octopus vulgaris')
00317 
00318         """
00319         if terminal is not None:
00320             kwargs['terminal'] = terminal
00321         is_matching_elem = _combine_matchers(target, kwargs, False)
00322         return self._filter_search(is_matching_elem, order, True)

Here is the call graph for this function:

Here is the caller graph for this function:

def Bio.Phylo.BaseTree.Tree.format (   self,
  format 
) [inherited]
Serialize the tree as a string in the specified file format.

This duplicates the __format__ magic method for pre-2.6 Pythons.

Definition at line 908 of file BaseTree.py.

00908 
00909     def format(self, format):
00910         """Serialize the tree as a string in the specified file format.
00911 
00912         This duplicates the __format__ magic method for pre-2.6 Pythons.
00913         """
00914         return self.__format__(format)

Here is the call graph for this function:

Here is the caller graph for this function:

def Bio.Phylo.PhyloXML.Phylogeny.from_clade (   cls,
  clade,
  kwargs 
)
Create a new Phylogeny given a Newick or BaseTree Clade object.

Keyword arguments are the usual `PhyloXML.Clade` constructor parameters.

Reimplemented from Bio.Phylo.BaseTree.Tree.

Definition at line 200 of file PhyloXML.py.

00200 
00201     def from_clade(cls, clade, **kwargs):
00202         """Create a new Phylogeny given a Newick or BaseTree Clade object.
00203 
00204         Keyword arguments are the usual `PhyloXML.Clade` constructor parameters.
00205         """
00206         return Clade.from_clade(clade).to_phylogeny(**kwargs)

def Bio.Phylo.PhyloXML.Phylogeny.from_tree (   cls,
  tree,
  kwargs 
)
Create a new Phylogeny given a Tree (from Newick/Nexus or BaseTree).

Keyword arguments are the usual `Phylogeny` constructor parameters.

Definition at line 186 of file PhyloXML.py.

00186 
00187     def from_tree(cls, tree, **kwargs):
00188         """Create a new Phylogeny given a Tree (from Newick/Nexus or BaseTree).
00189 
00190         Keyword arguments are the usual `Phylogeny` constructor parameters.
00191         """
00192         phy = cls(
00193                 root=Clade.from_clade(tree.root),
00194                 rooted=tree.rooted,
00195                 name=tree.name,
00196                 id=(tree.id is not None) and Id(str(tree.id)) or None)
00197         phy.__dict__.update(kwargs)
00198         return phy

def Bio.Phylo.BaseTree.TreeMixin.get_nonterminals (   self,
  order = 'preorder' 
) [inherited]
Get a list of all of this tree's nonterminal (internal) nodes.

Definition at line 370 of file BaseTree.py.

00370 
00371     def get_nonterminals(self, order='preorder'):
00372         """Get a list of all of this tree's nonterminal (internal) nodes."""
00373         return list(self.find_clades(terminal=False, order=order))

Here is the call graph for this function:

def Bio.Phylo.BaseTree.TreeMixin.get_path (   self,
  target = None,
  kwargs 
) [inherited]
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.

Definition at line 346 of file BaseTree.py.

00346 
00347     def get_path(self, target=None, **kwargs):
00348         """List the clades directly between this root and the given target.
00349 
00350         :returns: list of all clade objects along this path, ending with the
00351             given target, but excluding the root clade.
00352         """
00353         # Only one path will work -- ignore weights and visits
00354         path = []
00355         match = _combine_matchers(target, kwargs, True)
00356         def check_in_path(v):
00357             if match(v):
00358                 path.append(v)
00359                 return True
00360             elif v.is_terminal():
00361                 return False
00362             for child in v:
00363                 if check_in_path(child):
00364                     path.append(v)
00365                     return True
00366             return False
00367         if not check_in_path(self.root):
00368             return None
00369         return path[-2::-1]

Here is the call graph for this function:

Here is the caller graph for this function:

def Bio.Phylo.BaseTree.TreeMixin.get_terminals (   self,
  order = 'preorder' 
) [inherited]
Get a list of all of this tree's terminal (leaf) nodes.

Definition at line 374 of file BaseTree.py.

00374 
00375     def get_terminals(self, order='preorder'):
00376         """Get a list of all of this tree's terminal (leaf) nodes."""
00377         return list(self.find_clades(terminal=True, order=order))

Here is the call graph for this function:

Here is the caller graph for this function:

def Bio.Phylo.BaseTree.TreeMixin.is_bifurcating (   self) [inherited]
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.

Definition at line 457 of file BaseTree.py.

00457 
00458     def is_bifurcating(self):
00459         """Return True if tree downstream of node is strictly bifurcating.
00460 
00461         I.e., all nodes have either 2 or 0 children (internal or external,
00462         respectively). The root may have 3 descendents and still be considered
00463         part of a bifurcating tree, because it has no ancestor.
00464         """
00465         # Root can be trifurcating
00466         if isinstance(self, Tree) and len(self.root) == 3:
00467             return (self.root.clades[0].is_bifurcating() and
00468                     self.root.clades[1].is_bifurcating() and
00469                     self.root.clades[2].is_bifurcating())
00470         if len(self.root) == 2:
00471             return (self.root.clades[0].is_bifurcating() and
00472                     self.root.clades[1].is_bifurcating())
00473         if len(self.root) == 0:
00474             return True
00475         return False

def Bio.Phylo.BaseTree.TreeMixin.is_monophyletic (   self,
  terminals,
  more_terminals 
) [inherited]
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.

Definition at line 476 of file BaseTree.py.

00476 
00477     def is_monophyletic(self, terminals, *more_terminals):
00478         """MRCA of terminals if they comprise a complete subclade, or False.
00479 
00480         I.e., there exists a clade such that its terminals are the same set as
00481         the given targets.
00482 
00483         The given targets must be terminals of the tree.
00484 
00485         To match both `Bio.Nexus.Trees` and the other multi-target methods in
00486         Bio.Phylo, arguments to this method can be specified either of two ways:
00487         (i) as a single list of targets, or (ii) separately specified targets,
00488         e.g. is_monophyletic(t1, t2, t3) -- but not both.
00489 
00490         For convenience, this method returns the common ancestor (MCRA) of the
00491         targets if they are monophyletic (instead of the value True), and False
00492         otherwise.
00493 
00494         :returns: common ancestor if terminals are monophyletic, otherwise False.
00495         """
00496         target_set = set(_combine_args(terminals, *more_terminals))
00497         current = self.root
00498         while True:
00499             if set(current.get_terminals()) == target_set:
00500                 return current
00501             # Try a narrower subclade
00502             for subclade in current.clades:
00503                 if set(subclade.get_terminals()).issuperset(target_set):
00504                     current = subclade
00505                     break
00506             else:
00507                 return False

Here is the call graph for this function:

def Bio.Phylo.BaseTree.TreeMixin.is_parent_of (   self,
  target = None,
  kwargs 
) [inherited]
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: ...``

Definition at line 508 of file BaseTree.py.

00508 
00509     def is_parent_of(self, target=None, **kwargs):
00510         """True if target is a descendent of this tree.
00511 
00512         Not required to be a direct descendent.
00513 
00514         To check only direct descendents of a clade, simply use list membership
00515         testing: ``if subclade in clade: ...``
00516         """
00517         return self.get_path(target, **kwargs) is not None

Here is the call graph for this function:

def Bio.Phylo.BaseTree.TreeMixin.is_preterminal (   self) [inherited]
True if all direct descendents are terminal.

Definition at line 518 of file BaseTree.py.

00518 
00519     def is_preterminal(self):
00520         """True if all direct descendents are terminal."""
00521         if self.root.is_terminal():
00522             return False
00523         for clade in self.root.clades:
00524             if not clade.is_terminal():
00525                 return False
00526         return True

def Bio.Phylo.BaseTree.Tree.is_terminal (   self) [inherited]
True if the root of this tree is terminal.

Definition at line 883 of file BaseTree.py.

00883 
00884     def is_terminal(self):
00885         """True if the root of this tree is terminal."""
00886         return (not self.root.clades)

def Bio.Phylo.BaseTree.TreeMixin.ladderize (   self,
  reverse = False 
) [inherited]
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.

Definition at line 593 of file BaseTree.py.

00593 
00594     def ladderize(self, reverse=False):
00595         """Sort clades in-place according to the number of terminal nodes.
00596 
00597         Deepest clades are last by default. Use ``reverse=True`` to sort clades
00598         deepest-to-shallowest.
00599         """
00600         self.root.clades.sort(key=lambda c: c.count_terminals(),
00601                               reverse=reverse)
00602         for subclade in self.root.clades:
00603             subclade.ladderize(reverse=reverse)

def Bio.Phylo.BaseTree.TreeMixin.prune (   self,
  target = None,
  kwargs 
) [inherited]
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

Definition at line 604 of file BaseTree.py.

00604 
00605     def prune(self, target=None, **kwargs):
00606         """Prunes a terminal clade from the tree.
00607 
00608         If taxon is from a bifurcation, the connecting node will be collapsed
00609         and its branch length added to remaining terminal node. This might be no
00610         longer be a meaningful value.
00611 
00612         :returns: parent clade of the pruned target
00613         """
00614         if 'terminal' in kwargs and kwargs['terminal']:
00615             raise ValueError("target must be terminal")
00616         path = self.get_path(target, terminal=True, **kwargs)
00617         if not path:
00618             raise ValueError("can't find a matching target below this root")
00619         if len(path) == 1:
00620             parent = self.root
00621         else:
00622             parent = path[-2]
00623         parent.clades.remove(path[-1])
00624         if len(parent) == 1:
00625             # We deleted a branch from a bifurcation
00626             if parent == self.root:
00627                 # If we're at the root, move the root upwards
00628                 # NB: This loses the length of the original branch
00629                 newroot = parent.clades[0]
00630                 newroot.branch_length = None
00631                 parent = self.root = newroot
00632             else:
00633                 # If we're not at the root, collapse this parent
00634                 child = parent.clades[0]
00635                 if child.branch_length is not None:
00636                     child.branch_length += (parent.branch_length or 0.0)
00637                 if len(path) < 3:
00638                     grandparent = self.root
00639                 else:
00640                     grandparent = path[-3]
00641                 # Replace parent with child at the same place in grandparent
00642                 index = grandparent.clades.index(parent)
00643                 grandparent.clades.pop(index)
00644                 grandparent.clades.insert(index, child)
00645                 parent = grandparent
00646         return parent

Here is the call graph for this function:

def Bio.Phylo.BaseTree.Tree.randomized (   cls,
  taxa,
  branch_length = 1.0,
  branch_stdev = None 
) [inherited]
Create a randomized bifurcating tree given a list of taxa.

:param taxa: Either an integer specifying the number of taxa to create
    (automatically named taxon#), or an iterable of taxon names, as
    strings.

:returns: a tree of the same type as this class.

Definition at line 698 of file BaseTree.py.

00698 
00699     def randomized(cls, taxa, branch_length=1.0, branch_stdev=None):
00700         """Create a randomized bifurcating tree given a list of taxa.
00701 
00702         :param taxa: Either an integer specifying the number of taxa to create
00703             (automatically named taxon#), or an iterable of taxon names, as
00704             strings.
00705 
00706         :returns: a tree of the same type as this class.
00707         """
00708         if isinstance(taxa, int):
00709             taxa = ['taxon%s' % (i+1) for i in range(taxa)]
00710         elif hasattr(taxa, '__iter__'):
00711             taxa = list(taxa)
00712         else:
00713             raise TypeError("taxa argument must be integer (# taxa) or "
00714                             "iterable of taxon names.")
00715         rtree = cls()
00716         terminals = [rtree.root]
00717         while len(terminals) < len(taxa):
00718             newsplit = random.choice(terminals)
00719             newterms = newsplit.split(branch_length=branch_length)
00720             if branch_stdev:
00721                 # Add some noise to the branch lengths
00722                 for nt in newterms:
00723                     nt.branch_length = max(0,
00724                             random.gauss(branch_length, branch_stdev))
00725             terminals.remove(newsplit)
00726             terminals.extend(newterms)
00727         # Distribute taxon labels randomly
00728         random.shuffle(taxa)
00729         for node, name in zip(terminals, taxa):
00730             node.name = name
00731         return rtree

def Bio.Phylo.BaseTree.Tree.root_at_midpoint (   self) [inherited]
Root the tree at the midpoint of the two most distant taxa.

This operates in-place, leaving a bifurcating root. The topology of the
tree is otherwise retained, though no guarantees are made about the
stability of clade/node/taxon ordering.

Definition at line 846 of file BaseTree.py.

00846 
00847     def root_at_midpoint(self):
00848         """Root the tree at the midpoint of the two most distant taxa.
00849 
00850         This operates in-place, leaving a bifurcating root. The topology of the
00851         tree is otherwise retained, though no guarantees are made about the
00852         stability of clade/node/taxon ordering.
00853         """
00854         # Identify the largest pairwise distance
00855         max_distance = 0.0
00856         tips = self.get_terminals()
00857         for tip in tips:
00858             self.root_with_outgroup(tip)
00859             new_max = max(self.depths().iteritems(), key=lambda nd: nd[1])
00860             if new_max[1] > max_distance:
00861                 tip1 = tip
00862                 tip2 = new_max[0]
00863                 max_distance = new_max[1]
00864         self.root_with_outgroup(tip1)
00865         # Depth to go from the ingroup tip toward the outgroup tip
00866         root_remainder = 0.5 * (max_distance - (self.root.branch_length or 0))
00867         assert root_remainder >= 0
00868         # Identify the midpoint and reroot there.
00869         # Trace the path to the outgroup tip until all of the root depth has
00870         # been traveled/accounted for.
00871         for node in self.get_path(tip2):
00872             root_remainder -= node.branch_length
00873             if root_remainder < 0:
00874                 outgroup_node = node
00875                 outgroup_branch_length = -root_remainder
00876                 break
00877         else:
00878             raise ValueError("Somehow, failed to find the midpoint!")
00879         self.root_with_outgroup(outgroup_node,
00880                                 outgroup_branch_length=outgroup_branch_length)

Here is the call graph for this function:

def Bio.Phylo.BaseTree.Tree.root_with_outgroup (   self,
  outgroup_targets,
  more_targets,
  kwargs 
) [inherited]
Reroot this tree with the outgroup clade containing outgroup_targets.

Operates in-place.

Edge cases:

- If ``outgroup == self.root``, no change
- If outgroup is terminal, create new bifurcating root node with a
  0-length branch to the outgroup
- If outgroup is internal, use the given outgroup node as the new
  trifurcating root, keeping branches the same
- If the original root was bifurcating, drop it from the tree,
  preserving total branch lengths

:param outgroup_branch_length: length of the branch leading to the
    outgroup after rerooting. If not specified (None), then:

    - If the outgroup is an internal node (not a single terminal taxon),
      then use that node as the new root.
    - Otherwise, create a new root node as the parent of the outgroup.

Definition at line 748 of file BaseTree.py.

00748 
00749     def root_with_outgroup(self, outgroup_targets, *more_targets, **kwargs):
00750         """Reroot this tree with the outgroup clade containing outgroup_targets.
00751 
00752         Operates in-place.
00753 
00754         Edge cases:
00755 
00756         - If ``outgroup == self.root``, no change
00757         - If outgroup is terminal, create new bifurcating root node with a
00758           0-length branch to the outgroup
00759         - If outgroup is internal, use the given outgroup node as the new
00760           trifurcating root, keeping branches the same
00761         - If the original root was bifurcating, drop it from the tree,
00762           preserving total branch lengths
00763 
00764         :param outgroup_branch_length: length of the branch leading to the
00765             outgroup after rerooting. If not specified (None), then:
00766 
00767             - If the outgroup is an internal node (not a single terminal taxon),
00768               then use that node as the new root.
00769             - Otherwise, create a new root node as the parent of the outgroup.
00770 
00771         """
00772         # This raises a ValueError if any target is not in this tree
00773         # Otherwise, common_ancestor guarantees outgroup is in this tree
00774         outgroup = self.common_ancestor(outgroup_targets, *more_targets)
00775         outgroup_path = self.get_path(outgroup)
00776         if len(outgroup_path) == 0:
00777             # Outgroup is the current root -- no change
00778             return
00779 
00780         prev_blen = outgroup.branch_length or 0.0
00781         # Hideous kludge because Py2.x doesn't allow keyword args after *args
00782         outgroup_branch_length = kwargs.get('outgroup_branch_length')
00783         if outgroup_branch_length is not None:
00784             assert 0 <= outgroup_branch_length <= prev_blen, \
00785                     "outgroup_branch_length must be between 0 and the " \
00786                     "original length of the branch leading to the outgroup."
00787 
00788         if outgroup.is_terminal() or outgroup_branch_length is not None:
00789             # Create a new root with a 0-length branch to the outgroup
00790             outgroup.branch_length = outgroup_branch_length or 0.0
00791             new_root = self.root.__class__(
00792                     branch_length=self.root.branch_length, clades=[outgroup])
00793             # The first branch reversal (see the upcoming loop) is modified
00794             if len(outgroup_path) == 1:
00795                 # No nodes between the original root and outgroup to rearrange.
00796                 # Most of the code below will be skipped, but we still need
00797                 # 'new_parent' pointing at the new root.
00798                 new_parent = new_root
00799             else:
00800                 parent = outgroup_path.pop(-2)
00801                 # First iteration of reversing the path to the outgroup
00802                 parent.clades.pop(parent.clades.index(outgroup))
00803                 (prev_blen, parent.branch_length) = (parent.branch_length,
00804                         prev_blen - outgroup.branch_length)
00805                 new_root.clades.insert(0, parent)
00806                 new_parent = parent
00807         else:
00808             # Use the given outgroup node as the new (trifurcating) root
00809             new_root = outgroup
00810             new_root.branch_length = self.root.branch_length
00811             new_parent = new_root
00812 
00813         # Tracing the outgroup lineage backwards, reattach the subclades under a
00814         # new root clade. Reverse the branches directly above the outgroup in
00815         # the tree, but keep the descendants of those clades as they are.
00816         for parent in outgroup_path[-2::-1]:
00817             parent.clades.pop(parent.clades.index(new_parent))
00818             prev_blen, parent.branch_length = parent.branch_length, prev_blen
00819             new_parent.clades.insert(0, parent)
00820             new_parent = parent
00821 
00822         # Finally, handle the original root according to number of descendents
00823         old_root = self.root
00824         if outgroup in old_root.clades:
00825             assert len(outgroup_path) == 1
00826             old_root.clades.pop(old_root.clades.index(outgroup))
00827         else:
00828             old_root.clades.pop(old_root.clades.index(new_parent))
00829         if len(old_root) == 1:
00830             # Delete the old bifurcating root & add branch lengths
00831             ingroup = old_root.clades[0]
00832             if ingroup.branch_length:
00833                 ingroup.branch_length += prev_blen
00834             else:
00835                 ingroup.branch_length = prev_blen
00836             new_parent.clades.insert(0, ingroup)
00837             # ENH: If annotations are attached to old_root, do... something.
00838         else:
00839             # Keep the old trifurcating/polytomous root as an internal node
00840             old_root.branch_length = prev_blen
00841             new_parent.clades.insert(0, old_root)
00842 
00843         self.root = new_root
00844         self.rooted = True
00845         return

Here is the call graph for this function:

Here is the caller graph for this function:

def Bio.Phylo.BaseTree.TreeMixin.split (   self,
  n = 2,
  branch_length = 1.0 
) [inherited]
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".

Definition at line 647 of file BaseTree.py.

00647 
00648     def split(self, n=2, branch_length=1.0):
00649         """Generate n (default 2) new descendants.
00650 
00651         In a species tree, this is a speciation event.
00652 
00653         New clades have the given branch_length and the same name as this
00654         clade's root plus an integer suffix (counting from 0). For example,
00655         splitting a clade named "A" produces sub-clades named "A0" and "A1".
00656         """
00657         clade_cls = type(self.root)
00658         base_name = self.root.name or ''
00659         for i in range(n):
00660             clade = clade_cls(name=base_name+str(i),
00661                                 branch_length=branch_length)
00662             self.root.clades.append(clade)
00663 

Construct an alignment from the aligned sequences in this tree.

Definition at line 218 of file PhyloXML.py.

00218 
00219     def to_alignment(self):
00220         """Construct an alignment from the aligned sequences in this tree."""
00221         def is_aligned_seq(elem):
00222             if isinstance(elem, Sequence) and elem.mol_seq.is_aligned:
00223                 return True
00224             return False
00225         seqs = self._filter_search(is_aligned_seq, 'preorder', True)
00226         try:
00227             first_seq = seqs.next()
00228         except StopIteration:
00229             # No aligned sequences were found --> empty MSA
00230             return MultipleSeqAlignment([])
00231         msa = MultipleSeqAlignment([first_seq.to_seqrecord()],
00232                                    first_seq.get_alphabet())
00233         msa.extend(seq.to_seqrecord() for seq in seqs)
00234         return msa

Here is the call graph for this function:

Create a new Phyloxml object containing just this phylogeny.

Definition at line 214 of file PhyloXML.py.

00214 
00215     def to_phyloxml_container(self, **kwargs):
00216         """Create a new Phyloxml object containing just this phylogeny."""
00217         return Phyloxml(kwargs, phylogenies=[self])

Calculate the sum of all the branch lengths in this tree.

Definition at line 527 of file BaseTree.py.

00527 
00528     def total_branch_length(self):
00529         """Calculate the sum of all the branch lengths in this tree."""
00530         return sum(node.branch_length
00531                    for node in self.find_clades(branch_length=True))

Here is the call graph for this function:

def Bio.Phylo.BaseTree.TreeMixin.trace (   self,
  start,
  finish 
) [inherited]
List of all clade object between two targets in this tree.

Excluding `start`, including `finish`.

Definition at line 378 of file BaseTree.py.

00378 
00379     def trace(self, start, finish):
00380         """List of all clade object between two targets in this tree.
00381 
00382         Excluding `start`, including `finish`.
00383         """
00384         mrca = self.common_ancestor(start, finish)
00385         fromstart = mrca.get_path(start)[-2::-1]
00386         to = mrca.get_path(finish)
00387         return fromstart + [mrca] + to

Here is the call graph for this function:


Member Data Documentation

Definition at line 173 of file PhyloXML.py.

Definition at line 180 of file PhyloXML.py.

Definition at line 179 of file PhyloXML.py.

Definition at line 178 of file PhyloXML.py.

Definition at line 177 of file PhyloXML.py.

Reimplemented from Bio.Phylo.BaseTree.Tree.

Definition at line 176 of file PhyloXML.py.

Reimplemented from Bio.Phylo.BaseTree.Tree.

Definition at line 175 of file PhyloXML.py.

Definition at line 183 of file PhyloXML.py.

Definition at line 182 of file PhyloXML.py.

Definition at line 172 of file PhyloXML.py.

Reimplemented from Bio.Phylo.BaseTree.Tree.

Definition at line 170 of file PhyloXML.py.

Reimplemented from Bio.Phylo.BaseTree.Tree.

Definition at line 171 of file PhyloXML.py.

Definition at line 181 of file PhyloXML.py.

Definition at line 174 of file PhyloXML.py.


Property Documentation

Definition at line 268 of file PhyloXML.py.


The documentation for this class was generated from the following file: